Merge fix/aggressive-subtitle-cache-prune
@@ -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.
@@ -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_15
const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);15
const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);16
// Removed byte size cap for event cache to prevent thrashing16
// Removed byte size cap for event cache to prevent thrashing17
const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 50 * 1024 * 1024);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 seeking19
const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);18
const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);20
const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);19
const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);21
const PGS_TIMEBASE = 90000;20
const 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 before694
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 cap716
// 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 threshold723
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 usage736
// 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 entry745
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 cap754
if (eventCache.totalBytes <= MAX_EVENT_CACHE_BYTES) break;755
}752
}756
}753
}757
754
@@ -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 45s68
// When a subtitle event ends at 30s, it should be dropped once the slowest69
// This tests the logic: dropThreshold = endTime + (endTime - startTime) + 569
// 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 kept77
// Before threshold: subtitle should be kept78
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 dropped81
// At or after threshold: subtitle should be dropped82
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 dropped85
// Later: definitely should be dropped86
const afterThreshold = 55;86
const afterThreshold = 45;87
expect(afterThreshold >= dropThreshold).toBe(true);87
expect(afterThreshold >= dropThreshold).toBe(true);88
});88
});89
});89
});