@torrent-tv/proxy 2.13.0 → 2.14.1

package/services/hls-session-manager.js

@@ -75,6 +75,47 @@ const MASTER_PLAYLIST_FILE_NAME = "master.m3u8";
 // directory level, so every relative name inside a variant's own playlist — its
 // segments and its init — resolves to that variant without any of them changing.
 const VARIANT_PATH_PREFIX = "v";
+// Where an audio rendition lives, and the name the variants refer to it by. One
+// directory level under the base session, exactly as a quality variant is, so
+// every relative name inside its playlist resolves to it unchanged.
+const AUDIO_PATH_PREFIX = "a";
+const AUDIO_GROUP_ID = "aud";
+
+/**
+ * Quote a value for an HLS attribute list. Only the quote itself can end the
+ * attribute early, and a track title comes from the file, so it is not ours to
+ * trust.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAttribute(value) {
+  // The quote would end the attribute early; a line break would end the LINE,
+  // splitting one `#EXT-X-MEDIA` into two and corrupting the master. Both come
+  // from the file's own metadata, which is not ours to trust.
+  return String(value ?? "").replace(/"/g, "'").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+}
+
+// ISO 639-2 codes as ffmpeg reports them, against the RFC 5646 tags HLS asks
+// for. Only the languages this serves in practice; anything else is passed
+// through, which is what players other than iOS accept anyway.
+const LANGUAGE_TAGS = new Map([
+  ["rus", "ru"], ["eng", "en"], ["ukr", "uk"], ["deu", "de"], ["ger", "de"],
+  ["fra", "fr"], ["fre", "fr"], ["spa", "es"], ["ita", "it"], ["jpn", "ja"],
+  ["kor", "ko"], ["zho", "zh"], ["chi", "zh"], ["pol", "pl"], ["por", "pt"],
+  ["tur", "tr"], ["ces", "cs"], ["cze", "cs"], ["nld", "nl"], ["dut", "nl"]
+]);
+
+/**
+ * The RFC 5646 tag for a language ffmpeg named, or the name unchanged.
+ *
+ * @param {string} language
+ * @returns {string}
+ */
+function languageTag(language) {
+  const code = String(language ?? "").toLowerCase();
+  return LANGUAGE_TAGS.get(code) ?? code;
+}
 // The resolutions a viewer may choose between. Only rungs at or below the
 // source are offered: upscaling invents detail and costs the encoder more than
 // the source itself.
@@ -1155,6 +1196,7 @@ export class HlsSessionManager {
     getSourceStats = null,
     tonemapSupported = false,
     getCachedMediaInfo = null,
+    getCachedAudioTracks = null,
     segmentFormatId = undefined,
     stateDir = ""
   }) {
@@ -1171,6 +1213,9 @@ export class HlsSessionManager {
     // Optional accessor for media info the playback planner already probed for
     // (sourceKey, fileIndex), so session create can skip its own ffmpeg scan.
     this.getCachedMediaInfo = typeof getCachedMediaInfo === "function" ? getCachedMediaInfo : null;
+    // The file's audio tracks, for the master playlist's rendition group. Same
+    // inventory the browser's audio menu is built from.
+    this.getCachedAudioTracks = typeof getCachedAudioTracks === "function" ? getCachedAudioTracks : null;
     // Optional async accessor for a source's live download stats, used by the
     // realtime budget to tell a CPU limit from a download-starved input:
     // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
@@ -1254,6 +1299,20 @@ export class HlsSessionManager {
     startPositionSeconds = 0,
     audioTrackIndex = 0,
     manualQuality = false,
+    // The caller takes its audio from a rendition group, so the picture is
+    // encoded without it and each audio track is encoded once for the file
+    // instead of once per rung. Off unless asked for: a browser that does not
+    // know about renditions must still get its audio in the stream.
+    audioRenditions = false,
+    // This session IS one of those renditions: one audio track, no picture, cut
+    // on the same grid as the video it accompanies.
+    audioOnly = false,
+    // The arrangement decided by the session this one belongs to — a variant or
+    // a rendition of it. Every session of one master must agree about where the
+    // audio is, and only the base is in a position to decide: a variant asked on
+    // its own would answer about the rungs IT would be offered at, which is a
+    // different list. Null means "decide it here", which is what a base does.
+    inheritedAudioSeparate = null,
     segmentFormatId = "",
     // The cut grid of the session this one is a quality variant of: its
     // keyframe times and which container they were read from. Present only for
@@ -1308,6 +1367,11 @@ export class HlsSessionManager {
       String(normalizedTargetWidth),
       String(normalizedTargetHeight),
       forceManualQuality ? "q-manual" : "q-auto",
+      // What the output CARRIES. A picture without its audio, a single audio
+      // track without a picture, and the two muxed together are three different
+      // encodes of the same file, and nothing about them is interchangeable —
+      // so they cannot share a session, a directory or an encoder.
+      audioOnly === true ? "audio-only" : (audioRenditions === true ? "video-only" : "muxed"),
       String(normalizedStartPosition),
       // Two viewers asking for different containers cannot share one ffmpeg.
       segmentFormat.id,
@@ -1446,7 +1510,7 @@ export class HlsSessionManager {
     if (inheritedGrid) {
       keyframeTimes = inheritedGrid.keyframeTimes;
       containerFormat = inheritedGrid.containerFormat ?? "";
-    } else if (hasDuration && !transcodeVideo) {
+    } else if (hasDuration && !transcodeVideo && !audioOnly) {
       // Video-COPY path: keyframeTimes are REQUIRED to build correct segment
       // boundaries (the playlist itself), so this MUST block session creation —
       // an incorrect playlist is worse than a slower start. Short timeout: mp4
@@ -1515,10 +1579,17 @@ export class HlsSessionManager {
     // it produces every frame and may put keyframes where it likes — unless it
     // is a variant of a keyframe-cut session, in which case it must land on the
     // same times to be interchangeable with it.
+    // An audio rendition carries no picture, so it has no keyframes of its own
+    // to be cut at: it takes the grid of the video it accompanies, whatever that
+    // is. Handed one, it uses it; handed none, the base is on the even grid and
+    // so is this. Falling into the COPY branch instead — which is what
+    // `transcodeVideo: false` means everywhere else — would put the audio of a
+    // re-encoded stream on the source's keyframe times while the player was
+    // told the even grid, and the two drift further apart with every segment.
     const useKeyframeGrid = hasDuration &&
       Array.isArray(keyframeTimes) &&
       keyframeTimes.length > 0 &&
-      (!transcodeVideo || inheritedGrid != null);
+      (audioOnly ? inheritedGrid != null : (!transcodeVideo || inheritedGrid != null));
     // A rung takes the grid it was handed, rather than working one out again
     // from the same index. The two are not the same table: the one it is handed
     // has been CORRECTED wherever a produced segment showed the index to be
@@ -1614,6 +1685,12 @@ export class HlsSessionManager {
       transcodeVideo,
       transcodeAudio,
       audioTrackIndex: normalizedAudioTrack,
+      // What this session's output carries. `audioOnly` is a rendition — one
+      // audio track, no picture; `videoOnly` is a stream whose audio the viewer
+      // takes from such a rendition. Neither is set on the ordinary muxed
+      // session, which is what every browser gets until it says otherwise.
+      audioOnly: audioOnly === true,
+      audioRenditions: audioRenditions === true,
       outputFps,
       // Client-requested target box (the orientation-independent ceiling). Kept
       // for the session key and reference; the actual encode uses encodeWidth/
@@ -1750,6 +1827,23 @@ export class HlsSessionManager {
     }
     this.sessionsById.set(sessionId, session);
     this.sessionIdBySource.set(sourceMapKey, sessionId);
+    // Settled ONCE, here, and never derived again. Whether the audio travels
+    // separately decides the ffmpeg arguments, what the master says and whether
+    // the rendition route answers at all, and those three must agree for the
+    // whole life of the session — a session whose picture was encoded without
+    // audio cannot start muxing it in at the next restart without either
+    // playing it twice or refusing the append.
+    //
+    // It cannot be answered before this point (it asks what heights this
+    // session will be offered at, which needs the record) and it must not be
+    // asked after it, because the answer moves: the offered list is recomputed
+    // as the host learns what this source costs, and crossing "two rungs" would
+    // flip the arrangement under a stream that is playing.
+    session.audioSeparate = inheritedAudioSeparate === null
+      ? audioRenditions === true &&
+        this.#variantHeights(session).length >= 2 &&
+        this.#audioRenditionsOf(session).length > 0
+      : inheritedAudioSeparate === true;
 
     logger.info(
       // Proxy version on the session-start line: a field report always includes
@@ -1873,9 +1967,17 @@ export class HlsSessionManager {
       sourceKey: session.sourceKey,
       fileIndex: session.fileIndex
     }) ?? null;
+    // What the SOURCE has, narrowed to what this session's output carries. A
+    // rendition maps only audio and a stream whose audio travels separately
+    // maps only video, so answering from the source alone would tell the
+    // browser about a track that is not in the stream, and would leave
+    // `#initFromFirstSegment` waiting for a second track that no init will ever
+    // declare — its warning about a short header would then fire on every one.
+    const carriesVideo = session.audioOnly !== true;
+    const carriesAudio = !this.#servesAudioSeparately(session);
     return {
-      video: Boolean(probed?.videoCodec),
-      audio: Boolean(probed?.audioCodec)
+      video: carriesVideo && Boolean(probed?.videoCodec),
+      audio: carriesAudio && Boolean(probed?.audioCodec)
     };
   }
 
@@ -2528,8 +2630,34 @@ export class HlsSessionManager {
     if (this.videoEncoder?.kind !== "software") {
       return;
     }
+    // One tick at a time. It awaits torrent statistics per session now, so a
+    // slow or stuck answer would otherwise let the next tick in behind it —
+    // two passes over the same sessions, taking the same reading twice and
+    // acting on the same speed twice.
+    if (this.budgetTickRunning === true) {
+      return;
+    }
+    this.budgetTickRunning = true;
+    try {
+      await this.#realtimeBudgetPass();
+    } finally {
+      this.budgetTickRunning = false;
+    }
+  }
+
+  /** One pass over the sessions. See `#enforceRealtimeBudget`. */
+  async #realtimeBudgetPass() {
     const now = Date.now();
     for (const session of this.sessionsById.values()) {
+      // What this file costs to decode is learned from EVERY encoding session,
+      // before any of the budget's own conditions are consulted. Those exist to
+      // decide whether to step the quality down, and they exclude most of what
+      // is worth measuring: a rung already at the foot of its ladder has
+      // nowhere to step, and a 240p variant IS its whole ladder — which is
+      // exactly the rung the field measured at 0.95x on 2026-08-15, learning
+      // nothing from three minutes of it because the loop had already skipped
+      // the session as un-actionable.
+      await this.#learnFromEncoder(session);
       if (
         !session ||
         session.state === "disposed" ||
@@ -2565,10 +2693,6 @@ export class HlsSessionManager {
       }
       if (speed >= BUDGET_SPEED_OK) {
         session.budgetSlowSince = 0; // recovered — reset the slow window
-        // A run keeping up with realtime cannot be badly starved of input, so
-        // what it reports is about this machine and this source. That is the
-        // reading worth learning from, and it needs no further check.
-        this.#learnDecodeCost(session, speed);
         continue;
       }
       if (speed >= BUDGET_SPEED_SLOW) {
@@ -2596,10 +2720,6 @@ export class HlsSessionManager {
         session.budgetSlowSince = 0; // re-evaluate fresh; don't thrash on this
         continue;
       }
-      // Sustained, and the encoder — not the torrent — is what is short. So the
-      // figure describes the machine on this source, and it is the case that
-      // matters most: a rung nobody can hold teaches exactly here.
-      this.#learnDecodeCost(session, speed);
       await this.#applyBudgetDownshift(session, `speed=${speed.toFixed(2)}x`, bound);
     }
   }
@@ -2912,7 +3032,17 @@ export class HlsSessionManager {
       }
       args.push("-i", session.inputUrl);
     }
-    if (session.transcodeVideo) {
+    // Which timeline the output is labelled on. An audio rendition has no
+    // picture of its own to follow, so it follows the grid it was given — the
+    // same one the video it plays with is on. Deciding by `transcodeVideo`, as
+    // everything else here does, would put the audio of a re-encoded stream on
+    // the copy branch: `-copyts` and a shift by the container's start time,
+    // against a picture labelled from zero. The two would be offset by
+    // `sourceStartTime` for the whole file.
+    const onKeyframeGrid = session.audioOnly === true
+      ? session.cutGrid === "keyframe"
+      : !session.transcodeVideo;
+    if (!onKeyframeGrid) {
       // Branch A (re-encode): fixed GOP makes keyframes land exactly on the
       // segment grid; relabel output onto the original timeline so segment N
       // carries PTS = N × segmentDuration.
@@ -2932,15 +3062,29 @@ export class HlsSessionManager {
         args.push("-output_ts_offset", ffmpegSeconds(-sourceStartTime));
       }
     }
-    args.push(
-      "-map",
-      "0:v:0?",
-      "-map",
-      // Type-relative audio track chosen by the viewer (default 0).
-      `0:a:${session.audioTrackIndex ?? 0}?`,
-      ...videoCodecArgs,
-      ...audioCodecArgs
-    );
+    if (session.audioOnly === true) {
+      // An audio RENDITION: one track, no picture. Published as its own
+      // `#EXT-X-MEDIA` and shared by every video variant, so the track is
+      // encoded once for the file instead of once per rung, and changing it is
+      // the player switching rendition rather than this proxy rebuilding the
+      // session. Cut on the same grid as the video it accompanies, which is
+      // what lets the two be played together.
+      args.push("-vn", "-map", `0:a:${session.audioTrackIndex ?? 0}?`, ...audioCodecArgs);
+    } else if (this.#servesAudioSeparately(session)) {
+      // The other half of the same arrangement: the picture alone, because its
+      // audio is published as a rendition and would otherwise play twice.
+      args.push("-an", "-map", "0:v:0?", ...videoCodecArgs);
+    } else {
+      args.push(
+        "-map",
+        "0:v:0?",
+        "-map",
+        // Type-relative audio track chosen by the viewer (default 0).
+        `0:a:${session.audioTrackIndex ?? 0}?`,
+        ...videoCodecArgs,
+        ...audioCodecArgs
+      );
+    }
 
     // Where the cuts come from. On the copy path they are the source's own
     // keyframes, and until now they were only ever GUESSED: ffmpeg got a target
@@ -3426,6 +3570,17 @@ export class HlsSessionManager {
     if (head - index > BEHIND_HEAD_REPAIR_MAX_SEGMENTS) {
       return;
     }
+    // An audio rendition is never repaired by moving it. Its run is placed
+    // where the VIEWER is, from the session they are watching, so a request
+    // behind that is not a run in the wrong place — it is the player probing.
+    // Measured 2026-08-15: changing track at 159 s, hls.js asked for the new
+    // rendition's segment #0, the repair obligingly took the encoder to the
+    // start of the film, and the audio the viewer was waiting for arrived
+    // 20.5 s later instead of at once. Left where it is, the right segment is
+    // already being produced.
+    if (session.audioOnly === true) {
+      return;
+    }
     // Nothing is encoding: a rung the viewer has switched away from is left
     // exactly so, and its held requests must not bring its encoder back.
     if (session.ffmpeg == null || hasChildExited(session.ffmpeg)) {
@@ -3513,6 +3668,19 @@ export class HlsSessionManager {
     // variants, so a seek it reports means the stream on screen.
     named.viewerPositionSeconds = positionSeconds;
     named.lastAccessedAt = Date.now();
+    // The audio the viewer is listening to moves with them. It is a separate
+    // encoder on a separate session that the browser cannot name, and nothing
+    // else would ever reposition it: a request far AHEAD of its run is not
+    // 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() ?? []) {
+      const rendition = this.sessionsById.get(renditionId);
+      if (rendition && rendition.state !== "disposed") {
+        rendition.lastAccessedAt = Date.now();
+        this.#seekSession(rendition, positionSeconds);
+      }
+    }
     return this.#seekSession(this.#activeVariant(named), positionSeconds);
   }
 
@@ -4048,6 +4216,32 @@ export class HlsSessionManager {
     );
   }
 
+  /**
+   * The session a family answers as: the base a rung belongs to, or the session
+   * itself when it is not a rung.
+   *
+   * A rung knows only its own encode, so anything that is a property of the
+   * FILE rather than of one encode of it — what the source is, whether its
+   * video can be copied, which heights this host can serve it at — has to be
+   * asked here. A live base is required: a rung whose base has been disposed
+   * answers for itself rather than following a dead reference.
+   *
+   * @param {HlsSession} session
+   * @returns {HlsSession}
+   */
+  #baseOf(session) {
+    if (!(session?.variantBases instanceof Set)) {
+      return session;
+    }
+    for (const baseId of session.variantBases) {
+      const base = this.sessionsById.get(baseId);
+      if (base && base !== session && base.state !== "disposed") {
+        return base;
+      }
+    }
+    return session;
+  }
+
   /**
    * Every session cut on one grid: a base and its quality rungs.
    *
@@ -4168,43 +4362,65 @@ export class HlsSessionManager {
    * @returns {number[]}
    */
   #variantHeights(session) {
+    // Always answered by the family's BASE, whichever member is asking. A rung
+    // is a session of its own, and it knows only its own encode: asked while
+    // the viewer watches 240p, the 240p session priced the 1080p rung as a
+    // re-encode — because ITS video is re-encoded — and refused it on a host
+    // that was serving that very height by COPY minutes earlier. Field
+    // 2026-08-15: `proxy now offers 360p 240p` seconds after the switch, and
+    // the viewer could not go back. Only the base knows what the family can do
+    // with the source.
+    // Answered ON the base, never recursively: the family is one level deep by
+    // construction, and a `variantBases` cycle would otherwise blow the stack on
+    // the path that serves every playlist, init and segment.
+    const owner = this.#baseOf(session);
     // Settled once per session, and re-settled when this file's own decode cost
-    // is measured or improves. Everything else is fixed for the session's life
-    // — the source, the host's benchmarks, the height it settled on — and this
-    // is asked on the path that serves every playlist, init and segment, where
-    // recomputing it meant repeating the refusal in the log every few seconds.
-    const observed = this.#observedDecodeCost.get(`${session.sourceKey}:${session.fileIndex}`) ?? null;
-    const version = observed?.version ?? 0;
-    if (Array.isArray(session.offeredHeightsCache) && session.offeredHeightsVersion === version) {
-      return session.offeredHeightsCache;
-    }
-    session.offeredHeightsVersion = version;
-    const heights = new Set(variantHeightsFor(Number(session.sourceHeight) || 0));
-    const own = this.variantHeightOf(session);
+    // is measured or improves, or when the viewer moves to another rung — the
+    // rung on screen is exempt from refusal, so it is an INPUT to this list and
+    // belongs in what identifies a cached answer. Left out, the exemption
+    // outlived the rung: a rung the host cannot hold went on being offered, and
+    // went on passing every route guard, after the viewer had left it.
+    // Everything else is fixed for the session's life.
+    const observed = this.#observedDecodeCost.get(`${owner.sourceKey}:${owner.fileIndex}`) ?? null;
+    const playing = this.variantHeightOf(this.#activeVariant(owner));
+    const version = `${observed?.version ?? 0}:${playing}`;
+    if (Array.isArray(owner.offeredHeightsCache) && owner.offeredHeightsVersion === version) {
+      return owner.offeredHeightsCache;
+    }
+    const heights = new Set(variantHeightsFor(Number(owner.sourceHeight) || 0));
+    const own = this.variantHeightOf(owner);
     if (own > 0) {
       heights.add(own);
     }
     const ordered = [...heights].sort((left, right) => right - left);
-    // The rung ON SCREEN is never withdrawn. The list is now recomputed as the
-    // host learns what this source costs, and the reading that teaches it comes
-    // from the rung the viewer has just switched to — so the rung that taught
-    // the lesson would be the first to be dropped, and every route guard reads
-    // this list: its next segment would 404 on a stream that is playing, with
-    // its own encoder still running. It leaves the offer when the viewer leaves
-    // it, not while they are watching it.
-    const playing = this.variantHeightOf(this.#activeVariant(session));
-    session.offeredHeightsCache = this.#sustainableHeights({
+    // The rung ON SCREEN is never withdrawn while it is on screen. The list is
+    // recomputed as the host learns what this source costs, and the reading
+    // that teaches it comes from the rung the viewer has just switched to — so
+    // the rung that taught the lesson would be the first to be dropped, and
+    // every route guard reads this list: its next segment would 404 on a stream
+    // that is playing, with its own encoder still running.
+    const answer = this.#sustainableHeights({
       heights: ordered,
       ownHeight: own,
       playingHeight: playing,
-      sourceWidth: Number(session.sourceWidth) || 0,
-      sourceHeight: Math.round(Number(session.sourceHeight) || 0),
-      fps: Number(session.outputFps) || TRANSCODE_FPS,
-      source: session.sourceDecode ?? null,
-      transcodeVideo: session.transcodeVideo === true,
+      sourceWidth: Number(owner.sourceWidth) || 0,
+      sourceHeight: Math.round(Number(owner.sourceHeight) || 0),
+      fps: Number(owner.outputFps) || TRANSCODE_FPS,
+      source: owner.sourceDecode ?? null,
+      transcodeVideo: owner.transcodeVideo === true,
       observedDecodeCostSec: observed?.costSec ?? null
     });
-    return session.offeredHeightsCache;
+    if (owner !== session) {
+      // An orphan: its base is gone, so this is the family's last word and
+      // there is nobody to keep it for. Answering is right — the viewer is
+      // still watching it — but caching it on a session whose flags are its
+      // own encode's is how the wrong answer became the family's in the first
+      // place.
+      return answer;
+    }
+    owner.offeredHeightsVersion = version;
+    owner.offeredHeightsCache = answer;
+    return answer;
   }
 
   /**
@@ -4246,6 +4462,46 @@ export class HlsSessionManager {
    * @param {HlsSession} session
    * @param {number} speed - The `speed=` ffmpeg reports, as a multiple of realtime.
    */
+  /**
+   * Take a reading off an encoder that is running, if this one is worth having.
+   *
+   * Separate from the realtime budget, which asks a different question — should
+   * the quality step down — and answers it only where it CAN step down. Most of
+   * what is worth measuring is excluded by that: a rung at the foot of its
+   * ladder, a variant whose ladder is one rung long, a base whose video is
+   * copied. Measuring has no such preconditions.
+   *
+   * What it does refuse: a suspended encoder (ffmpeg reports a CUMULATIVE
+   * speed, so a look-ahead pause is divided into it and the figure decays while
+   * nothing is being encoded), a reading that has not moved since the last one
+   * (the loop runs every 5 s and a stalled encoder would otherwise fill the
+   * whole window with one frozen sample), and a run short of input, where what
+   * is short is the torrent rather than the machine.
+   *
+   * @param {HlsSession} session
+   */
+  async #learnFromEncoder(session) {
+    if (
+      !session ||
+      session.state === "disposed" ||
+      session.state === "failed" ||
+      !session.ffmpeg ||
+      session.encoderPaused === true ||
+      session.transcodeVideo !== true
+    ) {
+      return;
+    }
+    const speed = this.#parseSpeed(session.progress?.speed);
+    if (speed === null || speed === session.lastLearnedSpeed) {
+      return;
+    }
+    if (speed < BUDGET_SPEED_OK && await this.#classifyTranscodeBound(session) === "download") {
+      return; // the torrent is what is short; this says nothing about the host
+    }
+    session.lastLearnedSpeed = speed;
+    this.#learnDecodeCost(session, speed);
+  }
+
   #learnDecodeCost(session, speed) {
     if (session.transcodeVideo !== true || !(speed > 0)) {
       return; // a copied video decodes nothing, so it says nothing about decoding
@@ -4407,11 +4663,18 @@ export class HlsSessionManager {
     const dropped = [];
     for (const height of heights) {
       // The height an encoder is ALREADY producing, and the source's own height
-      // when the video is copied — neither has to be predicted, because it is
-      // happening. A source height that would have to be RE-ENCODED is a
-      // prediction like any other: on a session whose budget downshifted to
-      // 480p, the source's 1080p is neither copied nor being produced, and
-      // keeping it unpriced would offer exactly the kind of rung this refuses.
+      // when the FAMILY serves it by copy — neither has to be predicted,
+      // because it is happening. A copied rung costs no encoder at all, so no
+      // measurement of this host can ever be a reason to withdraw it, and the
+      // whole point of it is that it is where a viewer on a rung the machine
+      // cannot hold goes back to. `transcodeVideo` here is the base's, not the
+      // asking session's: a 240p rung re-encodes, and reading its own flag is
+      // what withdrew a copied 1080p in the field on 2026-08-15.
+      //
+      // A source height that would have to be RE-ENCODED is a prediction like
+      // any other: on a session whose budget downshifted to 480p, the source's
+      // 1080p is neither copied nor being produced, and keeping it unpriced
+      // would offer exactly the kind of rung this refuses.
       if (
         height === ownHeight ||
         height === playingHeight ||
@@ -4646,6 +4909,16 @@ export class HlsSessionManager {
       // variants could drift onto the same height and the choice would mean
       // nothing.
       manualQuality: true,
+      // A rung of a session whose audio is published separately carries no
+      // audio either — every rung of one master must agree about that, or
+      // switching rung would start or stop a second copy of the same track.
+      audioRenditions: base.audioRenditions === true,
+      // Not re-decided here: asked on its own, a variant would answer about the
+      // rungs IT would be offered at — a 540p rung of a copied 1080p source is
+      // offered nothing but itself, so it would conclude "audio muxed" and
+      // start carrying a second copy of a track the player is already fetching
+      // from the rendition.
+      inheritedAudioSeparate: base.audioSeparate === true,
       segmentFormatId: base.segmentFormat?.id ?? "",
       // Cut where the base is cut. Only for a base on the source's own keyframe
       // grid — a copy — where the variant has to land on those exact times to
@@ -4934,19 +5207,204 @@ export class HlsSessionManager {
     }
     const sourceWidth = Number(session.sourceWidth) || 0;
     const lines = ["#EXTM3U", `#EXT-X-VERSION:${session.segmentFormat.playlistVersion}`];
+    // The audio tracks, published once for the whole file rather than muxed
+    // into every rung. Two things follow from that: the same track is not
+    // encoded once per rung on a host that struggles to encode it once, and
+    // changing track becomes the player switching rendition instead of this
+    // proxy rebuilding the session with another `audioTrackIndex`.
+    //
+    // Only for a session that asked for them. A browser that does not know
+    // about renditions is served audio in its stream, as before, and gets no
+    // `#EXT-X-MEDIA` lines to be confused by.
+    const renditions = this.#servesAudioSeparately(session) ? this.#audioRenditionsOf(session) : [];
+    const audioGroup = renditions.length > 0 ? AUDIO_GROUP_ID : "";
+    for (const rendition of renditions) {
+      lines.push(
+        `#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="${audioGroup}",NAME="${escapeAttribute(rendition.name)}"` +
+        (rendition.language ? `,LANGUAGE="${escapeAttribute(languageTag(rendition.language))}"` : "") +
+        `,AUTOSELECT=YES,DEFAULT=${rendition.isDefault ? "YES" : "NO"}` +
+        `,URI="${AUDIO_PATH_PREFIX}/${rendition.trackIndex}/${PLAYLIST_FILE_NAME}"`
+      );
+    }
     for (const height of rungs) {
       const width = sourceHeight > 0 && sourceWidth > 0
         ? Math.round((sourceWidth / sourceHeight) * height / 2) * 2
         : 0;
       lines.push(
         `#EXT-X-STREAM-INF:BANDWIDTH=${estimatedBitrateFor(height)}` +
-        (width > 0 ? `,RESOLUTION=${width}x${height}` : "")
+        (width > 0 ? `,RESOLUTION=${width}x${height}` : "") +
+        (audioGroup ? `,AUDIO="${audioGroup}"` : "")
       );
       lines.push(`${VARIANT_PATH_PREFIX}/${height}/${PLAYLIST_FILE_NAME}`);
     }
     return `${lines.join("\n")}\n`;
   }
 
+  /**
+   * Whether this session's audio is published separately rather than muxed into
+   * its picture.
+   *
+   * Two things have to hold, and the second is why this is asked here rather
+   * than settled when the session was made. The browser must understand
+   * renditions — it says so when it creates the session, and one that does not
+   * has to be sent audio in the stream. AND there must be a master playlist to
+   * publish them in: a stream served as a single media playlist has nowhere to
+   * carry an `#EXT-X-MEDIA` line, so taking the audio out of it would leave the
+   * viewer with a picture and silence.
+   *
+   * @param {HlsSession} session
+   * @returns {boolean}
+   */
+  #servesAudioSeparately(session) {
+    return session.audioOnly !== true && session.audioSeparate === true;
+  }
+
+  /**
+   * One file of an audio rendition: its playlist, its init segment or one of
+   * its segments.
+   *
+   * A rendition is an ordinary session underneath — same source, same file,
+   * same cut grid, one audio track and no picture — created on the first
+   * request for it, exactly as a quality variant is. What differs is that the
+   * player fetches it ALONGSIDE a variant rather than instead of one, so both
+   * encoders run: a rung and the audio it is played with.
+   *
+   * @param {string} baseSessionId
+   * @param {number} trackIndex
+   * @param {string} fileName
+   * @returns {Promise<{ sessionId: string | null, error?: string }>}
+   */
+  async resolveAudioRenditionFile(baseSessionId, trackIndex, fileName) {
+    if (!isSafeSessionId(baseSessionId) || !Number.isInteger(trackIndex) || trackIndex < 0) {
+      return { sessionId: null };
+    }
+    const base = this.sessionsById.get(baseSessionId);
+    if (!base || base.state === "disposed" || !this.#servesAudioSeparately(base)) {
+      return { sessionId: null };
+    }
+    const isPlaylist = fileName === PLAYLIST_FILE_NAME;
+    const isInit = base.segmentFormat.initFileName !== null && fileName === base.segmentFormat.initFileName;
+    const isSegment = base.segmentFormat.isSegmentFileName(fileName);
+    if (!isPlaylist && !isInit && !isSegment) {
+      return { sessionId: null };
+    }
+    if (!this.#audioRenditionsOf(base).some((rendition) => rendition.trackIndex === trackIndex)) {
+      return { sessionId: null };
+    }
+    // The playlist is answered from the base, for the same reason a variant's
+    // is: every rendition of a file has the same boundaries and the same
+    // duration — they are cut on one grid — and the player fetches the playlist
+    // of tracks it may never select. Starting an encoder for each would put as
+    // many encoders on the host as the file has languages.
+    if (isPlaylist) {
+      return { sessionId: base.id };
+    }
+    let rendition;
+    try {
+      rendition = await this.#resolveAudioRenditionSession(base, trackIndex);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(
+        `transcode ${baseSessionId} could not prepare audio track ${trackIndex}: ${message}` +
+        (error instanceof Error && error.stack ? `\n${error.stack}` : "")
+      );
+      return { sessionId: null, error: message };
+    }
+    return { sessionId: rendition?.id ?? null };
+  }
+
+  /**
+   * The session producing one audio track of this file, made on first request.
+   *
+   * @param {HlsSession} base
+   * @param {number} trackIndex
+   * @returns {Promise<HlsSession | null>}
+   */
+  async #resolveAudioRenditionSession(base, trackIndex) {
+    const existingId = base.audioRenditionSessions?.get(trackIndex);
+    const existing = existingId ? this.sessionsById.get(existingId) : null;
+    if (existing && existing.state !== "disposed") {
+      existing.lastAccessedAt = Date.now();
+      return existing;
+    }
+    const rendition = await this.createOrGetSession({
+      sourceKey: base.sourceKey,
+      fileIndex: base.fileIndex,
+      // No picture at all: the video flag says what to do with a video stream
+      // this output does not carry.
+      transcodeVideo: false,
+      transcodeAudio: base.transcodeAudio,
+      fileName: base.fileName,
+      consumerId: variantConsumerId(base.id),
+      audioTrackIndex: trackIndex,
+      audioOnly: true,
+      // Where the viewer is, so the rendition starts with the picture rather
+      // than at the beginning of the file. Read the same way a quality variant
+      // reads it: the base's own field is only written by a seek or by a
+      // segment IT served, so on a resume-from-position open it is still unset
+      // 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.
+      startPositionSeconds:
+        Math.floor(this.#viewerPositionOf(this.#activeVariant(base)) / 10) * 10,
+      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
+      // table as it stands now, corrections included. A base on the uniform
+      // grid passes nothing: the rendition computes the same even grid from the
+      // same duration.
+      inheritedGrid: base.cutGrid === "keyframe"
+        ? {
+            boundaries: base.segmentBoundaries,
+            keyframeTimes: base.keyframeTimes,
+            containerFormat: base.containerFormat
+          }
+        : null,
+      acquireSource: base.acquireSource
+    });
+    if (!rendition) {
+      return null;
+    }
+    if (!(base.audioRenditionSessions instanceof Map)) {
+      base.audioRenditionSessions = new Map();
+    }
+    base.audioRenditionSessions.set(trackIndex, rendition.id);
+    return rendition;
+  }
+
+  /**
+   * The audio tracks of this session's file, as renditions for the master.
+   *
+   * Taken from the inventory the playback plan already probed — the same list
+   * the browser's audio menu is built from — so nothing is probed again here.
+   * The track the session was created with is the default one: it is what the
+   * viewer chose (or the file's first track), and a master that defaulted to
+   * something else would change the language on its own.
+   *
+   * @param {HlsSession} session
+   * @returns {Array<{ trackIndex: number, name: string, language: string, isDefault: boolean }>}
+   */
+  #audioRenditionsOf(session) {
+    const tracks = this.getCachedAudioTracks?.({
+      sourceKey: session.sourceKey,
+      fileIndex: session.fileIndex
+    }) ?? [];
+    if (!Array.isArray(tracks) || tracks.length === 0) {
+      return [];
+    }
+    const chosen = Number(session.audioTrackIndex) || 0;
+    return tracks.map((track, order) => {
+      const language = typeof track?.language === "string" ? track.language : "";
+      const title = typeof track?.title === "string" && track.title.length > 0 ? track.title : "";
+      return {
+        trackIndex: order,
+        name: title || language || `Track ${order + 1}`,
+        language,
+        isDefault: order === chosen
+      };
+    });
+  }
+
   /**
    * How many times the viewer has moved since this session started.
    *
@@ -5416,6 +5874,34 @@ export class HlsSessionManager {
     // at this position (server-side seeking).  The caller long-polls.
     if (!isPlaylist) {
       const requestedIndex = session.segmentFormat.segmentIndexFromName(fileName);
+      // An audio rendition asked for something behind its run says so at once
+      // instead of holding. Its run is placed where the viewer is and is not
+      // moved from there, so the request can never be answered — and holding it
+      // for the full window costs the player its own patience on the fragment
+      // it needs NEXT. Measured 2026-08-15: on a track change at 159 s hls.js
+      // asked for segment #0, and a held request plus a repaired encoder cost
+      // 20.5 s of silence. Refused promptly, the player moves to the segment
+      // that is genuinely being produced.
+      if (
+        session.audioOnly === true &&
+        Number.isFinite(requestedIndex) &&
+        requestedIndex < (session.encodeStartIndex ?? 0) &&
+        session.ffmpeg != null &&
+        // Not while a seek of its own is settling. A viewer seeking BACKWARDS
+        // is reported to the base and forwarded here, but the run only moves
+        // when the settle fires — until then `encodeStartIndex` still names the
+        // old position, and every request for the new one is "behind" it. Those
+        // are exactly the requests the viewer is waiting for, so they are held,
+        // as they were before this refusal existed.
+        session.seekTarget == null &&
+        session.seekSettleTimer == null
+      ) {
+        logger.info(
+          `transcode ${session.id} audio segment #${requestedIndex} is behind this rendition's run ` +
+          `(#${session.encodeStartIndex}); it is not made and the run stays where the viewer is`
+        );
+        return { kind: "not-found" };
+      }
       this.#ensureEncodingFor(
         session,
         requestedIndex,
@@ -5597,6 +6083,21 @@ export class HlsSessionManager {
         );
       }
     }
+    // The audio renditions of this session, for the same reason and in the same
+    // way. Nobody outside this class knows their ids — the browser holds one id
+    // for the whole file — so nothing else could ever release them, and each
+    // holds a consumer, a claim on the torrent, a directory and a live encoder.
+    if (session.audioRenditionSessions instanceof Map) {
+      const renditionIds = [...session.audioRenditionSessions.values()];
+      session.audioRenditionSessions.clear();
+      for (const renditionId of renditionIds) {
+        await this.releaseSessionConsumer(
+          renditionId,
+          variantConsumerId(sessionId),
+          "the session its audio belonged to ended"
+        );
+      }
+    }
     // Disposed on its own (idle, or with its last family): it must stop being
     // offered, or the next request for that height would be answered with a
     // session that no longer exists.