BlueGit

timfa filemanager

Fix subtitle prune timing and add 30-second grace window

timfa Tim Falken · pushed by timfa

Authored 2026-05-17 · 6 months ago

Hash
421a6e3225b2a919dd1600c749bea945ac96c69e
Parent
7548d8bc
4 files changed +15 −14
.github/technical-reference.md +2 −2
@@ -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).
.github/tests.md +1 −1
@@ -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
server/image-subtitles.js +4 −3
@@ -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;
14const MAX_EVENT_CACHE_ITEMS = 6;
14const MAX_EVENT_CACHE_ITEMS = 6;
15const MAX_FRAME_CACHE_ITEMS = 400;
15const MAX_FRAME_CACHE_ITEMS = 400;
16const PGS_TIMEBASE = 90000;
16const PGS_TIMEBASE = 90000;
17const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 30;
17
18
18const eventCache = new Map();
19const eventCache = new Map();
19const frameCache = new Map();
20const 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 {
tests/image-subtitles.test.js +8 −8
@@ -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 40s
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)
36 // This tests the logic: dropThreshold = endTime + (endTime - startTime) + 30
37 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 kept
44 // Before threshold: subtitle should be kept
45 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 dropped
48 // At or after threshold: subtitle should be dropped
49 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 dropped
52 // Later: definitely should be dropped
53 const afterThreshold = 50;
53 const afterThreshold = 80;
54 expect(afterThreshold >= dropThreshold).toBe(true);
54 expect(afterThreshold >= dropThreshold).toBe(true);
55 });
55 });
56});
56});