BlueGit

timfa filemanager

Merge fix/image-subtitle-render-scale-knobs

timfa Tim Falken · pushed by timfa

Authored 2026-05-20 · 6 months ago

Hash
175aaeb979ffb4582ce48e0c9762beb2925ddba9
3 files changed +25 −15
.github/technical-reference.md +2 −1
@@ -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.
server/image-subtitles.js +17 −8
@@ -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');
9const sharp = require('sharp');
9const sharp = require('sharp');
10
10
11const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');
11const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');
12const EVENT_CACHE_TTL_MS = 5 * 60 * 1000;
12const EVENT_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS, 5 * 60 * 1000);
13const FRAME_CACHE_TTL_MS = 2 * 60 * 1000;
13const FRAME_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS, 2 * 60 * 1000);
14const MAX_EVENT_CACHE_ITEMS = 3;
14const MAX_EVENT_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS, 3);
15const MAX_FRAME_CACHE_ITEMS = 96;
15const MAX_FRAME_CACHE_ITEMS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, 96);
16const MAX_EVENT_CACHE_BYTES = 96 * 1024 * 1024;
16const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 96 * 1024 * 1024);
17const MAX_FRAME_CACHE_BYTES = 48 * 1024 * 1024;
17const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
18const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.5, 0.1, 1);
18const PGS_TIMEBASE = 90000;
19const PGS_TIMEBASE = 90000;
19const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = 5;
20const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = toPositiveInt(process.env.IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS, 5);
20
21
21const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);
22const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);
22const frameCache = createCacheState(MAX_FRAME_CACHE_ITEMS, MAX_FRAME_CACHE_BYTES);
23const 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
69function 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
68function hashSubtitleKey (filePath, streamIndex, stat)
77function hashSubtitleKey (filePath, streamIndex, stat)
69{
78{
70 return crypto
79 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
tests/image-subtitles.test.js +6 −6
@@ -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', () =>