BlueGit

timfa filemanager

test

timfa Tim Falken · pushed by timfa

Authored 2026-05-25 · 5 months ago

Hash
3a9cbe01f38653caa5519441499a0225c2012542
Parent
7960f07c
7 files changed +74 −25
.github/technical-reference.md +2 −2
@@ -15,10 +15,10 @@
15 15 - 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.
16 16
17 17 ## server/subtitle-debug-log.js
18 - appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a dated per-video text log under the local temp cache (`yyyy-mm-dd-videoname-subtitlelog.txt`), merging static context into each line and pruning the oldest files when the subtitle log cache exceeds 10 MB.
18 - appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
19 19 - getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
20 20 - pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
21 - subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the per-day subtitle timing log path for a video name using a filesystem-safe filename.
21 - subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
22 22
23 23 ## server/image-subtitles.js
24 24 - 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.
@@ -15,10 +15,10 @@
15- 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.
15- 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.
16
16
17## server/subtitle-debug-log.js
17## server/subtitle-debug-log.js
18- appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a dated per-video text log under the local temp cache (`yyyy-mm-dd-videoname-subtitlelog.txt`), merging static context into each line and pruning the oldest files when the subtitle log cache exceeds 10 MB.
18- appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
19- getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
19- getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
20- pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
20- pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
21- subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the per-day subtitle timing log path for a video name using a filesystem-safe filename.
21- subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
22
22
23## server/image-subtitles.js
23## server/image-subtitles.js
24- 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.
24- 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.
public/app.js +3 −3
@@ -387,9 +387,9 @@ function bindUserVideoTrackPrefs (player, prefs)
387 387 if (!shared || typeof shared.bindTrackPrefs !== 'function')
388 388 {
389 389 return {
390 applySavedTracks: () => {},
391 captureSelectedTracks: () => {},
392 detach: () => {},
390 applySavedTracks: () => { },
391 captureSelectedTracks: () => { },
392 detach: () => { },
393 393 };
394 394 }
395 395 return shared.bindTrackPrefs(player, prefs, saveUserVideoPrefs);
@@ -387,9 +387,9 @@ function bindUserVideoTrackPrefs (player, prefs)
387 if (!shared || typeof shared.bindTrackPrefs !== 'function')
387 if (!shared || typeof shared.bindTrackPrefs !== 'function')
388 {
388 {
389 return {
389 return {
390 applySavedTracks: () => {},
390 applySavedTracks: () => { },
391 captureSelectedTracks: () => {},
391 captureSelectedTracks: () => { },
392 detach: () => {},
392 detach: () => { },
393 };
393 };
394 }
394 }
395 return shared.bindTrackPrefs(player, prefs, saveUserVideoPrefs);
395 return shared.bindTrackPrefs(player, prefs, saveUserVideoPrefs);
public/share.html +3 −3
@@ -302,9 +302,9 @@
302 302 if (!shared || typeof shared.bindTrackPrefs !== 'function')
303 303 {
304 304 return {
305 applySavedTracks: () => {},
306 captureSelectedTracks: () => {},
307 detach: () => {},
305 applySavedTracks: () => { },
306 captureSelectedTracks: () => { },
307 detach: () => { },
308 308 };
309 309 }
310 310 return shared.bindTrackPrefs(player, prefs, saveShareVideoPrefs);
@@ -302,9 +302,9 @@
302 if (!shared || typeof shared.bindTrackPrefs !== 'function')
302 if (!shared || typeof shared.bindTrackPrefs !== 'function')
303 {
303 {
304 return {
304 return {
305 applySavedTracks: () => {},
305 applySavedTracks: () => { },
306 captureSelectedTracks: () => {},
306 captureSelectedTracks: () => { },
307 detach: () => {},
307 detach: () => { },
308 };
308 };
309 }
309 }
310 return shared.bindTrackPrefs(player, prefs, saveShareVideoPrefs);
310 return shared.bindTrackPrefs(player, prefs, saveShareVideoPrefs);
public/shared-video-player.js +3 −3
@@ -190,7 +190,7 @@
190 190
191 191 function bindTrackPrefs (player, prefs, savePrefs)
192 192 {
193 const save = typeof savePrefs === 'function' ? savePrefs : (() => {});
193 const save = typeof savePrefs === 'function' ? savePrefs : (() => { });
194 194 const applySavedTracks = () =>
195 195 {
196 196 applySavedSubtitleTrack(player, prefs.subtitleTrackName);
@@ -253,9 +253,9 @@
253 253
254 254 if (!imageTracks.length) return null;
255 255
256 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => {});
256 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => { });
257 257 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
258 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => {});
258 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => { });
259 259 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
260 260 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
261 261 const lookaheadSeconds = Number.isFinite(requestedLookaheadSeconds)
@@ -190,7 +190,7 @@
190
190
191 function bindTrackPrefs (player, prefs, savePrefs)
191 function bindTrackPrefs (player, prefs, savePrefs)
192 {
192 {
193 const save = typeof savePrefs === 'function' ? savePrefs : (() => {});
193 const save = typeof savePrefs === 'function' ? savePrefs : (() => { });
194 const applySavedTracks = () =>
194 const applySavedTracks = () =>
195 {
195 {
196 applySavedSubtitleTrack(player, prefs.subtitleTrackName);
196 applySavedSubtitleTrack(player, prefs.subtitleTrackName);
@@ -253,9 +253,9 @@
253
253
254 if (!imageTracks.length) return null;
254 if (!imageTracks.length) return null;
255
255
256 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => {});
256 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => { });
257 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
257 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
258 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => {});
258 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => { });
259 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
259 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
260 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
260 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
261 const lookaheadSeconds = Number.isFinite(requestedLookaheadSeconds)
261 const lookaheadSeconds = Number.isFinite(requestedLookaheadSeconds)
server/subtitle-debug-log.js +31 −10
@@ -6,16 +6,12 @@ const path = require('path');
6 6
7 7 const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
8 8 const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
9 const subtitleLogFileByContext = new Map();
9 10
10 function padNumber (value)
11 function normaliseTimestampMs (timestampMs)
11 12 {
12 return String(Math.max(0, Number(value) || 0)).padStart(2, '0');
13 }
14
15 function localDateStamp (timestampMs)
16 {
17 const date = new Date(Number.isFinite(timestampMs) ? timestampMs : Date.now());
18 return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}`;
13 const parsed = Number(timestampMs);
14 return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : Date.now();
19 15 }
20 16
21 17 function sanitiseVideoName (videoName)
@@ -27,10 +23,31 @@ function sanitiseVideoName (videoName)
27 23
28 24 function subtitleDebugLogFilePath (videoName, timestampMs = Date.now())
29 25 {
30 const fileName = `${localDateStamp(timestampMs)}-${sanitiseVideoName(videoName)}-subtitlelog.txt`;
26 const stamp = normaliseTimestampMs(timestampMs);
27 const fileName = `${stamp}-${sanitiseVideoName(videoName)}-subtitlelog.txt`;
31 28 return path.join(SUBTITLE_DEBUG_LOG_DIR, fileName);
32 29 }
33 30
31 function subtitleLogContextKey (videoName, context)
32 {
33 const source = context && context.source ? String(context.source) : 'unknown';
34 const sessionHint = context && (context.sessionId || context.shareToken)
35 ? String(context.sessionId || context.shareToken)
36 : 'no-session';
37 return `${sanitiseVideoName(videoName)}|${source}|${sessionHint}`;
38 }
39
40 function resolveSubtitleLogPath (videoName, timestampMs, context)
41 {
42 const key = subtitleLogContextKey(videoName, context);
43 const existing = subtitleLogFileByContext.get(key);
44 if (existing) return existing;
45
46 const targetPath = subtitleDebugLogFilePath(videoName, timestampMs);
47 subtitleLogFileByContext.set(key, targetPath);
48 return targetPath;
49 }
50
34 51 function ensureSubtitleDebugLogDir ()
35 52 {
36 53 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
@@ -112,7 +129,11 @@ function appendSubtitleDebugEntries ({ videoName, entries, context = null })
112 129 if (!rows.length) return null;
113 130
114 131 const firstTimestamp = rows.find((entry) => entry && Number.isFinite(entry.loggedAtMs));
115 const targetPath = subtitleDebugLogFilePath(videoName, firstTimestamp ? firstTimestamp.loggedAtMs : Date.now());
132 const targetPath = resolveSubtitleLogPath(
133 videoName,
134 firstTimestamp ? firstTimestamp.loggedAtMs : Date.now(),
135 context,
136 );
116 137
117 138 try
118 139 {
@@ -6,16 +6,12 @@ const path = require('path');
6
6
7const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
7const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
8const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
8const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
9const subtitleLogFileByContext = new Map();
9
10
10function padNumber (value)
11function normaliseTimestampMs (timestampMs)
11{
12{
12 return String(Math.max(0, Number(value) || 0)).padStart(2, '0');
13 const parsed = Number(timestampMs);
13}
14 return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : Date.now();
14
15function localDateStamp (timestampMs)
16{
17 const date = new Date(Number.isFinite(timestampMs) ? timestampMs : Date.now());
18 return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}`;
19}
15}
20
16
21function sanitiseVideoName (videoName)
17function sanitiseVideoName (videoName)
@@ -27,10 +23,31 @@ function sanitiseVideoName (videoName)
27
23
28function subtitleDebugLogFilePath (videoName, timestampMs = Date.now())
24function subtitleDebugLogFilePath (videoName, timestampMs = Date.now())
29{
25{
30 const fileName = `${localDateStamp(timestampMs)}-${sanitiseVideoName(videoName)}-subtitlelog.txt`;
26 const stamp = normaliseTimestampMs(timestampMs);
27 const fileName = `${stamp}-${sanitiseVideoName(videoName)}-subtitlelog.txt`;
31 return path.join(SUBTITLE_DEBUG_LOG_DIR, fileName);
28 return path.join(SUBTITLE_DEBUG_LOG_DIR, fileName);
32}
29}
33
30
31function subtitleLogContextKey (videoName, context)
32{
33 const source = context && context.source ? String(context.source) : 'unknown';
34 const sessionHint = context && (context.sessionId || context.shareToken)
35 ? String(context.sessionId || context.shareToken)
36 : 'no-session';
37 return `${sanitiseVideoName(videoName)}|${source}|${sessionHint}`;
38}
39
40function resolveSubtitleLogPath (videoName, timestampMs, context)
41{
42 const key = subtitleLogContextKey(videoName, context);
43 const existing = subtitleLogFileByContext.get(key);
44 if (existing) return existing;
45
46 const targetPath = subtitleDebugLogFilePath(videoName, timestampMs);
47 subtitleLogFileByContext.set(key, targetPath);
48 return targetPath;
49}
50
34function ensureSubtitleDebugLogDir ()
51function ensureSubtitleDebugLogDir ()
35{
52{
36 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
53 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
@@ -112,7 +129,11 @@ function appendSubtitleDebugEntries ({ videoName, entries, context = null })
112 if (!rows.length) return null;
129 if (!rows.length) return null;
113
130
114 const firstTimestamp = rows.find((entry) => entry && Number.isFinite(entry.loggedAtMs));
131 const firstTimestamp = rows.find((entry) => entry && Number.isFinite(entry.loggedAtMs));
115 const targetPath = subtitleDebugLogFilePath(videoName, firstTimestamp ? firstTimestamp.loggedAtMs : Date.now());
132 const targetPath = resolveSubtitleLogPath(
133 videoName,
134 firstTimestamp ? firstTimestamp.loggedAtMs : Date.now(),
135 context,
136 );
116
137
117 try
138 try
118 {
139 {
tests/shared-video-player.test.js +1 −1
@@ -133,7 +133,7 @@ describe('shared image subtitle prefetching', () =>
133 133 dom.window.Headers = Headers;
134 134 dom.window.Request = Request;
135 135 dom.window.URL.createObjectURL = () => 'blob:subtitle';
136 dom.window.URL.revokeObjectURL = () => {};
136 dom.window.URL.revokeObjectURL = () => { };
137 137
138 138 return dom.window;
139 139 }
@@ -133,7 +133,7 @@ describe('shared image subtitle prefetching', () =>
133 dom.window.Headers = Headers;
133 dom.window.Headers = Headers;
134 dom.window.Request = Request;
134 dom.window.Request = Request;
135 dom.window.URL.createObjectURL = () => 'blob:subtitle';
135 dom.window.URL.createObjectURL = () => 'blob:subtitle';
136 dom.window.URL.revokeObjectURL = () => {};
136 dom.window.URL.revokeObjectURL = () => { };
137
137
138 return dom.window;
138 return dom.window;
139 }
139 }
tests/subtitle-debug-log.test.js +31 −3
@@ -15,24 +15,52 @@ describe('subtitle debug log writer', () =>
15 15 fs.rmSync(logDir, { recursive: true, force: true });
16 16 });
17 17
18 test('writes dated per-video subtitle log files', () =>
18 test('writes timestamped per-video subtitle log files', () =>
19 19 {
20 20 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
21 const timestampMs = new Date('2026-05-25T10:00:00Z').getTime();
21 22
22 23 const targetPath = appendSubtitleDebugEntries({
23 24 videoName: 'My Film.mkv',
24 25 context: { source: 'app' },
25 26 entries: [
26 { loggedAtMs: new Date('2026-05-25T10:00:00Z').getTime(), eventType: 'subtitle_png_requested' },
27 { loggedAtMs: timestampMs, eventType: 'subtitle_png_requested' },
27 28 ],
28 29 });
29 30
30 expect(targetPath).toContain('2026-05-25-My-Film.mkv-subtitlelog.txt');
31 expect(targetPath).toContain(`${timestampMs}-My-Film.mkv-subtitlelog.txt`);
31 32 const text = fs.readFileSync(targetPath, 'utf8');
32 33 expect(text).toContain('subtitle_png_requested');
33 34 expect(text).toContain('"source":"app"');
34 35 });
35 36
37 test('reuses one timestamped file per playback session', () =>
38 {
39 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
40
41 const firstPath = appendSubtitleDebugEntries({
42 videoName: 'My Film.mkv',
43 context: { source: 'app', sessionId: 'sess-1' },
44 entries: [
45 { loggedAtMs: 1000, eventType: 'subtitle_png_requested' },
46 ],
47 });
48
49 const secondPath = appendSubtitleDebugEntries({
50 videoName: 'My Film.mkv',
51 context: { source: 'app', sessionId: 'sess-1' },
52 entries: [
53 { loggedAtMs: 2000, eventType: 'subtitle_png_received' },
54 ],
55 });
56
57 expect(secondPath).toBe(firstPath);
58
59 const text = fs.readFileSync(firstPath, 'utf8');
60 expect(text).toContain('subtitle_png_requested');
61 expect(text).toContain('subtitle_png_received');
62 });
63
36 64 test('prunes oldest subtitle log files when cache exceeds 10 MB', () =>
37 65 {
38 66 const logModule = require('../server/subtitle-debug-log');
@@ -15,24 +15,52 @@ describe('subtitle debug log writer', () =>
15 fs.rmSync(logDir, { recursive: true, force: true });
15 fs.rmSync(logDir, { recursive: true, force: true });
16 });
16 });
17
17
18 test('writes dated per-video subtitle log files', () =>
18 test('writes timestamped per-video subtitle log files', () =>
19 {
19 {
20 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
20 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
21 const timestampMs = new Date('2026-05-25T10:00:00Z').getTime();
21
22
22 const targetPath = appendSubtitleDebugEntries({
23 const targetPath = appendSubtitleDebugEntries({
23 videoName: 'My Film.mkv',
24 videoName: 'My Film.mkv',
24 context: { source: 'app' },
25 context: { source: 'app' },
25 entries: [
26 entries: [
26 { loggedAtMs: new Date('2026-05-25T10:00:00Z').getTime(), eventType: 'subtitle_png_requested' },
27 { loggedAtMs: timestampMs, eventType: 'subtitle_png_requested' },
27 ],
28 ],
28 });
29 });
29
30
30 expect(targetPath).toContain('2026-05-25-My-Film.mkv-subtitlelog.txt');
31 expect(targetPath).toContain(`${timestampMs}-My-Film.mkv-subtitlelog.txt`);
31 const text = fs.readFileSync(targetPath, 'utf8');
32 const text = fs.readFileSync(targetPath, 'utf8');
32 expect(text).toContain('subtitle_png_requested');
33 expect(text).toContain('subtitle_png_requested');
33 expect(text).toContain('"source":"app"');
34 expect(text).toContain('"source":"app"');
34 });
35 });
35
36
37 test('reuses one timestamped file per playback session', () =>
38 {
39 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
40
41 const firstPath = appendSubtitleDebugEntries({
42 videoName: 'My Film.mkv',
43 context: { source: 'app', sessionId: 'sess-1' },
44 entries: [
45 { loggedAtMs: 1000, eventType: 'subtitle_png_requested' },
46 ],
47 });
48
49 const secondPath = appendSubtitleDebugEntries({
50 videoName: 'My Film.mkv',
51 context: { source: 'app', sessionId: 'sess-1' },
52 entries: [
53 { loggedAtMs: 2000, eventType: 'subtitle_png_received' },
54 ],
55 });
56
57 expect(secondPath).toBe(firstPath);
58
59 const text = fs.readFileSync(firstPath, 'utf8');
60 expect(text).toContain('subtitle_png_requested');
61 expect(text).toContain('subtitle_png_received');
62 });
63
36 test('prunes oldest subtitle log files when cache exceeds 10 MB', () =>
64 test('prunes oldest subtitle log files when cache exceeds 10 MB', () =>
37 {
65 {
38 const logModule = require('../server/subtitle-debug-log');
66 const logModule = require('../server/subtitle-debug-log');