@torrent-tv/proxy 2.90.0 → 2.92.0

package/routes/api/subtitles/get.js

@@ -4,8 +4,7 @@
  * modes:
  *
  *   - Embedded track:  ?sourceKey&fileIndex=<video>&trackIndex=<sub stream N>
- *     ffmpeg extracts the text subtitle stream (`-map 0:s:N -f webvtt`),
- *     streamed as it is produced.
+ *     indexed text packets are read from available source bytes.
  *   - External file:   ?sourceKey&fileIndex=<subtitle file>   (no trackIndex)
  *     the subtitle FILE is read, decoded (UTF-8/Windows-1251), and converted
  *     (.srt/.ass/.ssa → WebVTT) here on the proxy.
@@ -18,20 +17,12 @@
  * @param {{
  *   sourceRegistry: ReturnType<import("../../../store/source-registry.js").createSourceRegistry>,
  *   torrentPool: import("../../../services/torrent/torrent-pool.js").TorrentPool,
- *   ffmpegBin: string,
- *   localBaseUrl: string
  * }} deps
  * @returns {Promise<void>}
  */
 
 import { deriveSourceKey } from "../../../utils/torrent-source-key.js";
-import { spawn } from "node:child_process";
-import { TextSubtitleTrack } from "../../../services/media/tracks/TextSubtitleTrack.js";
 import { SubtitleController } from "../../../services/server/controllers/SubtitleController.js";
-import { logger } from "../../../utils/logger.js";
-
-// Safety cap: no embedded extraction may outlive this.
-const EXTRACTION_TIMEOUT_MS = 30 * 60 * 1000;
 
 /** Set the detected-language response headers (no-op when detection failed). */
 function setLanguageHeaders(reply, lang) {
@@ -45,7 +36,7 @@ function setLanguageHeaders(reply, lang) {
   }
 }
 
-export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torrentPool, ffmpegBin, localBaseUrl, viewers, subtitles }) {
+export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torrentPool, viewers, subtitles }) {
   const query = req.query ?? {};
   const sourceKey = typeof query.sourceKey === "string" ? query.sourceKey.trim() : "";
   const fileIndex = Number(query.fileIndex);
@@ -55,6 +46,9 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
   if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
     return reply.code(400).send({ error: "sourceKey and fileIndex are required." });
   }
+  if (hasTrackIndex && (!Number.isSafeInteger(trackIndex) || trackIndex < 0)) {
+    return reply.code(400).send({ error: "trackIndex must be a non-negative integer.", canRetry: false });
+  }
 
   // Turning subtitles on is a fact about the VIEWER, and this is the only place
   // that knows both the person and the file, so this is where it is recorded.
@@ -85,17 +79,30 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
   const controller = new SubtitleController({ sourceRegistry, torrentPool, subtitles });
   const since = Number.parseInt(String(req.query?.since ?? ""), 10);
   const after = Number.parseFloat(String(req.query?.after ?? ""));
-  const result = await controller.getSubtitle({
+  const cancellation = new AbortController();
+  const closed = () => cancellation.abort(new DOMException("Subtitle caller closed.", "AbortError"));
+  reply.raw.once("close", closed);
+  let result;
+  try { result = await controller.getSubtitle({
     sourceKey,
     fileIndex,
     trackIndex: hasTrackIndex ? trackIndex : undefined,
     since: Number.isInteger(since) ? since : null,
-    after: Number.isFinite(after) ? after : null
-  });
+    after: Number.isFinite(after) ? after : null,
+    signal: cancellation.signal
+  }); } finally { reply.raw.removeListener("close", closed); }
 
   if (result.error) {
     return reply.code(result.status ?? 400).send({ error: result.error });
   }
+  if (hasTrackIndex) {
+    reply.header("X-Subtitle-Delivery", "push");
+    reply.header("Access-Control-Expose-Headers",
+      "X-Subtitle-Delivery, X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters, X-Subtitle-Cursor");
+  }
+  if (result.pending && !hasTrackIndex) {
+    return reply.code(202).send({ pending: true });
+  }
   if (result.vtt !== undefined) {
     if (result.vtt !== null) {
       // External file or cluster-held cues — controller already detected language.
@@ -109,122 +116,12 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
           for (const [k, v] of Object.entries(result.headers)) reply.header(k, String(v));
           reply.raw.setHeader(
             "Access-Control-Expose-Headers",
-            "X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters, X-Subtitle-Cursor"
+            "X-Subtitle-Delivery, X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters, X-Subtitle-Cursor"
           );
         }
       }
       return reply.send(result.vtt);
     }
   }
-  // If controller returned pending, fall through to ffmpeg extraction below.
-
-  // ---- Embedded track — controller had no held cues, try cluster path directly for headers compatibility
-  // The controller's getSubtitle already attempted the cluster walk; reaching here means it returned pending.
-  if (!hasTrackIndex) {
-    // Should have been handled above — pending for external is unsupported format
-    return reply.code(422).send({ error: "Unsupported subtitle format" });
-  }
-  if (!Number.isInteger(trackIndex) || trackIndex < 0) {
-    return reply.code(400).send({ error: "trackIndex must be a non-negative integer." });
-  }
-
-  const inputUrl = new URL("/stream", `${localBaseUrl}/`);
-  inputUrl.searchParams.set("sourceKey", sourceKey);
-  inputUrl.searchParams.set("fileIndex", String(fileIndex));
-
-  const key = `${sourceKey}:${fileIndex}:${trackIndex}`;
-  const known = extractions.get(key);
-  if (known?.state === "done") {
-    setLanguageHeaders(reply, known.language);
-    reply.header("content-type", "text/vtt; charset=utf-8");
-    reply.header("cache-control", "no-store");
-    reply.header("access-control-allow-origin", "*");
-    return reply.send(known.body);
-  }
-  if (known?.state === "failed") {
-    return reply.code(422).send({ error: known.error });
-  }
-  if (known?.state !== "running") {
-    startExtraction({ key, ffmpegBin, localBaseUrl, sourceKey, fileIndex, trackIndex });
-  }
-  // Being prepared. The connection is NOT held: extracting an embedded track
-  // makes ffmpeg read the whole file, because subtitles are interleaved through
-  // it, and that means downloading the film for the sake of a few kilobytes of
-  // text. Measured 2026-08-19: track 0 of one release produced 3040 bytes over
-  // **752 seconds**, with the data channel idle the whole time — the browser
-  // gave up at its own sixty-second limit, and every retry started the same
-  // twelve-minute scan again. So the work runs once in the background and the
-  // caller is told to come back.
   return reply.code(202).send({ pending: true });
 }
-
-/**
- * Extractions by `sourceKey:fileIndex:trackIndex`, so the scan happens once per
- * track however many times it is asked for.
- *
- * @type {Map<string, { state: "running" | "done" | "failed", body?: Buffer, language?: { code: string, name: string } | null, error?: string }>}
- */
-const extractions = new Map();
-
-/**
- * Run one extraction to completion in the background, keeping the result.
- *
- * @param {{ key: string, ffmpegBin: string, localBaseUrl: string, sourceKey: string, fileIndex: number, trackIndex: number }} params
- * @returns {void}
- */
-function startExtraction({ key, ffmpegBin, localBaseUrl, sourceKey, fileIndex, trackIndex }) {
-  const inputUrl = new URL("/stream", `${localBaseUrl}/`);
-  inputUrl.searchParams.set("sourceKey", sourceKey);
-  inputUrl.searchParams.set("fileIndex", String(fileIndex));
-
-  extractions.set(key, { state: "running" });
-  const startedAt = Date.now();
-  const ffmpeg = spawn(
-    ffmpegBin,
-    ["-hide_banner", "-loglevel", "error", "-i", inputUrl.toString(), "-map", `0:s:${trackIndex}`, "-f", "webvtt", "pipe:1"],
-    { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }
-  );
-
-  let stderr = "";
-  ffmpeg.stderr.on("data", (chunk) => {
-    if (stderr.length < 4096) {
-      stderr += String(chunk);
-    }
-  });
-
-  /** @type {Buffer[]} */
-  const chunks = [];
-  ffmpeg.stdout.on("data", (chunk) => chunks.push(chunk));
-
-  const killTimer = setTimeout(() => {
-    if (!ffmpeg.killed) {
-      ffmpeg.kill("SIGKILL");
-    }
-  }, EXTRACTION_TIMEOUT_MS);
-  killTimer.unref?.();
-
-  const settle = () => {
-    clearTimeout(killTimer);
-    const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
-    const body = Buffer.concat(chunks);
-    if (body.length === 0) {
-      extractions.set(key, {
-        state: "failed",
-        error: `Subtitle track could not be extracted: ${stderr.trim() || "no output from ffmpeg"}`
-      });
-      logger.warn(`subtitles ${key}: nothing produced after ${seconds}s`);
-      return;
-    }
-    // The whole document, decoded as one string, and only its cue text.
-    // Detecting on the first 4096 BYTES was wrong twice over: a byte cut lands
-    // mid-character on any non-Latin track, and most of those bytes are
-    // timestamps rather than words. This runs once per track in the background,
-    // so reading all of it costs nothing anybody waits for.
-    extractions.set(key, { state: "done", body, language: TextSubtitleTrack.detectLanguageFromVtt(body.toString("utf8")) });
-    logger.info(`subtitles ${key}: ${body.length} bytes in ${seconds}s`);
-  };
-  ffmpeg.once("close", settle);
-  ffmpeg.once("error", settle);
-}
-
-

package/routes/api/subtitles/post.js

@@ -0,0 +1,26 @@
+/** Record subtitle choice independently of document delivery. */
+export async function handleApiSubtitlesPost(req, reply, { viewers, sourceRegistry, subtitleFilesFor, subtitleTracksFor }) {
+  const body = req.body ?? {};
+  const { consumerId, sourceKey, fileIndex, trackIndex = null, off = false } = body;
+  if (typeof consumerId !== "string" || !consumerId || typeof sourceKey !== "string" ||
+    !Number.isSafeInteger(fileIndex) || fileIndex < 0 || typeof off !== "boolean" ||
+    (trackIndex !== null && (!Number.isSafeInteger(trackIndex) || trackIndex < 0))) {
+    return reply.code(400).send({ error: "A viewer, source and subtitle file are required.", canRetry: false });
+  }
+  const viewer = viewers.get(consumerId);
+  if (!sourceRegistry.get(sourceKey) || !viewer || viewer.gone || viewer.source?.sourceKey !== sourceKey ||
+    (!off && trackIndex === null && !subtitleFilesFor(sourceKey, viewer.source.selectedFileIndex).includes(fileIndex))) {
+    return reply.code(409).send({ code: "REQUEST_OBSOLETE", error: "The subtitle selection is no longer current.", canRetry: false });
+  }
+  if (!off && trackIndex !== null && fileIndex === viewer.source.selectedFileIndex) {
+    const track = subtitleTracksFor(sourceKey, fileIndex).find(track => track.declaredIndex === trackIndex);
+    if (!track || track.isTextBased?.() !== true) {
+      return reply.code(422).send({ error: "The subtitle track is not supported.", canRetry: false });
+    }
+  }
+  if (off) viewers.clearsSubtitle(consumerId, sourceKey);
+  else if (!viewers.selectsSubtitle(consumerId, sourceKey, fileIndex, trackIndex)) {
+    return reply.code(409).send({ code: "REQUEST_OBSOLETE", canRetry: false });
+  }
+  return reply.send({ received: true });
+}

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

@@ -12,6 +12,7 @@
 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";
+import { waitForPlan } from "../../../services/media/await-plan.js";
 
 /**
  * Extract a plain object from the request body, guarding against
@@ -28,7 +29,7 @@ function getPayload(body) {
 }
 
 
-export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequests, renditions, quality, outputs, lookaheadSeconds, sourceRegistry, torrentPool }) {
+export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequests, renditions, quality, outputs, lookaheadSeconds, sourceRegistry, torrentPool, subscribeSource }) {
   const payload = getPayload(req.body);
   const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
   const fileIndex = Number(payload.fileIndex);
@@ -79,8 +80,13 @@ export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequest
     return reply.code(400).send({ error: "consumerId is required." });
   }
 
+  const cancellation = new AbortController();
+  const cancelled = () => cancellation.abort();
+  reply.raw?.once?.("close", cancelled);
+  if (reply.raw?.destroyed) cancelled();
   try {
-    const session = await viewerRequests.createOrGetSession({
+    const open = () => viewerRequests.createOrGetSession({
+      signal: cancellation.signal,
       sourceKey,
       fileIndex,
       transcodeVideo,
@@ -107,6 +113,16 @@ export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequest
         Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
       segmentFormatId
     });
+    const session = subscribeSource ? (await waitForPlan({ signal: cancellation.signal,
+      subscribe: listener => subscribeSource(sourceKey, fileIndex, listener),
+      read: async () => {
+        try { return { pending: false, session: await open() }; }
+        catch (error) {
+          if (error?.code === "MEDIA_BYTES_UNAVAILABLE") return { pending: true };
+          throw error;
+        }
+      }
+    })).session : await open();
     // 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
@@ -152,6 +168,10 @@ export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequest
       lookaheadSeconds: lookaheadSeconds
     });
   } catch (error) {
+    if (cancellation.signal.aborted || error?.name === "AbortError") return;
+    if (error?.code === "SOURCE_FORGOTTEN") {
+      return reply.code(410).send({ error: error.message, retryable: false, terminal: true });
+    }
     if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
       return reply.code(409).send({ error: error.message });
     }
@@ -174,5 +194,7 @@ export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequest
         `${error instanceof Error ? (error.stack ?? "") : ""}`
     );
     return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
+  } finally {
+    reply.raw?.removeListener?.("close", cancelled);
   }
 }

package/routes/media/get.js

@@ -0,0 +1,80 @@
+import { Readable } from "node:stream";
+
+function mediaRange(header, length) {
+  if (!header) return { start: 0, end: length - 1 };
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header);
+  if (!match || (!match[1] && !match[2])) return null;
+  if (!match[1]) {
+    const suffix = Number(match[2]);
+    if (!Number.isSafeInteger(suffix) || suffix <= 0) return null;
+    return { start: Math.max(0, length - suffix), end: length - 1 };
+  }
+  const start = Number(match[1]);
+  const end = match[2] ? Number(match[2]) : length - 1;
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= length || end < start) return null;
+  return { start, end: Math.min(end, length - 1) };
+}
+
+/** Serve existing downloaded bytes without creating source demand. */
+export async function handleMediaGet(req, reply, { torrentPool, onMissing = () => {} }) {
+  const sourceKey = typeof req.query?.sourceKey === "string" ? req.query.sourceKey : "";
+  const rawIndex = String(req.query?.fileIndex ?? "");
+  if (!sourceKey || !/^\d+$/.test(rawIndex)) {
+    return reply.code(400).send({ error: "A source and file index are required." });
+  }
+  const fileIndex = Number(rawIndex);
+  const torrent = torrentPool.knownTorrent(sourceKey);
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !(file.length > 0)) {
+    return reply.code(404).send({ error: "Media file is not available." });
+  }
+  const rangeHeader = req.headers?.range;
+  const range = mediaRange(rangeHeader, file.length);
+  if (!range || range.start >= file.length) {
+    reply.header("Content-Range", `bytes */${file.length}`);
+    return reply.code(416).send({ error: "Invalid media byte range." });
+  }
+  const portion = Number(torrent.pieceLength);
+  if (!Number.isSafeInteger(portion) || portion <= 0) {
+    return reply.code(500).send({ error: "Source piece length is unavailable." });
+  }
+  if (req.method === "HEAD") {
+    reply.header("Accept-Ranges", "bytes");
+    reply.header("Content-Length", String(file.length));
+    reply.header("Content-Type", "application/octet-stream");
+    return reply.send();
+  }
+  const missing = (start, end) => {
+    onMissing({ sourceKey, fileIndex, start, end, requestId: req.query?.readId ?? req.id });
+    const error = new Error(`Media bytes ${start}-${end} have not arrived.`);
+    error.code = "MEDIA_BYTES_UNAVAILABLE";
+    return error;
+  };
+  const endOfPortion = (start) => Math.min(range.end, start + portion - 1);
+  const firstEnd = endOfPortion(range.start);
+  const first = await torrentPool.readHeldOf(torrent, fileIndex, range.start, firstEnd);
+  if (!first || first.length !== firstEnd - range.start + 1) {
+    const error = missing(range.start, firstEnd);
+    return reply.code(409).send({ kind: "needs-ranges", ranges: [[range.start, firstEnd]], error: error.message });
+  }
+  reply.header("Accept-Ranges", "bytes");
+  reply.header("Content-Type", "application/octet-stream");
+  reply.header("Content-Length", String(range.end - range.start + 1));
+  reply.header("Cache-Control", "no-store");
+  if (rangeHeader) {
+    reply.code(206);
+    reply.header("Content-Range", `bytes ${range.start}-${range.end}/${file.length}`);
+  }
+  async function* bytes() {
+    yield first;
+    for (let start = firstEnd + 1; start <= range.end;) {
+      if (reply.raw?.destroyed) return;
+      const end = endOfPortion(start);
+      const data = await torrentPool.readHeldOf(torrent, fileIndex, start, end);
+      if (!data || data.length !== end - start + 1) throw missing(start, end);
+      yield data;
+      start = end + 1;
+    }
+  }
+  return reply.send(Readable.from(bytes()));
+}

package/routes/stream/get.js

@@ -60,43 +60,19 @@ function getSourceParams(query, sourceRegistry) {
   return { sourceType, source, sourceKey };
 }
 
-/**
- * How long a request may wait for a torrent that is still being added.
- *
- * Adding a magnet takes as long as its metadata does — seconds when peers
- * answer, forever when none do — and `getTorrent` waits for it. Awaiting that
- * with no bound is what made this route answer nothing at all.
- */
-const TORRENT_READY_TIMEOUT_MS = 10_000;
-
-/**
- * The torrent for a source, or a `TORRENT_NOT_READY` error once the wait has
- * gone on long enough to be worth reporting.
- *
- * The underlying add is NOT cancelled: it keeps running and warms the pool, so
- * the client's next attempt is likely to find it ready.
- *
- * @param {import("../../services/torrent/torrent-pool.js").TorrentPool} torrentPool
- * @param {string} sourceType
- * @param {string} source
- * @returns {Promise<import("webtorrent").Torrent>}
- */
-async function waitForTorrent(torrentPool, sourceType, source) {
-  let timer = null;
-  const expiry = new Promise((_resolve, reject) => {
-    timer = setTimeout(() => {
-      const error = new Error("Torrent metadata is not available yet.");
-      error.code = "TORRENT_NOT_READY";
-      reject(error);
-    }, TORRENT_READY_TIMEOUT_MS);
-    timer.unref?.();
-  });
+/** Torrent metadata has no elapsed-time failure; a disconnected caller cancels its wait. */
+async function waitForTorrent(torrentPool, sourceType, source, req, reply) {
+  let cancelled;
+  const until = new Promise((_resolve, reject) => { cancelled = () => reject(new DOMException("Source read was cancelled.", "AbortError")); });
+  const closed = () => { if (!reply.raw?.writableEnded) cancelled(); };
+  req.raw?.once?.("aborted", cancelled);
+  reply.raw?.once?.("close", closed);
   try {
-    return await Promise.race([torrentPool.getTorrent(sourceType, source), expiry]);
+    if (req.raw?.aborted) throw new DOMException("Source read was cancelled.", "AbortError");
+    return await Promise.race([torrentPool.getTorrent(sourceType, source), until]);
   } finally {
-    if (timer) {
-      clearTimeout(timer);
-    }
+    req.raw?.off?.("aborted", cancelled);
+    reply.raw?.off?.("close", closed);
   }
 }
 
@@ -212,18 +188,9 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
 
   let torrent;
   try {
-    torrent = await waitForTorrent(torrentPool, sourceType, source);
+    torrent = await waitForTorrent(torrentPool, sourceType, source, req, reply);
   } catch (error) {
-    if (error instanceof Error && error.code === "TORRENT_NOT_READY") {
-      // Say so, rather than holding the connection until the client gives up.
-      // Reproduced 2026-08-04 on a magnet whose metadata never arrived: both a
-      // ranged GET and a HEAD returned nothing at all for the full 30 s the
-      // probe was willing to wait, and the route had written neither a status
-      // nor a header — from the client that is indistinguishable from the proxy
-      // having died, and it left no trace in the log either.
-      reply.header("Retry-After", "1");
-      return reply.code(503).send({ error: "Torrent metadata is not available yet." });
-    }
+    if (error?.name === "AbortError") return;
     const message = error instanceof Error ? error.message : String(error);
     return reply.code(500).send({ error: `Failed to load torrent source: ${message}` });
   }
@@ -259,20 +226,6 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
   }
 
   const range = parseRange(req.headers.range, file.length);
-  // Prioritize the pieces at this read position so a seek (a request at a new
-  // byte offset) downloads first instead of waiting behind the sequential
-  // backlog — this is what caused ~15-18 s stalls when seeking into an
-  // undownloaded region.
-  // Only the encoder's own input read tracks where the viewer is. Everything
-  // else that comes through here — the codec probe, the keyframe index, a
-  // subtitle fetch — reads the file's edges, and treating those as a viewer
-  // position made every session start and every encoder restart look like a
-  // burst of seeks (measured: two spurious "the viewer moved" per start).
-  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0, undefined, {
-    wholeFileRead: range === null,
-    isPlaybackRead: req.query.reader === "playback"
-  });
-
   const start = range ? range.start : 0;
   const end = range ? range.end : file.length - 1;
   const contentLength = end - start + 1;
@@ -281,16 +234,6 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
   // no copy on either thread, at the cost of doing the writing by hand, because
   // only the write callback tells us when a piece may be released. Falls back to
   // the ordinary stream for sources without a shared pool.
-  // How far ahead of its own read head this reader should ask the swarm for.
-  // Supplied by whoever knows the media's byte rate — the transcode session
-  // puts it on the ffmpeg input URL, sized in seconds of playback — because
-  // this thread knows only bytes, and 32 MB is half a minute of a 1080p film
-  // but four seconds of a disc remux. Absent or unusable, the reader's own
-  // default stands.
-  const windowBytesRaw = Number(req.query.windowBytes);
-  const windowBytes =
-    Number.isFinite(windowBytesRaw) && windowBytesRaw > 0 ? windowBytesRaw : undefined;
-
   // Which transcode session this read feeds, when it feeds one. Put on the URL
   // by the session that builds it, because this route otherwise knows only a
   // file — and two sessions can read one file, so the file cannot stand in for
@@ -303,7 +246,7 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
     : null;
 
   const fragments = typeof file.createFragmentReader === "function"
-    ? file.createFragmentReader({ start, end, windowBytes })
+    ? file.createFragmentReader({ start, end })
     : null;
 
   if (fragments) {
@@ -327,10 +270,11 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
           fragment.release();
           break;
         }
-        await new Promise((resolve, reject) => {
-          reply.raw.write(fragment.bytes, (error) => (error ? reject(error) : resolve()));
-        });
-        sent += fragment.bytes.length;
+        try {
+          await new Promise((resolve, reject) => {
+            reply.raw.write(fragment.bytes, (error) => (error ? reject(error) : resolve()));
+          });
+          sent += fragment.bytes.length;
         // Say so, if this read belongs to a transcode session. It is the only
         // proof that a session which has produced nothing yet is nevertheless
         // being fed: the encoder's own progress cannot move until its first
@@ -345,7 +289,9 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
         // Only now are these bytes gone: the piece can be unpinned, and the
         // slot it occupies reused. Releasing before this point corrupts the
         // response silently.
-        fragment.release();
+        } finally {
+          fragment.release();
+        }
       }
       // THE BODY MUST BE AS LONG AS THE HEADER PROMISED, and nothing checked.
       //
@@ -365,11 +311,8 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
       // whether the body was short — which either names the cause or removes
       // the last candidate.
       if (sent !== contentLength) {
-        logger.error(
-          `stream: read of "${file.name}" bytes ${start}-${end} ENDED SHORT — ` +
-          `${sent} of ${contentLength} bytes sent under a Content-Length that promised all of them. ` +
-          "Whatever is reading this has a truncated body and no way to know it."
-        );
+        if (req.raw.aborted || reply.raw.destroyed) return;
+        throw new Error(`Source response is incomplete: ${sent} of ${contentLength} bytes.`);
       }
       reply.raw.end();
     } catch (error) {
@@ -400,17 +343,6 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool,
     return;
   }
 
-  reply.header("Accept-Ranges", "bytes");
-  reply.header("Content-Type", "application/octet-stream");
-  reply.header("Content-Disposition", `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`);
-
-  if (!range) {
-    reply.header("Content-Length", String(file.length));
-    return reply.send(file.createReadStream());
-  }
-
-  reply.code(206);
-  reply.header("Content-Length", String(contentLength));
-  reply.header("Content-Range", `bytes ${start}-${end}/${file.length}`);
-  return reply.send(file.createReadStream({ start, end }));
+  return reply.code(500).send({ error: "The map-governed source reader is unavailable.",
+    code: "SOURCE_READER_UNAVAILABLE", canRetry: false });
 }

package/routes/transcode/audio-warm/get.js

@@ -16,13 +16,10 @@
  * start as a spinner over a stopped picture (measured 2026-08-15).
  *
  * Answers 204 when the segment at that position is ready, so the caller can
- * switch into bytes that already exist; 503 while it is still being made.
+ * switch into bytes that already exist. Otherwise it waits for readiness or refusal.
  */
 
-import { waitForSessionFile } from "../../../services/server/transcode-session-files.js";
-
-/** How long to hold the request before telling the caller to retry. */
-const WARM_WAIT_MS = 12_000;
+import { waitForRequestedFile } from "../../../services/server/transcode-session-files.js";
 
 /**
  * @param {import("fastify").FastifyRequest} req
@@ -65,19 +62,19 @@ export async function handleTranscodeAudioWarmGet(req, reply, { renditions, serv
     );
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    reply.header("Retry-After", "1");
-    return reply.code(503).send({ error: `Could not prepare the audio track: ${message}` });
+    return reply.code(500).send({ canRetry: false, error: `Could not prepare the audio track: ${message}` });
   }
   if (!prepared) {
     return reply.code(404).send({ error: "No such audio track for this transcode session." });
   }
 
-  const result = await waitForSessionFile(
-    serving,
+  const result = await waitForRequestedFile(
+    req, reply, serving,
     prepared.sessionId,
     prepared.fileName,
-    { holdMs: WARM_WAIT_MS }
+    consumerId
   );
+  if (result.kind === "cancelled") return;
   if (result.kind === "file") {
     // The bytes are the player's to fetch; the handle opened to reach them is
     // ours to close, or a long-running proxy walks to EMFILE one track change
@@ -86,16 +83,7 @@ export async function handleTranscodeAudioWarmGet(req, reply, { renditions, serv
     return reply.code(204).send();
   }
   if (result.kind === "failed") {
-    return reply.code(500).send({ error: result.message });
+    return reply.code(500).send({ error: result.message, canRetry: false });
   }
-  // Still being produced. The caller may switch anyway — it will wait where it
-  // would have waited before — or ask again.
-  //
-  // `warming: true` says the track and how it is produced ARE recorded for this
-  // viewer — `prepareAudioTrack` records them before the wait — which the
-  // status alone cannot say: the 503 above is a preparation that recorded
-  // nothing. A page restating its soundtrack after a reconnect needs to know
-  // which of the two it got.
-  reply.header("Retry-After", "1");
-  return reply.code(503).send({ error: "The audio track is still warming up.", warming: true });
+  return reply.code(404).send({ error: "The requested output is no longer wanted.", canRetry: false });
 }