BlueGit

timfa filemanager

Merge feature/image-subtitle-lookahead-prefetch: add subtitle lookahead prefetch

timfa Tim Falken · pushed by timfa

Authored 2026-05-22 · 5 months ago

Hash
011867c68cde63dd7bdbc1d64cf790949704814c
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++;