test
@@ -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.
@@ -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);@@ -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
7
const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');7
const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');8
const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;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
const parsed = Number(timestampMs);13
}14
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : Date.now();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())}`;19
}15
}20
16
21
function sanitiseVideoName (videoName)17
function sanitiseVideoName (videoName)@@ -27,10 +23,31 @@ function sanitiseVideoName (videoName)27
23
28
function subtitleDebugLogFilePath (videoName, timestampMs = Date.now())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
return path.join(SUBTITLE_DEBUG_LOG_DIR, fileName);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
function ensureSubtitleDebugLogDir ()51
function 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
try138
try118
{139
{@@ -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');