BlueGit

timfa filemanager

Prune subtitle caches at slowest-viewer frontier

Server-side image subtitle caches now evict frame and event data as soon as the slowest active viewer has passed each event (with a short grace), instead of keeping old event bytes until cache-cap pressure.\n\nThis reduces long-session memory growth and lowers crash risk when subtitle prefetch advances quickly through many events.

timfa Tim Falken · pushed by timfa

Authored 2026-05-27 · 5 months ago

Hash
f8b442ed31a2649bc4a78ed4d71da3b47b5c517e
Parent
16be31c9
3 files changed +30 −33
.github/technical-reference.md +1 −1
@@ -25,7 +25,7 @@
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 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 - 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 and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly.
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.
30 30 - touchCachedEntry(cache, key, ttlMs) - Refreshes the TTL of an existing cache entry without changing its value; used to keep actively-watched subtitle tracks alive past their initial 5-minute TTL and prevent expensive full re-parses during long playback sessions.
31 31 - getImageSubtitleDebugSnapshot() - Returns event/frame cache totals, timing counters (cache hits/misses, event build timing, frame render/request timing), and per-video cache usage ({event entries/bytes/count, frame entries/bytes}) so admin diagnostics can distinguish cache-thrash or cold-parse stalls from steady-state rendering.
@@ -25,7 +25,7 @@
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; 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.
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 and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly.
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.
30- touchCachedEntry(cache, key, ttlMs) - Refreshes the TTL of an existing cache entry without changing its value; used to keep actively-watched subtitle tracks alive past their initial 5-minute TTL and prevent expensive full re-parses during long playback sessions.
30- touchCachedEntry(cache, key, ttlMs) - Refreshes the TTL of an existing cache entry without changing its value; used to keep actively-watched subtitle tracks alive past their initial 5-minute TTL and prevent expensive full re-parses during long playback sessions.
31- getImageSubtitleDebugSnapshot() - Returns event/frame cache totals, timing counters (cache hits/misses, event build timing, frame render/request timing), and per-video cache usage ({event entries/bytes/count, frame entries/bytes}) so admin diagnostics can distinguish cache-thrash or cold-parse stalls from steady-state rendering.
31- getImageSubtitleDebugSnapshot() - Returns event/frame cache totals, timing counters (cache hits/misses, event build timing, frame render/request timing), and per-video cache usage ({event entries/bytes/count, frame entries/bytes}) so admin diagnostics can distinguish cache-thrash or cold-parse stalls from steady-state rendering.
server/image-subtitles.js +20 −23
@@ -15,7 +15,6 @@ const MAX_EVENT_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_EVENT_
15 15 const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);
16 16 // Removed byte size cap for event cache to prevent thrashing
17 17 const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 50 * 1024 * 1024);
18 const MIN_EVENT_WINDOW_SECONDS = 30; // Always keep at least this much for seeking
19 18 const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
20 19 const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);
21 20 const PGS_TIMEBASE = 90000;
@@ -692,7 +691,9 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
692 691 const prefix = cachePrefixForFile(filePath);
693 692 if (!prefix || !Number.isFinite(slowestViewerTimeSeconds)) return;
694 693
695 // Prune frameCache as before
694 const pruneThresholdSeconds = slowestViewerTimeSeconds - IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
695
696 // Prune frame cache entries that ended before the slowest viewer + grace.
696 697 const keysToDelete = [];
697 698 for (const key of frameCache.map.keys())
698 699 {
@@ -700,11 +701,9 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
700 701 const entry = frameCache.map.get(key);
701 702 if (!entry) continue;
702 703 const eventEntry = entry.value || {};
703 const { startTimeSeconds, endTimeSeconds } = eventEntry;
704 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;
705 const duration = Math.max(0, endTimeSeconds - startTimeSeconds);
706 const dropThreshold = endTimeSeconds + duration + IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
707 if (slowestViewerTimeSeconds >= dropThreshold)
704 const endTimeSeconds = Number(eventEntry.endTimeSeconds);
705 if (!Number.isFinite(endTimeSeconds)) continue;
706 if (endTimeSeconds <= pruneThresholdSeconds)
708 707 {
709 708 keysToDelete.push(key);
710 709 }
@@ -714,44 +713,42 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
714 713 deleteCachedValue(frameCache, key);
715 714 }
716 715
717 // Smart eventCache pruning: only prune if over cap
718 let totalBytes = eventCache.totalBytes;
719 if (totalBytes <= MAX_EVENT_CACHE_BYTES) return;
720 // For each entry, prune events that end before (slowestViewerTimeSeconds - MIN_EVENT_WINDOW_SECONDS)
716 // Prune event cache entries unconditionally as viewer frontier advances.
721 717 for (const [key, entry] of eventCache.map.entries())
722 718 {
723 719 if (!key.startsWith(prefix)) continue;
724 720 const value = entry.value;
725 721 if (!value || !Array.isArray(value.events)) continue;
726 722 let events = value.events;
727 // Find first event that ends after the retention threshold
728 const minKeepTime = Math.max(0, slowestViewerTimeSeconds - MIN_EVENT_WINDOW_SECONDS);
723
724 // Keep only events not yet passed by the slowest viewer (+ grace).
729 725 let pruneIdx = 0;
730 while (pruneIdx < events.length && events[pruneIdx].endTimeSeconds < minKeepTime)
726 while (pruneIdx < events.length)
731 727 {
728 const event = events[pruneIdx];
729 const endTimeSeconds = Number(event && event.endTimeSeconds);
730 if (!Number.isFinite(endTimeSeconds) || endTimeSeconds > pruneThresholdSeconds) break;
732 731 pruneIdx++;
733 732 }
733
734 734 if (pruneIdx > 0)
735 735 {
736 // Remove pruned events and update memory usage
736 // Remove pruned events and update cache accounting.
737 737 const removed = events.splice(0, pruneIdx);
738 738 for (const ev of removed)
739 739 {
740 if (ev && Buffer.isBuffer(ev.imagePng))
741 {
742 entry.sizeBytes -= ev.imagePng.length + 160;
743 eventCache.totalBytes -= ev.imagePng.length + 160;
744 }
740 const estimatedBytes = (ev && Buffer.isBuffer(ev.imagePng) ? ev.imagePng.length : 0) + 160;
741 entry.sizeBytes = Math.max(0, toValidCacheSize(entry.sizeBytes) - estimatedBytes);
742 eventCache.totalBytes = Math.max(0, toValidCacheSize(eventCache.totalBytes) - estimatedBytes);
745 743 }
746 744 }
747 // If all events are pruned, remove the entry
745
746 // If all events are pruned, remove the entry and extracted sup file.
748 747 if (events.length === 0)
749 748 {
750 749 deleteSupFileForKey(key);
751 750 deleteCachedValue(eventCache, key);
752 751 }
753 // Stop pruning if under cap
754 if (eventCache.totalBytes <= MAX_EVENT_CACHE_BYTES) break;
755 752 }
756 753 }
757 754
@@ -15,7 +15,6 @@ const MAX_EVENT_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_EVENT_
15const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);
15const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);
16// Removed byte size cap for event cache to prevent thrashing
16// Removed byte size cap for event cache to prevent thrashing
17const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 50 * 1024 * 1024);
17const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 50 * 1024 * 1024);
18const MIN_EVENT_WINDOW_SECONDS = 30; // Always keep at least this much for seeking
19const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
18const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
20const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);
19const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);
21const PGS_TIMEBASE = 90000;
20const PGS_TIMEBASE = 90000;
@@ -692,7 +691,9 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
692 const prefix = cachePrefixForFile(filePath);
691 const prefix = cachePrefixForFile(filePath);
693 if (!prefix || !Number.isFinite(slowestViewerTimeSeconds)) return;
692 if (!prefix || !Number.isFinite(slowestViewerTimeSeconds)) return;
694
693
695 // Prune frameCache as before
694 const pruneThresholdSeconds = slowestViewerTimeSeconds - IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
695
696 // Prune frame cache entries that ended before the slowest viewer + grace.
696 const keysToDelete = [];
697 const keysToDelete = [];
697 for (const key of frameCache.map.keys())
698 for (const key of frameCache.map.keys())
698 {
699 {
@@ -700,11 +701,9 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
700 const entry = frameCache.map.get(key);
701 const entry = frameCache.map.get(key);
701 if (!entry) continue;
702 if (!entry) continue;
702 const eventEntry = entry.value || {};
703 const eventEntry = entry.value || {};
703 const { startTimeSeconds, endTimeSeconds } = eventEntry;
704 const endTimeSeconds = Number(eventEntry.endTimeSeconds);
704 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;
705 if (!Number.isFinite(endTimeSeconds)) continue;
705 const duration = Math.max(0, endTimeSeconds - startTimeSeconds);
706 if (endTimeSeconds <= pruneThresholdSeconds)
706 const dropThreshold = endTimeSeconds + duration + IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
707 if (slowestViewerTimeSeconds >= dropThreshold)
708 {
707 {
709 keysToDelete.push(key);
708 keysToDelete.push(key);
710 }
709 }
@@ -714,44 +713,42 @@ function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
714 deleteCachedValue(frameCache, key);
713 deleteCachedValue(frameCache, key);
715 }
714 }
716
715
717 // Smart eventCache pruning: only prune if over cap
716 // Prune event cache entries unconditionally as viewer frontier advances.
718 let totalBytes = eventCache.totalBytes;
719 if (totalBytes <= MAX_EVENT_CACHE_BYTES) return;
720 // For each entry, prune events that end before (slowestViewerTimeSeconds - MIN_EVENT_WINDOW_SECONDS)
721 for (const [key, entry] of eventCache.map.entries())
717 for (const [key, entry] of eventCache.map.entries())
722 {
718 {
723 if (!key.startsWith(prefix)) continue;
719 if (!key.startsWith(prefix)) continue;
724 const value = entry.value;
720 const value = entry.value;
725 if (!value || !Array.isArray(value.events)) continue;
721 if (!value || !Array.isArray(value.events)) continue;
726 let events = value.events;
722 let events = value.events;
727 // Find first event that ends after the retention threshold
723
728 const minKeepTime = Math.max(0, slowestViewerTimeSeconds - MIN_EVENT_WINDOW_SECONDS);
724 // Keep only events not yet passed by the slowest viewer (+ grace).
729 let pruneIdx = 0;
725 let pruneIdx = 0;
730 while (pruneIdx < events.length && events[pruneIdx].endTimeSeconds < minKeepTime)
726 while (pruneIdx < events.length)
731 {
727 {
728 const event = events[pruneIdx];
729 const endTimeSeconds = Number(event && event.endTimeSeconds);
730 if (!Number.isFinite(endTimeSeconds) || endTimeSeconds > pruneThresholdSeconds) break;
732 pruneIdx++;
731 pruneIdx++;
733 }
732 }
733
734 if (pruneIdx > 0)
734 if (pruneIdx > 0)
735 {
735 {
736 // Remove pruned events and update memory usage
736 // Remove pruned events and update cache accounting.
737 const removed = events.splice(0, pruneIdx);
737 const removed = events.splice(0, pruneIdx);
738 for (const ev of removed)
738 for (const ev of removed)
739 {
739 {
740 if (ev && Buffer.isBuffer(ev.imagePng))
740 const estimatedBytes = (ev && Buffer.isBuffer(ev.imagePng) ? ev.imagePng.length : 0) + 160;
741 {
741 entry.sizeBytes = Math.max(0, toValidCacheSize(entry.sizeBytes) - estimatedBytes);
742 entry.sizeBytes -= ev.imagePng.length + 160;
742 eventCache.totalBytes = Math.max(0, toValidCacheSize(eventCache.totalBytes) - estimatedBytes);
743 eventCache.totalBytes -= ev.imagePng.length + 160;
744 }
745 }
743 }
746 }
744 }
747 // If all events are pruned, remove the entry
745
746 // If all events are pruned, remove the entry and extracted sup file.
748 if (events.length === 0)
747 if (events.length === 0)
749 {
748 {
750 deleteSupFileForKey(key);
749 deleteSupFileForKey(key);
751 deleteCachedValue(eventCache, key);
750 deleteCachedValue(eventCache, key);
752 }
751 }
753 // Stop pruning if under cap
754 if (eventCache.totalBytes <= MAX_EVENT_CACHE_BYTES) break;
755 }
752 }
756}
753}
757
754
tests/image-subtitles.test.js +9 −9
@@ -63,27 +63,27 @@ describe('image subtitle option parsing', () =>
63 63 expect(parsed.canvasHeight).toBe(400);
64 64 });
65 65
66 test('prune calculates drop threshold as end plus duration plus 5 seconds', () =>
66 test('prune calculates drop threshold as end plus 5-second grace', () =>
67 67 {
68 // When a subtitle event is 20-30s (10s duration), it should be dropped after 45s
69 // This tests the logic: dropThreshold = endTime + (endTime - startTime) + 5
68 // When a subtitle event ends at 30s, it should be dropped once the slowest
69 // viewer passes 35s (event end + grace).
70 70 const startTime = 20;
71 71 const endTime = 30;
72 const duration = endTime - startTime;
73 const dropThreshold = endTime + duration + 5;
72 const dropThreshold = endTime + 5;
74 73
75 expect(dropThreshold).toBe(45);
74 expect(startTime).toBeLessThan(endTime);
75 expect(dropThreshold).toBe(35);
76 76
77 77 // Before threshold: subtitle should be kept
78 const beforeThreshold = 44.999;
78 const beforeThreshold = 34.999;
79 79 expect(beforeThreshold < dropThreshold).toBe(true);
80 80
81 81 // At or after threshold: subtitle should be dropped
82 const atThreshold = 45;
82 const atThreshold = 35;
83 83 expect(atThreshold >= dropThreshold).toBe(true);
84 84
85 85 // Later: definitely should be dropped
86 const afterThreshold = 55;
86 const afterThreshold = 45;
87 87 expect(afterThreshold >= dropThreshold).toBe(true);
88 88 });
89 89 });
@@ -63,27 +63,27 @@ describe('image subtitle option parsing', () =>
63 expect(parsed.canvasHeight).toBe(400);
63 expect(parsed.canvasHeight).toBe(400);
64 });
64 });
65
65
66 test('prune calculates drop threshold as end plus duration plus 5 seconds', () =>
66 test('prune calculates drop threshold as end plus 5-second grace', () =>
67 {
67 {
68 // When a subtitle event is 20-30s (10s duration), it should be dropped after 45s
68 // When a subtitle event ends at 30s, it should be dropped once the slowest
69 // This tests the logic: dropThreshold = endTime + (endTime - startTime) + 5
69 // viewer passes 35s (event end + grace).
70 const startTime = 20;
70 const startTime = 20;
71 const endTime = 30;
71 const endTime = 30;
72 const duration = endTime - startTime;
72 const dropThreshold = endTime + 5;
73 const dropThreshold = endTime + duration + 5;
74
73
75 expect(dropThreshold).toBe(45);
74 expect(startTime).toBeLessThan(endTime);
75 expect(dropThreshold).toBe(35);
76
76
77 // Before threshold: subtitle should be kept
77 // Before threshold: subtitle should be kept
78 const beforeThreshold = 44.999;
78 const beforeThreshold = 34.999;
79 expect(beforeThreshold < dropThreshold).toBe(true);
79 expect(beforeThreshold < dropThreshold).toBe(true);
80
80
81 // At or after threshold: subtitle should be dropped
81 // At or after threshold: subtitle should be dropped
82 const atThreshold = 45;
82 const atThreshold = 35;
83 expect(atThreshold >= dropThreshold).toBe(true);
83 expect(atThreshold >= dropThreshold).toBe(true);
84
84
85 // Later: definitely should be dropped
85 // Later: definitely should be dropped
86 const afterThreshold = 55;
86 const afterThreshold = 45;
87 expect(afterThreshold >= dropThreshold).toBe(true);
87 expect(afterThreshold >= dropThreshold).toBe(true);
88 });
88 });
89});
89});