Merge feature/sidecar-srt-subtitles
@@ -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.
@@ -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
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
try570
{571
const exactStat = fs.statSync(exactPath);572
if (exactStat.isFile()) return exactPath;573
} catch574
{575
// Fall back to case-insensitive directory scan.576
}577
578
const wantedName = `${baseName}.srt`.toLowerCase();579
580
try581
{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
} catch590
{591
return null;592
}593
594
return null;595
}596
562
async function extractSubtitleTracks (sourcePath, outputDir, subtitleStreams)597
async 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
try657
{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
} catch676
{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,@@ -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) =>