Add render-scale and cache env knobs for image subtitles
@@ -10,10 +10,11 @@
10
10
- logError(message, error, details) - Appends error lines to logs.txt, trimming old lines so the file stays under 1 MB; use for route failures and process-level exceptions.
11
11
12
12
## server/image-subtitles.js
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; canvas is scaled down within a 1280x720 ceiling while preserving requested aspect ratio to keep subtitle placement stable in fullscreen.
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; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.5`) while preserving requested aspect ratio.
14
14
- renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/scaled PNG subtitle bitmaps (without full-frame transparent compositing) 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 using path-prefixed cache keys and byte-accounted eviction; called when video stream sessions end to prevent memory accumulation.
16
16
- 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.
17
- IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS / IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES / IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES / IMAGE_SUBTITLE_RENDER_SCALE / IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS - Environment knobs for subtitle cache retention, item caps, byte caps, render resolution, and prune grace window.
17
18
18
19
## server/thumbnail-cache.js
19
20
- 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.
@@ -10,10 +10,11 @@10
- logError(message, error, details) - Appends error lines to logs.txt, trimming old lines so the file stays under 1 MB; use for route failures and process-level exceptions.
10
- logError(message, error, details) - Appends error lines to logs.txt, trimming old lines so the file stays under 1 MB; use for route failures and process-level exceptions.
11
11
12
## server/image-subtitles.js
12
## server/image-subtitles.js
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; canvas is scaled down within a 1280x720 ceiling while preserving requested aspect ratio to keep subtitle placement stable in fullscreen.
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; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.5`) while preserving requested aspect ratio.
14
- renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/scaled PNG subtitle bitmaps (without full-frame transparent compositing) 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/scaled PNG subtitle bitmaps (without full-frame transparent compositing) 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 using path-prefixed cache keys and byte-accounted eviction; 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 using path-prefixed cache keys and byte-accounted eviction; called when video stream sessions end to prevent memory accumulation.
16
- 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.
16
- 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.
17
- IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS / IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES / IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES / IMAGE_SUBTITLE_RENDER_SCALE / IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS - Environment knobs for subtitle cache retention, item caps, byte caps, render resolution, and prune grace window.
17
18
18
## server/thumbnail-cache.js
19
## 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.
20
- 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.
@@ -9,14 +9,15 @@ const { Readable } = require('stream');
9
9
const sharp = require('sharp');
10
10
11
11
const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');
12
const EVENT_CACHE_TTL_MS = 5 * 60 * 1000;
13
const FRAME_CACHE_TTL_MS = 2 * 60 * 1000;
14
const MAX_EVENT_CACHE_ITEMS = 3;
15
const MAX_FRAME_CACHE_ITEMS = 96;
16
const MAX_EVENT_CACHE_BYTES = 96 * 1024 * 1024;
17
const MAX_FRAME_CACHE_BYTES = 48 * 1024 * 1024;
12
const EVENT_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS, 5 * 60 * 1000);
13
const FRAME_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS, 2 * 60 * 1000);
14
const MAX_EVENT_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS, 3);
15
const MAX_FRAME_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, 96);
16
const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 96 * 1024 * 1024);
17
const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
18
const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.5, 0.1, 1);
18
19
const PGS_TIMEBASE = 90000;
19
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 5;
20
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = toPositiveInt(process.env.IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS, 5);
20
21
21
22
const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);
22
23
const frameCache = createCacheState(MAX_FRAME_CACHE_ITEMS, MAX_FRAME_CACHE_BYTES);
@@ -65,6 +66,14 @@ function toPositiveInt (value, fallback)
65
66
return fallback;
66
67
}
67
68
69
function toBoundedNumber (value, fallback, min, max)
70
{
71
const numeric = Number.parseFloat(String(value || ''));
72
if (!Number.isFinite(numeric)) return fallback;
73
if (numeric < min || numeric > max) return fallback;
74
return numeric;
75
}
76
68
77
function hashSubtitleKey (filePath, streamIndex, stat)
69
78
{
70
79
return crypto
@@ -466,7 +475,7 @@ function parseRenderOptions (options)
466
475
const timeSeconds = Number.parseFloat(String(input.timeSeconds ?? ''), 10);
467
476
const requestedWidth = Math.max(1, toPositiveInt(input.canvasWidth ?? '', 1280));
468
477
const requestedHeight = Math.max(1, toPositiveInt(input.canvasHeight ?? '', 720));
469
const scale = Math.min(1, 1280 / requestedWidth, 720 / requestedHeight);
478
const scale = Math.min(1, 1280 / requestedWidth, 720 / requestedHeight) * IMAGE_SUBTITLE_RENDER_SCALE;
470
479
const canvasWidth = Math.max(1, Math.round(requestedWidth * scale));
471
480
const canvasHeight = Math.max(1, Math.round(requestedHeight * scale));
472
481
@@ -9,14 +9,15 @@ const { Readable } = require('stream');9
const sharp = require('sharp');9
const sharp = require('sharp');10
10
11
const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');11
const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');12
const EVENT_CACHE_TTL_MS = 5 * 60 * 1000;12
const EVENT_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS, 5 * 60 * 1000);13
const FRAME_CACHE_TTL_MS = 2 * 60 * 1000;13
const FRAME_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS, 2 * 60 * 1000);14
const MAX_EVENT_CACHE_ITEMS = 3;14
const MAX_EVENT_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS, 3);15
const MAX_FRAME_CACHE_ITEMS = 96;15
const MAX_FRAME_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, 96);16
const MAX_EVENT_CACHE_BYTES = 96 * 1024 * 1024;16
const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 96 * 1024 * 1024);17
const MAX_FRAME_CACHE_BYTES = 48 * 1024 * 1024;17
const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);18
const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.5, 0.1, 1);18
const PGS_TIMEBASE = 90000;19
const PGS_TIMEBASE = 90000;19
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 5;20
const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = toPositiveInt(process.env.IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS, 5);20
21
21
const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);22
const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);22
const frameCache = createCacheState(MAX_FRAME_CACHE_ITEMS, MAX_FRAME_CACHE_BYTES);23
const frameCache = createCacheState(MAX_FRAME_CACHE_ITEMS, MAX_FRAME_CACHE_BYTES);@@ -65,6 +66,14 @@ function toPositiveInt (value, fallback)65
return fallback;66
return fallback;66
}67
}67
68
69
function toBoundedNumber (value, fallback, min, max)70
{71
const numeric = Number.parseFloat(String(value || ''));72
if (!Number.isFinite(numeric)) return fallback;73
if (numeric < min || numeric > max) return fallback;74
return numeric;75
}76
68
function hashSubtitleKey (filePath, streamIndex, stat)77
function hashSubtitleKey (filePath, streamIndex, stat)69
{78
{70
return crypto79
return crypto@@ -466,7 +475,7 @@ function parseRenderOptions (options)466
const timeSeconds = Number.parseFloat(String(input.timeSeconds ?? ''), 10);475
const timeSeconds = Number.parseFloat(String(input.timeSeconds ?? ''), 10);467
const requestedWidth = Math.max(1, toPositiveInt(input.canvasWidth ?? '', 1280));476
const requestedWidth = Math.max(1, toPositiveInt(input.canvasWidth ?? '', 1280));468
const requestedHeight = Math.max(1, toPositiveInt(input.canvasHeight ?? '', 720));477
const requestedHeight = Math.max(1, toPositiveInt(input.canvasHeight ?? '', 720));469
const scale = Math.min(1, 1280 / requestedWidth, 720 / requestedHeight);478
const scale = Math.min(1, 1280 / requestedWidth, 720 / requestedHeight) * IMAGE_SUBTITLE_RENDER_SCALE;470
const canvasWidth = Math.max(1, Math.round(requestedWidth * scale));479
const canvasWidth = Math.max(1, Math.round(requestedWidth * scale));471
const canvasHeight = Math.max(1, Math.round(requestedHeight * scale));480
const canvasHeight = Math.max(1, Math.round(requestedHeight * scale));472
481
@@ -30,7 +30,7 @@ describe('image subtitle option parsing', () =>
30
30
expect(parsed.isValid).toBe(false);
31
31
});
32
32
33
test('caps subtitle render canvas within 1280x720 bounds', () =>
33
test('caps subtitle render canvas and applies render scale', () =>
34
34
{
35
35
const parsed = parseRenderOptions({
36
36
filePath: '/tmp/example.mkv',
@@ -40,13 +40,13 @@ describe('image subtitle option parsing', () =>
40
40
canvasHeight: 2160,
41
41
});
42
42
43
expect(parsed.canvasWidth).toBe(1280);
44
expect(parsed.canvasHeight).toBe(675);
43
expect(parsed.canvasWidth).toBe(640);
44
expect(parsed.canvasHeight).toBe(338);
45
45
expect(parsed.canvasWidth).toBeLessThanOrEqual(1280);
46
46
expect(parsed.canvasHeight).toBeLessThanOrEqual(720);
47
47
});
48
48
49
test('preserves requested aspect ratio when canvas is capped', () =>
49
test('preserves requested aspect ratio when capped and scaled', () =>
50
50
{
51
51
const parsed = parseRenderOptions({
52
52
filePath: '/tmp/example.mkv',
@@ -56,8 +56,8 @@ describe('image subtitle option parsing', () =>
56
56
canvasHeight: 1600,
57
57
});
58
58
59
expect(parsed.canvasWidth).toBe(1280);
60
expect(parsed.canvasHeight).toBe(533);
59
expect(parsed.canvasWidth).toBe(640);
60
expect(parsed.canvasHeight).toBe(267);
61
61
});
62
62
63
63
test('prune calculates drop threshold as end plus duration plus 5 seconds', () =>
@@ -30,7 +30,7 @@ describe('image subtitle option parsing', () =>30
expect(parsed.isValid).toBe(false);30
expect(parsed.isValid).toBe(false);31
});31
});32
32
33
test('caps subtitle render canvas within 1280x720 bounds', () =>33
test('caps subtitle render canvas and applies render scale', () =>34
{34
{35
const parsed = parseRenderOptions({35
const parsed = parseRenderOptions({36
filePath: '/tmp/example.mkv',36
filePath: '/tmp/example.mkv',@@ -40,13 +40,13 @@ describe('image subtitle option parsing', () =>40
canvasHeight: 2160,40
canvasHeight: 2160,41
});41
});42
42
43
expect(parsed.canvasWidth).toBe(1280);43
expect(parsed.canvasWidth).toBe(640);44
expect(parsed.canvasHeight).toBe(675);44
expect(parsed.canvasHeight).toBe(338);45
expect(parsed.canvasWidth).toBeLessThanOrEqual(1280);45
expect(parsed.canvasWidth).toBeLessThanOrEqual(1280);46
expect(parsed.canvasHeight).toBeLessThanOrEqual(720);46
expect(parsed.canvasHeight).toBeLessThanOrEqual(720);47
});47
});48
48
49
test('preserves requested aspect ratio when canvas is capped', () =>49
test('preserves requested aspect ratio when capped and scaled', () =>50
{50
{51
const parsed = parseRenderOptions({51
const parsed = parseRenderOptions({52
filePath: '/tmp/example.mkv',52
filePath: '/tmp/example.mkv',@@ -56,8 +56,8 @@ describe('image subtitle option parsing', () =>56
canvasHeight: 1600,56
canvasHeight: 1600,57
});57
});58
58
59
expect(parsed.canvasWidth).toBe(1280);59
expect(parsed.canvasWidth).toBe(640);60
expect(parsed.canvasHeight).toBe(533);60
expect(parsed.canvasHeight).toBe(267);61
});61
});62
62
63
test('prune calculates drop threshold as end plus duration plus 5 seconds', () =>63
test('prune calculates drop threshold as end plus duration plus 5 seconds', () =>