@torrent-tv/proxy 2.9.141 → 2.11.0

package/services/hwaccel.js

@@ -148,15 +148,37 @@ function safeDimensions(targetWidth, targetHeight) {
 
 /**
  * Force a keyframe on every segment boundary so each HLS segment is
- * independently decodable and exactly `segmentDurationSec` long.
+ * independently decodable.
+ *
+ * Two grids exist. The usual one is even — a keyframe every
+ * `segmentDurationSec` — and the encoder is free to place them because it is
+ * producing every frame anyway. The other is the SOURCE's own keyframe times,
+ * used when this encode has to be interchangeable with a stream that is
+ * COPIED: a copy can only be cut where the source already has a keyframe, so a
+ * rung meant to splice into it must be cut at exactly those times and nowhere
+ * else. Then the times are given outright.
  *
  * @param {number} segmentDurationSec
+ * @param {number[] | null} [forcedTimes] - Run-relative seconds, ascending.
  * @returns {string[]}
  */
-function keyFrameArgs(segmentDurationSec) {
+function keyFrameArgs(segmentDurationSec, forcedTimes = null) {
+  if (Array.isArray(forcedTimes) && forcedTimes.length > 0) {
+    return ["-force_key_frames", forcedTimes.join(",")];
+  }
   return ["-force_key_frames", `expr:gte(t,n_forced*${segmentDurationSec})`];
 }
 
+/**
+ * Whether an explicit cut list was supplied.
+ *
+ * @param {number[] | null | undefined} forcedTimes
+ * @returns {boolean}
+ */
+function hasForcedTimes(forcedTimes) {
+  return Array.isArray(forcedTimes) && forcedTimes.length > 0;
+}
+
 /** @returns {import("./hwaccel.js").VideoEncoderDescriptor} */
 export function softwareDescriptor() {
   return {
@@ -164,7 +186,7 @@ export function softwareDescriptor() {
     kind: "software",
     device: null,
     inputArgs: [],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps, tonemap }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps, tonemap, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       const chosenPreset = typeof preset === "string" && preset.length > 0 ? preset : SOFTWARE_PRESET;
       // Output frame rate: inherited from the source (rounded/capped) by the
@@ -200,11 +222,24 @@ export function softwareDescriptor() {
         // independent of the PTS offset used on seek-restart — every HLS segment
         // is exactly segmentDurationSec long and starts on a keyframe, so segment
         // boundaries line up with the synthetic playlist with no gaps. (The old
-        // `-force_key_frames expr:gte(t,n_forced*SEG)` broke after a seek because
-        // `t` is offset by `-output_ts_offset`, forcing keyframes at the wrong
-        // places.)
+        // the OLD `expr:` form of -force_key_frames broke after a seek, because
+        // the `t` it reads is shifted by `-output_ts_offset`.)
+        //
+        // An explicit cut LIST is a different thing and does work: verified by
+        // running it, its times are on the run's own timeline — the same one
+        // `-segment_times` is measured on — so both are given one list and
+        // cannot drift apart. It replaces the frame-count GOP, which cannot
+        // describe the source's keyframes because they are not evenly spaced.
+        // `-g` stays as an upper bound on the interval: an extra keyframe
+        // inside a segment costs a little bitrate and cuts nothing, while
+        // leaving the interval unbounded means a driver that ignores the list
+        // produces one enormous segment instead of a wrong but cut one.
+        // `-keyint_min` goes, since a MINIMUM interval is the one thing that
+        // could argue with a forced keyframe.
         "-g", String(segmentDurationSec * outFps),
-        "-keyint_min", String(segmentDurationSec * outFps),
+        ...(hasForcedTimes(forcedKeyframeTimes)
+          ? keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
+          : ["-keyint_min", String(segmentDurationSec * outFps)]),
         "-sc_threshold", "0"
       ];
     }
@@ -224,14 +259,14 @@ function vaapiDescriptor(device) {
     inputArgs: ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", device],
     // No fps filter: VAAPI inherits the source rate and keeps keyframes on the
     // grid via time-based -force_key_frames, so it already honours source fps.
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf",
         `scale_vaapi=w=${w}:h=${h}:force_original_aspect_ratio=decrease`,
         "-c:v", "h264_vaapi",
         "-qp", "24",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -247,13 +282,13 @@ function qsvDescriptor(device) {
     kind: "qsv",
     device,
     inputArgs: ["-hwaccel", "qsv", "-qsv_device", device],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf", `scale_qsv=w=${w}:h=${h}`,
         "-c:v", "h264_qsv",
         "-global_quality", "24",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -269,7 +304,7 @@ function nvencDescriptor() {
     // No fps filter: NVENC is fast and places keyframes by time-based
     // -force_key_frames, so it inherits the exact source rate (fractional
     // included) with no need to round or cap. Same rationale as VAAPI/QSV.
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf",
@@ -278,7 +313,7 @@ function nvencDescriptor() {
         "-preset", "p4",
         "-cq", "24",
         "-pix_fmt", "yuv420p",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -296,7 +331,7 @@ function v4l2m2mDescriptor() {
     kind: "v4l2m2m",
     device: null,
     inputArgs: [],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, fps }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, fps, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       const outFps = Number.isInteger(fps) && fps > 0 ? fps : TRANSCODE_FPS;
       return [
@@ -308,8 +343,12 @@ function v4l2m2mDescriptor() {
         // userspace").
         "-num_capture_buffers", "32",
         "-b:v", "3M",
+        // Kept even with an explicit cut list, as an upper bound on the
+        // interval: this encoder is the one known not always to honour keyframe
+        // hints, and without any bound a list it ignores yields one segment for
+        // the whole file rather than a wrongly-cut one.
         "-g", String(outFps * segmentDurationSec),
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -322,7 +361,7 @@ function v4l2m2mDescriptor() {
  * @property {"software"|"vaapi"|"qsv"|"nvenc"|"v4l2m2m"} kind
  * @property {string|null} device
  * @property {string[]} inputArgs
- * @property {(opts: { targetWidth: number, targetHeight: number, segmentDurationSec: number }) => string[]} buildVideoArgs
+ * @property {(opts: { targetWidth: number, targetHeight: number, segmentDurationSec: number, preset?: string, fps?: number, tonemap?: boolean, forcedKeyframeTimes?: number[] | null }) => string[]} buildVideoArgs
  */
 
 /**

package/test/behind-head-repair.test.js

@@ -0,0 +1,187 @@
+/**
+ * @file A segment request below the running encode must not be held for ever.
+ *
+ * The encoder only moves forward from where its run began, so a request BELOW
+ * that point cannot be answered by anything the run does. Every other far
+ * request is a claim the running encode may yet reach; this one is a hole.
+ *
+ * Measured 2026-08-11: a quality switch placed a run at segment #770 while the
+ * player needed #757, and the request was held for two minutes forty-one while
+ * the encoder produced 409 s of video nobody had asked for at 2.48x. The
+ * placement that caused it is fixed; this is the guard that stops the SHAPE
+ * from hanging a session again, whatever puts it there.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const SESSION_ID = "bbbbbbbb-cccc-dddd-eeee-ffffffffffff";
+const SEGMENT_SECONDS = 4;
+const RUN_STARTS_AT = 770;
+const WANTED = 757;
+
+/**
+ * A session whose run began well past the segment being asked for.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string, restarts: number[] }>}
+ */
+async function managerWithRunAhead() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "behind-head-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    fileName: "film.avi",
+    startedAt: Date.now(),
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    lastError: "",
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    transcodeVideo: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: Array.from({ length: 1937 }, (_, index) => index * SEGMENT_SECONDS),
+    segmentCount: 1936,
+    encodeStartIndex: RUN_STARTS_AT,
+    encodeRunGeneration: 0,
+    lastRestartAt: 0,
+    seekFailureTarget: -1,
+    seekFailureCount: 0,
+    seekSettleTimer: null,
+    seekTarget: null,
+    waitEpoch: 0,
+    firstWantedAt: new Map(),
+    ffmpeg: { pid: 4321, exitCode: null, signalCode: null, kill() {}, once(event, handler) { if (event === "exit") handler(); } },
+    progress: { state: "running", processedSeconds: RUN_STARTS_AT * SEGMENT_SECONDS + 400, startPositionSeconds: RUN_STARTS_AT * SEGMENT_SECONDS }
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  const restarts = [];
+  return { manager, session, dirPath, restarts };
+}
+
+test("a request behind the run is repaired once it has waited", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Asked for four seconds ago and still unanswerable.
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    WANTED - 1,
+    "the encoder must be moved back to it — one segment early, for the preceding keyframe"
+  );
+});
+
+test("a request behind the run is left alone at first", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "a burst around a reported seek settles by itself, and the seek is what should move the encoder"
+  );
+});
+
+test("a seek already settling is not overridden", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+  // The viewer has stated where they are and it is about to be acted on.
+  session.seekTarget = 1200;
+  session.seekSettleTimer = setTimeout(() => {}, 60_000);
+  t.after(() => clearTimeout(session.seekSettleTimer));
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    1200,
+    "a statement from the viewer outranks anything inferred from what the player is fetching"
+  );
+});
+
+test("a playlist scan far below the run is left where it belongs", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // A player that cannot get what it wants scans the playlist: field log
+  // 2026-08-02, probes at #178, #681, #725, #807, #74, #245, #387 within half a
+  // second. Steering on the lowest of those put the encoder at the start of the
+  // film and left the viewer's own requests unreachable ahead of it — the exact
+  // reason request-steering was removed from this proxy.
+  const probe = 74;
+  session.firstWantedAt.set(probe, Date.now() - 30_000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(probe), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "a misplaced run is out by a buffer; a scan probe is out by anything, and the two must not be confused"
+  );
+});
+
+test("a rung whose encoder was stopped is not brought back by a held request", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // What a quality switch leaves behind: the rung nobody is watching, parked.
+  session.ffmpeg = null;
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "restarting it would put a second encoder on a host sized for one, for a rung nobody is watching"
+  );
+});
+
+test("a request ahead of the run is not touched", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const ahead = RUN_STARTS_AT + 400;
+  session.firstWantedAt.set(ahead, Date.now() - 30_000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(ahead), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "the running encode may yet reach it; restarting on a far request is what produced nine restarts in a minute"
+  );
+});

package/test/keyframe-index-accuracy.test.js

@@ -0,0 +1,68 @@
+/**
+ * @file How well a container's keyframe index describes its own file.
+ *
+ * The cut times of a copied video ARE its index — ffmpeg can only cut where a
+ * keyframe already is — and an index can be wrong: measured 2026-08-06, one
+ * claimed a keyframe at 157.99 s where the real ones were 153.82 and 164.247.
+ * Whether a re-encoded rung can be cut on that same grid and spliced into the
+ * copy depends entirely on how often that happens, so it is counted.
+ *
+ * No scan is involved and no undownloaded byte is touched: each produced piece
+ * states where it truly begins, and it is already read whole in order to be
+ * stamped. Only boundaries that were actually produced are counted — the parts
+ * somebody watched.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { newIndexCheck, noteIndexDeviation } from "../services/hls-session-manager.js";
+
+test("an index that describes its file exactly is reported as such", () => {
+  const check = newIndexCheck();
+
+  for (let index = 0; index < 4; index += 1) {
+    noteIndexDeviation(check, index, 0);
+  }
+
+  assert.equal(check.checked, 4);
+  assert.equal(check.disagreed, 0, "nothing disagreed — which is a finding, not silence");
+  assert.equal(check.maxDeviationSec, 0);
+});
+
+test("a boundary the index placed wrongly is counted, with how far out it was", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 0, 0);
+  // The measured shape: the playlist said 157.99 s, the file cut at 153.82 s.
+  noteIndexDeviation(check, 2, 4.17);
+  noteIndexDeviation(check, 3, 0.01);
+
+  assert.equal(check.checked, 3);
+  assert.equal(check.disagreed, 1);
+  assert.equal(check.firstDisagreementIndex, 2);
+  assert.equal(
+    check.maxDeviationSec,
+    4.17,
+    "the size of the error is what decides whether a rung can be cut on this grid"
+  );
+});
+
+test("a deviation within tolerance is not a disagreement, but still shows in the worst case", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 0, 0.2);
+
+  assert.equal(check.disagreed, 0, "rounding in a container's timestamps is not the index being wrong");
+  assert.equal(check.maxDeviationSec, 0.2, "and it is still worth knowing how close to the line it ran");
+});
+
+test("a segment requested again is not new evidence", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 1, 0.9);
+  noteIndexDeviation(check, 1, 0.9);
+  noteIndexDeviation(check, 1, 0.9);
+
+  assert.equal(check.checked, 1, "a repeat request is the same boundary, counted once");
+  assert.equal(check.disagreed, 1);
+});