Merge fix/subtitle-prune-grace-30s
@@ -13,7 +13,7 @@
13
13
- 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.
14
14
- renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/composited PNG subtitle frames for a requested timestamp; returns null when no subtitle is active.
15
15
- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path; called when video stream sessions end to prevent memory accumulation.
16
- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their "double duration" threshold (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 40s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
16
- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 30 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 70s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
17
17
18
18
## server/thumbnail-cache.js
19
19
- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
@@ -107,7 +107,7 @@
107
107
- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data.
108
108
- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
109
109
- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
110
- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames (events past their double-duration threshold), so subtitle buffers follow the same retention rules as video chunks.
110
- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
111
111
- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
112
112
- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
113
113
- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
@@ -13,7 +13,7 @@13
- 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.
13
- 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.
14
- renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/composited PNG subtitle frames for a requested timestamp; returns null when no subtitle is active.
14
- renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/composited PNG subtitle frames for a requested timestamp; returns null when no subtitle is active.
15
- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path; called when video stream sessions end to prevent memory accumulation.
15
- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path; called when video stream sessions end to prevent memory accumulation.
16
- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their "double duration" threshold (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 40s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
16
- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 30 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 70s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
17
17
18
## server/thumbnail-cache.js
18
## server/thumbnail-cache.js
19
- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
19
- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
@@ -107,7 +107,7 @@107
- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data.
107
- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data.
108
- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
108
- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
109
- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
109
- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
110
- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames (events past their double-duration threshold), so subtitle buffers follow the same retention rules as video chunks.
110
- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
111
- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
111
- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
112
- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
112
- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
113
- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
113
- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
@@ -52,7 +52,7 @@
52
52
53
53
## `test/image-subtitles.test.js`
54
54
- `image subtitle option parsing`
55
- `prune calculates drop threshold as double event duration past event end`
55
- `prune calculates drop threshold as end plus duration plus 30 seconds`
56
56
57
57
---
58
58
@@ -52,7 +52,7 @@52
52
53
## `test/image-subtitles.test.js`53
## `test/image-subtitles.test.js`54
- `image subtitle option parsing`54
- `image subtitle option parsing`55
- `prune calculates drop threshold as double event duration past event end`55
- `prune calculates drop threshold as end plus duration plus 30 seconds`56
56
57
---57
---58
58
@@ -14,6 +14,7 @@ const FRAME_CACHE_TTL_MS = 10 * 60 * 1000;
14
14
const MAX_EVENT_CACHE_ITEMS = 6;
15
15
const MAX_FRAME_CACHE_ITEMS = 400;
16
16
const PGS_TIMEBASE = 90000;
17
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 30;
17
18
18
19
const eventCache = new Map();
19
20
const frameCache = new Map();
@@ -412,7 +413,7 @@ async function renderImageSubtitleFrame (options)
412
413
const cachedFrame = getCachedValue(frameCache, frameKey);
413
414
if (cachedFrame)
414
415
{
415
return cachedFrame;
416
return cachedFrame.frame || cachedFrame;
416
417
}
417
418
418
419
const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);
@@ -439,8 +440,8 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
439
440
440
441
if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;
441
442
442
const duration = endTimeSeconds - startTimeSeconds;
443
const dropThreshold = endTimeSeconds + duration;
443
const duration = Math.max(0, endTimeSeconds - startTimeSeconds);
444
const dropThreshold = endTimeSeconds + duration + IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
444
445
445
446
if (slowestViewerTimeSeconds >= dropThreshold)
446
447
{
@@ -14,6 +14,7 @@ const FRAME_CACHE_TTL_MS = 10 * 60 * 1000;14
const MAX_EVENT_CACHE_ITEMS = 6;14
const MAX_EVENT_CACHE_ITEMS = 6;15
const MAX_FRAME_CACHE_ITEMS = 400;15
const MAX_FRAME_CACHE_ITEMS = 400;16
const PGS_TIMEBASE = 90000;16
const PGS_TIMEBASE = 90000;17
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 30;17
18
18
const eventCache = new Map();19
const eventCache = new Map();19
const frameCache = new Map();20
const frameCache = new Map();@@ -412,7 +413,7 @@ async function renderImageSubtitleFrame (options)412
const cachedFrame = getCachedValue(frameCache, frameKey);413
const cachedFrame = getCachedValue(frameCache, frameKey);413
if (cachedFrame)414
if (cachedFrame)414
{415
{415
return cachedFrame;416
return cachedFrame.frame || cachedFrame;416
}417
}417
418
418
const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);419
const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);@@ -439,8 +440,8 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)439
440
440
if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;441
if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;441
442
442
const duration = endTimeSeconds - startTimeSeconds;443
const duration = Math.max(0, endTimeSeconds - startTimeSeconds);443
const dropThreshold = endTimeSeconds + duration;444
const dropThreshold = endTimeSeconds + duration + IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;444
445
445
if (slowestViewerTimeSeconds >= dropThreshold)446
if (slowestViewerTimeSeconds >= dropThreshold)446
{447
{@@ -30,27 +30,27 @@ describe('image subtitle option parsing', () =>
30
30
expect(parsed.isValid).toBe(false);
31
31
});
32
32
33
test('prune calculates drop threshold as double event duration past event end', () =>
33
test('prune calculates drop threshold as end plus duration plus 30 seconds', () =>
34
34
{
35
// When a subtitle event is 20-30s (10s duration), it should be dropped after 40s
36
// This tests the logic: dropThreshold = endTime + (endTime - startTime)
35
// When a subtitle event is 20-30s (10s duration), it should be dropped after 70s
36
// This tests the logic: dropThreshold = endTime + (endTime - startTime) + 30
37
37
const startTime = 20;
38
38
const endTime = 30;
39
39
const duration = endTime - startTime;
40
const dropThreshold = endTime + duration;
40
const dropThreshold = endTime + duration + 30;
41
41
42
expect(dropThreshold).toBe(40);
42
expect(dropThreshold).toBe(70);
43
43
44
44
// Before threshold: subtitle should be kept
45
const beforeThreshold = 39.999;
45
const beforeThreshold = 69.999;
46
46
expect(beforeThreshold < dropThreshold).toBe(true);
47
47
48
48
// At or after threshold: subtitle should be dropped
49
const atThreshold = 40;
49
const atThreshold = 70;
50
50
expect(atThreshold >= dropThreshold).toBe(true);
51
51
52
52
// Later: definitely should be dropped
53
const afterThreshold = 50;
53
const afterThreshold = 80;
54
54
expect(afterThreshold >= dropThreshold).toBe(true);
55
55
});
56
56
});
@@ -30,27 +30,27 @@ describe('image subtitle option parsing', () =>30
expect(parsed.isValid).toBe(false);30
expect(parsed.isValid).toBe(false);31
});31
});32
32
33
test('prune calculates drop threshold as double event duration past event end', () =>33
test('prune calculates drop threshold as end plus duration plus 30 seconds', () =>34
{34
{35
// When a subtitle event is 20-30s (10s duration), it should be dropped after 40s35
// When a subtitle event is 20-30s (10s duration), it should be dropped after 70s36
// This tests the logic: dropThreshold = endTime + (endTime - startTime)36
// This tests the logic: dropThreshold = endTime + (endTime - startTime) + 3037
const startTime = 20;37
const startTime = 20;38
const endTime = 30;38
const endTime = 30;39
const duration = endTime - startTime;39
const duration = endTime - startTime;40
const dropThreshold = endTime + duration;40
const dropThreshold = endTime + duration + 30;41
41
42
expect(dropThreshold).toBe(40);42
expect(dropThreshold).toBe(70);43
43
44
// Before threshold: subtitle should be kept44
// Before threshold: subtitle should be kept45
const beforeThreshold = 39.999;45
const beforeThreshold = 69.999;46
expect(beforeThreshold < dropThreshold).toBe(true);46
expect(beforeThreshold < dropThreshold).toBe(true);47
47
48
// At or after threshold: subtitle should be dropped48
// At or after threshold: subtitle should be dropped49
const atThreshold = 40;49
const atThreshold = 70;50
expect(atThreshold >= dropThreshold).toBe(true);50
expect(atThreshold >= dropThreshold).toBe(true);51
51
52
// Later: definitely should be dropped52
// Later: definitely should be dropped53
const afterThreshold = 50;53
const afterThreshold = 80;54
expect(afterThreshold >= dropThreshold).toBe(true);54
expect(afterThreshold >= dropThreshold).toBe(true);55
});55
});56
});56
});