@torrent-tv/proxy 2.14.3 → 2.15.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.15.0
+
+- **New**: An audio track is prepared before the player is told to change to it — `GET /transcode/:id/a/:track/warm?position=<seconds>`, the same shape the quality rung has had since 2.12.0. Changing track makes the player discard the audio it holds, and it cannot show a frame until the new track covers the playhead: switching first and producing second therefore put the track's whole cold start on screen as a spinner over a stopped picture. Prepared first, the player finds the bytes already made. A track prepared for a change the viewer then did not make is stopped, as a warmed rung is.
+- **Fix**: The audio track a viewer leaves is stopped, and a seek reaches only the track being listened to. Each track is an ffmpeg process AND a reader holding pieces of the torrent, and one viewer who had changed track once had three readers on one file — picture, the track chosen and the track left. At a seek all three revived their windows at once, every resident piece was pinned, a read ended with zero bytes, ffmpeg read that as the end of the file, and every encoder died; the sessions answered 500 to everything after that until the viewer gave up.
+- **Fix**: A read waits for a piece to be released instead of failing outright. Every resident piece being read at once is not a permanent condition — a pin lasts one read of one piece — so the store now waits for one, and a released pin wakes whoever is waiting. Failing there ended a read with zero bytes, which is indistinguishable from the end of the file to the process reading it. A five-second deadline keeps a genuine deadlock visible, and the wait re-checks on a timer: waiting on events alone hung, because when everything is pinned and nothing else is in flight there is no event left to fire — it hung this store's own test for the ten minutes a run is allowed.
+
 ## 2.14.3
 
 - **Fix**: A separately published audio track begins where the PICTURE is, measured rather than guessed. The position this class keeps is the read head, and the viewer sits behind it by whatever the player has buffered — a figure the browser already reports with every link report, so the playhead is one subtraction away (less one segment of margin, since the report can be ten seconds old). 2.14.2 subtracted the whole look-ahead instead, which was safe but made the encoder produce up to two minutes of audio nobody would hear before reaching the part that was wanted. A report older than fifteen seconds is ignored — a viewer may have seeked since — and then the whole look-ahead is subtracted as before.

package/package.json

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

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

@@ -0,0 +1,71 @@
+/**
+ * @file GET /transcode/:sessionId/a/:track/warm?position=<seconds> — prepare an
+ * audio track before the player is told to change to it.
+ *
+ * The picture keeps playing while a quality rung is warmed (`variant-warm`),
+ * and a track change deserves the same: the player discards the audio it holds
+ * the moment it switches and cannot show a frame until the new track covers the
+ * playhead, so switching first and producing second shows the track's cold
+ * 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.
+ */
+
+import { waitForSessionFile } from "../session-file/get.js";
+
+/** How long to hold the request before telling the caller to retry. */
+const WARM_WAIT_MS = 12_000;
+
+/**
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ */
+export async function handleTranscodeAudioWarmGet(req, reply, { hlsSessionManager }) {
+  const baseSessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const trackIndex = Number(req.params.track);
+  const positionSeconds = Number(req.query?.position);
+
+  if (
+    !Number.isInteger(trackIndex) ||
+    trackIndex < 0 ||
+    !Number.isFinite(positionSeconds) ||
+    positionSeconds < 0
+  ) {
+    return reply.code(400).send({ error: "A track index and a non-negative position are required." });
+  }
+
+  let prepared;
+  try {
+    prepared = await hlsSessionManager.prepareAudioTrack(baseSessionId, trackIndex, positionSeconds);
+  } 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}` });
+  }
+  if (!prepared) {
+    return reply.code(404).send({ error: "No such audio track for this transcode session." });
+  }
+
+  const result = await waitForSessionFile(
+    hlsSessionManager,
+    prepared.sessionId,
+    prepared.fileName,
+    WARM_WAIT_MS
+  );
+  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
+    // at a time.
+    result.stream?.destroy?.();
+    return reply.code(204).send();
+  }
+  if (result.kind === "failed") {
+    return reply.code(500).send({ error: result.message });
+  }
+  // Still being produced. The caller may switch anyway — it will wait where it
+  // would have waited before — or ask again.
+  reply.header("Retry-After", "1");
+  return reply.code(503).send({ error: "The audio track is still warming up." });
+}

package/server.js

@@ -32,6 +32,7 @@ import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/g
 import { handleTranscodeVariantFileGet } from "./routes/transcode/variant-file/get.js";
 import { handleTranscodeAudioFileGet } from "./routes/transcode/audio-file/get.js";
 import { handleTranscodeVariantWarmGet } from "./routes/transcode/variant-warm/get.js";
+import { handleTranscodeAudioWarmGet } from "./routes/transcode/audio-warm/get.js";
 import { createSourceRegistry } from "./store/source-registry.js";
 import { WorkerTorrentPool } from "./services/torrent-worker/pool-adapter.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
@@ -249,6 +250,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.get("/transcode/:sessionId/v/:height/warm", async (req, reply) =>
     handleTranscodeVariantWarmGet(req, reply, { hlsSessionManager })
   );
+  app.get("/transcode/:sessionId/a/:track/warm", async (req, reply) =>
+    handleTranscodeAudioWarmGet(req, reply, { hlsSessionManager })
+  );
   app.get("/transcode/:sessionId/a/:trackIndex/:fileName", async (req, reply) =>
     handleTranscodeAudioFileGet(req, reply, { hlsSessionManager })
   );

package/services/hls-session-manager.js

@@ -3720,7 +3720,16 @@ export class HlsSessionManager {
     // treated as a seek anywhere in this class, so after a forward jump the
     // audio would be held, refused, and left grinding forward from where it
     // was — the picture playing over silence for as long as the jump was.
-    for (const renditionId of named.audioRenditionSessions?.values() ?? []) {
+    // Only the track being LISTENED to. A track the viewer left keeps its place
+    // but not an encoder, and seeking it would start one for nobody — which is
+    // how a single viewer came to have three ffmpeg processes and three readers
+    // on one file (2026-08-15), enough to pin every resident piece and kill the
+    // session outright.
+    const listening = named.activeAudioTrackIndex ?? named.audioTrackIndex;
+    for (const [trackIndex, renditionId] of named.audioRenditionSessions ?? []) {
+      if (trackIndex !== listening) {
+        continue;
+      }
       const rendition = this.sessionsById.get(renditionId);
       if (rendition && rendition.state !== "disposed") {
         rendition.lastAccessedAt = Date.now();
@@ -5129,6 +5138,54 @@ export class HlsSessionManager {
    * @param {number} positionSeconds - Where the switch will happen.
    * @returns {Promise<{ sessionId: string, fileName: string } | null>}
    */
+  /**
+   * Prepare an audio track at a position, so a change of track is instant.
+   *
+   * The player, told to change track, discards the audio it holds and cannot
+   * show a frame until the new track covers the playhead — so switching first
+   * and producing second puts the whole of the track's cold start on screen as
+   * a spinner. Measured 2026-08-15: the picture stopped for as long as the
+   * first piece took. Prepared first, the player finds the bytes already there.
+   *
+   * The same shape as {@link prepareVariant}, and for the same reason.
+   *
+   * @param {string} baseSessionId
+   * @param {number} trackIndex
+   * @param {number} positionSeconds
+   * @returns {Promise<{ sessionId: string, fileName: string } | null>}
+   */
+  async prepareAudioTrack(baseSessionId, trackIndex, positionSeconds) {
+    const base = this.sessionsById.get(baseSessionId);
+    if (!base || base.state === "disposed" || !this.#servesAudioSeparately(base)) {
+      return null;
+    }
+    if (!this.#audioRenditionsOf(base).some((track) => track.trackIndex === trackIndex)) {
+      return null;
+    }
+    const rendition = await this.#resolveAudioRenditionSession(base, trackIndex);
+    if (!rendition) {
+      return null;
+    }
+    // A track prepared for a change the viewer did not make would otherwise
+    // encode for nobody until its own idle timer noticed — the same trap
+    // warming a quality rung has, and the same answer.
+    const stillWarming = base.warmingAudioSessionId;
+    if (stillWarming && stillWarming !== rendition.id) {
+      const abandoned = this.sessionsById.get(stillWarming);
+      const listening = base.activeAudioTrackIndex ?? base.audioTrackIndex;
+      const active = base.audioRenditionSessions?.get(listening);
+      if (abandoned && abandoned.id !== active) {
+        this.#stopEncodeRun(abandoned, "prepared for a track change the viewer did not make");
+      }
+    }
+    base.warmingAudioSessionId = rendition.id;
+    // Pointed at the position the switch will land on: an existing track is
+    // parked wherever the viewer left it.
+    this.#seekSession(rendition, positionSeconds);
+    const index = this.#segmentIndexForTime(rendition, positionSeconds);
+    return { sessionId: rendition.id, fileName: rendition.segmentFormat.segmentFileName(index) };
+  }
+
   async prepareVariant(baseSessionId, height, positionSeconds) {
     if (!isSafeSessionId(baseSessionId)) {
       return null;
@@ -5387,9 +5444,53 @@ export class HlsSessionManager {
       );
       return { sessionId: null, error: message };
     }
+    if (isSegment && rendition) {
+      this.#noteAudioTrackActive(base, rendition, trackIndex);
+    }
     return { sessionId: rendition?.id ?? null };
   }
 
+  /**
+   * A SEGMENT of this track is what says the viewer is listening to it — the
+   * player fetches the playlist and the init of tracks it may never choose.
+   *
+   * Every other track is then stopped. Each one is an ffmpeg process AND a
+   * reader holding pieces of the torrent in memory, and the store can only
+   * spill a piece nobody is reading: on 2026-08-15 a viewer who had changed
+   * track once had three readers on one file — picture, the track they chose
+   * and the track they left — and at a seek all three revived their windows at
+   * once, every resident piece was pinned, a read ended with zero bytes, and
+   * every encoder took that for the end of the file and died. Playback was over
+   * for good; the sessions answered 500 to everything after that.
+   *
+   * Stopped, not disposed: the track keeps its place, its grid and its
+   * position, so switching back does not build it again — the same treatment a
+   * quality rung gets when the viewer moves off it.
+   *
+   * @param {HlsSession} base
+   * @param {HlsSession} active
+   * @param {number} trackIndex
+   */
+  #noteAudioTrackActive(base, active, trackIndex) {
+    if (base.activeAudioTrackIndex === trackIndex) {
+      return;
+    }
+    base.activeAudioTrackIndex = trackIndex;
+    for (const [otherIndex, sessionId] of base.audioRenditionSessions ?? []) {
+      if (otherIndex === trackIndex) {
+        continue;
+      }
+      const other = this.sessionsById.get(sessionId);
+      if (!other || other.state === "disposed" || other.ffmpeg == null) {
+        continue;
+      }
+      // Requests held on it are for segments nobody will produce now, and the
+      // player stopped waiting for them the moment it changed track.
+      other.waitEpoch = (other.waitEpoch ?? 0) + 1;
+      this.#stopEncodeRun(other, `the viewer moved to audio track ${trackIndex}`);
+    }
+  }
+
   /**
    * The session producing one audio track of this file, made on first request.
    *

package/services/piece-store/shared-piece-store.js

@@ -109,6 +109,14 @@ const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
  * in. With one, a single reader would deadlock the store against itself.
  */
 const MIN_RESIDENT_PIECES = 2;
+/**
+ * How long a caller waits for a pinned piece to be released before the store
+ * calls it a deadlock. A pin lasts one read of one piece — milliseconds — so
+ * anything approaching this is a reader waiting for itself.
+ */
+const PINNED_WAIT_MS = 5_000;
+/** How often a wait for a slot looks again when no event is due to wake it. */
+const CLAIM_RETRY_MS = 50;
 
 /**
  * A chunk store holding pieces in a `SharedArrayBuffer`, spilling to disk.
@@ -151,6 +159,8 @@ export class SharedPieceStore {
    * store is exhausted, when in fact it is merely mid-flight.
    */
   #outstandingSlots = 0;
+  /** When the wait for a pinned piece began; 0 when nothing is waiting. */
+  #pinnedWaitStartedAt = 0;
   /** Resolvers waiting for a slot to become claimable. @type {(() => void)[]} */
   #waiters = [];
   #lru;
@@ -169,7 +179,8 @@ export class SharedPieceStore {
     fromDisk: 0,
     spills: 0,
     revivals: 0,
-    blockedByPins: 0
+    blockedByPins: 0,
+    waitedForPins: 0
   };
 
   /**
@@ -308,6 +319,8 @@ export class SharedPieceStore {
    */
   unpin(index) {
     this.#lru.unpin(index);
+    // A released pin can be exactly what a caller waiting for a slot needs.
+    this.#wake();
   }
 
   /**
@@ -330,6 +343,15 @@ export class SharedPieceStore {
         for (const spill of this.#evicting.values()) {
           void spill.then(() => this.#wake(), () => this.#wake());
         }
+        // A wake is not guaranteed to come. Waiting for a spill is safe — one
+        // is in flight and will finish — but waiting for a PIN to be released
+        // is not: if every piece is held and nothing else is happening, there
+        // is no event left to fire, and the deadline that gives up cannot be
+        // reached because it is only tested inside an attempt. That is a hang,
+        // and it hung this store's own test for the full ten minutes a run is
+        // allowed. So the wait also re-checks on a timer.
+        const retry = setTimeout(() => this.#wake(), CLAIM_RETRY_MS);
+        retry.unref?.();
       });
     }
   }
@@ -394,11 +416,34 @@ export class SharedPieceStore {
       if (this.#evicting.size > 0 || this.#outstandingSlots > 0) {
         return null;
       }
-      // Every resident piece is being read. Taking one anyway is precisely the
-      // failure this store exists to make impossible.
+      // Every resident piece is being READ right now. That is not a permanent
+      // condition: a pin lasts as long as one read of one piece, and the reader
+      // releases it a moment later. So wait for that, exactly as the loop above
+      // waits for a spill — pins now wake the waiters.
+      //
+      // It became reachable when a viewer could have three readers on one file
+      // (2026-08-15: picture, the audio track chosen and the one left behind);
+      // failing here ended a read with zero bytes, which ffmpeg reads as the
+      // end of the file, so every encoder died and the session answered 500 to
+      // everything after that.
+      //
+      // The deadline is what keeps a genuine deadlock visible: a reader that
+      // holds a pin while waiting for a slot would otherwise wait for itself
+      // for ever.
+      if (this.#pinnedWaitStartedAt === 0) {
+        this.#pinnedWaitStartedAt = Date.now();
+      }
+      if (Date.now() - this.#pinnedWaitStartedAt < PINNED_WAIT_MS) {
+        this.#counters.waitedForPins += 1;
+        return null;
+      }
+      this.#pinnedWaitStartedAt = 0;
       this.#counters.blockedByPins += 1;
-      throw new Error("Every resident piece is pinned; no slot can be freed.");
+      throw new Error(
+        `Every resident piece is pinned and none was released in ${PINNED_WAIT_MS}ms; no slot can be freed.`
+      );
     }
+    this.#pinnedWaitStartedAt = 0;
 
     const slot = this.#slotOf.get(victim);
 

package/test/quality-variants.test.js

@@ -703,3 +703,36 @@ test("a stale buffer report is not used to place an audio track", async (t) => {
     "the whole look-ahead is subtracted instead — it cannot leave the run ahead of the viewer"
   );
 });
+
+test("an audio track is prepared at the position the switch will land on", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  base.audioSeparate = true;
+  manager.getCachedAudioTracks = () => [
+    { index: 0, language: "rus", title: "", isDefault: true },
+    { index: 1, language: "eng", title: "", isDefault: false }
+  ];
+  const rendition = fakeSession({ id: VARIANT_ID, encodeHeight: 0, dirPath });
+  rendition.audioOnly = true;
+  rendition.audioTrackIndex = 1;
+  rendition.ffmpeg = fakeEncoder();
+  rendition.encodeStartIndex = 0;
+  manager.sessionsById.set(VARIANT_ID, rendition);
+  base.audioRenditionSessions = new Map([[1, VARIANT_ID]]);
+
+  const prepared = await manager.prepareAudioTrack(BASE_ID, 1, 240);
+
+  assert.deepEqual(
+    prepared,
+    { sessionId: VARIANT_ID, fileName: "segment-00060.mp4" },
+    "the caller is told which segment to wait for — 240 s on a four-second grid"
+  );
+  assert.equal(
+    rendition.seekTarget,
+    59,
+    "and the track is pointed at the switch position, one back for the preceding keyframe"
+  );
+});