BlueGit

timfa filemanager

Files

filemanager / server / image-subtitles.js

image-subtitles.js

Clamp subtitle tail ranges
timfa Tim Falken · pushed by timfa · 5 months ago
be2f2fac History
image-subtitles.js 27.3 KiB Download Raw
1'use strict';
2
3const { spawn } = require('child_process');
4const crypto = require('crypto');
5const fs = require('fs');
6const os = require('os');
7const path = require('path');
8const { Readable } = require('stream');
9const sharp = require('sharp');
10
11const SUBTITLE_CACHE_DIR = path.join(os.tmpdir(), 'filemanager-video-subtitles');
12const EVENT_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS, 5 * 60 * 1000);
13const FRAME_CACHE_TTL_MS = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS, 2 * 60 * 1000);
14const MAX_EVENT_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS, Infinity);
15const MAX_FRAME_CACHE_ITEMS = toCacheItemLimit(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS, Infinity);
16// Removed byte size cap for event cache to prevent thrashing
17const MAX_EVENT_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES, 50 * 1024 * 1024);
18const MAX_FRAME_CACHE_BYTES = toPositiveInt(process.env.IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES, 48 * 1024 * 1024);
19const IMAGE_SUBTITLE_RENDER_SCALE = toBoundedNumber(process.env.IMAGE_SUBTITLE_RENDER_SCALE, 0.75, 0.1, 1);
20const PGS_TIMEBASE = 90000;
21const IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS = toPositiveInt(process.env.IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS, 5);
22
23const eventCache = createCacheState(MAX_EVENT_CACHE_ITEMS, MAX_EVENT_CACHE_BYTES);
24const frameCache = createCacheState(MAX_FRAME_CACHE_ITEMS, MAX_FRAME_CACHE_BYTES);
25const subtitleDebugStats = createSubtitleDebugStats();
26
27let parseDisplaySets = null;
28
29function createDurationStats ()
30{
31 return {
32 count: 0,
33 totalMs: 0,
34 maxMs: 0,
35 lastMs: 0,
36 };
37}
38
39function createSubtitleDebugStats ()
40{
41 return {
42 eventCacheHits: 0,
43 eventCacheMisses: 0,
44 eventCachePendingHits: 0,
45 eventCacheBuilds: 0,
46 eventCacheBuildErrors: 0,
47 frameCacheHits: 0,
48 frameCacheMisses: 0,
49 frameRenders: 0,
50 eventBuildDurationMs: createDurationStats(),
51 frameRenderDurationMs: createDurationStats(),
52 frameRequestDurationMs: createDurationStats(),
53 };
54}
55
56function recordDuration (stats, startedAt)
57{
58 if (!stats || !Number.isFinite(startedAt)) return 0;
59
60 const elapsedMs = Math.max(0, Date.now() - startedAt);
61 stats.count += 1;
62 stats.totalMs += elapsedMs;
63 stats.lastMs = elapsedMs;
64 if (elapsedMs > stats.maxMs) stats.maxMs = elapsedMs;
65 return elapsedMs;
66}
67
68function averageDurationMs (stats)
69{
70 if (!stats || !stats.count) return 0;
71 return Number((stats.totalMs / stats.count).toFixed(1));
72}
73
74function debugLimitValue (value)
75{
76 return Number.isFinite(value) ? value : null;
77}
78
79function ensureImageDataGlobal ()
80{
81 if (typeof globalThis.ImageData === 'function') return;
82
83 class ImageDataPolyfill
84 {
85 constructor(data, width, height)
86 {
87 this.data = data;
88 this.width = width;
89 this.height = height;
90 }
91 }
92
93 globalThis.ImageData = ImageDataPolyfill;
94}
95
96function loadPgsParser ()
97{
98 if (parseDisplaySets) return parseDisplaySets;
99 ensureImageDataGlobal();
100 ({ parseDisplaySets } = require('pgs-parser'));
101 return parseDisplaySets;
102}
103
104function ffmpegPath ()
105{
106 return process.env.FFMPEG_PATH || 'ffmpeg';
107}
108
109function ensureSubtitleCacheDir ()
110{
111 fs.mkdirSync(SUBTITLE_CACHE_DIR, { recursive: true });
112}
113
114function toPositiveInt (value, fallback)
115{
116 const number = Number.parseInt(String(value || ''), 10);
117 if (Number.isInteger(number) && number > 0) return number;
118 return fallback;
119}
120
121function toCacheItemLimit (value, fallback)
122{
123 const raw = String(value || '').trim().toLowerCase();
124 if (!raw) return fallback;
125 if (raw === '0' || raw === 'none' || raw === 'infinity' || raw === 'inf' || raw === 'unbounded' || raw === 'unlimited')
126 {
127 return Infinity;
128 }
129
130 const number = Number.parseInt(raw, 10);
131 if (Number.isInteger(number) && number > 0) return number;
132 return fallback;
133}
134
135function toBoundedNumber (value, fallback, min, max)
136{
137 const numeric = Number.parseFloat(String(value || ''));
138 if (!Number.isFinite(numeric)) return fallback;
139 if (numeric < min || numeric > max) return fallback;
140 return numeric;
141}
142
143function hashSubtitleKey (filePath, streamIndex, stat)
144{
145 return crypto
146 .createHash('sha1')
147 .update(`${filePath}|${streamIndex}|${stat.size}|${Math.floor(stat.mtimeMs)}`)
148 .digest('hex');
149}
150
151function createCacheState (maxItems, maxBytes)
152{
153 return {
154 map: new Map(),
155 totalBytes: 0,
156 maxItems,
157 maxBytes,
158 };
159}
160
161function normaliseFilePath (filePath)
162{
163 return path.resolve(String(filePath || '').trim());
164}
165
166function cachePrefixForFile (filePath)
167{
168 const normalised = String(filePath || '').trim();
169 if (!normalised) return '';
170 return `${normaliseFilePath(normalised)}|`;
171}
172
173function eventIdentityKey (filePath, streamIndex, stat)
174{
175 const normalisedPath = normaliseFilePath(filePath);
176 const hash = hashSubtitleKey(normalisedPath, streamIndex, stat);
177 return `${normalisedPath}|${streamIndex}|${hash}`;
178}
179
180function eventCacheFileKey (identityKey)
181{
182 const hash = crypto.createHash('sha1').update(String(identityKey || '')).digest('hex');
183 return `event-${hash}`;
184}
185
186function toValidCacheSize (value)
187{
188 const number = Number(value);
189 if (!Number.isFinite(number) || number <= 0) return 0;
190 return Math.floor(number);
191}
192
193function estimateEventCacheBytes (value)
194{
195 if (!value) return 0;
196 if (typeof value.then === 'function') return 1024;
197 if (!Array.isArray(value.events)) return 1024;
198
199 let bytes = 1024;
200 for (const event of value.events)
201 {
202 if (event && Buffer.isBuffer(event.imagePng)) bytes += event.imagePng.length;
203 bytes += 160;
204 }
205 return bytes;
206}
207
208function estimateFrameCacheBytes (value)
209{
210 if (!value) return 0;
211 if (Buffer.isBuffer(value)) return value.length;
212 if (value && Buffer.isBuffer(value.frame)) return value.frame.length + 96;
213 return 1024;
214}
215
216function deleteCachedValue (cache, key)
217{
218 const entry = cache.map.get(key);
219 if (!entry) return false;
220
221 cache.map.delete(key);
222 cache.totalBytes = Math.max(0, cache.totalBytes - toValidCacheSize(entry.sizeBytes));
223 return true;
224}
225
226function touchCachedEntry (cache, key, ttlMs)
227{
228 const entry = cache.map.get(key);
229 if (!entry) return;
230 entry.expiresAt = Date.now() + ttlMs;
231 cache.map.delete(key);
232 cache.map.set(key, entry);
233}
234
235function getCachedValue (cache, key)
236{
237 const now = Date.now();
238 const entry = cache.map.get(key);
239 if (!entry) return null;
240
241 if (entry.expiresAt <= now)
242 {
243 deleteCachedValue(cache, key);
244 return null;
245 }
246
247 cache.map.delete(key);
248 cache.map.set(key, entry);
249 return entry.value;
250}
251
252function setCachedValue (cache, key, value, ttlMs, estimateBytes)
253{
254 const now = Date.now();
255 deleteCachedValue(cache, key);
256
257 const sizeBytes = toValidCacheSize(typeof estimateBytes === 'function' ? estimateBytes(value) : 0);
258
259 cache.map.set(key, {
260 value,
261 expiresAt: now + ttlMs,
262 sizeBytes,
263 });
264 cache.totalBytes += sizeBytes;
265
266 while (cache.map.size > cache.maxItems || cache.maxBytes !== Infinity && cache.totalBytes > cache.maxBytes)
267 {
268 const oldestKey = cache.map.keys().next().value;
269 deleteCachedValue(cache, oldestKey);
270 }
271}
272
273function runCommand (command, args)
274{
275 return new Promise((resolve, reject) =>
276 {
277 const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'pipe'] });
278 let stderr = '';
279
280 child.stderr.on('data', (chunk) =>
281 {
282 stderr += chunk.toString();
283 if (stderr.length > 16000) stderr = stderr.slice(-16000);
284 });
285
286 child.on('error', reject);
287 child.on('close', (code) =>
288 {
289 if (code === 0)
290 {
291 resolve();
292 return;
293 }
294 reject(new Error(stderr.trim() || `ffmpeg exited with code ${code}`));
295 });
296 });
297}
298
299async function extractSupFile (sourcePath, streamIndex, cacheKey)
300{
301 ensureSubtitleCacheDir();
302 const supPath = path.join(SUBTITLE_CACHE_DIR, `${cacheKey}.sup`);
303
304 if (fs.existsSync(supPath) && fs.statSync(supPath).size > 0)
305 {
306 return supPath;
307 }
308
309 await runCommand(ffmpegPath(), [
310 '-hide_banner',
311 '-loglevel', 'error',
312 '-nostdin',
313 '-y',
314 '-i', sourcePath,
315 '-map', `0:s:${streamIndex}`,
316 '-c:s', 'copy',
317 '-f', 'sup',
318 supPath,
319 ]);
320
321 return supPath;
322}
323
324function toSeconds (pgsTimestamp)
325{
326 const numeric = Number(pgsTimestamp);
327 if (!Number.isFinite(numeric) || numeric < 0) return 0;
328 return numeric / PGS_TIMEBASE;
329}
330
331function parseDisplaySetTimestamp (displaySet)
332{
333 if (displaySet && displaySet.presentationCompositionSegment && displaySet.presentationCompositionSegment.header)
334 {
335 return toSeconds(displaySet.presentationCompositionSegment.header.presentationTimestamp);
336 }
337 if (displaySet && displaySet.endDefinitionSegment && displaySet.endDefinitionSegment.header)
338 {
339 return toSeconds(displaySet.endDefinitionSegment.header.presentationTimestamp);
340 }
341 return 0;
342}
343
344async function parseSupEvents (supPath)
345{
346 const parserFactory = loadPgsParser();
347 if (typeof Readable.toWeb !== 'function')
348 {
349 throw new Error('Node.js stream bridge is unavailable for subtitle parsing.');
350 }
351
352 const subtitleStream = Readable.toWeb(fs.createReadStream(supPath));
353 const parserStream = subtitleStream.pipeThrough(parserFactory());
354 const reader = parserStream.getReader();
355
356 const events = [];
357 let currentEvent = null;
358 let scratchBuffer = null;
359
360 while (true)
361 {
362 const { done, value: displaySet } = await reader.read();
363 if (done) break;
364
365 const timestampSeconds = parseDisplaySetTimestamp(displaySet);
366
367 if (currentEvent && timestampSeconds > currentEvent.startTimeSeconds)
368 {
369 currentEvent.endTimeSeconds = timestampSeconds;
370 events.push(currentEvent);
371 currentEvent = null;
372 }
373
374 if (!displaySet || !Array.isArray(displaySet.objectDefinitionSegments) || displaySet.objectDefinitionSegments.length === 0)
375 {
376 continue;
377 }
378
379 const pcs = displaySet.presentationCompositionSegment;
380 if (!pcs) continue;
381
382 const neededPixels = Number(pcs.width || 0) * Number(pcs.height || 0) * 4;
383 if (!scratchBuffer || !Number.isInteger(neededPixels) || neededPixels <= 0 || scratchBuffer.length < neededPixels)
384 {
385 scratchBuffer = neededPixels > 0 ? new Uint8ClampedArray(neededPixels) : null;
386 }
387
388 let imageData;
389 try
390 {
391 imageData = displaySet.imageData(scratchBuffer || undefined);
392 } catch
393 {
394 continue;
395 }
396
397 if (!imageData || !imageData.data || !Number.isInteger(imageData.width) || !Number.isInteger(imageData.height))
398 {
399 continue;
400 }
401
402 const rawPixels = Buffer.from(imageData.data);
403 const imagePng = await sharp(rawPixels, {
404 raw: {
405 width: imageData.width,
406 height: imageData.height,
407 channels: 4,
408 },
409 }).png().toBuffer();
410
411 currentEvent = {
412 startTimeSeconds: timestampSeconds,
413 endTimeSeconds: Number.POSITIVE_INFINITY,
414 screenWidth: toPositiveInt(pcs.width, imageData.width),
415 screenHeight: toPositiveInt(pcs.height, imageData.height),
416 left: toPositiveInt(pcs.objectHorizontalPosition, 0),
417 top: toPositiveInt(pcs.objectVerticalPosition, 0),
418 imageWidth: imageData.width,
419 imageHeight: imageData.height,
420 imagePng,
421 };
422 }
423
424 if (currentEvent)
425 {
426 events.push(currentEvent);
427 }
428
429 return events;
430}
431
432async function buildEventCacheEntry (filePath, streamIndex, identityKey)
433{
434 const subtitleFileCacheKey = eventCacheFileKey(identityKey);
435 const supPath = await extractSupFile(filePath, streamIndex, subtitleFileCacheKey);
436 const events = await parseSupEvents(supPath);
437 return {
438 cacheKey: identityKey,
439 events,
440 };
441}
442
443function beginEventCacheBuild (normalisedPath, streamIndex, identityKey)
444{
445 subtitleDebugStats.eventCacheBuilds += 1;
446 const buildStartedAt = Date.now();
447 const pending = buildEventCacheEntry(normalisedPath, streamIndex, identityKey);
448 setCachedValue(eventCache, identityKey, pending, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
449
450 pending
451 .then((resolved) =>
452 {
453 recordDuration(subtitleDebugStats.eventBuildDurationMs, buildStartedAt);
454 setCachedValue(eventCache, identityKey, resolved, EVENT_CACHE_TTL_MS, estimateEventCacheBytes);
455 return resolved;
456 })
457 .catch(() =>
458 {
459 subtitleDebugStats.eventCacheBuildErrors += 1;
460 deleteCachedValue(eventCache, identityKey);
461 });
462
463 return pending;
464}
465
466async function getEventCacheEntry (filePath, streamIndex, options = {})
467{
468 const waitForBuild = options.waitForBuild !== false;
469 const normalisedPath = normaliseFilePath(filePath);
470 const stat = await fs.promises.stat(normalisedPath);
471 const identityKey = eventIdentityKey(normalisedPath, streamIndex, stat);
472
473 const cached = getCachedValue(eventCache, identityKey);
474 if (cached)
475 {
476 if (typeof cached.then === 'function') subtitleDebugStats.eventCachePendingHits += 1;
477 else subtitleDebugStats.eventCacheHits += 1;
478 touchCachedEntry(eventCache, identityKey, EVENT_CACHE_TTL_MS);
479
480 if (typeof cached.then === 'function')
481 {
482 return waitForBuild ? cached : null;
483 }
484
485 return cached;
486 }
487
488 subtitleDebugStats.eventCacheMisses += 1;
489 const pending = beginEventCacheBuild(normalisedPath, streamIndex, identityKey);
490 return waitForBuild ? pending : null;
491}
492
493function findActiveEventIndex (events, timeSeconds)
494{
495 let left = 0;
496 let right = events.length - 1;
497 let candidate = -1;
498
499 while (left <= right)
500 {
501 const middle = Math.floor((left + right) / 2);
502 const event = events[middle];
503
504 if (event.startTimeSeconds <= timeSeconds)
505 {
506 candidate = middle;
507 left = middle + 1;
508 } else
509 {
510 right = middle - 1;
511 }
512 }
513
514 if (candidate < 0) return -1;
515
516 const active = events[candidate];
517 if (timeSeconds >= active.endTimeSeconds) return -1;
518 return candidate;
519}
520
521async function renderEventFrame (event, canvasWidth, canvasHeight)
522{
523 const sourceWidth = Math.max(1, toPositiveInt(event.screenWidth, canvasWidth));
524 const sourceHeight = Math.max(1, toPositiveInt(event.screenHeight, canvasHeight));
525
526 const scaleX = canvasWidth / sourceWidth;
527 const scaleY = canvasHeight / sourceHeight;
528
529 const targetWidth = Math.max(1, Math.round(event.imageWidth * scaleX));
530 const targetHeight = Math.max(1, Math.round(event.imageHeight * scaleY));
531 const left = Math.round(event.left * scaleX);
532 const top = Math.round(event.top * scaleY);
533 const right = left + targetWidth;
534 const bottom = top + targetHeight;
535
536 const visibleLeft = Math.max(0, left);
537 const visibleTop = Math.max(0, top);
538 const visibleRight = Math.min(canvasWidth, right);
539 const visibleBottom = Math.min(canvasHeight, bottom);
540 const visibleWidth = Math.max(0, visibleRight - visibleLeft);
541 const visibleHeight = Math.max(0, visibleBottom - visibleTop);
542
543 if (visibleWidth <= 0 || visibleHeight <= 0)
544 {
545 return null;
546 }
547
548 let imageBuffer = (targetWidth === event.imageWidth && targetHeight === event.imageHeight)
549 ? event.imagePng
550 : await sharp(event.imagePng).resize({ width: targetWidth, height: targetHeight, fit: 'fill' }).png().toBuffer();
551
552 if (visibleWidth < targetWidth || visibleHeight < targetHeight)
553 {
554 imageBuffer = await sharp(imageBuffer)
555 .extract({
556 left: Math.max(0, visibleLeft - left),
557 top: Math.max(0, visibleTop - top),
558 width: visibleWidth,
559 height: visibleHeight,
560 })
561 .png()
562 .toBuffer();
563 }
564
565 return {
566 frame: imageBuffer,
567 left: visibleLeft,
568 top: visibleTop,
569 width: visibleWidth,
570 height: visibleHeight,
571 canvasWidth,
572 canvasHeight,
573 };
574}
575
576function parseRenderOptions (options)
577{
578 const input = options || {};
579 const filePath = String(input.filePath ?? '').trim();
580 const streamIndex = Number.parseInt(String(input.streamIndex ?? ''), 10);
581 const timeSeconds = Number.parseFloat(String(input.timeSeconds ?? ''), 10);
582 const requestedWidth = Math.max(1, toPositiveInt(input.canvasWidth ?? '', 1280));
583 const requestedHeight = Math.max(1, toPositiveInt(input.canvasHeight ?? '', 720));
584 const scale = Math.min(1, 1280 / requestedWidth, 720 / requestedHeight) * IMAGE_SUBTITLE_RENDER_SCALE;
585 const canvasWidth = Math.max(1, Math.round(requestedWidth * scale));
586 const canvasHeight = Math.max(1, Math.round(requestedHeight * scale));
587
588 return {
589 filePath,
590 streamIndex,
591 timeSeconds,
592 canvasWidth,
593 canvasHeight,
594 isValid: !!(filePath && Number.isInteger(streamIndex) && streamIndex >= 0 && Number.isFinite(timeSeconds) && timeSeconds >= 0),
595 };
596}
597
598function parseRenderRangeOptions (options)
599{
600 const parsed = parseRenderOptions({
601 ...options,
602 timeSeconds: options && options.startTimeSeconds,
603 });
604 const startTimeSeconds = parsed.timeSeconds;
605 const endTimeSeconds = Number.parseFloat(String((options && options.endTimeSeconds) ?? ''), 10);
606
607 return {
608 filePath: parsed.filePath,
609 streamIndex: parsed.streamIndex,
610 startTimeSeconds,
611 endTimeSeconds,
612 canvasWidth: parsed.canvasWidth,
613 canvasHeight: parsed.canvasHeight,
614 isValid: !!(parsed.isValid && Number.isFinite(endTimeSeconds) && endTimeSeconds >= startTimeSeconds),
615 };
616}
617
618async function getRenderedFrameForEvent (entry, eventIndex, canvasWidth, canvasHeight)
619{
620 if (!entry || !Array.isArray(entry.events) || eventIndex < 0 || eventIndex >= entry.events.length) return null;
621
622 const frameKey = `${entry.cacheKey}|${eventIndex}|${canvasWidth}x${canvasHeight}`;
623 const cachedFrame = getCachedValue(frameCache, frameKey);
624 if (cachedFrame)
625 {
626 subtitleDebugStats.frameCacheHits += 1;
627 return cachedFrame;
628 }
629
630 subtitleDebugStats.frameCacheMisses += 1;
631 subtitleDebugStats.frameRenders += 1;
632 const renderStartedAt = Date.now();
633 const frameData = await renderEventFrame(entry.events[eventIndex], canvasWidth, canvasHeight);
634 if (!frameData)
635 {
636 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
637 return null;
638 }
639 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
640
641 const event = entry.events[eventIndex];
642 const cacheValue = {
643 frame: frameData.frame,
644 left: frameData.left,
645 top: frameData.top,
646 width: frameData.width,
647 height: frameData.height,
648 canvasWidth: frameData.canvasWidth,
649 canvasHeight: frameData.canvasHeight,
650 startTimeSeconds: event.startTimeSeconds,
651 endTimeSeconds: event.endTimeSeconds,
652 };
653 setCachedValue(
654 frameCache,
655 frameKey,
656 cacheValue,
657 FRAME_CACHE_TTL_MS,
658 estimateFrameCacheBytes,
659 );
660 return cacheValue;
661}
662
663async function renderImageSubtitleFrame (options)
664{
665 const requestStartedAt = Date.now();
666 const parsed = parseRenderOptions(options);
667 const { filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight } = parsed;
668
669 if (!parsed.isValid)
670 {
671 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
672 return null;
673 }
674
675 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
676 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
677 {
678 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
679 return null;
680 }
681
682 const eventIndex = findActiveEventIndex(entry.events, timeSeconds);
683 if (eventIndex < 0)
684 {
685 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
686 return null;
687 }
688
689 const cacheValue = await getRenderedFrameForEvent(entry, eventIndex, canvasWidth, canvasHeight);
690 if (!cacheValue)
691 {
692 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
693 return null;
694 }
695 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
696 return cacheValue;
697}
698
699async function renderImageSubtitleFramesInRange (options)
700{
701 const requestStartedAt = Date.now();
702 const parsed = parseRenderRangeOptions(options);
703 const { filePath, streamIndex, startTimeSeconds, endTimeSeconds, canvasWidth, canvasHeight } = parsed;
704
705 if (!parsed.isValid)
706 {
707 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
708 return {
709 frames: [],
710 startTimeSeconds,
711 endTimeSeconds,
712 };
713 }
714
715 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
716 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
717 {
718 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
719 return {
720 frames: [],
721 startTimeSeconds,
722 endTimeSeconds,
723 };
724 }
725
726 let eventIndex = findActiveEventIndex(entry.events, startTimeSeconds);
727 if (eventIndex < 0)
728 {
729 eventIndex = entry.events.findIndex((event) => event && Number(event.endTimeSeconds) > startTimeSeconds);
730 }
731
732 const frames = [];
733 for (let index = Math.max(0, eventIndex); index < entry.events.length; index++)
734 {
735 const event = entry.events[index];
736 if (!event) continue;
737 if (Number(event.startTimeSeconds) >= endTimeSeconds) break;
738 if (Number(event.endTimeSeconds) <= startTimeSeconds) continue;
739
740 const frame = await getRenderedFrameForEvent(entry, index, canvasWidth, canvasHeight);
741 if (!frame || !frame.frame) continue;
742 frames.push(frame);
743 }
744
745 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
746 return {
747 frames,
748 startTimeSeconds,
749 endTimeSeconds,
750 };
751}
752
753function deleteSupFileForKey (identityKey)
754{
755 const cacheKey = eventCacheFileKey(identityKey);
756 const supPath = path.join(SUBTITLE_CACHE_DIR, `${cacheKey}.sup`);
757 fs.unlink(supPath, () =>
758 {
759 // Best-effort; file may not exist if extraction never completed.
760 });
761}
762
763function purgeSubtitleCacheDir ()
764{
765 try
766 {
767 fs.rmSync(SUBTITLE_CACHE_DIR, { recursive: true, force: true });
768 } catch
769 {
770 // Best-effort; directory may not exist.
771 }
772}
773
774function pruneOldImageSubtitleCaches (filePath, slowestViewerTimeSeconds)
775{
776 const prefix = cachePrefixForFile(filePath);
777 if (!prefix || !Number.isFinite(slowestViewerTimeSeconds)) return;
778
779 const pruneThresholdSeconds = slowestViewerTimeSeconds - IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS;
780
781 // Prune frame cache entries that ended before the slowest viewer + grace.
782 const keysToDelete = [];
783 for (const key of frameCache.map.keys())
784 {
785 if (!key.startsWith(prefix)) continue;
786 const entry = frameCache.map.get(key);
787 if (!entry) continue;
788 const eventEntry = entry.value || {};
789 const endTimeSeconds = Number(eventEntry.endTimeSeconds);
790 if (!Number.isFinite(endTimeSeconds)) continue;
791 if (endTimeSeconds <= pruneThresholdSeconds)
792 {
793 keysToDelete.push(key);
794 }
795 }
796 for (const key of keysToDelete)
797 {
798 deleteCachedValue(frameCache, key);
799 }
800
801 // Prune event cache entries unconditionally as viewer frontier advances.
802 for (const [key, entry] of eventCache.map.entries())
803 {
804 if (!key.startsWith(prefix)) continue;
805 const value = entry.value;
806 if (!value || !Array.isArray(value.events)) continue;
807 let events = value.events;
808
809 // Keep only events not yet passed by the slowest viewer (+ grace).
810 let pruneIdx = 0;
811 while (pruneIdx < events.length)
812 {
813 const event = events[pruneIdx];
814 const endTimeSeconds = Number(event && event.endTimeSeconds);
815 if (!Number.isFinite(endTimeSeconds) || endTimeSeconds > pruneThresholdSeconds) break;
816 pruneIdx++;
817 }
818
819 if (pruneIdx > 0)
820 {
821 // Remove pruned events and update cache accounting.
822 const removed = events.splice(0, pruneIdx);
823 for (const ev of removed)
824 {
825 const estimatedBytes = (ev && Buffer.isBuffer(ev.imagePng) ? ev.imagePng.length : 0) + 160;
826 entry.sizeBytes = Math.max(0, toValidCacheSize(entry.sizeBytes) - estimatedBytes);
827 eventCache.totalBytes = Math.max(0, toValidCacheSize(eventCache.totalBytes) - estimatedBytes);
828 }
829 }
830
831 // If all events are pruned, remove the entry and extracted sup file.
832 if (events.length === 0)
833 {
834 deleteSupFileForKey(key);
835 deleteCachedValue(eventCache, key);
836 }
837 }
838}
839
840function clearCachesForFile (filePath)
841{
842 const prefix = cachePrefixForFile(filePath);
843 if (!prefix) return;
844
845 const eventKeysToDelete = [];
846 const frameKeysToDelete = [];
847
848 for (const key of eventCache.map.keys())
849 {
850 if (key.startsWith(prefix)) eventKeysToDelete.push(key);
851 }
852
853 for (const key of frameCache.map.keys())
854 {
855 if (key.startsWith(prefix)) frameKeysToDelete.push(key);
856 }
857
858 for (const key of eventKeysToDelete)
859 {
860 deleteSupFileForKey(key);
861 deleteCachedValue(eventCache, key);
862 }
863
864 for (const key of frameKeysToDelete)
865 {
866 deleteCachedValue(frameCache, key);
867 }
868}
869
870function filePathFromCacheKey (key)
871{
872 const raw = String(key || '');
873 const divider = raw.indexOf('|');
874 if (divider < 0) return '';
875 return raw.slice(0, divider);
876}
877
878function getImageSubtitleDebugSnapshot ()
879{
880 const byFile = {};
881
882 for (const [key, entry] of eventCache.map.entries())
883 {
884 const filePath = filePathFromCacheKey(key);
885 if (!filePath) continue;
886
887 const row = byFile[filePath] || {
888 filePath,
889 eventEntries: 0,
890 eventBytes: 0,
891 eventCount: 0,
892 eventImageBytes: 0,
893 frameEntries: 0,
894 frameBytes: 0,
895 };
896
897 row.eventEntries += 1;
898 row.eventBytes += Number(entry && entry.sizeBytes) || 0;
899
900 const value = entry && entry.value;
901 if (value && Array.isArray(value.events))
902 {
903 row.eventCount += value.events.length;
904 for (const event of value.events)
905 {
906 if (event && Buffer.isBuffer(event.imagePng))
907 {
908 row.eventImageBytes += event.imagePng.length;
909 }
910 }
911 }
912
913 byFile[filePath] = row;
914 }
915
916 for (const [key, entry] of frameCache.map.entries())
917 {
918 const filePath = filePathFromCacheKey(key);
919 if (!filePath) continue;
920
921 const row = byFile[filePath] || {
922 filePath,
923 eventEntries: 0,
924 eventBytes: 0,
925 eventCount: 0,
926 eventImageBytes: 0,
927 frameEntries: 0,
928 frameBytes: 0,
929 };
930
931 row.frameEntries += 1;
932 row.frameBytes += Number(entry && entry.sizeBytes) || 0;
933
934 byFile[filePath] = row;
935 }
936
937 return {
938 eventCache: {
939 entries: eventCache.map.size,
940 bytes: eventCache.totalBytes,
941 maxItems: debugLimitValue(eventCache.maxItems),
942 maxBytes: eventCache.maxBytes,
943 },
944 frameCache: {
945 entries: frameCache.map.size,
946 bytes: frameCache.totalBytes,
947 maxItems: debugLimitValue(frameCache.maxItems),
948 maxBytes: frameCache.maxBytes,
949 },
950 metrics: {
951 eventCacheHits: subtitleDebugStats.eventCacheHits,
952 eventCacheMisses: subtitleDebugStats.eventCacheMisses,
953 eventCachePendingHits: subtitleDebugStats.eventCachePendingHits,
954 eventCacheBuilds: subtitleDebugStats.eventCacheBuilds,
955 eventCacheBuildErrors: subtitleDebugStats.eventCacheBuildErrors,
956 frameCacheHits: subtitleDebugStats.frameCacheHits,
957 frameCacheMisses: subtitleDebugStats.frameCacheMisses,
958 frameRenders: subtitleDebugStats.frameRenders,
959 eventBuildDurationMs: {
960 last: subtitleDebugStats.eventBuildDurationMs.lastMs,
961 max: subtitleDebugStats.eventBuildDurationMs.maxMs,
962 average: averageDurationMs(subtitleDebugStats.eventBuildDurationMs),
963 },
964 frameRenderDurationMs: {
965 last: subtitleDebugStats.frameRenderDurationMs.lastMs,
966 max: subtitleDebugStats.frameRenderDurationMs.maxMs,
967 average: averageDurationMs(subtitleDebugStats.frameRenderDurationMs),
968 },
969 frameRequestDurationMs: {
970 last: subtitleDebugStats.frameRequestDurationMs.lastMs,
971 max: subtitleDebugStats.frameRequestDurationMs.maxMs,
972 average: averageDurationMs(subtitleDebugStats.frameRequestDurationMs),
973 },
974 },
975 byFile,
976 };
977}
978
979module.exports = {
980 parseRenderOptions,
981 parseRenderRangeOptions,
982 renderImageSubtitleFrame,
983 renderImageSubtitleFramesInRange,
984 clearCachesForFile,
985 pruneOldImageSubtitleCaches,
986 purgeSubtitleCacheDir,
987 getImageSubtitleDebugSnapshot,
988};