BlueGit

timfa filemanager

er

timfa Tim Falken · pushed by timfa

Authored 2026-05-26 · 5 months ago

Hash
b92cf2b3bb32e44c9230f292f247bd95131003bb
Parent
508d3ef0
3 files changed +83 −2
.github/technical-reference.md +1 −1
@@ -183,7 +183,7 @@
183 183 - 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.
184 184 - 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.
185 185 - 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.
186 - 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 and returns a controller with stop()/done()/getStatus()/subscribe().
186 - 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 when timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
187 187 - 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 and removes itself on detach.
188 188 - 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.
189 189 - clearVideoStreamClientCache(playlistUrl) - Best-effort cache cleanup helper that removes cached HLS entries for one stream session when preview playback is closed.
@@ -183,7 +183,7 @@
183- 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.
183- 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.
184- 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.
184- 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.
185- 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.
185- 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.
186- 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 and returns a controller with stop()/done()/getStatus()/subscribe().
186- 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 when timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
187- 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 and removes itself on detach.
187- 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 and removes itself on detach.
188- 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.
188- 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.
189- clearVideoStreamClientCache(playlistUrl) - Best-effort cache cleanup helper that removes cached HLS entries for one stream session when preview playback is closed.
189- clearVideoStreamClientCache(playlistUrl) - Best-effort cache cleanup helper that removes cached HLS entries for one stream session when preview playback is closed.
public/shared-video-player.js +24 −1
@@ -1710,6 +1710,28 @@
1710 1710 };
1711 1711 }
1712 1712
1713 function inferSegmentEndSecondsFromAssetUrl (assetUrl)
1714 {
1715 const value = String(assetUrl || '');
1716 if (!value) return null;
1717
1718 let pathname = value;
1719 try
1720 {
1721 pathname = new URL(value, window.location.href).pathname || value;
1722 } catch
1723 {
1724 // Ignore URL parsing failures and fall back to raw value matching.
1725 }
1726
1727 const match = pathname.match(/_segment_(\d+)\.ts(?:$|\?)/i);
1728 if (!match) return null;
1729
1730 const segmentIndex = Number.parseInt(match[1], 10);
1731 if (!Number.isInteger(segmentIndex) || segmentIndex < 0) return null;
1732 return (segmentIndex + 1) * VIDEO_STREAM_SEGMENT_DURATION_FALLBACK_SECONDS;
1733 }
1734
1713 1735 function bindStreamAheadSeekMarker (player, streamAheadPrefetch, opts = {})
1714 1736 {
1715 1737 if (!player || typeof player.on !== 'function' || !streamAheadPrefetch) return null;
@@ -1980,7 +2002,8 @@
1980 2002 if (!fetched) continue;
1981 2003
1982 2004 fetchedAssetUrls.add(assetUrl);
1983 const segmentEndSeconds = segmentEndSecondsByAssetUrl.get(assetUrl);
2005 const segmentEndSeconds = segmentEndSecondsByAssetUrl.get(assetUrl)
2006 ?? inferSegmentEndSecondsFromAssetUrl(assetUrl);
1984 2007 if (Number.isFinite(segmentEndSeconds))
1985 2008 {
1986 2009 if (!Number.isFinite(cachedThroughSeconds) || segmentEndSeconds > cachedThroughSeconds)
@@ -1710,6 +1710,28 @@
1710 };
1710 };
1711 }
1711 }
1712
1712
1713 function inferSegmentEndSecondsFromAssetUrl (assetUrl)
1714 {
1715 const value = String(assetUrl || '');
1716 if (!value) return null;
1717
1718 let pathname = value;
1719 try
1720 {
1721 pathname = new URL(value, window.location.href).pathname || value;
1722 } catch
1723 {
1724 // Ignore URL parsing failures and fall back to raw value matching.
1725 }
1726
1727 const match = pathname.match(/_segment_(\d+)\.ts(?:$|\?)/i);
1728 if (!match) return null;
1729
1730 const segmentIndex = Number.parseInt(match[1], 10);
1731 if (!Number.isInteger(segmentIndex) || segmentIndex < 0) return null;
1732 return (segmentIndex + 1) * VIDEO_STREAM_SEGMENT_DURATION_FALLBACK_SECONDS;
1733 }
1734
1713 function bindStreamAheadSeekMarker (player, streamAheadPrefetch, opts = {})
1735 function bindStreamAheadSeekMarker (player, streamAheadPrefetch, opts = {})
1714 {
1736 {
1715 if (!player || typeof player.on !== 'function' || !streamAheadPrefetch) return null;
1737 if (!player || typeof player.on !== 'function' || !streamAheadPrefetch) return null;
@@ -1980,7 +2002,8 @@
1980 if (!fetched) continue;
2002 if (!fetched) continue;
1981
2003
1982 fetchedAssetUrls.add(assetUrl);
2004 fetchedAssetUrls.add(assetUrl);
1983 const segmentEndSeconds = segmentEndSecondsByAssetUrl.get(assetUrl);
2005 const segmentEndSeconds = segmentEndSecondsByAssetUrl.get(assetUrl)
2006 ?? inferSegmentEndSecondsFromAssetUrl(assetUrl);
1984 if (Number.isFinite(segmentEndSeconds))
2007 if (Number.isFinite(segmentEndSeconds))
1985 {
2008 {
1986 if (!Number.isFinite(cachedThroughSeconds) || segmentEndSeconds > cachedThroughSeconds)
2009 if (!Number.isFinite(cachedThroughSeconds) || segmentEndSeconds > cachedThroughSeconds)
tests/shared-video-player.test.js +58 −0
@@ -1164,6 +1164,64 @@ describe('shared image subtitle prefetching', () =>
1164 1164 window.close();
1165 1165 });
1166 1166
1167 test('stream-ahead prefetch infers cached-through progress from segment filenames', async () =>
1168 {
1169 const window = createWindow();
1170 const helper = loadSharedVideoPlayer(window);
1171 const progressSamples = [];
1172
1173 window.fetch = jest.fn(async (input) =>
1174 {
1175 const url = String(input && input.url ? input.url : input);
1176
1177 if (url === 'http://localhost/master.m3u8')
1178 {
1179 return new Response('#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=100000\nstream_0.m3u8\n#EXT-X-ENDLIST\n', {
1180 status: 200,
1181 headers: { 'Content-Type': 'application/vnd.apple.mpegurl' },
1182 });
1183 }
1184
1185 if (url === 'http://localhost/stream_0.m3u8')
1186 {
1187 return new Response('#EXTM3U\nstream_0_segment_000000.ts\nstream_0_segment_000001.ts\n#EXT-X-ENDLIST\n', {
1188 status: 200,
1189 headers: { 'Content-Type': 'application/vnd.apple.mpegurl' },
1190 });
1191 }
1192
1193 if (url === 'http://localhost/stream_0_segment_000000.ts' || url === 'http://localhost/stream_0_segment_000001.ts')
1194 {
1195 return new Response(new Uint8Array([1, 2, 3, 4]), {
1196 status: 200,
1197 headers: { 'Content-Type': 'video/mp2t' },
1198 });
1199 }
1200
1201 return new Response(null, { status: 404 });
1202 });
1203
1204 const controller = helper.bindStreamAheadPrefetch({
1205 playlistUrl: 'http://localhost/master.m3u8',
1206 pollIntervalMs: 0,
1207 credentials: 'same-origin',
1208 });
1209
1210 expect(controller).toBeTruthy();
1211 const unsubscribe = controller.subscribe((status) =>
1212 {
1213 progressSamples.push(status && status.cachedThroughSeconds);
1214 });
1215
1216 await controller.done();
1217 unsubscribe();
1218
1219 expect(progressSamples.some((value) => Number.isFinite(value) && value >= 8)).toBe(true);
1220
1221 controller.stop();
1222 window.close();
1223 });
1224
1167 1225 test('clears cached stream assets for a finished playlist session', async () =>
1168 1226 {
1169 1227 const window = createWindow();
@@ -1164,6 +1164,64 @@ describe('shared image subtitle prefetching', () =>
1164 window.close();
1164 window.close();
1165 });
1165 });
1166
1166
1167 test('stream-ahead prefetch infers cached-through progress from segment filenames', async () =>
1168 {
1169 const window = createWindow();
1170 const helper = loadSharedVideoPlayer(window);
1171 const progressSamples = [];
1172
1173 window.fetch = jest.fn(async (input) =>
1174 {
1175 const url = String(input && input.url ? input.url : input);
1176
1177 if (url === 'http://localhost/master.m3u8')
1178 {
1179 return new Response('#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=100000\nstream_0.m3u8\n#EXT-X-ENDLIST\n', {
1180 status: 200,
1181 headers: { 'Content-Type': 'application/vnd.apple.mpegurl' },
1182 });
1183 }
1184
1185 if (url === 'http://localhost/stream_0.m3u8')
1186 {
1187 return new Response('#EXTM3U\nstream_0_segment_000000.ts\nstream_0_segment_000001.ts\n#EXT-X-ENDLIST\n', {
1188 status: 200,
1189 headers: { 'Content-Type': 'application/vnd.apple.mpegurl' },
1190 });
1191 }
1192
1193 if (url === 'http://localhost/stream_0_segment_000000.ts' || url === 'http://localhost/stream_0_segment_000001.ts')
1194 {
1195 return new Response(new Uint8Array([1, 2, 3, 4]), {
1196 status: 200,
1197 headers: { 'Content-Type': 'video/mp2t' },
1198 });
1199 }
1200
1201 return new Response(null, { status: 404 });
1202 });
1203
1204 const controller = helper.bindStreamAheadPrefetch({
1205 playlistUrl: 'http://localhost/master.m3u8',
1206 pollIntervalMs: 0,
1207 credentials: 'same-origin',
1208 });
1209
1210 expect(controller).toBeTruthy();
1211 const unsubscribe = controller.subscribe((status) =>
1212 {
1213 progressSamples.push(status && status.cachedThroughSeconds);
1214 });
1215
1216 await controller.done();
1217 unsubscribe();
1218
1219 expect(progressSamples.some((value) => Number.isFinite(value) && value >= 8)).toBe(true);
1220
1221 controller.stop();
1222 window.close();
1223 });
1224
1167 test('clears cached stream assets for a finished playlist session', async () =>
1225 test('clears cached stream assets for a finished playlist session', async () =>
1168 {
1226 {
1169 const window = createWindow();
1227 const window = createWindow();