Merge fix/nonblocking-subtitle-cache-build
@@ -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
});