@torrent-tv/proxy 2.14.3 → 2.15.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.15.1
+
+- **Fix**: A magnet that never found its metadata no longer makes the same film unplayable from its own `.torrent`. One infohash is one torrent, so the second add is refused and the pool takes the one already there — which is right when it is ready and wrong when it is not: a magnet whose swarm has not answered has no file list, and everything bound to it is answered 404. Measured 2026-08-15 on the addon host: a magnet with no reachable trackers was added first, the film's own `.torrent` then joined that empty torrent instead of replacing it, `/stream` answered 404, the encoder died on its first read, and the film stayed unplayable until the proxy was restarted. A `.torrent` carries the file list, the piece hashes and the trackers outright, so when it meets a torrent with no metadata it now replaces it; two magnets still wait, because neither has anything the other lacks.
+
+## 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.1",
   "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/services/torrent-pool.js

@@ -315,6 +315,30 @@ function computeDefaultDiskCap(storePath) {
  * @param {string} source                   - Magnet URI or base64-encoded .torrent file.
  * @returns {string | Buffer}
  */
+/**
+ * What to do when WebTorrent refuses an add because that infohash is already
+ * here: take the one that exists, replace it, or wait for it to be ready.
+ *
+ * The same content arrives as a `.torrent` and as a magnet — different pool
+ * keys, one swarm — so a duplicate is ordinary. What is NOT ordinary is a
+ * duplicate with no metadata: a magnet whose swarm has not answered has no file
+ * list, and every request bound to it is answered 404 for as long as it lives.
+ * If this add carries metadata — a `.torrent` holds the files, the piece hashes
+ * and the trackers outright — waiting for the swarm to supply what is already
+ * in our hands is waiting for nothing. Measured 2026-08-15: one magnet with no
+ * reachable peers made the same film unplayable from its own `.torrent` until
+ * the proxy was restarted.
+ *
+ * @param {{ existingIsReady: boolean, incomingHasMetadata: boolean }} params
+ * @returns {"adopt" | "replace" | "wait"}
+ */
+export function duplicateAddDecision({ existingIsReady, incomingHasMetadata }) {
+  if (existingIsReady) {
+    return "adopt";
+  }
+  return incomingHasMetadata ? "replace" : "wait";
+}
+
 function decodeTorrentSource(sourceType, source) {
   if (sourceType === "magnet") {
     return source;
@@ -972,11 +996,58 @@ export class TorrentPool {
               this.#pending.delete(key);
               resolve(existing);
             };
-            if (existing.ready) {
+            const decision = duplicateAddDecision({
+              existingIsReady: existing.ready === true,
+              incomingHasMetadata: Buffer.isBuffer(torrentId)
+            });
+            if (decision === "adopt") {
               settle();
-            } else {
-              existing.once("ready", settle);
+              return;
+            }
+            // The one already here has no metadata, and THIS add carries it —
+            // a `.torrent` holds the file list, the piece hashes and the
+            // trackers outright. Waiting for the other one to become ready is
+            // waiting on the swarm to supply what is already in our hands, and
+            // when the swarm cannot (a magnet with no reachable peers) it never
+            // arrives: measured 2026-08-15, a magnet added first left every
+            // later attempt at the same infohash — including the complete
+            // `.torrent` — bound to an empty torrent, `/stream` answering 404
+            // and playback impossible until the proxy was restarted.
+            if (decision === "replace") {
+              logger.info(
+                `torrent-pool: [${dupMatch[1].slice(0, 8)}] replacing a torrent with no metadata ` +
+                `with the .torrent just given, which has it`
+              );
+              // Everything this class remembers about the old one goes with it,
+              // or a later request finds it through a map and works with a
+              // torrent the client no longer has.
+              for (const [otherKey, value] of this.torrents) {
+                if (value === existing) {
+                  this.torrents.delete(otherKey);
+                }
+              }
+              this.fileUsageByTorrent.delete(existing);
+              this.#lastAccess.delete(existing);
+              this.#readPositionByTorrent.delete(existing);
+              this.client.remove(existing, { destroyStore: true }, () => {
+                this.client.add(torrentId, {
+                  store: SharedPieceStore,
+                  storeCacheSlots: 0,
+                  storeOpts: { memoryBytes: this.#memoryBytes }
+                }, (replacement) => {
+                  this.torrents.set(key, replacement);
+                  this.#lastAccess.set(replacement, Date.now());
+                  this.#attachSwarmDiagnostics(dupMatch[1].slice(0, 8), replacement);
+                  this.#pending.delete(key);
+                  resolve(replacement);
+                });
+              });
+              return;
             }
+            // Both are magnets: there is nothing here the other does not have,
+            // so wait for the swarm — the caller's own bound answers if it
+            // takes too long.
+            existing.once("ready", settle);
             return;
           }
         }

package/test/duplicate-add.test.js

@@ -0,0 +1,48 @@
+/**
+ * @file One infohash, two sources: what happens when the second add is refused.
+ *
+ * The same film arrives as a magnet and as a `.torrent`. WebTorrent refuses the
+ * second add — one infohash, one torrent — and the pool then has to decide what
+ * to hand back. Adopting the one already there is right when it is ready, and
+ * wrong when it is not: a magnet whose swarm has not answered has no file list,
+ * so everything bound to it is answered 404.
+ *
+ * Measured 2026-08-15 on the addon host: a magnet with no reachable trackers
+ * was added first and never became ready; the same film's own `.torrent`, which
+ * carries the file list, the piece hashes and the trackers, then joined that
+ * empty torrent instead of replacing it. `/stream` answered 404, the encoder
+ * died on its first read, and the film stayed unplayable until the proxy was
+ * restarted — one bad magnet poisoning every later attempt at that infohash.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { duplicateAddDecision } from "../services/torrent-pool.js";
+
+test("a ready torrent is adopted, whatever the new source carries", () => {
+  assert.equal(
+    duplicateAddDecision({ existingIsReady: true, incomingHasMetadata: true }),
+    "adopt",
+    "one swarm per infohash: a second copy would download the same pieces twice"
+  );
+  assert.equal(
+    duplicateAddDecision({ existingIsReady: true, incomingHasMetadata: false }),
+    "adopt"
+  );
+});
+
+test("an unready torrent is replaced when this add brings the metadata", () => {
+  assert.equal(
+    duplicateAddDecision({ existingIsReady: false, incomingHasMetadata: true }),
+    "replace",
+    "the .torrent holds what the swarm was being asked for; waiting for it is waiting for nothing"
+  );
+});
+
+test("two magnets wait, because neither has anything the other lacks", () => {
+  assert.equal(
+    duplicateAddDecision({ existingIsReady: false, incomingHasMetadata: false }),
+    "wait",
+    "replacing here would only restart the same search, and the caller's own bound answers"
+  );
+});

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"
+  );
+});