@torrent-tv/proxy 2.75.0 → 2.76.0

package/CLAUDE.md

@@ -33,6 +33,14 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     `deselect` or `critical`, and `registry.js`, which holds one per torrent and
     owns the cross-torrent rule that withholds the speculative levels while
     anything urgent is missing anywhere. See `docs/download-architecture.md`.
+  - `output/` — domain layer: `OutputSpec`, `VideoOutput`, `AudioOutput`,
+    `CutGrid`. What a session PRODUCES — which tracks, in what form, cut how,
+    packaged how — and therefore its identity: two outputs whose parameters
+    agree ARE the same output, and the encoded result is reused by definition.
+    Nothing about a VIEWER appears in it (not the consumer id, not where they
+    started, not their viewport), and nothing about the request that does not
+    change a byte of the result. `hls-session-manager` builds one and keys the
+    session on it.
   - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
     `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
     (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
@@ -43,7 +51,9 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     RFC 9559 §5.1.4.1, FlagOriginal/Commentary only on audio, tkhd
     track_enabled / alternate_group, elng BCP47).
   - `orchestrators/` — application layer: `ContainerOrchestrator` (detect + per-file
-    cache, `getTracks`/`getKeyframeIndex`), `SubtitleOrchestrator` (wraps
+    cache, `getTracks`/`getMediaInfo`/`getKeyframeIndex` — the keyframe table is
+    a property of immutable bytes like the other two, memoized on the container
+    and read once per file by whoever asks), `SubtitleOrchestrator` (wraps
     `torrent-worker/subtitle-cues.js` + `Container` tracks, warm/push). The walk
     itself is `MatroskaContainer.walkHeldClusters` / `Mp4Container.readHeldSamples`;
     `subtitle-cues.js` supplies the torrent's read policy and keeps the cursor.

package/biome.json

@@ -17,5 +17,186 @@
 				"noPrivateImports": "error"
 			}
 		}
-	}
+	},
+	"overrides": [
+		{
+			"includes": [
+				"services/demand/**",
+				"services/piece-store/**",
+				"services/segment-formats/**",
+				"services/tracks/**",
+				"services/output/**",
+				"services/viewer/**",
+				"services/encode/**",
+				"services/source/**",
+				"services/torrent/**"
+			],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": ["../**"],
+										"message": "This layer states facts and imports nothing above itself. Anything it needs from outside — a logger, a clock, a way to read bytes — is passed in."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/download/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../container/**",
+											"../controllers/**",
+											"../encode/**",
+											"../orchestrators/**",
+											"../output/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../tracks/**",
+											"../viewer/**"
+										],
+										"message": "What the swarm is told is decided from what is wanted (demand/) and what is held (piece-store/), and from nothing else."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/container/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../controllers/**",
+											"../demand/**",
+											"../download/**",
+											"../encode/**",
+											"../orchestrators/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../viewer/**"
+										],
+										"message": "A container answers for itself and hands out tracks/. It knows nothing of torrents, encoders or viewers: the four functions it is built with are its whole outside world."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/orchestrators/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../controllers/**",
+											"../demand/**",
+											"../download/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../viewer/**"
+										],
+										"message": "An orchestrator composes the layers below it. Reaching sideways into serving or downloading is what put a scenario in two places before."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/controllers/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../demand/**",
+											"../download/**",
+											"../encode/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../viewer/**"
+										],
+										"message": "A controller translates a request for an orchestrator. Every layer below the orchestrator is reached through it, never around it."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/torrent-worker/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../hls-session-manager.js",
+											"../controllers/**",
+											"../encode/**",
+											"../output/**",
+											"../viewer/**",
+											"../segment-formats/**"
+										],
+										"message": "The torrent thread serves bytes. What is produced from them, and for whom, is decided in the main thread and never asked of this one."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		}
+	]
 }

package/docs/container-architecture.md

@@ -162,7 +162,8 @@ flowchart TB
 ## Orchestrators & Controllers
 
 - `ContainerFactory.create({readRange,fileSize})` — sniffs 16 bytes, returns precise `Container` subclass. No torrent knowledge.
-- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getKeyframeIndex()`. Transport-agnostic.
+- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getMediaInfo()` / `getKeyframeIndex()`. Transport-agnostic.
+- **The keyframe table is read once per file**, like the other two. `Container.readKeyframeIndex` memoizes and each format implements `parseKeyframeIndex`, so the wait belongs to the FILE: two sessions created in the same moment join one read rather than making two, which is exactly what two viewers opening one film do. A read that THREW is not remembered — the bytes it needed may simply not have arrived. Who asks: `torrent-worker/container-tracks.js` `containerKeyframesOf`, over the torrent, reached from the session manager by the `container-keyframes` command. The manager's own HTTP read remains for a manager wired without that path (every unit test).
 - `SubtitleOrchestrator` — wraps `torrent-worker/subtitle-cues.js` (`planFor`, `cuesHeldFor`, `warmSubtitleCues`) behind the `ContainerTrack` abstraction. Routes depend on this, not on the worker directly. The reading itself is the containers' — that module supplies the torrent's read policy and keeps the cursor.
 - `PlaybackController` / `SubtitleController` — thin interface adapters; `routes/api/*` delegate to them, handle HTTP headers (`X-Subtitle-Language`, `X-Subtitle-Cursor`) only.
 

package/docs/encode-run-state.md

@@ -1,4 +1,4 @@
-<!-- GENERATED from services/encode-run-state.js by scripts/render-run-graph.js.
+<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.
      Do not edit by hand: change the table and run `npm run graph`. -->
 
 # The encoder run — states and transitions

package/knip.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "entry": [
+    "test/*.test.js"
+  ],
+  "project": [
+    "bin/**/*.js",
+    "routes/**/*.js",
+    "services/**/*.js",
+    "utils/**/*.js",
+    "server.js",
+    "test/**/*.js"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.75.0",
+  "version": "2.76.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/warm/post.js

@@ -3,7 +3,7 @@ import {
   countVideoFiles,
   matchSidecarFiles,
   TEXT_SUBTITLE_SIDECAR_EXTENSIONS
-} from "../../../../services/sidecar-files.js";
+} from "../../../../services/torrent/files.js";
 
 /**
  * Start fetching a source before anyone asks to play it.

package/routes/api/transcode-sessions/post.js

@@ -1,185 +1,185 @@
-/**
- * Create or return an existing HLS transcode session for a torrent file.
- *
- * POST /api/transcode-sessions
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sourceRegistry: object, torrentPool: object }} deps
- * @returns {Promise<void>}
- */
-
-import { logger } from "../../../utils/logger.js";
-
-/**
- * Extract a plain object from the request body, guarding against
- * non-object payloads (arrays, primitives, null).
- *
- * @param {unknown} body
- * @returns {Record<string, unknown>}
- */
-function getPayload(body) {
-  if (body && typeof body === "object" && !Array.isArray(body)) {
-    return body;
-  }
-  return {};
-}
-
-/**
- * Claim the source's file so the pool cannot clean it up under a live session.
- *
- * Asynchronous underneath — the torrent lives on another thread — but the
- * caller needs a release function immediately, so the claim is chased and the
- * release waits for it.
- *
- * @param {{ sourceRegistry: object, torrentPool: object, sourceKey: string, fileIndex: number }} params
- * @returns {() => void}
- */
-function holdSource({ sourceRegistry, torrentPool, sourceKey, fileIndex }) {
-  let release = null;
-  let releasedEarly = false;
-  const record = sourceRegistry?.get?.(sourceKey);
-  if (!record) {
-    return () => {};
-  }
-  void Promise.resolve(torrentPool.getTorrent(record.sourceType, record.source))
-    .then((torrent) => {
-      release = torrentPool.acquireFile(torrent, fileIndex);
-      if (releasedEarly) {
-        release();
-      }
-    })
-    .catch(() => {});
-  return () => {
-    releasedEarly = true;
-    if (typeof release === "function") {
-      release();
-      release = null;
-    }
-  };
-}
-
-export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager, sourceRegistry, torrentPool }) {
-  const payload = getPayload(req.body);
-  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
-  const fileIndex = Number(payload.fileIndex);
-  const transcodeVideo = payload.transcodeVideo === true;
-  const transcodeAudio = payload.transcodeAudio === true;
-  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
-  const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
-  const targetWidth = Number(payload.targetWidth);
-  const targetHeight = Number(payload.targetHeight);
-  // Manual quality: the target box is a user-forced resolution, encoded exactly
-  // (capped to source), with the realtime budget's auto-downscale + runtime
-  // downswitch disabled for the session.
-  const manualQuality = payload.manualQuality === true;
-  // Whether this browser will take its audio from a separate rendition group in
-  // the master playlist rather than muxed into the picture. It has to say so:
-  // publishing renditions AND muxing the same audio would play it twice, while
-  // a browser that does not know about them would get no sound at all.
-  const audioRenditions = payload.audioRenditions === true;
-  const startPositionSeconds = Number(payload.startPositionSeconds);
-  const audioTrackIndex = Number(payload.audioTrackIndex);
-  // Which container to produce. The browser knows what its media stack will
-  // accept for the tracks it asked to be copied; an absent or unknown value
-  // leaves the proxy's own `--segment-format` in charge.
-  const segmentFormatId =
-    typeof payload.segmentFormat === "string" ? payload.segmentFormat.trim() : "";
-
-  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
-    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
-  }
-
-  try {
-    const session = await hlsSessionManager.createOrGetSession({
-      sourceKey,
-      fileIndex,
-      transcodeVideo,
-      transcodeAudio,
-      consumerId,
-      fileName,
-      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
-      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
-      manualQuality,
-      audioRenditions,
-      startPositionSeconds:
-        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
-          ? startPositionSeconds
-          : 0,
-      audioTrackIndex:
-        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
-      segmentFormatId,
-      // Hold the torrent for as long as this session lives. Reads take a claim
-      // only while they run, and a seek leaves a gap with no read at all — the
-      // disk sweep caught that gap on 2026-08-06 and deleted the film being
-      // watched.
-      // Takes the file to hold, because a session does not always read the file
-      // it was created for: a release whose dub ships as its own file gives that
-      // soundtrack a session of its own, reading a different index of the same
-      // torrent. Defaults to the picture, which is every other case.
-      acquireSource: (heldFileIndex = fileIndex) =>
-        holdSource({
-          sourceRegistry,
-          torrentPool,
-          sourceKey,
-          fileIndex: Number.isInteger(heldFileIndex) ? heldFileIndex : fileIndex
-        })
-    });
-    // The index of quality variants, when this session has more than one to
-    // offer. Its presence is what tells the browser it can change quality
-    // without a new session: the player switches variants itself, appending the
-    // new one after what is already buffered. Absent for a copied video, whose
-    // segments are cut at the source's own keyframes and so cannot be spliced
-    // with a re-encoded rung.
-    const hasVariants = hlsSessionManager.buildMasterPlaylist(session.id) !== null;
-    return reply.send({
-      sessionId: session.id,
-      playlistPath: `/transcode/${session.id}/index.m3u8`,
-      ...(hasVariants
-        ? {
-            masterPath: `/transcode/${session.id}/master.m3u8`,
-            // Which of the master's variants this session IS. The browser pins
-            // the player to it, so loading the master costs nothing: an encoder
-            // is already producing that height, and any other rung would be a
-            // second cold start before the first frame.
-            variantHeight: hlsSessionManager.variantHeightOf(session)
-          }
-        : {}),
-      // The heights this host will actually serve this file at, largest first
-      // — the ladder minus every rung it cannot produce faster than it is
-      // watched. The browser needs it whether or not a master exists: without
-      // it, it fell back to a ladder of its own invention and offered rungs the
-      // proxy had just refused, and picking one re-opened the session at a
-      // height measured at a third of realtime.
-      offeredHeights: hlsSessionManager.offeredHeights(session),
-      // What this session's output will carry, stated rather than left to be
-      // discovered. The browser checks what it actually got against this: a
-      // track that never arrives is otherwise noticed only by its absence,
-      // minutes later, as a black picture with working sound.
-      tracks: hlsSessionManager.declaredTracks(session),
-      // How far ahead of the viewer this proxy lets the encoder run, in seconds
-      // of playback. The browser sizes its own forward buffer from it, so the
-      // two sides agree by construction instead of each carrying a constant of
-      // its own — which is how the browser came to hold thirty seconds while
-      // two minutes stood produced on disk (roadmap item 4).
-      lookaheadSeconds: hlsSessionManager.lookaheadSeconds
-    });
-  } catch (error) {
-    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
-      return reply.code(409).send({ error: error.message });
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    // Say why on the proxy's own log, not only in the answer. This route
-    // answered 500 for every viewer of proxy 2.9.101-2.9.102 (an undeclared
-    // constant) and the addon log carried nothing but the data-channel layer's
-    // bare "→ 500": the cause had to be recovered by replaying the request
-    // against the live proxy. The stack is worth the two lines it costs — a
-    // programming error here is invisible to the viewer, who only sees that
-    // nothing plays.
-    logger.error(
-      `transcode-sessions: ${sourceKey}:${fileIndex} failed to prepare: ${message}\n` +
-        `${error instanceof Error ? (error.stack ?? "") : ""}`
-    );
-    return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
-  }
-}
+/**
+ * Create or return an existing HLS transcode session for a torrent file.
+ *
+ * POST /api/transcode-sessions
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sourceRegistry: object, torrentPool: object }} deps
+ * @returns {Promise<void>}
+ */
+
+import { logger } from "../../../utils/logger.js";
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+/**
+ * Claim the source's file so the pool cannot clean it up under a live session.
+ *
+ * Asynchronous underneath — the torrent lives on another thread — but the
+ * caller needs a release function immediately, so the claim is chased and the
+ * release waits for it.
+ *
+ * @param {{ sourceRegistry: object, torrentPool: object, sourceKey: string, fileIndex: number }} params
+ * @returns {() => void}
+ */
+function holdSource({ sourceRegistry, torrentPool, sourceKey, fileIndex }) {
+  let release = null;
+  let releasedEarly = false;
+  const record = sourceRegistry?.get?.(sourceKey);
+  if (!record) {
+    return () => {};
+  }
+  void Promise.resolve(torrentPool.getTorrent(record.sourceType, record.source))
+    .then((torrent) => {
+      release = torrentPool.acquireFile(torrent, fileIndex);
+      if (releasedEarly) {
+        release();
+      }
+    })
+    .catch(() => {});
+  return () => {
+    releasedEarly = true;
+    if (typeof release === "function") {
+      release();
+      release = null;
+    }
+  };
+}
+
+export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager, sourceRegistry, torrentPool }) {
+  const payload = getPayload(req.body);
+  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
+  const fileIndex = Number(payload.fileIndex);
+  const transcodeVideo = payload.transcodeVideo === true;
+  const transcodeAudio = payload.transcodeAudio === true;
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
+  const targetWidth = Number(payload.targetWidth);
+  const targetHeight = Number(payload.targetHeight);
+  // Manual quality: the target box is a user-forced resolution, encoded exactly
+  // (capped to source), with the realtime budget's auto-downscale + runtime
+  // downswitch disabled for the session.
+  const manualQuality = payload.manualQuality === true;
+  // Whether this browser will take its audio from a separate rendition group in
+  // the master playlist rather than muxed into the picture. It has to say so:
+  // publishing renditions AND muxing the same audio would play it twice, while
+  // a browser that does not know about them would get no sound at all.
+  const audioRenditions = payload.audioRenditions === true;
+  const startPositionSeconds = Number(payload.startPositionSeconds);
+  const audioTrackIndex = Number(payload.audioTrackIndex);
+  // Which container to produce. The browser knows what its media stack will
+  // accept for the tracks it asked to be copied; an absent or unknown value
+  // leaves the proxy's own `--segment-format` in charge.
+  const segmentFormatId =
+    typeof payload.segmentFormat === "string" ? payload.segmentFormat.trim() : "";
+
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+
+  try {
+    const session = await hlsSessionManager.createOrGetSession({
+      sourceKey,
+      fileIndex,
+      transcodeVideo,
+      transcodeAudio,
+      consumerId,
+      fileName,
+      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
+      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
+      manualQuality,
+      audioRenditions,
+      startPositionSeconds:
+        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
+          ? startPositionSeconds
+          : 0,
+      audioTrackIndex:
+        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
+      segmentFormatId,
+      // Hold the torrent for as long as this session lives. Reads take a claim
+      // only while they run, and a seek leaves a gap with no read at all — the
+      // disk sweep caught that gap on 2026-08-06 and deleted the film being
+      // watched.
+      // Takes the file to hold, because a session does not always read the file
+      // it was created for: a release whose dub ships as its own file gives that
+      // soundtrack a session of its own, reading a different index of the same
+      // torrent. Defaults to the picture, which is every other case.
+      acquireSource: (heldFileIndex = fileIndex) =>
+        holdSource({
+          sourceRegistry,
+          torrentPool,
+          sourceKey,
+          fileIndex: Number.isInteger(heldFileIndex) ? heldFileIndex : fileIndex
+        })
+    });
+    // The index of quality variants, when this session has more than one to
+    // offer. Its presence is what tells the browser it can change quality
+    // without a new session: the player switches variants itself, appending the
+    // new one after what is already buffered. Absent for a copied video, whose
+    // segments are cut at the source's own keyframes and so cannot be spliced
+    // with a re-encoded rung.
+    const hasVariants = hlsSessionManager.buildMasterPlaylist(session.id) !== null;
+    return reply.send({
+      sessionId: session.id,
+      playlistPath: `/transcode/${session.id}/index.m3u8`,
+      ...(hasVariants
+        ? {
+            masterPath: `/transcode/${session.id}/master.m3u8`,
+            // Which of the master's variants this session IS. The browser pins
+            // the player to it, so loading the master costs nothing: an encoder
+            // is already producing that height, and any other rung would be a
+            // second cold start before the first frame.
+            variantHeight: hlsSessionManager.liveOutputs.variantHeightOf(session)
+          }
+        : {}),
+      // The heights this host will actually serve this file at, largest first
+      // — the ladder minus every rung it cannot produce faster than it is
+      // watched. The browser needs it whether or not a master exists: without
+      // it, it fell back to a ladder of its own invention and offered rungs the
+      // proxy had just refused, and picking one re-opened the session at a
+      // height measured at a third of realtime.
+      offeredHeights: hlsSessionManager.offeredHeights(session),
+      // What this session's output will carry, stated rather than left to be
+      // discovered. The browser checks what it actually got against this: a
+      // track that never arrives is otherwise noticed only by its absence,
+      // minutes later, as a black picture with working sound.
+      tracks: hlsSessionManager.declaredTracks(session),
+      // How far ahead of the viewer this proxy lets the encoder run, in seconds
+      // of playback. The browser sizes its own forward buffer from it, so the
+      // two sides agree by construction instead of each carrying a constant of
+      // its own — which is how the browser came to hold thirty seconds while
+      // two minutes stood produced on disk (roadmap item 4).
+      lookaheadSeconds: hlsSessionManager.lookaheadSeconds
+    });
+  } catch (error) {
+    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
+      return reply.code(409).send({ error: error.message });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    // Say why on the proxy's own log, not only in the answer. This route
+    // answered 500 for every viewer of proxy 2.9.101-2.9.102 (an undeclared
+    // constant) and the addon log carried nothing but the data-channel layer's
+    // bare "→ 500": the cause had to be recovered by replaying the request
+    // against the live proxy. The stack is worth the two lines it costs — a
+    // programming error here is invisible to the viewer, who only sees that
+    // nothing plays.
+    logger.error(
+      `transcode-sessions: ${sourceKey}:${fileIndex} failed to prepare: ${message}\n` +
+        `${error instanceof Error ? (error.stack ?? "") : ""}`
+    );
+    return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
+  }
+}

package/routes/api/transcode-sessions/progress/get.js

@@ -14,7 +14,11 @@ export async function handleApiTranscodeSessionsProgressGet(req, reply, { hlsSes
     return reply.code(400).send({ error: "sessionId is required." });
   }
 
-  const progress = await hlsSessionManager.getSessionProgress(sessionId);
+  // Whose progress. One picture serves everyone watching it, and after a
+  // quality change the stream on screen is another session — a different one
+  // for each viewer who changed.
+  const consumerId = typeof req.query?.consumer === "string" ? req.query.consumer : "";
+  const progress = await hlsSessionManager.getSessionProgress(sessionId, consumerId);
   if (!progress) {
     return reply.code(404).send({ error: "Transcode session was not found." });
   }