@torrent-tv/proxy 2.14.2 → 2.15.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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.
+- **Fix**: A request behind the encode run is acted on when the player ASKS AGAIN, not after three seconds of waiting. Repetition is the player saying it still needs that exact segment; a delay only says time has passed, and those three seconds were part of the twenty a track change cost. A scan is told apart by what else is being asked for — more than three distinct segments behind the run within two seconds is the player sweeping the playlist, and moving the encoder to one of them would be moving it to a number picked at random.
+- **Fix**: That scan count is taken over a two-second window rather than over the life of the run. Accumulated, it would have crossed the threshold on any long session and disabled the repair for good — silently, since nothing about a repair that never fires is logged.
+
 ## 2.14.2
 
 - **Fix**: A separately published audio track starts BEHIND the picture's read head, and a request behind its run is answered as before. Two mistakes compounded in 2.14.1 and left the viewer on a spinner that never ended. The position this class keeps is written by the segments a session serves — the READ head — while the viewer's picture sits behind it by everything they have buffered, so the track was started AHEAD of them: field 2026-08-15, the run placed at segment #16 while the player asked for #10. On top of that, 2.14.1 had begun answering such a request "not found" at once instead of holding it, which turned a condition the encoder used to correct in twenty seconds into a permanent refusal: hls.js retried #10 for a minute and a half, raised a fatal network error, recovered, and retried it again. The prompt refusal is withdrawn — it was written for a probe and met a real request — and the track now starts a whole look-ahead behind the read head, which is exactly how far apart the two can be. The price is audio the player already holds: at ten to twenty times realtime and 75 KB a piece, a second or two of work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.14.2",
+  "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

@@ -354,6 +354,10 @@ const READ_WINDOW_SECONDS = 30;
 const READ_WINDOW_MIN_BYTES = 16 * 1024 * 1024;
 const READ_WINDOW_MAX_BYTES = 96 * 1024 * 1024;
 const LOOKAHEAD_PAUSE_SECONDS = 120;
+// How old a viewer's link report may be and still describe where they are. It
+// is sent every 10 s, and a seek in between moves them somewhere this cannot
+// predict — so anything older is treated as no report at all.
+const NET_REPORT_FRESH_MS = 15_000;
 const LOOKAHEAD_RESUME_SECONDS = 60;
 // Seek debounce. A far (out-of-window) segment request is a server-side seek.
 // Rather than restart ffmpeg on the first one, wait a short quiet period:
@@ -389,7 +393,18 @@ const SEEK_SETTLE_MS = 300;
 // seek settles on its own — the seek is what should move the encoder — and
 // short enough that a session cannot sit on an unanswerable request, which
 // measured two minutes forty-one before a viewer gave up.
-const BEHIND_HEAD_REPAIR_MS = 3_000;
+// A request behind the run is acted on once it has been REPEATED, not once it
+// has waited: repetition is the player saying it still needs this exact
+// segment, while a delay only says time has passed. The floor below stays as a
+// last guard against acting on a single stray poll.
+const BEHIND_HEAD_REPAIR_MIN_ASKS = 2;
+// More distinct indices than this behind the head at once is the player
+// scanning the playlist rather than waiting for a frame.
+const BEHIND_HEAD_SCAN_INDICES = 3;
+// The window the count above is taken over. A player's scan lands inside half a
+// second (field log 2026-08-02); a viewer waiting asks every few seconds.
+const BEHIND_HEAD_SCAN_WINDOW_MS = 2_000;
+const BEHIND_HEAD_REPAIR_MS = 400;
 // How far behind the run a request may be and still be treated as the encoder
 // standing in the wrong place rather than as a player scanning the playlist. A
 // misplaced run is out by at most the buffer the player was holding — measured
@@ -2886,6 +2901,7 @@ export class HlsSessionManager {
     // for the seek that should move the encoder. It also stops the map growing
     // for the life of a session.
     session.firstWantedAt = new Map();
+    session.behindHeadAsks = new Map();
     const generation = ++session.encodeRunGeneration;
     const previousFfmpeg = session.ffmpeg;
     // A suspended process does not act on SIGTERM until it is continued, so the
@@ -3461,6 +3477,16 @@ export class HlsSessionManager {
     if (!session.firstWantedAt.has(index)) {
       session.firstWantedAt.set(index, Date.now());
     }
+    // How often each index behind the run has been asked for, and how many
+    // distinct ones there are. The repair reads both: one index asked twice is
+    // a viewer waiting, a dozen asked once each is the player scanning. Kept
+    // only for what is behind the head — everything ahead is ordinary
+    // read-ahead — and cleared with each run, like the record above.
+    if (index < session.encodeStartIndex) {
+      session.behindHeadAsks ??= new Map();
+      const asked = session.behindHeadAsks.get(index);
+      session.behindHeadAsks.set(index, { count: (asked?.count ?? 0) + 1, at: Date.now() });
+    }
     if (!session || session.state === "disposed" || index < 0) {
       return;
     }
@@ -3580,6 +3606,37 @@ export class HlsSessionManager {
     if (session.seekSettleTimer != null) {
       return;
     }
+    // What separates a request the viewer is waiting for from the player
+    // scanning the playlist is not TIME but what else it is asking for. On a
+    // seek hls.js fires dozens of DIFFERENT indices within half a second (field
+    // log: #178, #681, #725, #807, #74, #245, #387) and abandons them all; a
+    // viewer waiting for audio asks for the SAME one, over and over, because it
+    // is the only thing that will let playback continue.
+    //
+    // So: this index has been asked for at least twice, and it is the only
+    // thing behind the head being asked for. Both are facts about the traffic,
+    // available at once, where a delay is a guess about it — and it was three
+    // seconds of the twenty a track change cost on 2026-08-15.
+    const asked = session.behindHeadAsks?.get(index)?.count ?? 0;
+    if (asked < BEHIND_HEAD_REPAIR_MIN_ASKS) {
+      return;
+    }
+    // Counted over a WINDOW, not over the run: a scan is many indices at once,
+    // while the same map left to accumulate would eventually hold every
+    // behind-head request a long run ever saw and switch the repair off for
+    // good.
+    const scanSince = Date.now() - BEHIND_HEAD_SCAN_WINDOW_MS;
+    let distinctBehind = 0;
+    for (const record of session.behindHeadAsks?.values() ?? []) {
+      if (record.at >= scanSince) {
+        distinctBehind += 1;
+      }
+    }
+    if (distinctBehind > BEHIND_HEAD_SCAN_INDICES) {
+      // A scan, not a wait. Moving the encoder to one of these is moving it to
+      // a number the player picked at random.
+      return;
+    }
     const wantedAt = session.firstWantedAt?.get(index);
     if (!Number.isFinite(wantedAt) || Date.now() - wantedAt < BEHIND_HEAD_REPAIR_MS) {
       return;
@@ -3663,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();
@@ -4751,6 +4817,37 @@ export class HlsSessionManager {
     return this.#viewerPositionOf(this.#activeVariant(base));
   }
 
+  /**
+   * Where to start a separately published audio track, in seconds.
+   *
+   * The player, on changing track, discards the audio it holds and refills from
+   * the PICTURE onwards — so that is where the encoder has to begin. What this
+   * class knows directly is the read head, which runs ahead of the picture by
+   * the player's own buffer; the browser reports that buffer with every link
+   * report, so the picture is the one subtraction below.
+   *
+   * One segment of margin, because the report is up to ten seconds old and the
+   * picture has moved on since — a run that begins a little early costs a
+   * segment of audio nobody plays, while one that begins a little late is
+   * behind the viewer and can only be fixed by restarting it.
+   *
+   * With no fresh report, the whole look-ahead is subtracted instead: it is the
+   * furthest the two can be apart, so it cannot leave the run ahead of them.
+   *
+   * @param {HlsSession} base
+   * @returns {number}
+   */
+  #audioStartSecondsFor(base) {
+    const watching = this.#activeVariant(base);
+    const readHead = this.#viewerPositionOf(watching);
+    const report = watching.netReport;
+    const reportAge = Number.isFinite(report?.at) ? Date.now() - report.at : Number.POSITIVE_INFINITY;
+    const buffered = reportAge <= NET_REPORT_FRESH_MS && Number.isFinite(report?.bufferedAheadSec)
+      ? report.bufferedAheadSec
+      : LOOKAHEAD_PAUSE_SECONDS;
+    return Math.max(0, readHead - buffered - this.segmentDurationSec);
+  }
+
   #viewerPositionOf(session) {
     if (Number.isFinite(session.viewerPositionSeconds) && session.viewerPositionSeconds > 0) {
       return session.viewerPositionSeconds;
@@ -5041,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;
@@ -5299,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.
    *
@@ -5334,26 +5523,23 @@ export class HlsSessionManager {
       // while the player is asking for segment #537 — and the audio would begin
       // at zero and never catch up, since nothing treats a far request as a
       // seek. The accessor falls back to the last segment actually requested.
-      // Behind where the picture has been READ to, by the whole look-ahead.
+      // Where the PICTURE is, not where it has been read to.
       //
       // The position this class keeps is written by the segments a session
-      // serves, so it is the READ head, and the player's picture sits behind it
-      // by everything it has buffered — up to the look-ahead cap. Starting the
-      // audio at the read head therefore starts it AHEAD of the viewer, and
-      // every request they then make is behind a run that only moves forward.
-      // Field 2026-08-15: the run was placed at #16, the player asked for #10,
-      // and the audio never arrived until the encoder was dragged back.
+      // serves, so it is the READ head, and the viewer's picture sits behind it
+      // by everything the player has buffered. Started at the read head, the
+      // audio run begins AHEAD of the viewer, and every request they then make
+      // is behind a run that only moves forward — field 2026-08-15, placed at
+      // #16 while the player asked for #10, and the audio arrived only after
+      // the encoder was dragged back.
       //
-      // The cap is exactly how far apart the two can be, so subtracting it
-      // cannot leave the run ahead of the viewer. The price is audio the player
-      // already has — for a track being encoded at ten to twenty times realtime
-      // and served in 75 KB pieces, that is a second or two of work.
-      startPositionSeconds: Math.max(
-        0,
-        Math.floor(
-          (this.#viewerPositionOf(this.#activeVariant(base)) - LOOKAHEAD_PAUSE_SECONDS) / 10
-        ) * 10
-      ),
+      // The distance is measured, not assumed: the browser reports how many
+      // seconds it holds ahead of the picture with every link report, so the
+      // playhead is one subtraction away. A stale report is no use — a viewer
+      // who seeked since then is somewhere else entirely — so an old one is
+      // ignored and the whole look-ahead is subtracted instead, which cannot
+      // leave the run ahead of them.
+      startPositionSeconds: this.#audioStartSecondsFor(base),
       segmentFormatId: base.segmentFormat.id,
       // Cut where the picture is cut. Two streams meant to be played together
       // have to be divided at the same times, and the grid is the base's — the

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/behind-head-repair.test.js

@@ -71,16 +71,23 @@ async function managerWithRunAhead() {
   return { manager, session, dirPath, restarts };
 }
 
-test("a request behind the run is repaired once it has waited", async (t) => {
+test("a request behind the run is repaired once the player asks again", async (t) => {
   const { manager, session, dirPath } = await managerWithRunAhead();
   t.after(async () => {
     await manager.disposeAll();
     await rm(dirPath, { recursive: true, force: true });
   });
-  // Asked for four seconds ago and still unanswerable.
-  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+  // Asked for a moment ago and still unanswerable. What decides is that the
+  // player comes BACK for the same segment: it is the only one it wants, and no
+  // amount of waiting could say that as clearly.
+  session.firstWantedAt.set(WANTED, Date.now() - 1000);
+  const name = fmp4Format.segmentFileName(WANTED);
 
-  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+  await manager.getFileStream(SESSION_ID, name, { requestSeq: 1 });
+
+  assert.equal(session.seekTarget, null, "one poll is not yet evidence");
+
+  await manager.getFileStream(SESSION_ID, name, { requestSeq: 2 });
 
   assert.equal(
     session.seekTarget,
@@ -89,6 +96,33 @@ test("a request behind the run is repaired once it has waited", async (t) => {
   );
 });
 
+test("a burst of different segments behind the run is a scan, and moves nothing", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // What hls.js does on a seek: dozens of indices within half a second, each
+  // abandoned. Field log 2026-08-02: #178, #681, #725, #807, #74, #245, #387.
+  const scanned = [WANTED, WANTED - 40, WANTED - 120, WANTED - 200, WANTED - 300];
+  for (const index of scanned) {
+    session.firstWantedAt.set(index, Date.now() - 1000);
+  }
+  // Interleaved, as they arrive on the wire: the player opens them together
+  // rather than finishing with one before opening the next.
+  for (const seq of [1, 2]) {
+    for (const index of scanned) {
+      await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(index), { requestSeq: seq });
+    }
+  }
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "moving the encoder to one of these would be moving it to a number the player picked at random"
+  );
+});
+
 test("a request behind the run is left alone at first", async (t) => {
   const { manager, session, dirPath } = await managerWithRunAhead();
   t.after(async () => {

package/test/quality-variants.test.js

@@ -638,19 +638,18 @@ test("a rung served by copy stays offered while a re-encoded rung is on screen",
   );
 });
 
-test("a separately published audio track starts behind the picture's read head", async (t) => {
+test("a separately published audio track starts where the picture is, from the reported buffer", async (t) => {
   const { manager, base, dirPath } = await managerWithBase();
   t.after(async () => {
     await manager.disposeAll();
     await rm(dirPath, { recursive: true, force: true });
   });
-  // What broke playback on 2026-08-15: the position this class keeps is where
-  // segments have been SERVED to, and the viewer's picture is behind it by
-  // everything they have buffered. Started at the read head, the audio run sat
-  // ahead of the viewer and every request they made was behind a run that only
-  // moves forward.
-  base.viewerPositionSeconds = 140;
   base.audioSeparate = true;
+  // Served up to 140 s, and the browser says it holds 40 s ahead of the
+  // picture — so the viewer is at 100 s, and that, less a segment of margin,
+  // is where the track has to begin.
+  base.viewerPositionSeconds = 140;
+  base.netReport = { linkMbps: 20, bufferedAheadSec: 40, at: Date.now() };
   manager.getCachedAudioTracks = () => [
     { index: 0, language: "rus", title: "", isDefault: true },
     { index: 1, language: "eng", title: "", isDefault: false }
@@ -663,13 +662,77 @@ test("a separately published audio track starts behind the picture's read head",
     return { sessionId: VARIANT_ID, session: rendition };
   };
 
-  // A segment, not the playlist: the playlist is answered from the base and
-  // deliberately starts no encoder.
   await manager.resolveAudioRenditionFile(BASE_ID, 1, "segment-00010.mp4");
 
   assert.equal(created.length, 1, "the track's own session was made");
-  assert.ok(
-    created[0].startPositionSeconds <= 20,
-    `started behind the picture, not at the read head — got ${created[0].startPositionSeconds}s for a read head of 140s`
+  assert.equal(
+    created[0].startPositionSeconds,
+    96,
+    "140 s served, less the 40 s the player holds, less one segment of margin"
+  );
+});
+
+test("a stale buffer report is not used to place an audio track", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  base.audioSeparate = true;
+  base.viewerPositionSeconds = 300;
+  // Sent a minute ago: the viewer may have seeked anywhere since, so it says
+  // nothing about where they are now.
+  base.netReport = { linkMbps: 20, bufferedAheadSec: 5, at: Date.now() - 60_000 };
+  manager.getCachedAudioTracks = () => [
+    { index: 0, language: "rus", title: "", isDefault: true },
+    { index: 1, language: "eng", title: "", isDefault: false }
+  ];
+  const created = [];
+  manager.createOrGetSession = async (params) => {
+    created.push(params);
+    const rendition = fakeSession({ id: VARIANT_ID, encodeHeight: 0, dirPath });
+    rendition.audioOnly = true;
+    return { sessionId: VARIANT_ID, session: rendition };
+  };
+
+  await manager.resolveAudioRenditionFile(BASE_ID, 1, "segment-00010.mp4");
+
+  assert.equal(
+    created[0].startPositionSeconds,
+    176,
+    "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"
   );
 });