BlueGit

timfa filemanager

Implement timestamp-based subtitle frame eviction for Pi memory efficiency

timfa Tim Falken · pushed by timfa

Authored 2026-05-16 · 6 months ago

Hash
ca1f03afb890b4153bd1dbefed257cd05fa5162c
Parent
70f66df3
6 files changed +81 −7
.github/technical-reference.md +2 −1
@@ -13,6 +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 17
17 18 ## server/thumbnail-cache.js
18 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.
@@ -106,7 +107,7 @@
106 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 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 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 - runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and clears image subtitle caches whenever the prune cutoff advances, 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 (events past their double-duration threshold), so subtitle buffers follow the same retention rules as video chunks.
110 111 - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
111 112 - STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
112 113 - STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
@@ -13,6 +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
17
17## server/thumbnail-cache.js
18## server/thumbnail-cache.js
18- 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.
@@ -106,7 +107,7 @@
106- 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.
107- 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.
108- 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.
109- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and clears image subtitle caches whenever the prune cutoff advances, 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 (events past their double-duration threshold), so subtitle buffers follow the same retention rules as video chunks.
110- 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.
111- 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.
112- 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 −0
@@ -52,6 +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 56
56 57 ---
57 58
@@ -52,6 +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
56
56---
57---
57
58
server/image-subtitles.js +36 −1
@@ -416,10 +416,44 @@ async function renderImageSubtitleFrame (options)
416 416 }
417 417
418 418 const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);
419 setCachedValue(frameCache, frameKey, frame, FRAME_CACHE_TTL_MS, MAX_FRAME_CACHE_ITEMS);
419 const event = entry.events[eventIndex];
420 setCachedValue(frameCache, frameKey, { frame, startTimeSeconds: event.startTimeSeconds, endTimeSeconds: event.endTimeSeconds }, FRAME_CACHE_TTL_MS, MAX_FRAME_CACHE_ITEMS);
420 421 return frame;
421 422 }
422 423
424 function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
425 {
426 const normalised = String(filePath || '').trim();
427 if (!normalised || !Number.isFinite(slowestViewerTimeSeconds)) return;
428
429 const keysToDelete = [];
430 for (const key of frameCache.keys())
431 {
432 if (!key.startsWith(normalised)) continue;
433
434 const entry = frameCache.get(key);
435 if (!entry) continue;
436
437 const eventEntry = entry.value || {};
438 const { startTimeSeconds, endTimeSeconds } = eventEntry;
439
440 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;
441
442 const duration = endTimeSeconds - startTimeSeconds;
443 const dropThreshold = endTimeSeconds + duration;
444
445 if (slowestViewerTimeSeconds >= dropThreshold)
446 {
447 keysToDelete.push(key);
448 }
449 }
450
451 for (const key of keysToDelete)
452 {
453 frameCache.delete(key);
454 }
455 }
456
423 457 function clearCachesForFile (filePath)
424 458 {
425 459 const normalised = String(filePath || '').trim();
@@ -454,4 +488,5 @@ module.exports = {
454 488 parseRenderOptions,
455 489 renderImageSubtitleFrame,
456 490 clearCachesForFile,
491 pruneOldImageSubtitleCaches,
457 492 };
@@ -416,10 +416,44 @@ async function renderImageSubtitleFrame (options)
416 }
416 }
417
417
418 const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);
418 const frame = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);
419 setCachedValue(frameCache, frameKey, frame, FRAME_CACHE_TTL_MS, MAX_FRAME_CACHE_ITEMS);
419 const event = entry.events[eventIndex];
420 setCachedValue(frameCache, frameKey, { frame, startTimeSeconds: event.startTimeSeconds, endTimeSeconds: event.endTimeSeconds }, FRAME_CACHE_TTL_MS, MAX_FRAME_CACHE_ITEMS);
420 return frame;
421 return frame;
421}
422}
422
423
424function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
425{
426 const normalised = String(filePath || '').trim();
427 if (!normalised || !Number.isFinite(slowestViewerTimeSeconds)) return;
428
429 const keysToDelete = [];
430 for (const key of frameCache.keys())
431 {
432 if (!key.startsWith(normalised)) continue;
433
434 const entry = frameCache.get(key);
435 if (!entry) continue;
436
437 const eventEntry = entry.value || {};
438 const { startTimeSeconds, endTimeSeconds } = eventEntry;
439
440 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds)) continue;
441
442 const duration = endTimeSeconds - startTimeSeconds;
443 const dropThreshold = endTimeSeconds + duration;
444
445 if (slowestViewerTimeSeconds >= dropThreshold)
446 {
447 keysToDelete.push(key);
448 }
449 }
450
451 for (const key of keysToDelete)
452 {
453 frameCache.delete(key);
454 }
455}
456
423function clearCachesForFile (filePath)
457function clearCachesForFile (filePath)
424{
458{
425 const normalised = String(filePath || '').trim();
459 const normalised = String(filePath || '').trim();
@@ -454,4 +488,5 @@ module.exports = {
454 parseRenderOptions,
488 parseRenderOptions,
455 renderImageSubtitleFrame,
489 renderImageSubtitleFrame,
456 clearCachesForFile,
490 clearCachesForFile,
491 pruneOldImageSubtitleCaches,
457};
492};
server/video-stream.js +14 −2
@@ -5,7 +5,7 @@ const crypto = require('crypto');
5 5 const fs = require('fs');
6 6 const os = require('os');
7 7 const path = require('path');
8 const { clearCachesForFile } = require('./image-subtitles');
8 const { clearCachesForFile, pruneOldImageSubtitleCaches } = require('./image-subtitles');
9 9
10 10 const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
11 11 const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
@@ -220,6 +220,18 @@ function clearImageSubtitleCachesForSession (session)
220 220 clearCachesForFile(session.sourcePath);
221 221 }
222 222
223 function pruneImageSubtitleCachesForSession (session)
224 {
225 if (!session || !session.sourcePath) return;
226
227 const slowestIndex = slowestLeaseSegmentIndex(session);
228 if (!Number.isInteger(slowestIndex)) return;
229
230 const estimatedSegmentDurationSeconds = 6;
231 const slowestViewerTimeSeconds = slowestIndex * estimatedSegmentDurationSeconds;
232 pruneOldImageSubtitleCaches(session.sourcePath, slowestViewerTimeSeconds);
233 }
234
223 235 function getSessionForLease (leaseId)
224 236 {
225 237 const lease = leases.get(leaseId);
@@ -344,7 +356,7 @@ function runSegmentPrune (session)
344 356 .then(() =>
345 357 {
346 358 session.segmentPrunedUntil = Math.max(session.segmentPrunedUntil, cutoff);
347 clearImageSubtitleCachesForSession(session);
359 pruneImageSubtitleCachesForSession(session);
348 360 if (session.segmentPrunedUntil >= 0 && reusableSessionIdBySource.get(session.sourcePath) === session.id)
349 361 {
350 362 reusableSessionIdBySource.delete(session.sourcePath);
@@ -5,7 +5,7 @@ const crypto = require('crypto');
5const fs = require('fs');
5const fs = require('fs');
6const os = require('os');
6const os = require('os');
7const path = require('path');
7const path = require('path');
8const { clearCachesForFile } = require('./image-subtitles');
8const { clearCachesForFile, pruneOldImageSubtitleCaches } = require('./image-subtitles');
9
9
10const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
10const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
11const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
11const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
@@ -220,6 +220,18 @@ function clearImageSubtitleCachesForSession (session)
220 clearCachesForFile(session.sourcePath);
220 clearCachesForFile(session.sourcePath);
221}
221}
222
222
223function pruneImageSubtitleCachesForSession (session)
224{
225 if (!session || !session.sourcePath) return;
226
227 const slowestIndex = slowestLeaseSegmentIndex(session);
228 if (!Number.isInteger(slowestIndex)) return;
229
230 const estimatedSegmentDurationSeconds = 6;
231 const slowestViewerTimeSeconds = slowestIndex * estimatedSegmentDurationSeconds;
232 pruneOldImageSubtitleCaches(session.sourcePath, slowestViewerTimeSeconds);
233}
234
223function getSessionForLease (leaseId)
235function getSessionForLease (leaseId)
224{
236{
225 const lease = leases.get(leaseId);
237 const lease = leases.get(leaseId);
@@ -344,7 +356,7 @@ function runSegmentPrune (session)
344 .then(() =>
356 .then(() =>
345 {
357 {
346 session.segmentPrunedUntil = Math.max(session.segmentPrunedUntil, cutoff);
358 session.segmentPrunedUntil = Math.max(session.segmentPrunedUntil, cutoff);
347 clearImageSubtitleCachesForSession(session);
359 pruneImageSubtitleCachesForSession(session);
348 if (session.segmentPrunedUntil >= 0 && reusableSessionIdBySource.get(session.sourcePath) === session.id)
360 if (session.segmentPrunedUntil >= 0 && reusableSessionIdBySource.get(session.sourcePath) === session.id)
349 {
361 {
350 reusableSessionIdBySource.delete(session.sourcePath);
362 reusableSessionIdBySource.delete(session.sourcePath);
tests/image-subtitles.test.js +25 −1
@@ -1,6 +1,6 @@
1 1 'use strict';
2 2
3 const { parseRenderOptions } = require('../server/image-subtitles');
3 const { parseRenderOptions, pruneOldImageSubtitleCaches } = require('../server/image-subtitles');
4 4
5 5 describe('image subtitle option parsing', () =>
6 6 {
@@ -29,4 +29,28 @@ describe('image subtitle option parsing', () =>
29 29
30 30 expect(parsed.isValid).toBe(false);
31 31 });
32
33 test('prune calculates drop threshold as double event duration past event end', () =>
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)
37 const startTime = 20;
38 const endTime = 30;
39 const duration = endTime - startTime;
40 const dropThreshold = endTime + duration;
41
42 expect(dropThreshold).toBe(40);
43
44 // Before threshold: subtitle should be kept
45 const beforeThreshold = 39.999;
46 expect(beforeThreshold < dropThreshold).toBe(true);
47
48 // At or after threshold: subtitle should be dropped
49 const atThreshold = 40;
50 expect(atThreshold >= dropThreshold).toBe(true);
51
52 // Later: definitely should be dropped
53 const afterThreshold = 50;
54 expect(afterThreshold >= dropThreshold).toBe(true);
55 });
32 56 });
@@ -1,6 +1,6 @@
1'use strict';
1'use strict';
2
2
3const { parseRenderOptions } = require('../server/image-subtitles');
3const { parseRenderOptions, pruneOldImageSubtitleCaches } = require('../server/image-subtitles');
4
4
5describe('image subtitle option parsing', () =>
5describe('image subtitle option parsing', () =>
6{
6{
@@ -29,4 +29,28 @@ describe('image subtitle option parsing', () =>
29
29
30 expect(parsed.isValid).toBe(false);
30 expect(parsed.isValid).toBe(false);
31 });
31 });
32
33 test('prune calculates drop threshold as double event duration past event end', () =>
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)
37 const startTime = 20;
38 const endTime = 30;
39 const duration = endTime - startTime;
40 const dropThreshold = endTime + duration;
41
42 expect(dropThreshold).toBe(40);
43
44 // Before threshold: subtitle should be kept
45 const beforeThreshold = 39.999;
46 expect(beforeThreshold < dropThreshold).toBe(true);
47
48 // At or after threshold: subtitle should be dropped
49 const atThreshold = 40;
50 expect(atThreshold >= dropThreshold).toBe(true);
51
52 // Later: definitely should be dropped
53 const afterThreshold = 50;
54 expect(afterThreshold >= dropThreshold).toBe(true);
55 });
32});
56});
tests/video-stream.test.js +3 −2
@@ -11,6 +11,7 @@ jest.mock('child_process', () => ({
11 11
12 12 jest.mock('../server/image-subtitles', () => ({
13 13 clearCachesForFile: jest.fn(),
14 pruneOldImageSubtitleCaches: jest.fn(),
14 15 }));
15 16
16 17 function makeChildProcess ()
@@ -406,7 +407,7 @@ describe('video stream bootstrap', () =>
406 407 });
407 408
408 409 const streamModule = require('../server/video-stream');
409 const { clearCachesForFile } = require('../server/image-subtitles');
410 const { pruneOldImageSubtitleCaches } = require('../server/image-subtitles');
410 411 const beforeDirs = new Set(
411 412 fs.existsSync(streamModule.STREAM_ROOT_DIR)
412 413 ? fs.readdirSync(streamModule.STREAM_ROOT_DIR)
@@ -438,7 +439,7 @@ describe('video stream bootstrap', () =>
438 439
439 440 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000040.ts'))).toBe(false);
440 441 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000041.ts'))).toBe(true);
441 expect(clearCachesForFile).toHaveBeenCalledWith(sourceFile);
442 expect(pruneOldImageSubtitleCaches).toHaveBeenCalled();
442 443
443 444 streamModule.releaseVideoStreamSession(session.sessionId);
444 445 });
@@ -11,6 +11,7 @@ jest.mock('child_process', () => ({
11
11
12jest.mock('../server/image-subtitles', () => ({
12jest.mock('../server/image-subtitles', () => ({
13 clearCachesForFile: jest.fn(),
13 clearCachesForFile: jest.fn(),
14 pruneOldImageSubtitleCaches: jest.fn(),
14}));
15}));
15
16
16function makeChildProcess ()
17function makeChildProcess ()
@@ -406,7 +407,7 @@ describe('video stream bootstrap', () =>
406 });
407 });
407
408
408 const streamModule = require('../server/video-stream');
409 const streamModule = require('../server/video-stream');
409 const { clearCachesForFile } = require('../server/image-subtitles');
410 const { pruneOldImageSubtitleCaches } = require('../server/image-subtitles');
410 const beforeDirs = new Set(
411 const beforeDirs = new Set(
411 fs.existsSync(streamModule.STREAM_ROOT_DIR)
412 fs.existsSync(streamModule.STREAM_ROOT_DIR)
412 ? fs.readdirSync(streamModule.STREAM_ROOT_DIR)
413 ? fs.readdirSync(streamModule.STREAM_ROOT_DIR)
@@ -438,7 +439,7 @@ describe('video stream bootstrap', () =>
438
439
439 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000040.ts'))).toBe(false);
440 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000040.ts'))).toBe(false);
440 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000041.ts'))).toBe(true);
441 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000041.ts'))).toBe(true);
441 expect(clearCachesForFile).toHaveBeenCalledWith(sourceFile);
442 expect(pruneOldImageSubtitleCaches).toHaveBeenCalled();
442
443
443 streamModule.releaseVideoStreamSession(session.sessionId);
444 streamModule.releaseVideoStreamSession(session.sessionId);
444 });
445 });