BlueGit

timfa filemanager

Merge fix/subtitle-cache-only-viewer

timfa Tim Falken · pushed by timfa

Authored 2026-05-26 · 5 months ago

Hash
e29c4a1454226b2249bf184b48cbea47af29c045
5 files changed +67 −3
.github/technical-reference.md +1 −1
@@ -185,7 +185,7 @@
185 185 ## public/shared-video-player.js
186 186 - applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
187 187 - bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
188 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
188 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
189 189 - bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
190 190 - bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
191 191 - enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
@@ -185,7 +185,7 @@
185## public/shared-video-player.js
185## public/shared-video-player.js
186- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
186- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
187- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
187- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
188- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
188- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
189- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
189- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
190- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
190- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
191- enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
191- enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
public/app.js +1 −0
@@ -429,6 +429,7 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
429 429
430 430 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
431 431 savePrefs: saveUserVideoPrefs,
432 currentFetchEnabled: false,
432 433 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
433 434 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
434 435 sendSubtitleLogBatch,
@@ -429,6 +429,7 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
429
429
430 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
430 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
431 savePrefs: saveUserVideoPrefs,
431 savePrefs: saveUserVideoPrefs,
432 currentFetchEnabled: false,
432 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
433 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
433 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
434 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
434 sendSubtitleLogBatch,
435 sendSubtitleLogBatch,
public/share.html +1 −0
@@ -506,6 +506,7 @@
506 506 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
507 507 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
508 508 savePrefs: saveShareVideoPrefs,
509 currentFetchEnabled: false,
509 510 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
510 511 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
511 512 sendSubtitleLogBatch: (entries) =>
@@ -506,6 +506,7 @@
506 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
506 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
507 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
507 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
508 savePrefs: saveShareVideoPrefs,
508 savePrefs: saveShareVideoPrefs,
509 currentFetchEnabled: false,
509 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
510 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
510 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
511 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
511 sendSubtitleLogBatch: (entries) =>
512 sendSubtitleLogBatch: (entries) =>
public/shared-video-player.js +15 −2
@@ -297,6 +297,7 @@
297 297 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
298 298 ? Math.max(0, requestedPrefetchRequestIntervalMs)
299 299 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
300 const currentFetchEnabled = opts.currentFetchEnabled !== false;
300 301 const logToConsole = opts.logToConsole !== false;
301 302 if (!buildFrameRequest) return null;
302 303
@@ -832,7 +833,7 @@
832 833 }
833 834 };
834 835
835 const queueLookaheadPrefetch = (currentTime, { reset = false } = {}) =>
836 const queueLookaheadPrefetch = (currentTime, { reset = false, includeCurrentTime = false } = {}) =>
836 837 {
837 838 if (selectedStreamIndex === null) return;
838 839 if (trackDisabled) return;
@@ -871,7 +872,9 @@
871 872 return Math.max(...candidates);
872 873 })();
873 874
874 const startTime = currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
875 const startTime = includeCurrentTime
876 ? currentTime
877 : currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
875 878 const endTime = Math.max(
876 879 currentTime + lookaheadSeconds,
877 880 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
@@ -1072,6 +1075,16 @@
1072 1075 return;
1073 1076 }
1074 1077
1078 if (!currentFetchEnabled)
1079 {
1080 hideOverlay();
1081 queueLookaheadPrefetch(currentTime, {
1082 reset: force,
1083 includeCurrentTime: true,
1084 });
1085 return;
1086 }
1087
1075 1088 const refreshLifecycleToken = lifecycleToken;
1076 1089 if (force && currentFramePromise)
1077 1090 {
@@ -297,6 +297,7 @@
297 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
297 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
298 ? Math.max(0, requestedPrefetchRequestIntervalMs)
298 ? Math.max(0, requestedPrefetchRequestIntervalMs)
299 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
299 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
300 const currentFetchEnabled = opts.currentFetchEnabled !== false;
300 const logToConsole = opts.logToConsole !== false;
301 const logToConsole = opts.logToConsole !== false;
301 if (!buildFrameRequest) return null;
302 if (!buildFrameRequest) return null;
302
303
@@ -832,7 +833,7 @@
832 }
833 }
833 };
834 };
834
835
835 const queueLookaheadPrefetch = (currentTime, { reset = false } = {}) =>
836 const queueLookaheadPrefetch = (currentTime, { reset = false, includeCurrentTime = false } = {}) =>
836 {
837 {
837 if (selectedStreamIndex === null) return;
838 if (selectedStreamIndex === null) return;
838 if (trackDisabled) return;
839 if (trackDisabled) return;
@@ -871,7 +872,9 @@
871 return Math.max(...candidates);
872 return Math.max(...candidates);
872 })();
873 })();
873
874
874 const startTime = currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
875 const startTime = includeCurrentTime
876 ? currentTime
877 : currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
875 const endTime = Math.max(
878 const endTime = Math.max(
876 currentTime + lookaheadSeconds,
879 currentTime + lookaheadSeconds,
877 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
880 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
@@ -1072,6 +1075,16 @@
1072 return;
1075 return;
1073 }
1076 }
1074
1077
1078 if (!currentFetchEnabled)
1079 {
1080 hideOverlay();
1081 queueLookaheadPrefetch(currentTime, {
1082 reset: force,
1083 includeCurrentTime: true,
1084 });
1085 return;
1086 }
1087
1075 const refreshLifecycleToken = lifecycleToken;
1088 const refreshLifecycleToken = lifecycleToken;
1076 if (force && currentFramePromise)
1089 if (force && currentFramePromise)
1077 {
1090 {
tests/shared-video-player.test.js +49 −0
@@ -571,6 +571,55 @@ describe('shared image subtitle prefetching', () =>
571 571 window.close();
572 572 });
573 573
574 test('cache-only current mode avoids direct current subtitle fetch requests', async () =>
575 {
576 const window = createWindow();
577 const helper = loadSharedVideoPlayer(window);
578 const { player, videojs } = buildPlayerHarness(window);
579 const sentBatches = [];
580
581 player.setCurrentTime(8);
582 window.fetch = jest.fn(async () =>
583 {
584 return new Response(null, {
585 status: 204,
586 headers: {
587 'X-Subtitle-Frame-Status': 'none',
588 'X-Subtitle-Request-Received-At-Ms': '1000',
589 'X-Subtitle-Response-Sent-At-Ms': '1010',
590 },
591 });
592 });
593
594 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
595 sessionId: 'sess-1',
596 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
597 }, {
598 currentFetchEnabled: false,
599 lookaheadSeconds: 0,
600 sendSubtitleLogBatch: (entries) =>
601 {
602 sentBatches.push(entries);
603 return Promise.resolve();
604 },
605 buildFrameRequest: ({ currentTime, streamIndex }) => ({
606 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
607 }),
608 });
609
610 await flushAsyncWork(window, 8);
611 controller.detach();
612 await flushAsyncWork(window, 4);
613
614 const flattened = sentBatches.flat();
615 expect(flattened.length).toBeGreaterThan(0);
616 const requestKinds = new Set(flattened.map((entry) => entry.requestKind).filter(Boolean));
617 expect(requestKinds.has('prefetch')).toBe(true);
618 expect(requestKinds.has('current')).toBe(false);
619
620 window.close();
621 });
622
574 623 test('renders requested and received subtitle markers on the seek bar', async () =>
575 624 {
576 625 const window = createWindow();
@@ -571,6 +571,55 @@ describe('shared image subtitle prefetching', () =>
571 window.close();
571 window.close();
572 });
572 });
573
573
574 test('cache-only current mode avoids direct current subtitle fetch requests', async () =>
575 {
576 const window = createWindow();
577 const helper = loadSharedVideoPlayer(window);
578 const { player, videojs } = buildPlayerHarness(window);
579 const sentBatches = [];
580
581 player.setCurrentTime(8);
582 window.fetch = jest.fn(async () =>
583 {
584 return new Response(null, {
585 status: 204,
586 headers: {
587 'X-Subtitle-Frame-Status': 'none',
588 'X-Subtitle-Request-Received-At-Ms': '1000',
589 'X-Subtitle-Response-Sent-At-Ms': '1010',
590 },
591 });
592 });
593
594 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
595 sessionId: 'sess-1',
596 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
597 }, {
598 currentFetchEnabled: false,
599 lookaheadSeconds: 0,
600 sendSubtitleLogBatch: (entries) =>
601 {
602 sentBatches.push(entries);
603 return Promise.resolve();
604 },
605 buildFrameRequest: ({ currentTime, streamIndex }) => ({
606 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
607 }),
608 });
609
610 await flushAsyncWork(window, 8);
611 controller.detach();
612 await flushAsyncWork(window, 4);
613
614 const flattened = sentBatches.flat();
615 expect(flattened.length).toBeGreaterThan(0);
616 const requestKinds = new Set(flattened.map((entry) => entry.requestKind).filter(Boolean));
617 expect(requestKinds.has('prefetch')).toBe(true);
618 expect(requestKinds.has('current')).toBe(false);
619
620 window.close();
621 });
622
574 test('renders requested and received subtitle markers on the seek bar', async () =>
623 test('renders requested and received subtitle markers on the seek bar', async () =>
575 {
624 {
576 const window = createWindow();
625 const window = createWindow();