@torrent-tv/proxy 2.87.9 → 2.87.11

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

@@ -1,129 +1,136 @@
-import { recordViewerReport } from "../../../../services/viewer/report-intake.js";
-
-/**
- * Accept a viewer link report for a transcode session (adaptive bitrate).
- * The browser measures its own data-channel throughput per segment fetch and
- * posts a rolling median + its buffered seconds; the session manager's budget
- * loop uses the latest report as the link-deficit downshift trigger.
- *
- * POST /api/transcode-sessions/:sessionId/net-report
- * Body: { consumerId: string, bufferedAheadSec: number, linkMbps?: number,
- *         positionSeconds?: number, playingHeight?: number, … }
- *
- * `consumerId` and `positionSeconds` say WHO is reporting and WHERE they are.
- * A copied picture is one session shared by every viewer of it, so without them
- * the proxy could only act on whichever viewer reported last. The viewer is
- * required; the position is not.
- *
- * Best-effort telemetry: invalid body → 400, unknown session → 404, ok → 204.
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ outputs: { get: (id: string) => object | undefined }, viewers: object, renditions: { viewerPlays: Function, noteViewerReported: Function }, quality: { noteViewerReported: Function } }} deps -
- *   The live outputs, the registry of viewers, and the rungs of a picture. The
- *   VIEWER component takes the statement; which rung a stated height is, is the
- *   encoding component's. This route's whole job is turning a request into
- *   those calls and their answer into a status code.
- * @returns {Promise<void>}
- */
-export async function handleApiTranscodeSessionNetReportPost(req, reply, { outputs, viewers, renditions, quality }) {
-  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
-  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
-  // WHAT THIS REPORT IS. A statement by one viewer about itself: where the
-  // picture is, how much film it holds, whether it is moving, whether it is
-  // blocked on us, whether the page is on screen — and, when there has been
-  // anything to measure, how fast the link carried it.
-  //
-  // THE LINK FIGURE IS NOT REQUIRED, and requiring it is the fault of
-  // 2026-09-14. A page measures its link from completed transfers, so a page
-  // that has not yet been delivered a segment has no figure; at a cold open
-  // that is every page. Rejected here with 400, the page's own account of
-  // itself never arrived, this proxy filled the silence by assuming the film
-  // was running, and a viewer who had not seen a frame was placed 146 seconds
-  // into it — the soundtrack's encoder went there, and the segment the browser
-  // was actually asking for was ranked last of a hundred and answered 503.
-  const linkMbps = Number(body.linkMbps);
-  const bufferedAheadSec = Number(body.bufferedAheadSec);
-  if (!sessionId || !Number.isFinite(bufferedAheadSec) || bufferedAheadSec < 0) {
-    return reply.code(400).send({ error: "bufferedAheadSec (>=0) is required." });
-  }
-
-  // WHO is reporting is required: a viewer always has a name, and a reading of
-  // a link that belongs to nobody cannot be kept anywhere. The position is not
-  // required — a report without one is still a truthful reading of that link.
-  const consumerId = typeof body.consumerId === "string" ? body.consumerId.trim() : "";
-  if (!consumerId) {
-    return reply.code(400).send({ error: "consumerId is required." });
-  }
-  // Whether the picture is moving. Absent from a page that does not say, and
-  // then nothing is assumed: a statement about somebody else's machine is
-  // theirs to make, and assuming it walked a viewer 146 seconds into a film
-  // they had not begun (2026-09-14).
-  const playing = typeof body.playing === "boolean" ? body.playing : undefined;
-  // Whether this viewer is BLOCKED on material we owe them, which is a
-  // different state from having stopped the picture: the first is the most
-  // urgent viewer there is, the second consumes nothing and can wait. One
-  // boolean could not hold three states and read the first as the second.
-  const waiting = typeof body.waiting === "boolean" ? body.waiting : undefined;
-  // Whether the page is on screen, and whether the picture was pulled out of
-  // it. A hidden tab has its timers throttled, so it asks for nothing and looks
-  // exactly like a viewer holding a full cushion; picture-in-picture is the case
-  // that makes the distinction necessary, because there the tab is hidden and
-  // the viewer is watching. Absent from a page that does not say, and then the
-  // viewer is on screen, as every page meant before it could say otherwise.
-  const onScreen = typeof body.onScreen === "boolean" ? body.onScreen : undefined;
-  const inPictureInPicture =
-    typeof body.inPictureInPicture === "boolean" ? body.inPictureInPicture : undefined;
-  // Whether the size on screen was picked by hand or is the automatic choice.
-  // A size picked by hand is served exactly; the automatic choice may be served
-  // by an output of the same quality or better that is already made.
-  const qualityMode = body.qualityMode === "auto" || body.qualityMode === "manual" ? body.qualityMode : undefined;
-  const positionSeconds = Number(body.positionSeconds);
-  // The picture as the viewer sees it, in physical pixels: the upper bound of
-  // the height of a re-encoded output made for them (roadmap item 98). Sent the
-  // moment it changes; a page that does not say leaves the size as it was.
-  const visiblePicture = body.visiblePicture && typeof body.visiblePicture === "object"
-    ? { width: Number(body.visiblePicture.width), height: Number(body.visiblePicture.height) }
-    : undefined;
-  // WHICH RUNG THE PLAYER IS PLAYING, stated by the page the moment it
-  // switched. Stated before the report is recorded, because the report belongs
-  // to the rung on screen. A page that does not say leaves the rung as it was.
-  const playingHeight = Number(body.playingHeight);
-  if (Number.isInteger(playingHeight) && playingHeight > 0) {
-    renditions.viewerPlays(
-      sessionId,
-      consumerId,
-      playingHeight,
-      Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
-    );
-  }
-  const recorded = recordViewerReport({
-    outputs,
-    viewers,
-    sessionId,
-    report: {
-      linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
-      bufferedAheadSec,
-      consumerId,
-      playing,
-      waiting,
-      onScreen,
-      inPictureInPicture,
-      qualityMode,
-      visiblePicture,
-      positionSeconds:
-        Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
-    }
-  });
-  if (!recorded) {
-    return reply.code(404).send({ error: "Transcode session was not found." });
-  }
-  // After the statement is recorded, so what is judged is what they just said:
-  // a move of theirs to another limit may no longer be wanted.
-  renditions.noteViewerReported(sessionId, consumerId);
-  // And the quality budget judges this viewer now, on what they just said —
-  // their buffer's trend, their link, the picture they see — rather than at
-  // the next tick of a timer.
-  void quality.noteViewerReported(sessionId, consumerId);
-  return reply.code(204).send();
-}
+import { recordViewerReport } from "../../../../services/viewer/report-intake.js";
+
+/**
+ * Accept a viewer link report for a transcode session (adaptive bitrate).
+ * The browser measures its own data-channel throughput per segment fetch and
+ * posts a rolling median + its buffered seconds; the session manager's budget
+ * loop uses the latest report as the link-deficit downshift trigger.
+ *
+ * POST /api/transcode-sessions/:sessionId/net-report
+ * Body: { consumerId: string, bufferedAheadSec: number, linkMbps?: number,
+ *         positionSeconds?: number, playingHeight?: number, … }
+ *
+ * `consumerId` and `positionSeconds` say WHO is reporting and WHERE they are.
+ * A copied picture is one session shared by every viewer of it, so without them
+ * the proxy could only act on whichever viewer reported last. The viewer is
+ * required; the position is not.
+ *
+ * Best-effort telemetry: invalid body → 400, unknown session → 404, ok → 204.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ outputs: { get: (id: string) => object | undefined }, viewers: object, renditions: { viewerPlays: Function, noteViewerReported: Function }, quality: { noteViewerReported: Function } }} deps -
+ *   The live outputs, the registry of viewers, and the rungs of a picture. The
+ *   VIEWER component takes the statement; which rung a stated height is, is the
+ *   encoding component's. This route's whole job is turning a request into
+ *   those calls and their answer into a status code.
+ * @returns {Promise<void>}
+ */
+export async function handleApiTranscodeSessionNetReportPost(req, reply, { outputs, viewers, renditions, quality }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  // WHAT THIS REPORT IS. A statement by one viewer about itself: where the
+  // picture is, how much film it holds, whether it is moving, whether it is
+  // blocked on us, whether the page is on screen — and, when there has been
+  // anything to measure, how fast the link carried it.
+  //
+  // THE LINK FIGURE IS NOT REQUIRED, and requiring it is the fault of
+  // 2026-09-14. A page measures its link from completed transfers, so a page
+  // that has not yet been delivered a segment has no figure; at a cold open
+  // that is every page. Rejected here with 400, the page's own account of
+  // itself never arrived, this proxy filled the silence by assuming the film
+  // was running, and a viewer who had not seen a frame was placed 146 seconds
+  // into it — the soundtrack's encoder went there, and the segment the browser
+  // was actually asking for was ranked last of a hundred and answered 503.
+  const linkMbps = Number(body.linkMbps);
+  const linkSampleMbps = Number(body.linkSampleMbps);
+  const linkSampleAt = Number(body.linkSampleAt);
+  const bufferedAheadSec = Number(body.bufferedAheadSec);
+  const bufferLimitSeconds = Number(body.bufferLimitSeconds);
+  if (!sessionId || !Number.isFinite(bufferedAheadSec) || bufferedAheadSec < 0) {
+    return reply.code(400).send({ error: "bufferedAheadSec (>=0) is required." });
+  }
+
+  // WHO is reporting is required: a viewer always has a name, and a reading of
+  // a link that belongs to nobody cannot be kept anywhere. The position is not
+  // required — a report without one is still a truthful reading of that link.
+  const consumerId = typeof body.consumerId === "string" ? body.consumerId.trim() : "";
+  if (!consumerId) {
+    return reply.code(400).send({ error: "consumerId is required." });
+  }
+  // Whether the picture is moving. Absent from a page that does not say, and
+  // then nothing is assumed: a statement about somebody else's machine is
+  // theirs to make, and assuming it walked a viewer 146 seconds into a film
+  // they had not begun (2026-09-14).
+  const playing = typeof body.playing === "boolean" ? body.playing : undefined;
+  // Whether this viewer is BLOCKED on material we owe them, which is a
+  // different state from having stopped the picture: the first is the most
+  // urgent viewer there is, the second consumes nothing and can wait. One
+  // boolean could not hold three states and read the first as the second.
+  const waiting = typeof body.waiting === "boolean" ? body.waiting : undefined;
+  // Whether the page is on screen, and whether the picture was pulled out of
+  // it. A hidden tab has its timers throttled, so it asks for nothing and looks
+  // exactly like a viewer holding a full cushion; picture-in-picture is the case
+  // that makes the distinction necessary, because there the tab is hidden and
+  // the viewer is watching. Absent from a page that does not say, and then the
+  // viewer is on screen, as every page meant before it could say otherwise.
+  const onScreen = typeof body.onScreen === "boolean" ? body.onScreen : undefined;
+  const inPictureInPicture =
+    typeof body.inPictureInPicture === "boolean" ? body.inPictureInPicture : undefined;
+  // Whether the size on screen was picked by hand or is the automatic choice.
+  // A size picked by hand is served exactly; the automatic choice may be served
+  // by an output of the same quality or better that is already made.
+  const qualityMode = body.qualityMode === "auto" || body.qualityMode === "manual" ? body.qualityMode : undefined;
+  const positionSeconds = Number(body.positionSeconds);
+  // The picture as the viewer sees it, in physical pixels: the upper bound of
+  // the height of a re-encoded output made for them (roadmap item 98). Sent the
+  // moment it changes; a page that does not say leaves the size as it was.
+  const visiblePicture = body.visiblePicture && typeof body.visiblePicture === "object"
+    ? { width: Number(body.visiblePicture.width), height: Number(body.visiblePicture.height) }
+    : undefined;
+  // WHICH RUNG THE PLAYER IS PLAYING, stated by the page the moment it
+  // switched. Stated before the report is recorded, because the report belongs
+  // to the rung on screen. A page that does not say leaves the rung as it was.
+  const playingHeight = Number(body.playingHeight);
+  if (Number.isInteger(playingHeight) && playingHeight > 0) {
+    renditions.viewerPlays(
+      sessionId,
+      consumerId,
+      playingHeight,
+      Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
+    );
+  }
+  const recorded = recordViewerReport({
+    outputs,
+    viewers,
+    sessionId,
+    report: {
+      linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
+      linkSampleMbps: Number.isFinite(linkSampleMbps) && linkSampleMbps > 0 ? linkSampleMbps : undefined,
+      linkSampleAt: Number.isFinite(linkSampleAt) && linkSampleAt > 0 ? linkSampleAt : undefined,
+      bufferedAheadSec,
+      bufferLimitSeconds:
+        Number.isFinite(bufferLimitSeconds) && bufferLimitSeconds > 0 ? bufferLimitSeconds : undefined,
+      consumerId,
+      playing,
+      waiting,
+      onScreen,
+      inPictureInPicture,
+      qualityMode,
+      visiblePicture,
+      positionSeconds:
+        Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
+    }
+  });
+  if (!recorded) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  // After the statement is recorded, so what is judged is what they just said:
+  // a move of theirs to another limit may no longer be wanted.
+  renditions.noteViewerReported(sessionId, consumerId);
+  // And the quality budget judges this viewer now, on what they just said —
+  // their buffer's trend, their link, the picture they see — rather than at
+  // the next tick of a timer.
+  void quality.noteViewerReported(sessionId, consumerId);
+  return reply.code(204).send();
+}

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

@@ -1,160 +1,160 @@
-/**
- * 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 {{ viewerRequests: object, renditions: object, quality: object, outputs: object, lookaheadSeconds: number, sourceRegistry: object, torrentPool: object }} deps
- * @returns {Promise<void>}
- */
-
-import { logger } from "../../../utils/logger.js";
-import { OUTPUT_NO_CAPACITY, OUTPUT_UNAVAILABLE } from "../../../services/encode/output/index.js";
-import { replyNoCapacity, replyOutputUnavailable } from "../../../services/server/http-responses.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 {};
-}
-
-
-export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequests, renditions, quality, outputs, lookaheadSeconds, 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);
-  // The picture as the viewer sees it, in physical pixels. For a re-encoded
-  // picture the height made is the smallest rung whose frame is not smaller
-  // than this (roadmap item 98); it takes the place of a target box.
-  const visibleWidth = Number(payload.visiblePicture?.width);
-  const visibleHeight = Number(payload.visiblePicture?.height);
-  const visiblePicture = visibleWidth > 0 && visibleHeight > 0
-    ? { width: Math.round(visibleWidth), height: Math.round(visibleHeight) }
-    : null;
-  // The target box is produced exactly (capped to source), with the realtime
-  // budget's auto-downscale and runtime downswitch off for this session.
-  //
-  // It says nothing about WHO asked — a rung sets it whether the viewer picked
-  // that rung or the player moved itself onto one.
-  const exactSize = payload.exactSize === 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." });
-  }
-  // The output is opened FOR somebody, and a viewer always has a name.
-  if (!consumerId) {
-    return reply.code(400).send({ error: "consumerId is required." });
-  }
-
-  try {
-    const session = await viewerRequests.createOrGetSession({
-      sourceKey,
-      fileIndex,
-      transcodeVideo,
-      transcodeAudio,
-      consumerId,
-      fileName,
-      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
-      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
-      exactSize,
-      visiblePicture,
-      audioRenditions,
-      startPositionSeconds:
-        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
-          ? startPositionSeconds
-          : 0,
-      audioTrackIndex:
-        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
-      segmentFormatId
-    });
-    // 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 = renditions.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: outputs.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: quality.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: renditions.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: lookaheadSeconds
-    });
-  } catch (error) {
-    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
-      return reply.code(409).send({ error: error.message });
-    }
-    if (error?.code === OUTPUT_UNAVAILABLE) {
-      return replyOutputUnavailable(reply, error.details);
-    }
-    if (error?.code === OUTPUT_NO_CAPACITY) {
-      return replyNoCapacity(reply, error.details);
-    }
-    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 {{ viewerRequests: object, renditions: object, quality: object, outputs: object, lookaheadSeconds: number, sourceRegistry: object, torrentPool: object }} deps
+ * @returns {Promise<void>}
+ */
+
+import { logger } from "../../../utils/logger.js";
+import { OUTPUT_NO_CAPACITY, OUTPUT_UNAVAILABLE } from "../../../services/encode/output/index.js";
+import { replyNoCapacity, replyOutputUnavailable } from "../../../services/server/http-responses.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 {};
+}
+
+
+export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequests, renditions, quality, outputs, lookaheadSeconds, 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);
+  // The picture as the viewer sees it, in physical pixels. For a re-encoded
+  // picture the height made is the smallest rung whose frame is not smaller
+  // than this (roadmap item 98); it takes the place of a target box.
+  const visibleWidth = Number(payload.visiblePicture?.width);
+  const visibleHeight = Number(payload.visiblePicture?.height);
+  const visiblePicture = visibleWidth > 0 && visibleHeight > 0
+    ? { width: Math.round(visibleWidth), height: Math.round(visibleHeight) }
+    : null;
+  // The target box is produced exactly (capped to source), with the realtime
+  // budget's auto-downscale and runtime downswitch off for this session.
+  //
+  // It says nothing about WHO asked — a rung sets it whether the viewer picked
+  // that rung or the player moved itself onto one.
+  const exactSize = payload.exactSize === 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." });
+  }
+  // The output is opened FOR somebody, and a viewer always has a name.
+  if (!consumerId) {
+    return reply.code(400).send({ error: "consumerId is required." });
+  }
+
+  try {
+    const session = await viewerRequests.createOrGetSession({
+      sourceKey,
+      fileIndex,
+      transcodeVideo,
+      transcodeAudio,
+      consumerId,
+      fileName,
+      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
+      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
+      exactSize,
+      visiblePicture,
+      audioRenditions,
+      startPositionSeconds:
+        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
+          ? startPositionSeconds
+          : 0,
+      audioTrackIndex:
+        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
+      segmentFormatId
+    });
+    // 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 = renditions.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: outputs.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: quality.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: renditions.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: lookaheadSeconds
+    });
+  } catch (error) {
+    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
+      return reply.code(409).send({ error: error.message });
+    }
+    if (error?.code === OUTPUT_UNAVAILABLE) {
+      return replyOutputUnavailable(reply, error.details);
+    }
+    if (error?.code === OUTPUT_NO_CAPACITY) {
+      return replyNoCapacity(reply, error.details);
+    }
+    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}` });
+  }
+}