export interface JellyfinTimelinePlaybackState { itemId: string; mediaSourceId?: string; positionTicks?: number; playbackStartTimeTicks?: number; isPaused?: boolean; isMuted?: boolean; canSeek?: boolean; volumeLevel?: number; playbackRate?: number; playMethod?: string; audioStreamIndex?: number | null; subtitleStreamIndex?: number | null; playlistItemId?: string | null; eventName?: string; failed?: boolean; } export interface JellyfinTimelinePayload { ItemId: string; MediaSourceId?: string; PositionTicks: number; PlaybackStartTimeTicks: number; IsPaused: boolean; IsMuted: boolean; CanSeek: boolean; VolumeLevel: number; PlaybackRate: number; PlayMethod: string; AudioStreamIndex?: number | null; SubtitleStreamIndex?: number | null; PlaylistItemId?: string | null; Failed?: boolean; } export interface JellyfinPlaybackReporterOptions { serverUrl: string; accessToken: string; deviceId: string; clientName?: string; clientVersion?: string; deviceName?: string; fetchImpl?: typeof fetch; logWarn?: (message: string, details?: unknown) => void; } const JELLYFIN_REPORT_TIMEOUT_MS = 5000; function clampVolume(value: number | undefined): number { if (typeof value !== 'number' || !Number.isFinite(value)) return 100; return Math.max(0, Math.min(100, Math.round(value))); } function normalizeTicks(value: number | undefined): number { if (typeof value !== 'number' || !Number.isFinite(value)) return 0; return Math.max(0, Math.floor(value)); } function asNullableInteger(value: number | null | undefined): number | null { if (typeof value !== 'number' || !Number.isInteger(value)) return null; return value; } export function buildJellyfinTimelinePayload( state: JellyfinTimelinePlaybackState, ): JellyfinTimelinePayload { return { ItemId: state.itemId, MediaSourceId: state.mediaSourceId, PositionTicks: normalizeTicks(state.positionTicks), PlaybackStartTimeTicks: normalizeTicks(state.playbackStartTimeTicks), IsPaused: state.isPaused === true, IsMuted: state.isMuted === true, CanSeek: state.canSeek !== false, VolumeLevel: clampVolume(state.volumeLevel), PlaybackRate: typeof state.playbackRate === 'number' && Number.isFinite(state.playbackRate) ? state.playbackRate : 1, PlayMethod: state.playMethod || 'DirectPlay', AudioStreamIndex: asNullableInteger(state.audioStreamIndex), SubtitleStreamIndex: asNullableInteger(state.subtitleStreamIndex), PlaylistItemId: state.playlistItemId, Failed: state.failed, }; } // Authenticated JSON POSTs as this device. Playback timeline reports (start, progress, stop) // are plain HTTP, so they work whether or not the cast-control websocket is connected; that // is how Jellyfin learns the resume position and marks items played for every playback. export class JellyfinPlaybackReporter { readonly authHeader: string; private readonly serverUrl: string; private readonly fetchImpl: typeof fetch; private readonly logWarn?: (message: string, details?: unknown) => void; private readonly failedRequestPaths = new Set(); constructor(options: JellyfinPlaybackReporterOptions) { this.serverUrl = options.serverUrl.trim().replace(/\/+$/, ''); this.fetchImpl = options.fetchImpl ?? fetch; this.logWarn = options.logWarn; const clientName = options.clientName || 'SubMiner'; const clientVersion = options.clientVersion || '0.1.0'; const deviceName = options.deviceName || clientName; this.authHeader = `MediaBrowser Client="${clientName}", Device="${deviceName}", DeviceId="${options.deviceId}", Version="${clientVersion}", Token="${options.accessToken}"`; } reportPlaying(state: JellyfinTimelinePlaybackState): Promise { return this.postJson('/Sessions/Playing', buildJellyfinTimelinePayload(state)); } reportProgress(state: JellyfinTimelinePlaybackState): Promise { return this.postJson('/Sessions/Playing/Progress', buildJellyfinTimelinePayload(state)); } reportStopped(state: JellyfinTimelinePlaybackState): Promise { return this.postJson('/Sessions/Playing/Stopped', { ...buildJellyfinTimelinePayload(state), Failed: state.failed === true, }); } async postJson(path: string, payload: unknown): Promise { try { const response = await this.fetchImpl(`${this.serverUrl}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: this.authHeader, }, body: JSON.stringify(payload), // The stop report waits for in-flight progress reports, so a hung request must not // hold it back indefinitely. signal: AbortSignal.timeout(JELLYFIN_REPORT_TIMEOUT_MS), }); this.noteRequestOutcome(path, response.ok ? null : `HTTP ${response.status}`); return response.ok; } catch (error) { this.noteRequestOutcome(path, error); return false; } } // Warn once per path while it keeps failing so a rejected stop report is visible in the // log without a warning per progress tick. private noteRequestOutcome(path: string, failure: unknown): void { if (failure === null) { this.failedRequestPaths.delete(path); return; } if (this.failedRequestPaths.has(path)) return; this.failedRequestPaths.add(path); this.logWarn?.(`Jellyfin request failed: POST ${path}`, failure); } }