Implement timestamp-based subtitle frame eviction for Pi memory efficiency
@@ -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).
@@ -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
@@ -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
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
function clearCachesForFile (filePath)457
function 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
};@@ -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');5
const fs = require('fs');5
const fs = require('fs');6
const os = require('os');6
const os = require('os');7
const path = require('path');7
const path = require('path');8
const { clearCachesForFile } = require('./image-subtitles');8
const { clearCachesForFile, pruneOldImageSubtitleCaches } = require('./image-subtitles');9
9
10
const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');10
const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');11
const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;11
const 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
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
function getSessionForLease (leaseId)235
function 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);@@ -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
3
const { parseRenderOptions } = require('../server/image-subtitles');3
const { parseRenderOptions, pruneOldImageSubtitleCaches } = require('../server/image-subtitles');4
4
5
describe('image subtitle option parsing', () =>5
describe('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 40s36
// 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 kept45
const beforeThreshold = 39.999;46
expect(beforeThreshold < dropThreshold).toBe(true);47
48
// At or after threshold: subtitle should be dropped49
const atThreshold = 40;50
expect(atThreshold >= dropThreshold).toBe(true);51
52
// Later: definitely should be dropped53
const afterThreshold = 50;54
expect(afterThreshold >= dropThreshold).toBe(true);55
});32
});56
});@@ -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
12
jest.mock('../server/image-subtitles', () => ({12
jest.mock('../server/image-subtitles', () => ({13
clearCachesForFile: jest.fn(),13
clearCachesForFile: jest.fn(),14
pruneOldImageSubtitleCaches: jest.fn(),14
}));15
}));15
16
16
function makeChildProcess ()17
function 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
});