BlueGit

timfa filemanager

Add image subtitle lookahead prefetch

Image subtitle rendering now prefetches upcoming subtitle-frame buckets ahead
of the current playback position to reduce visible lag when a new bitmap subtitle
event starts. The shared player overlay keeps rendering behaviour unchanged for
the current frame, while best-effort background requests warm the server frame
cache for near-future timestamps.

Lookahead defaults to 5 seconds and is bounded to 15 seconds maximum, with
0.5-second prefetch steps to keep memory and request volume predictable. The
setting is wired through both authenticated and share playback paths so they
stay in sync with identical behaviour.

This keeps image subtitle memory usage controlled while improving subtitle
responsiveness at event boundaries.

timfa Tim Falken · pushed by timfa

Authored 2026-05-22 · 5 months ago

Hash
a44abe44cc3cd81494caa00041cc2fef57e9825a
Parent
7eb28159
4 files changed +78 −1
.github/technical-reference.md +1 −1
@@ -160,7 +160,7 @@
160 160 ## public/shared-video-player.js
161 161 - 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.
162 162 - 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.
163 - 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, and disables the track after the first hard failure.
163 - 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, prefetches lookahead subtitle frames (default 5 seconds, bounded to 15 seconds max) to reduce event-boundary lag, and disables the track after the first hard failure.
164 164 - configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
165 165 - ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
166 166
@@ -160,7 +160,7 @@
160## public/shared-video-player.js
160## public/shared-video-player.js
161- 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.
161- 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.
162- 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.
162- 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.
163- 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, and disables the track after the first hard failure.
163- 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, prefetches lookahead subtitle frames (default 5 seconds, bounded to 15 seconds max) to reduce event-boundary lag, and disables the track after the first hard failure.
164- configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
164- configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
165- ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
165- ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
166
166
public/app.js +2 −0
@@ -108,6 +108,7 @@ const FOLDER_GROUP_OPTIONS = [
108 108 ];
109 109 const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
110 110 const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
111 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 5;
111 112 let videoJsLoaderPromise = null;
112 113 let threePreviewModulesPromise = null;
113 114
@@ -401,6 +402,7 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
401 402
402 403 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
403 404 savePrefs: saveUserVideoPrefs,
405 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
404 406 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
405 407 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
406 408 headers: buildAuthHeaders(),
@@ -108,6 +108,7 @@ const FOLDER_GROUP_OPTIONS = [
108];
108];
109const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
109const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
110const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
110const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
111const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 5;
111let videoJsLoaderPromise = null;
112let videoJsLoaderPromise = null;
112let threePreviewModulesPromise = null;
113let threePreviewModulesPromise = null;
113
114
@@ -401,6 +402,7 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
401
402
402 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
403 return shared.bindImageSubtitleOverlay(player, videojs, prefs, session, {
403 savePrefs: saveUserVideoPrefs,
404 savePrefs: saveUserVideoPrefs,
405 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
404 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
406 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
405 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
407 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
406 headers: buildAuthHeaders(),
408 headers: buildAuthHeaders(),
public/share.html +2 −0
@@ -249,6 +249,7 @@
249 249
250 250 const token = location.pathname.split('/').pop();
251 251 const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 5;
252 253 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
253 254 let expiresAt = null;
254 255 let timerInterval = null;
@@ -461,6 +462,7 @@
461 462 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
462 463 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
463 464 savePrefs: saveShareVideoPrefs,
465 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
464 466 buildFrameRequest: ({ currentTime, streamIndex, session }) => ({
465 467 url: `/api/share/video-stream-subtitle-frame/${encodeURIComponent(token)}?streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(session.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(session.videoHeight || ''))}`,
466 468 credentials: 'same-origin',
@@ -249,6 +249,7 @@
249
249
250 const token = location.pathname.split('/').pop();
250 const token = location.pathname.split('/').pop();
251 const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
251 const VIDEO_FORWARD_BUFFER_SECONDS = 60 * 60;
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 5;
252 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
253 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
253 let expiresAt = null;
254 let expiresAt = null;
254 let timerInterval = null;
255 let timerInterval = null;
@@ -461,6 +462,7 @@
461 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
462 shareImageSubtitleController = shared && typeof shared.bindImageSubtitleOverlay === 'function'
462 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
463 ? shared.bindImageSubtitleOverlay(shareVideoPlayer, window.videojs, prefs, data, {
463 savePrefs: saveShareVideoPrefs,
464 savePrefs: saveShareVideoPrefs,
465 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
464 buildFrameRequest: ({ currentTime, streamIndex, session }) => ({
466 buildFrameRequest: ({ currentTime, streamIndex, session }) => ({
465 url: `/api/share/video-stream-subtitle-frame/${encodeURIComponent(token)}?streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(session.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(session.videoHeight || ''))}`,
467 url: `/api/share/video-stream-subtitle-frame/${encodeURIComponent(token)}?streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(session.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(session.videoHeight || ''))}`,
466 credentials: 'same-origin',
468 credentials: 'same-origin',
public/shared-video-player.js +73 −0
@@ -7,6 +7,9 @@
7 7 backgroundOpacity: '0',
8 8 edgeStyle: 'uniform',
9 9 });
10 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_DEFAULT = 5;
11 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_MAX = 15;
12 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 0.5;
10 13
11 14 function normaliseTrackName (name)
12 15 {
@@ -179,6 +182,10 @@
179 182 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => {});
180 183 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
181 184 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => {});
185 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
186 const lookaheadSeconds = Number.isFinite(requestedLookaheadSeconds)
187 ? Math.max(0, Math.min(IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_MAX, requestedLookaheadSeconds))
188 : IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_DEFAULT;
182 189 if (!buildFrameRequest) return null;
183 190
184 191 const trackByStreamIndex = new Map(imageTracks.map((track) => [track.streamIndex, track]));
@@ -193,6 +200,7 @@
193 200 let buttonEl = null;
194 201 let trackDisabled = false;
195 202 let failureNotified = false;
203 let lastPrefetchedBucket = -1;
196 204
197 205 const closeObjectUrl = () =>
198 206 {
@@ -291,6 +299,7 @@
291 299 failureNotified = false;
292 300 selectedStreamIndex = nextStreamIndex;
293 301 activeBucket = -1;
302 lastPrefetchedBucket = -1;
294 303 hideOverlay();
295 304 updateButtonState();
296 305 updateMenuState();
@@ -388,12 +397,76 @@
388 397
389 398 overlayEl.style.display = 'block';
390 399 overlayImgEl.style.display = 'block';
400
401 if (lookaheadSeconds > 0)
402 {
403 const currentBucket = Math.floor(currentTime * 4);
404 if (force || currentBucket !== lastPrefetchedBucket)
405 {
406 lastPrefetchedBucket = currentBucket;
407 void prefetchLookaheadFrames(currentTime, currentBucket, token);
408 }
409 }
391 410 } catch
392 411 {
393 412 if (token === requestToken) disableTrack();
394 413 }
395 414 };
396 415
416 const prefetchLookaheadFrames = async (currentTime, currentBucket, token) =>
417 {
418 if (selectedStreamIndex === null) return;
419 if (trackDisabled) return;
420 if (token !== requestToken) return;
421
422 const startTime = currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
423 const endTime = currentTime + lookaheadSeconds;
424 if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) return;
425
426 const prefetchedBuckets = new Set([currentBucket]);
427 for (let t = startTime; t <= endTime + 1e-6; t += IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS)
428 {
429 if (token !== requestToken) return;
430 if (selectedStreamIndex === null || trackDisabled) return;
431
432 const bucket = Math.floor(t * 4);
433 if (prefetchedBuckets.has(bucket)) continue;
434 prefetchedBuckets.add(bucket);
435
436 const request = buildFrameRequest({
437 streamIndex: selectedStreamIndex,
438 currentTime: t,
439 session,
440 });
441 if (!request || !request.url) return;
442
443 try
444 {
445 const res = await fetch(request.url, {
446 method: request.method || 'GET',
447 headers: request.headers,
448 credentials: request.credentials,
449 });
450
451 if (token !== requestToken) return;
452 if (res.status === 204)
453 {
454 const frameStatus = String(res.headers.get('X-Subtitle-Frame-Status') || '').toLowerCase();
455 if (frameStatus === 'error') return;
456 continue;
457 }
458
459 if (!res.ok) return;
460 // Ensure body is fully consumed so the browser can reuse connections.
461 await res.arrayBuffer();
462 } catch
463 {
464 // Best-effort prefetch; avoid disrupting active subtitle rendering.
465 return;
466 }
467 }
468 };
469
397 470 const dispose = () =>
398 471 {
399 472 requestToken++;
@@ -7,6 +7,9 @@
7 backgroundOpacity: '0',
7 backgroundOpacity: '0',
8 edgeStyle: 'uniform',
8 edgeStyle: 'uniform',
9 });
9 });
10 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_DEFAULT = 5;
11 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_MAX = 15;
12 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 0.5;
10
13
11 function normaliseTrackName (name)
14 function normaliseTrackName (name)
12 {
15 {
@@ -179,6 +182,10 @@
179 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => {});
182 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => {});
180 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
183 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
181 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => {});
184 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => {});
185 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
186 const lookaheadSeconds = Number.isFinite(requestedLookaheadSeconds)
187 ? Math.max(0, Math.min(IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_MAX, requestedLookaheadSeconds))
188 : IMAGE_SUBTITLE_LOOKAHEAD_SECONDS_DEFAULT;
182 if (!buildFrameRequest) return null;
189 if (!buildFrameRequest) return null;
183
190
184 const trackByStreamIndex = new Map(imageTracks.map((track) => [track.streamIndex, track]));
191 const trackByStreamIndex = new Map(imageTracks.map((track) => [track.streamIndex, track]));
@@ -193,6 +200,7 @@
193 let buttonEl = null;
200 let buttonEl = null;
194 let trackDisabled = false;
201 let trackDisabled = false;
195 let failureNotified = false;
202 let failureNotified = false;
203 let lastPrefetchedBucket = -1;
196
204
197 const closeObjectUrl = () =>
205 const closeObjectUrl = () =>
198 {
206 {
@@ -291,6 +299,7 @@
291 failureNotified = false;
299 failureNotified = false;
292 selectedStreamIndex = nextStreamIndex;
300 selectedStreamIndex = nextStreamIndex;
293 activeBucket = -1;
301 activeBucket = -1;
302 lastPrefetchedBucket = -1;
294 hideOverlay();
303 hideOverlay();
295 updateButtonState();
304 updateButtonState();
296 updateMenuState();
305 updateMenuState();
@@ -388,12 +397,76 @@
388
397
389 overlayEl.style.display = 'block';
398 overlayEl.style.display = 'block';
390 overlayImgEl.style.display = 'block';
399 overlayImgEl.style.display = 'block';
400
401 if (lookaheadSeconds > 0)
402 {
403 const currentBucket = Math.floor(currentTime * 4);
404 if (force || currentBucket !== lastPrefetchedBucket)
405 {
406 lastPrefetchedBucket = currentBucket;
407 void prefetchLookaheadFrames(currentTime, currentBucket, token);
408 }
409 }
391 } catch
410 } catch
392 {
411 {
393 if (token === requestToken) disableTrack();
412 if (token === requestToken) disableTrack();
394 }
413 }
395 };
414 };
396
415
416 const prefetchLookaheadFrames = async (currentTime, currentBucket, token) =>
417 {
418 if (selectedStreamIndex === null) return;
419 if (trackDisabled) return;
420 if (token !== requestToken) return;
421
422 const startTime = currentTime + IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS;
423 const endTime = currentTime + lookaheadSeconds;
424 if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) return;
425
426 const prefetchedBuckets = new Set([currentBucket]);
427 for (let t = startTime; t <= endTime + 1e-6; t += IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS)
428 {
429 if (token !== requestToken) return;
430 if (selectedStreamIndex === null || trackDisabled) return;
431
432 const bucket = Math.floor(t * 4);
433 if (prefetchedBuckets.has(bucket)) continue;
434 prefetchedBuckets.add(bucket);
435
436 const request = buildFrameRequest({
437 streamIndex: selectedStreamIndex,
438 currentTime: t,
439 session,
440 });
441 if (!request || !request.url) return;
442
443 try
444 {
445 const res = await fetch(request.url, {
446 method: request.method || 'GET',
447 headers: request.headers,
448 credentials: request.credentials,
449 });
450
451 if (token !== requestToken) return;
452 if (res.status === 204)
453 {
454 const frameStatus = String(res.headers.get('X-Subtitle-Frame-Status') || '').toLowerCase();
455 if (frameStatus === 'error') return;
456 continue;
457 }
458
459 if (!res.ok) return;
460 // Ensure body is fully consumed so the browser can reuse connections.
461 await res.arrayBuffer();
462 } catch
463 {
464 // Best-effort prefetch; avoid disrupting active subtitle rendering.
465 return;
466 }
467 }
468 };
469
397 const dispose = () =>
470 const dispose = () =>
398 {
471 {
399 requestToken++;
472 requestToken++;