BlueGit

timfa filemanager

Avoid subtitle frame stalls on cold cache

Fix a playback regression where image subtitle requests could appear to stop entirely after stream cache teardown. Subtitle event cache builds now run in the background, while frame requests return quickly with no-frame responses until parsing completes, allowing the player to keep polling and begin showing captions as soon as data is ready.\n\nAlso improve seek marker placement by anchoring the subtitle triangles to the seek track element so they line up with the actual bar. Add regression coverage to ensure renderImageSubtitleFrame returns promptly while cache build is still pending.

timfa Tim Falken · pushed by timfa

Authored 2026-05-25 · 5 months ago

Hash
dd3210176aa9ea2d32b77e2f02541b54720404f2
Parent
ae9cc981
4 files changed +81 −23
.github/technical-reference.md +1 −1
@@ -23,7 +23,7 @@
23 23
24 24 ## server/image-subtitles.js
25 25 - parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
26 - renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; request/build/render timing counters are tracked for debug diagnostics.
26 - renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
27 27 - clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
28 28 - pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 5 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 45s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
29 29 - purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
@@ -23,7 +23,7 @@
23
23
24## server/image-subtitles.js
24## server/image-subtitles.js
25- parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
25- parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
26- renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; request/build/render timing counters are tracked for debug diagnostics.
26- renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
27- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
27- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
28- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 5 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 45s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
28- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 5 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 45s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
29- purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
29- purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
public/shared-video-player.js +4 −3
@@ -471,9 +471,9 @@
471 471 const playerEl = player.el && player.el();
472 472 if (!playerEl) return;
473 473
474 const seekBarEl = playerEl.querySelector('.vjs-progress-control')
474 const seekBarEl = playerEl.querySelector('.vjs-seek-bar')
475 475 || playerEl.querySelector('.vjs-progress-holder')
476 || playerEl.querySelector('.vjs-seek-bar');
476 || playerEl.querySelector('.vjs-progress-control');
477 477 if (!seekBarEl) return;
478 478
479 479 const computedPosition = window.getComputedStyle(seekBarEl).position;
@@ -484,8 +484,9 @@
484 484 seekMarkerContainerEl.style.position = 'absolute';
485 485 seekMarkerContainerEl.style.left = '0';
486 486 seekMarkerContainerEl.style.right = '0';
487 seekMarkerContainerEl.style.top = '-9px';
487 seekMarkerContainerEl.style.top = '50%';
488 488 seekMarkerContainerEl.style.height = '10px';
489 seekMarkerContainerEl.style.transform = 'translateY(-50%)';
489 490 seekMarkerContainerEl.style.pointerEvents = 'none';
490 491 seekMarkerContainerEl.style.zIndex = '5';
491 492
@@ -471,9 +471,9 @@
471 const playerEl = player.el && player.el();
471 const playerEl = player.el && player.el();
472 if (!playerEl) return;
472 if (!playerEl) return;
473
473
474 const seekBarEl = playerEl.querySelector('.vjs-progress-control')
474 const seekBarEl = playerEl.querySelector('.vjs-seek-bar')
475 || playerEl.querySelector('.vjs-progress-holder')
475 || playerEl.querySelector('.vjs-progress-holder')
476 || playerEl.querySelector('.vjs-seek-bar');
476 || playerEl.querySelector('.vjs-progress-control');
477 if (!seekBarEl) return;
477 if (!seekBarEl) return;
478
478
479 const computedPosition = window.getComputedStyle(seekBarEl).position;
479 const computedPosition = window.getComputedStyle(seekBarEl).position;
@@ -484,8 +484,9 @@
484 seekMarkerContainerEl.style.position = 'absolute';
484 seekMarkerContainerEl.style.position = 'absolute';
485 seekMarkerContainerEl.style.left = '0';
485 seekMarkerContainerEl.style.left = '0';
486 seekMarkerContainerEl.style.right = '0';
486 seekMarkerContainerEl.style.right = '0';
487 seekMarkerContainerEl.style.top = '-9px';
487 seekMarkerContainerEl.style.top = '50%';
488 seekMarkerContainerEl.style.height = '10px';
488 seekMarkerContainerEl.style.height = '10px';
489 seekMarkerContainerEl.style.transform = 'translateY(-50%)';
489 seekMarkerContainerEl.style.pointerEvents = 'none';
490 seekMarkerContainerEl.style.pointerEvents = 'none';
490 seekMarkerContainerEl.style.zIndex = '5';
491 seekMarkerContainerEl.style.zIndex = '5';
491
492
server/image-subtitles.js +34 −19
@@ -441,8 +441,32 @@ async function buildEventCacheEntry (filePath, streamIndex, identityKey)
441 441 };
442 442 }
443 443
444 async function getEventCacheEntry (filePath, streamIndex)
444 function beginEventCacheBuild (normalisedPath, streamIndex, identityKey)
445 445 {
446 subtitleDebugStats.eventCacheBuilds += 1;
447 const buildStartedAt = Date.now();
448 const pending = buildEventCacheEntry(normalisedPath, streamIndex, identityKey);
449 setCachedValue(eventCache, identityKey, pending, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
450
451 pending
452 .then((resolved) =>
453 {
454 recordDuration(subtitleDebugStats.eventBuildDurationMs, buildStartedAt);
455 setCachedValue(eventCache, identityKey, resolved, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
456 return resolved;
457 })
458 .catch(() =>
459 {
460 subtitleDebugStats.eventCacheBuildErrors += 1;
461 deleteCachedValue(eventCache, identityKey);
462 });
463
464 return pending;
465 }
466
467 async function getEventCacheEntry (filePath, streamIndex, options = {})
468 {
469 const waitForBuild = options.waitForBuild !== false;
446 470 const normalisedPath = normaliseFilePath(filePath);
447 471 const stat = await fs.promises.stat(normalisedPath);
448 472 const identityKey = eventIdentityKey(normalisedPath, streamIndex, stat);
@@ -453,27 +477,18 @@ async function getEventCacheEntry (filePath, streamIndex)
453 477 if (typeof cached.then === 'function') subtitleDebugStats.eventCachePendingHits += 1;
454 478 else subtitleDebugStats.eventCacheHits += 1;
455 479 touchCachedEntry(eventCache, identityKey, EVENT_CACHE_TTL_MS);
480
481 if (typeof cached.then === 'function')
482 {
483 return waitForBuild ? cached : null;
484 }
485
456 486 return cached;
457 487 }
458 488
459 489 subtitleDebugStats.eventCacheMisses += 1;
460 subtitleDebugStats.eventCacheBuilds += 1;
461 const buildStartedAt = Date.now();
462 const pending = buildEventCacheEntry(normalisedPath, streamIndex, identityKey);
463 setCachedValue(eventCache, identityKey, pending, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
464
465 try
466 {
467 const resolved = await pending;
468 recordDuration(subtitleDebugStats.eventBuildDurationMs, buildStartedAt);
469 setCachedValue(eventCache, identityKey, resolved, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
470 return resolved;
471 } catch (error)
472 {
473 subtitleDebugStats.eventCacheBuildErrors += 1;
474 deleteCachedValue(eventCache, identityKey);
475 throw error;
476 }
490 const pending = beginEventCacheBuild(normalisedPath, streamIndex, identityKey);
491 return waitForBuild ? pending : null;
477 492 }
478 493
479 494 function findActiveEventIndex (events, timeSeconds)
@@ -593,7 +608,7 @@ async function renderImageSubtitleFrame (options)
593 608 return null;
594 609 }
595 610
596 const entry = await getEventCacheEntry(filePath, streamIndex);
611 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
597 612 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
598 613 {
599 614 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
@@ -441,8 +441,32 @@ async function buildEventCacheEntry (filePath, streamIndex, identityKey)
441 };
441 };
442}
442}
443
443
444async function getEventCacheEntry (filePath, streamIndex)
444function beginEventCacheBuild (normalisedPath, streamIndex, identityKey)
445{
445{
446 subtitleDebugStats.eventCacheBuilds += 1;
447 const buildStartedAt = Date.now();
448 const pending = buildEventCacheEntry(normalisedPath, streamIndex, identityKey);
449 setCachedValue(eventCache, identityKey, pending, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
450
451 pending
452 .then((resolved) =>
453 {
454 recordDuration(subtitleDebugStats.eventBuildDurationMs, buildStartedAt);
455 setCachedValue(eventCache, identityKey, resolved, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
456 return resolved;
457 })
458 .catch(() =>
459 {
460 subtitleDebugStats.eventCacheBuildErrors += 1;
461 deleteCachedValue(eventCache, identityKey);
462 });
463
464 return pending;
465}
466
467async function getEventCacheEntry (filePath, streamIndex, options = {})
468{
469 const waitForBuild = options.waitForBuild !== false;
446 const normalisedPath = normaliseFilePath(filePath);
470 const normalisedPath = normaliseFilePath(filePath);
447 const stat = await fs.promises.stat(normalisedPath);
471 const stat = await fs.promises.stat(normalisedPath);
448 const identityKey = eventIdentityKey(normalisedPath, streamIndex, stat);
472 const identityKey = eventIdentityKey(normalisedPath, streamIndex, stat);
@@ -453,27 +477,18 @@ async function getEventCacheEntry (filePath, streamIndex)
453 if (typeof cached.then === 'function') subtitleDebugStats.eventCachePendingHits += 1;
477 if (typeof cached.then === 'function') subtitleDebugStats.eventCachePendingHits += 1;
454 else subtitleDebugStats.eventCacheHits += 1;
478 else subtitleDebugStats.eventCacheHits += 1;
455 touchCachedEntry(eventCache, identityKey, EVENT_CACHE_TTL_MS);
479 touchCachedEntry(eventCache, identityKey, EVENT_CACHE_TTL_MS);
480
481 if (typeof cached.then === 'function')
482 {
483 return waitForBuild ? cached : null;
484 }
485
456 return cached;
486 return cached;
457 }
487 }
458
488
459 subtitleDebugStats.eventCacheMisses += 1;
489 subtitleDebugStats.eventCacheMisses += 1;
460 subtitleDebugStats.eventCacheBuilds += 1;
490 const pending = beginEventCacheBuild(normalisedPath, streamIndex, identityKey);
461 const buildStartedAt = Date.now();
491 return waitForBuild ? pending : null;
462 const pending = buildEventCacheEntry(normalisedPath, streamIndex, identityKey);
463 setCachedValue(eventCache, identityKey, pending, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
464
465 try
466 {
467 const resolved = await pending;
468 recordDuration(subtitleDebugStats.eventBuildDurationMs, buildStartedAt);
469 setCachedValue(eventCache, identityKey, resolved, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
470 return resolved;
471 } catch (error)
472 {
473 subtitleDebugStats.eventCacheBuildErrors += 1;
474 deleteCachedValue(eventCache, identityKey);
475 throw error;
476 }
477}
492}
478
493
479function findActiveEventIndex (events, timeSeconds)
494function findActiveEventIndex (events, timeSeconds)
@@ -593,7 +608,7 @@ async function renderImageSubtitleFrame (options)
593 return null;
608 return null;
594 }
609 }
595
610
596 const entry = await getEventCacheEntry(filePath, streamIndex);
611 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
597 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
612 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
598 {
613 {
599 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
614 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
tests/image-subtitles.test.js +42 −0
@@ -126,4 +126,46 @@ describe('subtitle cache directory management', () =>
126 126 {
127 127 expect(() => purgeSubtitleCacheDir()).not.toThrow();
128 128 });
129
130 test('renderImageSubtitleFrame returns quickly while event cache build is pending', async () =>
131 {
132 jest.resetModules();
133
134 jest.doMock('child_process', () => ({
135 spawn: jest.fn(() =>
136 {
137 const { EventEmitter } = require('events');
138 const child = new EventEmitter();
139 child.stderr = new EventEmitter();
140 child.stdout = new EventEmitter();
141 child.kill = jest.fn();
142 return child;
143 }),
144 }));
145
146 let isolated;
147 jest.isolateModules(() =>
148 {
149 isolated = require('../server/image-subtitles');
150 });
151
152 const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'filemanager-image-subtitle-pending-'));
153 const filePath = path.join(tmpRoot, 'video.mkv');
154 fs.writeFileSync(filePath, 'placeholder');
155
156 const fastResult = await Promise.race([
157 isolated.renderImageSubtitleFrame({
158 filePath,
159 streamIndex: 0,
160 timeSeconds: 1,
161 canvasWidth: 1280,
162 canvasHeight: 720,
163 }),
164 new Promise((resolve) => setTimeout(() => resolve('__timeout__'), 120)),
165 ]);
166
167 expect(fastResult).toBeNull();
168
169 jest.dontMock('child_process');
170 });
129 171 });
@@ -126,4 +126,46 @@ describe('subtitle cache directory management', () =>
126 {
126 {
127 expect(() => purgeSubtitleCacheDir()).not.toThrow();
127 expect(() => purgeSubtitleCacheDir()).not.toThrow();
128 });
128 });
129
130 test('renderImageSubtitleFrame returns quickly while event cache build is pending', async () =>
131 {
132 jest.resetModules();
133
134 jest.doMock('child_process', () => ({
135 spawn: jest.fn(() =>
136 {
137 const { EventEmitter } = require('events');
138 const child = new EventEmitter();
139 child.stderr = new EventEmitter();
140 child.stdout = new EventEmitter();
141 child.kill = jest.fn();
142 return child;
143 }),
144 }));
145
146 let isolated;
147 jest.isolateModules(() =>
148 {
149 isolated = require('../server/image-subtitles');
150 });
151
152 const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'filemanager-image-subtitle-pending-'));
153 const filePath = path.join(tmpRoot, 'video.mkv');
154 fs.writeFileSync(filePath, 'placeholder');
155
156 const fastResult = await Promise.race([
157 isolated.renderImageSubtitleFrame({
158 filePath,
159 streamIndex: 0,
160 timeSeconds: 1,
161 canvasWidth: 1280,
162 canvasHeight: 720,
163 }),
164 new Promise((resolve) => setTimeout(() => resolve('__timeout__'), 120)),
165 ]);
166
167 expect(fastResult).toBeNull();
168
169 jest.dontMock('child_process');
170 });
129});
171});