BlueGit

timfa filemanager

Merge feature/sidecar-srt-subtitles

timfa Tim Falken · pushed by timfa

Authored 2026-05-18 · 6 months ago

Hash
5f3c528ac987a83bfa9abda37e884017aafec2db
3 files changed +139 −2
.github/technical-reference.md +1 −1
@@ -113,7 +113,7 @@
113 113 - ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
114 114
115 115 ## server/video-stream.js
116 - createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data.
116 - createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data, including same-name sidecar `.srt` subtitles converted to WebVTT.
117 117 - sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
118 118 - releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
119 119 - runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
@@ -113,7 +113,7 @@
113- ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
113- ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
114
114
115## server/video-stream.js
115## server/video-stream.js
116- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data.
116- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data, including same-name sidecar `.srt` subtitles converted to WebVTT.
117- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
117- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
118- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
118- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
119- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
119- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
server/video-stream.js +68 −1
@@ -559,6 +559,41 @@ function trackLabel (stream, fallback)
559 559 return fallback;
560 560 }
561 561
562 function findMatchingSidecarSrtPath (sourcePath)
563 {
564 const absoluteSourcePath = path.resolve(String(sourcePath || ''));
565 const dirPath = path.dirname(absoluteSourcePath);
566 const baseName = path.parse(absoluteSourcePath).name;
567 const exactPath = path.join(dirPath, `${baseName}.srt`);
568
569 try
570 {
571 const exactStat = fs.statSync(exactPath);
572 if (exactStat.isFile()) return exactPath;
573 } catch
574 {
575 // Fall back to case-insensitive directory scan.
576 }
577
578 const wantedName = `${baseName}.srt`.toLowerCase();
579
580 try
581 {
582 const entries = fs.readdirSync(dirPath, { withFileTypes: true });
583 for (const entry of entries)
584 {
585 if (!entry.isFile()) continue;
586 if (entry.name.toLowerCase() !== wantedName) continue;
587 return path.join(dirPath, entry.name);
588 }
589 } catch
590 {
591 return null;
592 }
593
594 return null;
595 }
596
562 597 async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)
563 598 {
564 599 const extractedTracks = [];
@@ -612,9 +647,41 @@ async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)
612 647 trackNumber += 1;
613 648 }
614 649
650 const sidecarSrtPath = findMatchingSidecarSrtPath(sourcePath);
651 const hasSidecarSrt = !!sidecarSrtPath;
652 if (sidecarSrtPath)
653 {
654 const fileName = `subtitle-${trackNumber}.vtt`;
655 const targetPath = path.join(outputDir, fileName);
656 try
657 {
658 await runCommand(ffmpegPath(), [
659 '-hide_banner',
660 '-loglevel', 'error',
661 '-nostdin',
662 '-y',
663 '-i', sidecarSrtPath,
664 '-c:s', 'webvtt',
665 targetPath,
666 ]);
667
668 extractedTracks.push({
669 fileName,
670 label: `Subtitle ${trackNumber + 1} (external)`,
671 language: 'und',
672 isDefault: extractedTracks.length === 0 && imageBasedTracks.length === 0,
673 });
674 trackNumber += 1;
675 } catch
676 {
677 skippedCount += 1;
678 }
679 }
680
615 681 return {
616 682 tracks: extractedTracks,
617 683 imageBasedTracks,
684 hasSidecarSrt,
618 685 skippedCount,
619 686 };
620 687 }
@@ -801,7 +868,7 @@ async function initialiseSession (session)
801 868 session.subtitleTracks = subtitleResult.tracks;
802 869 session.imageSubtitleTracks = subtitleResult.imageBasedTracks;
803 870 session.subtitleSummary = {
804 total: streamInfo.subtitles.length,
871 total: streamInfo.subtitles.length + (subtitleResult.hasSidecarSrt ? 1 : 0),
805 872 converted: subtitleResult.tracks.length,
806 873 imageBased: subtitleResult.imageBasedTracks.length,
807 874 skipped: subtitleResult.skippedCount,
@@ -559,6 +559,41 @@ function trackLabel (stream, fallback)
559 return fallback;
559 return fallback;
560}
560}
561
561
562function findMatchingSidecarSrtPath (sourcePath)
563{
564 const absoluteSourcePath = path.resolve(String(sourcePath || ''));
565 const dirPath = path.dirname(absoluteSourcePath);
566 const baseName = path.parse(absoluteSourcePath).name;
567 const exactPath = path.join(dirPath, `${baseName}.srt`);
568
569 try
570 {
571 const exactStat = fs.statSync(exactPath);
572 if (exactStat.isFile()) return exactPath;
573 } catch
574 {
575 // Fall back to case-insensitive directory scan.
576 }
577
578 const wantedName = `${baseName}.srt`.toLowerCase();
579
580 try
581 {
582 const entries = fs.readdirSync(dirPath, { withFileTypes: true });
583 for (const entry of entries)
584 {
585 if (!entry.isFile()) continue;
586 if (entry.name.toLowerCase() !== wantedName) continue;
587 return path.join(dirPath, entry.name);
588 }
589 } catch
590 {
591 return null;
592 }
593
594 return null;
595}
596
562async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)
597async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)
563{
598{
564 const extractedTracks = [];
599 const extractedTracks = [];
@@ -612,9 +647,41 @@ async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)
612 trackNumber += 1;
647 trackNumber += 1;
613 }
648 }
614
649
650 const sidecarSrtPath = findMatchingSidecarSrtPath(sourcePath);
651 const hasSidecarSrt = !!sidecarSrtPath;
652 if (sidecarSrtPath)
653 {
654 const fileName = `subtitle-${trackNumber}.vtt`;
655 const targetPath = path.join(outputDir, fileName);
656 try
657 {
658 await runCommand(ffmpegPath(), [
659 '-hide_banner',
660 '-loglevel', 'error',
661 '-nostdin',
662 '-y',
663 '-i', sidecarSrtPath,
664 '-c:s', 'webvtt',
665 targetPath,
666 ]);
667
668 extractedTracks.push({
669 fileName,
670 label: `Subtitle ${trackNumber + 1} (external)`,
671 language: 'und',
672 isDefault: extractedTracks.length === 0 && imageBasedTracks.length === 0,
673 });
674 trackNumber += 1;
675 } catch
676 {
677 skippedCount += 1;
678 }
679 }
680
615 return {
681 return {
616 tracks: extractedTracks,
682 tracks: extractedTracks,
617 imageBasedTracks,
683 imageBasedTracks,
684 hasSidecarSrt,
618 skippedCount,
685 skippedCount,
619 };
686 };
620}
687}
@@ -801,7 +868,7 @@ async function initialiseSession (session)
801 session.subtitleTracks = subtitleResult.tracks;
868 session.subtitleTracks = subtitleResult.tracks;
802 session.imageSubtitleTracks = subtitleResult.imageBasedTracks;
869 session.imageSubtitleTracks = subtitleResult.imageBasedTracks;
803 session.subtitleSummary = {
870 session.subtitleSummary = {
804 total: streamInfo.subtitles.length,
871 total: streamInfo.subtitles.length + (subtitleResult.hasSidecarSrt ? 1 : 0),
805 converted: subtitleResult.tracks.length,
872 converted: subtitleResult.tracks.length,
806 imageBased: subtitleResult.imageBasedTracks.length,
873 imageBased: subtitleResult.imageBasedTracks.length,
807 skipped: subtitleResult.skippedCount,
874 skipped: subtitleResult.skippedCount,
tests/video-stream.test.js +70 −0
@@ -303,6 +303,76 @@ describe('video stream bootstrap', () =>
303 303 });
304 304 });
305 305
306 test('createVideoStreamSession includes matching sidecar srt subtitles', async () =>
307 {
308 fs.writeFileSync(path.join(path.dirname(sourceFile), 'clip.srt'), '1\n00:00:00,000 --> 00:00:01,000\nHello\n');
309
310 mockSpawn.mockImplementation((command, args) =>
311 {
312 const child = makeChildProcess();
313 const exeName = path.basename(String(command || '')).toLowerCase();
314
315 if (exeName.includes('ffprobe'))
316 {
317 process.nextTick(() =>
318 {
319 child.stdout.emit('data', Buffer.from(JSON.stringify({
320 streams: [
321 { codec_type: 'video', codec_name: 'h264', width: 854, height: 480, tags: {}, disposition: {} },
322 { codec_type: 'audio', codec_name: 'aac', tags: {}, disposition: { default: 1 } },
323 ],
324 })));
325 child.emit('close', 0);
326 });
327 return child;
328 }
329
330 const subtitleTarget = String(args[args.length - 1] || '');
331 if (args.includes('-c:s') && args.includes('webvtt') && subtitleTarget.endsWith('.vtt'))
332 {
333 process.nextTick(() =>
334 {
335 fs.mkdirSync(path.dirname(subtitleTarget), { recursive: true });
336 fs.writeFileSync(subtitleTarget, 'WEBVTT\n\n');
337 child.emit('close', 0);
338 });
339 return child;
340 }
341
342 const playlistPath = String(args[args.length - 1] || '');
343 const outputDir = path.dirname(playlistPath);
344 process.nextTick(() =>
345 {
346 fs.mkdirSync(outputDir, { recursive: true });
347 fs.writeFileSync(path.join(outputDir, 'master.m3u8'), '#EXTM3U\n');
348 });
349
350 return child;
351 });
352
353 const { createVideoStreamSession } = require('../server/video-stream');
354 await expect(createVideoStreamSession(sourceFile)).resolves.toEqual({
355 sessionId: expect.any(String),
356 durationSeconds: null,
357 videoWidth: 854,
358 videoHeight: 480,
359 subtitleTracks: [
360 expect.objectContaining({
361 fileName: 'subtitle-0.vtt',
362 language: 'und',
363 isDefault: true,
364 }),
365 ],
366 imageSubtitleTracks: [],
367 subtitleSummary: {
368 total: 1,
369 converted: 1,
370 imageBased: 0,
371 skipped: 0,
372 },
373 });
374 });
375
306 376 test('createVideoStreamSession keeps playback available when subtitle conversion fails', async () =>
307 377 {
308 378 mockSpawn.mockImplementation((command, args) =>
@@ -303,6 +303,76 @@ describe('video stream bootstrap', () =>
303 });
303 });
304 });
304 });
305
305
306 test('createVideoStreamSession includes matching sidecar srt subtitles', async () =>
307 {
308 fs.writeFileSync(path.join(path.dirname(sourceFile), 'clip.srt'), '1\n00:00:00,000 --> 00:00:01,000\nHello\n');
309
310 mockSpawn.mockImplementation((command, args) =>
311 {
312 const child = makeChildProcess();
313 const exeName = path.basename(String(command || '')).toLowerCase();
314
315 if (exeName.includes('ffprobe'))
316 {
317 process.nextTick(() =>
318 {
319 child.stdout.emit('data', Buffer.from(JSON.stringify({
320 streams: [
321 { codec_type: 'video', codec_name: 'h264', width: 854, height: 480, tags: {}, disposition: {} },
322 { codec_type: 'audio', codec_name: 'aac', tags: {}, disposition: { default: 1 } },
323 ],
324 })));
325 child.emit('close', 0);
326 });
327 return child;
328 }
329
330 const subtitleTarget = String(args[args.length - 1] || '');
331 if (args.includes('-c:s') && args.includes('webvtt') && subtitleTarget.endsWith('.vtt'))
332 {
333 process.nextTick(() =>
334 {
335 fs.mkdirSync(path.dirname(subtitleTarget), { recursive: true });
336 fs.writeFileSync(subtitleTarget, 'WEBVTT\n\n');
337 child.emit('close', 0);
338 });
339 return child;
340 }
341
342 const playlistPath = String(args[args.length - 1] || '');
343 const outputDir = path.dirname(playlistPath);
344 process.nextTick(() =>
345 {
346 fs.mkdirSync(outputDir, { recursive: true });
347 fs.writeFileSync(path.join(outputDir, 'master.m3u8'), '#EXTM3U\n');
348 });
349
350 return child;
351 });
352
353 const { createVideoStreamSession } = require('../server/video-stream');
354 await expect(createVideoStreamSession(sourceFile)).resolves.toEqual({
355 sessionId: expect.any(String),
356 durationSeconds: null,
357 videoWidth: 854,
358 videoHeight: 480,
359 subtitleTracks: [
360 expect.objectContaining({
361 fileName: 'subtitle-0.vtt',
362 language: 'und',
363 isDefault: true,
364 }),
365 ],
366 imageSubtitleTracks: [],
367 subtitleSummary: {
368 total: 1,
369 converted: 1,
370 imageBased: 0,
371 skipped: 0,
372 },
373 });
374 });
375
306 test('createVideoStreamSession keeps playback available when subtitle conversion fails', async () =>
376 test('createVideoStreamSession keeps playback available when subtitle conversion fails', async () =>
307 {
377 {
308 mockSpawn.mockImplementation((command, args) =>
378 mockSpawn.mockImplementation((command, args) =>