BlueGit

timfa filemanager

Merge fix/video-stream-stutter

timfa Tim Falken · pushed by timfa

Authored 2026-05-14 · 6 months ago

Hash
9b31f2267b2169e58c8e1738fab65b18fad073d4
3 files changed +171 −3
.github/technical-reference.md +3 −2
@@ -93,11 +93,12 @@
93 93
94 94 ## server/video-stream.js
95 95 - createVideoStreamSession(sourcePath) - Probes the input duration, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves only when HLS assets are present (not subtitle files alone); returns durationSeconds, subtitleTracks, and subtitleSummary {total, converted, skipped}.
96 - sendVideoStreamAsset(sessionId, assetPath, req, res) - Serves HLS playlists, segments, and extracted subtitle files, tracks request lifecycle, and stops session processing when clients go idle/disconnect.
96 - sendVideoStreamAsset(sessionId, assetPath, req, res) - Serves HLS playlists, segments, and extracted subtitle files, tracks request lifecycle, and prunes old .ts segments once playback has moved beyond the configured retention window.
97 97 - releaseVideoStreamSession(sessionId) - Explicitly stops an active stream session, terminates ffmpeg, and removes temporary assets.
98 98 - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
99 99 - STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
100 - STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated.
100 - STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
101 - STREAM_SEGMENT_RETENTION_COUNT - Number of most-recent HLS segment indices kept on disk while older segments are pruned (default 180, overridable via VIDEO_STREAM_SEGMENT_RETENTION_COUNT).
101 102
102 103 ## server/db.js
103 104 - initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
@@ -93,11 +93,12 @@
93
93
94## server/video-stream.js
94## server/video-stream.js
95- createVideoStreamSession(sourcePath) - Probes the input duration, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves only when HLS assets are present (not subtitle files alone); returns durationSeconds, subtitleTracks, and subtitleSummary {total, converted, skipped}.
95- createVideoStreamSession(sourcePath) - Probes the input duration, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves only when HLS assets are present (not subtitle files alone); returns durationSeconds, subtitleTracks, and subtitleSummary {total, converted, skipped}.
96- sendVideoStreamAsset(sessionId, assetPath, req, res) - Serves HLS playlists, segments, and extracted subtitle files, tracks request lifecycle, and stops session processing when clients go idle/disconnect.
96- sendVideoStreamAsset(sessionId, assetPath, req, res) - Serves HLS playlists, segments, and extracted subtitle files, tracks request lifecycle, and prunes old .ts segments once playback has moved beyond the configured retention window.
97- releaseVideoStreamSession(sessionId) - Explicitly stops an active stream session, terminates ffmpeg, and removes temporary assets.
97- releaseVideoStreamSession(sessionId) - Explicitly stops an active stream session, terminates ffmpeg, and removes temporary assets.
98- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
98- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
99- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
99- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
100- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated.
100- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
101- STREAM_SEGMENT_RETENTION_COUNT - Number of most-recent HLS segment indices kept on disk while older segments are pruned (default 180, overridable via VIDEO_STREAM_SEGMENT_RETENTION_COUNT).
101
102
102## server/db.js
103## server/db.js
103- initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
104- initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
server/video-stream.js +83 −1
@@ -9,9 +9,17 @@ const path = require('path');
9 9 const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
10 10 const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
11 11 const STREAM_READY_TIMEOUT_MS = 20 * 1000;
12 const STREAM_IDLE_STOP_MS = 20 * 1000;
12 const STREAM_IDLE_STOP_MS = 5 * 60 * 1000;
13 const STREAM_SEGMENT_RETENTION_COUNT = parseSegmentRetentionCount(process.env.VIDEO_STREAM_SEGMENT_RETENTION_COUNT);
13 14 const sessions = new Map();
14 15
16 function parseSegmentRetentionCount (value)
17 {
18 const parsed = Number.parseInt(String(value || ''), 10);
19 if (Number.isInteger(parsed) && parsed >= 30) return parsed;
20 return 180;
21 }
22
15 23 function hasInitialHlsAssets (outputDir)
16 24 {
17 25 try
@@ -139,6 +147,74 @@ function finishAssetRequest (session)
139 147 if (session.activeRequests === 0) scheduleIdleStop(session);
140 148 }
141 149
150 function parseSegmentIndexFromAssetPath (assetPath)
151 {
152 const baseName = path.basename(String(assetPath || ''));
153 const match = baseName.match(/^stream_\d+_segment_(\d+)\.ts$/i);
154 if (!match) return null;
155
156 const segmentIndex = Number.parseInt(match[1], 10);
157 return Number.isInteger(segmentIndex) ? segmentIndex : null;
158 }
159
160 function runSegmentPrune (session)
161 {
162 if (session.segmentPruneRunning) return;
163 if (session.segmentPrunePendingCutoff <= session.segmentPrunedUntil) return;
164
165 const cutoff = session.segmentPrunePendingCutoff;
166 session.segmentPruneRunning = true;
167
168 fs.promises.readdir(session.outputDir)
169 .then((entries) =>
170 {
171 const removals = [];
172 for (const entryName of entries)
173 {
174 const match = String(entryName).match(/^stream_\d+_segment_(\d+)\.ts$/i);
175 if (!match) continue;
176 const segmentIndex = Number.parseInt(match[1], 10);
177 if (!Number.isInteger(segmentIndex)) continue;
178 if (segmentIndex > cutoff) continue;
179
180 removals.push(
181 fs.promises.unlink(path.join(session.outputDir, entryName)).catch(() =>
182 {
183 // Ignore races while ffmpeg rotates temp files and request handlers read segments.
184 })
185 );
186 }
187 return Promise.all(removals);
188 })
189 .then(() =>
190 {
191 session.segmentPrunedUntil = Math.max(session.segmentPrunedUntil, cutoff);
192 })
193 .catch(() =>
194 {
195 // Best effort cleanup; keep streaming even if pruning fails.
196 })
197 .finally(() =>
198 {
199 session.segmentPruneRunning = false;
200 if (session.segmentPrunePendingCutoff > session.segmentPrunedUntil)
201 {
202 runSegmentPrune(session);
203 }
204 });
205 }
206
207 function scheduleSegmentPrune (session, segmentIndex)
208 {
209 if (!Number.isInteger(segmentIndex) || segmentIndex < 0) return;
210
211 const pruneCutoff = segmentIndex - STREAM_SEGMENT_RETENTION_COUNT;
212 if (pruneCutoff <= session.segmentPrunedUntil) return;
213
214 session.segmentPrunePendingCutoff = Math.max(session.segmentPrunePendingCutoff, pruneCutoff);
215 runSegmentPrune(session);
216 }
217
142 218 function runCommand (command, args)
143 219 {
144 220 return new Promise((resolve, reject) =>
@@ -543,6 +619,9 @@ async function createVideoStreamSession (sourcePath)
543 619 activeRequests: 0,
544 620 lastActivityAt: Date.now(),
545 621 idleTimer: null,
622 segmentPruneRunning: false,
623 segmentPrunePendingCutoff: -1,
624 segmentPrunedUntil: -1,
546 625 };
547 626
548 627 session.readyPromise = initialiseSession(session).catch((err) =>
@@ -594,6 +673,9 @@ async function sendVideoStreamAsset (sessionId, assetPath, req, res)
594 673 throw makeHttpError(404, 'Stream asset not found.');
595 674 }
596 675
676 const segmentIndex = parseSegmentIndexFromAssetPath(relativeAssetPath);
677 if (segmentIndex !== null) scheduleSegmentPrune(session, segmentIndex);
678
597 679 await waitForFile(resolvedPath, session);
598 680 res.set('Cache-Control', 'private, no-store');
599 681 res.type(contentTypeForAsset(resolvedPath));
@@ -9,9 +9,17 @@ const path = require('path');
9const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
9const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
10const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
10const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
11const STREAM_READY_TIMEOUT_MS = 20 * 1000;
11const STREAM_READY_TIMEOUT_MS = 20 * 1000;
12const STREAM_IDLE_STOP_MS = 20 * 1000;
12const STREAM_IDLE_STOP_MS = 5 * 60 * 1000;
13const STREAM_SEGMENT_RETENTION_COUNT = parseSegmentRetentionCount(process.env.VIDEO_STREAM_SEGMENT_RETENTION_COUNT);
13const sessions = new Map();
14const sessions = new Map();
14
15
16function parseSegmentRetentionCount (value)
17{
18 const parsed = Number.parseInt(String(value || ''), 10);
19 if (Number.isInteger(parsed) && parsed >= 30) return parsed;
20 return 180;
21}
22
15function hasInitialHlsAssets (outputDir)
23function hasInitialHlsAssets (outputDir)
16{
24{
17 try
25 try
@@ -139,6 +147,74 @@ function finishAssetRequest (session)
139 if (session.activeRequests === 0) scheduleIdleStop(session);
147 if (session.activeRequests === 0) scheduleIdleStop(session);
140}
148}
141
149
150function parseSegmentIndexFromAssetPath (assetPath)
151{
152 const baseName = path.basename(String(assetPath || ''));
153 const match = baseName.match(/^stream_\d+_segment_(\d+)\.ts$/i);
154 if (!match) return null;
155
156 const segmentIndex = Number.parseInt(match[1], 10);
157 return Number.isInteger(segmentIndex) ? segmentIndex : null;
158}
159
160function runSegmentPrune (session)
161{
162 if (session.segmentPruneRunning) return;
163 if (session.segmentPrunePendingCutoff <= session.segmentPrunedUntil) return;
164
165 const cutoff = session.segmentPrunePendingCutoff;
166 session.segmentPruneRunning = true;
167
168 fs.promises.readdir(session.outputDir)
169 .then((entries) =>
170 {
171 const removals = [];
172 for (const entryName of entries)
173 {
174 const match = String(entryName).match(/^stream_\d+_segment_(\d+)\.ts$/i);
175 if (!match) continue;
176 const segmentIndex = Number.parseInt(match[1], 10);
177 if (!Number.isInteger(segmentIndex)) continue;
178 if (segmentIndex > cutoff) continue;
179
180 removals.push(
181 fs.promises.unlink(path.join(session.outputDir, entryName)).catch(() =>
182 {
183 // Ignore races while ffmpeg rotates temp files and request handlers read segments.
184 })
185 );
186 }
187 return Promise.all(removals);
188 })
189 .then(() =>
190 {
191 session.segmentPrunedUntil = Math.max(session.segmentPrunedUntil, cutoff);
192 })
193 .catch(() =>
194 {
195 // Best effort cleanup; keep streaming even if pruning fails.
196 })
197 .finally(() =>
198 {
199 session.segmentPruneRunning = false;
200 if (session.segmentPrunePendingCutoff > session.segmentPrunedUntil)
201 {
202 runSegmentPrune(session);
203 }
204 });
205}
206
207function scheduleSegmentPrune (session, segmentIndex)
208{
209 if (!Number.isInteger(segmentIndex) || segmentIndex < 0) return;
210
211 const pruneCutoff = segmentIndex - STREAM_SEGMENT_RETENTION_COUNT;
212 if (pruneCutoff <= session.segmentPrunedUntil) return;
213
214 session.segmentPrunePendingCutoff = Math.max(session.segmentPrunePendingCutoff, pruneCutoff);
215 runSegmentPrune(session);
216}
217
142function runCommand (command, args)
218function runCommand (command, args)
143{
219{
144 return new Promise((resolve, reject) =>
220 return new Promise((resolve, reject) =>
@@ -543,6 +619,9 @@ async function createVideoStreamSession (sourcePath)
543 activeRequests: 0,
619 activeRequests: 0,
544 lastActivityAt: Date.now(),
620 lastActivityAt: Date.now(),
545 idleTimer: null,
621 idleTimer: null,
622 segmentPruneRunning: false,
623 segmentPrunePendingCutoff: -1,
624 segmentPrunedUntil: -1,
546 };
625 };
547
626
548 session.readyPromise = initialiseSession(session).catch((err) =>
627 session.readyPromise = initialiseSession(session).catch((err) =>
@@ -594,6 +673,9 @@ async function sendVideoStreamAsset (sessionId, assetPath, req, res)
594 throw makeHttpError(404, 'Stream asset not found.');
673 throw makeHttpError(404, 'Stream asset not found.');
595 }
674 }
596
675
676 const segmentIndex = parseSegmentIndexFromAssetPath(relativeAssetPath);
677 if (segmentIndex !== null) scheduleSegmentPrune(session, segmentIndex);
678
597 await waitForFile(resolvedPath, session);
679 await waitForFile(resolvedPath, session);
598 res.set('Cache-Control', 'private, no-store');
680 res.set('Cache-Control', 'private, no-store');
599 res.type(contentTypeForAsset(resolvedPath));
681 res.type(contentTypeForAsset(resolvedPath));
tests/video-stream.test.js +85 −0
@@ -18,6 +18,38 @@ function makeChildProcess ()
18 18 return child;
19 19 }
20 20
21 function makeReqRes ()
22 {
23 const req = new EventEmitter();
24 const res = new EventEmitter();
25 const headers = {};
26
27 res.set = (name, value) =>
28 {
29 headers[name] = value;
30 return res;
31 };
32 res.type = () => res;
33 res.sendFile = (targetPath, cb) =>
34 {
35 process.nextTick(() =>
36 {
37 if (!fs.existsSync(targetPath))
38 {
39 const err = new Error('File not found');
40 err.code = 'ENOENT';
41 cb(err);
42 return;
43 }
44
45 res.emit('finish');
46 cb();
47 });
48 };
49
50 return { req, res, headers };
51 }
52
21 53 describe('video stream bootstrap', () =>
22 54 {
23 55 let mockSpawn;
@@ -314,4 +346,57 @@ describe('video stream bootstrap', () =>
314 346 },
315 347 });
316 348 });
349
350 test('sendVideoStreamAsset prunes old segment files after playback moves far ahead', async () =>
351 {
352 mockSpawn.mockImplementation((command, args) =>
353 {
354 const child = makeChildProcess();
355 const exeName = path.basename(String(command || '')).toLowerCase();
356
357 if (exeName.includes('ffprobe'))
358 {
359 process.nextTick(() =>
360 {
361 child.stdout.emit('data', Buffer.from(JSON.stringify({
362 streams: [
363 { codec_type: 'video', codec_name: 'h264', tags: {}, disposition: {} },
364 { codec_type: 'audio', codec_name: 'aac', tags: {}, disposition: { default: 1 } },
365 ],
366 })));
367 child.emit('close', 0);
368 });
369 return child;
370 }
371
372 const playlistPath = String(args[args.length - 1] || '');
373 const outputDir = path.dirname(playlistPath);
374 process.nextTick(() =>
375 {
376 fs.mkdirSync(outputDir, { recursive: true });
377 fs.writeFileSync(path.join(outputDir, 'master.m3u8'), '#EXTM3U\n');
378 });
379 return child;
380 });
381
382 const streamModule = require('../server/video-stream');
383 const session = await streamModule.createVideoStreamSession(sourceFile);
384 const sessionDir = path.join(streamModule.STREAM_ROOT_DIR, session.sessionId);
385
386 for (let segmentIndex = 0; segmentIndex <= 220; segmentIndex += 1)
387 {
388 const fileName = `stream_0_segment_${String(segmentIndex).padStart(6, '0')}.ts`;
389 fs.writeFileSync(path.join(sessionDir, fileName), `segment-${segmentIndex}`);
390 }
391
392 const { req, res } = makeReqRes();
393 await streamModule.sendVideoStreamAsset(session.sessionId, 'stream_0_segment_000220.ts', req, res);
394
395 await new Promise((resolve) => setTimeout(resolve, 80));
396
397 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000040.ts'))).toBe(false);
398 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000041.ts'))).toBe(true);
399
400 streamModule.releaseVideoStreamSession(session.sessionId);
401 });
317 402 });
@@ -18,6 +18,38 @@ function makeChildProcess ()
18 return child;
18 return child;
19}
19}
20
20
21function makeReqRes ()
22{
23 const req = new EventEmitter();
24 const res = new EventEmitter();
25 const headers = {};
26
27 res.set = (name, value) =>
28 {
29 headers[name] = value;
30 return res;
31 };
32 res.type = () => res;
33 res.sendFile = (targetPath, cb) =>
34 {
35 process.nextTick(() =>
36 {
37 if (!fs.existsSync(targetPath))
38 {
39 const err = new Error('File not found');
40 err.code = 'ENOENT';
41 cb(err);
42 return;
43 }
44
45 res.emit('finish');
46 cb();
47 });
48 };
49
50 return { req, res, headers };
51}
52
21describe('video stream bootstrap', () =>
53describe('video stream bootstrap', () =>
22{
54{
23 let mockSpawn;
55 let mockSpawn;
@@ -314,4 +346,57 @@ describe('video stream bootstrap', () =>
314 },
346 },
315 });
347 });
316 });
348 });
349
350 test('sendVideoStreamAsset prunes old segment files after playback moves far ahead', async () =>
351 {
352 mockSpawn.mockImplementation((command, args) =>
353 {
354 const child = makeChildProcess();
355 const exeName = path.basename(String(command || '')).toLowerCase();
356
357 if (exeName.includes('ffprobe'))
358 {
359 process.nextTick(() =>
360 {
361 child.stdout.emit('data', Buffer.from(JSON.stringify({
362 streams: [
363 { codec_type: 'video', codec_name: 'h264', tags: {}, disposition: {} },
364 { codec_type: 'audio', codec_name: 'aac', tags: {}, disposition: { default: 1 } },
365 ],
366 })));
367 child.emit('close', 0);
368 });
369 return child;
370 }
371
372 const playlistPath = String(args[args.length - 1] || '');
373 const outputDir = path.dirname(playlistPath);
374 process.nextTick(() =>
375 {
376 fs.mkdirSync(outputDir, { recursive: true });
377 fs.writeFileSync(path.join(outputDir, 'master.m3u8'), '#EXTM3U\n');
378 });
379 return child;
380 });
381
382 const streamModule = require('../server/video-stream');
383 const session = await streamModule.createVideoStreamSession(sourceFile);
384 const sessionDir = path.join(streamModule.STREAM_ROOT_DIR, session.sessionId);
385
386 for (let segmentIndex = 0; segmentIndex <= 220; segmentIndex += 1)
387 {
388 const fileName = `stream_0_segment_${String(segmentIndex).padStart(6, '0')}.ts`;
389 fs.writeFileSync(path.join(sessionDir, fileName), `segment-${segmentIndex}`);
390 }
391
392 const { req, res } = makeReqRes();
393 await streamModule.sendVideoStreamAsset(session.sessionId, 'stream_0_segment_000220.ts', req, res);
394
395 await new Promise((resolve) => setTimeout(resolve, 80));
396
397 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000040.ts'))).toBe(false);
398 expect(fs.existsSync(path.join(sessionDir, 'stream_0_segment_000041.ts'))).toBe(true);
399
400 streamModule.releaseVideoStreamSession(session.sessionId);
401 });
317});
402});