BlueGit

timfa filemanager

Merge fix/nonblocking-subtitle-cache-build

timfa Tim Falken · pushed by timfa

Authored 2026-05-25 · 5 months ago

Hash
a38174054b92315f7c3282462b2a0f4cb7b68275
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});