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.
@@ -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.
@@ -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
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
pending452
.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
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
try466
{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
479
function findActiveEventIndex (events, timeSeconds)494
function 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);@@ -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
});