@torrent-tv/proxy 2.12.2 → 2.14.0

package/services/hls-session-manager.js

@@ -13,9 +13,9 @@ import { Readable } from "node:stream";
 import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import { logger } from "../utils/logger.js";
 import { readKeyframeIndex } from "./container-index/index.js";
 
@@ -25,10 +25,13 @@ import {
   softwareDescriptor,
   chooseSoftwareEncodeSettings,
   pickSoftwarePreset,
+  canSustainOutput,
+  REALTIME_SPEED_MARGIN,
   TRANSCODE_FPS,
   chooseOutputFps
 } from "./hwaccel.js";
 import {
+  parseFfmpegBitrateKbps,
   parseFfmpegDurationSeconds,
   parseFfmpegStartTimeSeconds,
   parseFfmpegVideoDimensions,
@@ -72,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.
@@ -112,6 +156,31 @@ export function variantHeightsFor(sourceHeight) {
   return [Math.round(sourceHeight), ...rungs];
 }
 
+/**
+ * What a source costs to DECODE, in the two figures the startup fit prices:
+ * its pixel rate and its bitrate. Every re-encode of this file pays this,
+ * whatever height it is encoded to, because the whole source is decoded first.
+ *
+ * Returns null when the probe did not report enough — the budget then prices
+ * the encoder alone rather than inventing a figure.
+ *
+ * @param {{ width: number | null, height: number | null, fps: number | null, bitrateKbps: number | null }} mediaInfo
+ * @returns {{ megapixelsPerSecond: number, megabitsPerSecond: number } | null}
+ */
+export function sourceDecodeCharacteristics(mediaInfo) {
+  const width = Number(mediaInfo?.width);
+  const height = Number(mediaInfo?.height);
+  const fps = Number(mediaInfo?.fps);
+  const kbps = Number(mediaInfo?.bitrateKbps);
+  if (!(width > 0) || !(height > 0) || !(fps > 0) || !(kbps > 0)) {
+    return null;
+  }
+  return {
+    megapixelsPerSecond: (width * height * fps) / 1e6,
+    megabitsPerSecond: kbps / 1000
+  };
+}
+
 /**
  * A fresh tally of how well a container's keyframe index matches its file.
  *
@@ -166,20 +235,51 @@ export function noteIndexDeviation(check, index, deviationSec) {
  * @param {{ ladder: { width: number, height: number }[], rungIndex: number } | null} budget
  * @param {number} outputFps
  * @param {unknown} benchmark
+ * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} [cost]
  * @returns {object | null}
  */
-function startAtLadderTop(budget, outputFps, benchmark) {
-  const top = budget?.ladder?.[0];
+function startAtLadderTop(budget, outputFps, benchmark, cost = {}) {
+  const ladder = budget?.ladder;
+  const top = ladder?.[0];
   if (!top) {
     return null;
   }
   const fps = Number.isInteger(outputFps) && outputFps > 0 ? outputFps : TRANSCODE_FPS;
+  // The top rung the viewer asked for, unless this host cannot hold it. A
+  // request naming a height arrives from a browser that was told which heights
+  // are on offer — but an older page, a stale tab or a repeated URL can still
+  // name one that was refused, and starting there means the encode never
+  // catches up. The runtime downshift would eventually step down; starting
+  // where the host can hold it means the viewer does not watch that happen.
+  // When NOTHING on the ladder can be held, start at its foot — the smallest
+  // picture this host has, which is the automatic path's answer to the same
+  // question and the best effort available. Starting at the top instead would
+  // hand the weakest hosts, the ones this exists for, the heaviest rung.
+  let startIndex = ladder.length - 1;
+  for (let index = 0; index < ladder.length; index += 1) {
+    const { sustainable } = canSustainOutput({
+      benchmark,
+      decodeModel: cost.decodeModel ?? null,
+      source: cost.source ?? null,
+      outputPixelsPerSec: ladder[index].width * ladder[index].height * fps,
+      observedDecodeCostSec: cost.observedDecodeCostSec ?? null
+    });
+    if (sustainable) {
+      startIndex = index;
+      break;
+    }
+  }
+  const start = ladder[startIndex];
   return {
     ...budget,
-    width: top.width,
-    height: top.height,
-    preset: pickSoftwarePreset(benchmark, top.width * top.height * fps),
-    rungIndex: 0
+    width: start.width,
+    height: start.height,
+    // Priced the same way the offer was. Without the cost the preset came from
+    // the encoder alone — so a rung offered on the combined figure was then
+    // encoded with a preset chosen as if decoding were free, which is how the
+    // check and the encode came to disagree on every rung a viewer picks.
+    preset: pickSoftwarePreset(benchmark, start.width * start.height * fps, cost),
+    rungIndex: startIndex
   };
 }
 
@@ -363,6 +463,18 @@ const BUDGET_SUSTAINED_MS = 15_000;
 const BUDGET_ACTION_COOLDOWN_MS = 30_000;
 // Never step down more than this many rungs below the startup choice.
 const BUDGET_MAX_DOWNSHIFTS = 3;
+// How long an encode run must have been going before a reading of its speed is
+// taken as evidence about decoding. `speed=` is cumulative over the run, so a
+// restart after a seek, a resume after a suspension and the wait for the first
+// pieces all sit in the denominator of an early reading.
+const DECODE_LEARNING_SETTLE_MS = 20_000;
+// How many readings the median is taken over. Long enough to outvote a single
+// disturbed moment, short enough to follow a host whose load has changed.
+const DECODE_LEARNING_READINGS = 7;
+// A new median has to differ by this much to be adopted. Below it the answer is
+// the same one, and re-publishing it would make every session recompute its
+// offer on the path that serves every playlist, init and segment.
+const DECODE_LEARNING_CHANGE = 0.05;
 // The input counts as "keeping up" when the torrent downloads at least this
 // multiple of the source's average byte rate. Below it (and not yet fully
 // downloaded), a low speed is download-bound, not CPU-bound → do NOT downscale.
@@ -621,6 +733,7 @@ async function probeInputMediaInfo(ffmpegBin, inputUrl) {
       const dims = parseFfmpegVideoDimensions(stderr);
       resolve({
         durationSeconds: parseFfmpegDurationSeconds(stderr),
+        bitrateKbps: parseFfmpegBitrateKbps(stderr),
         width: dims.width,
         height: dims.height,
         fps: parseFfmpegVideoFps(stderr),
@@ -1051,6 +1164,21 @@ export class HlsSessionManager {
    */
   #sessionCreateLatencies = [];
 
+  /**
+   * What decoding costs for a source this proxy has actually run, keyed by
+   * `sourceKey:fileIndex` — seconds of work per second of video, with a version
+   * that rises whenever a faster reading replaces the one held.
+   *
+   * The startup clips are H.264 and a source that has to be re-encoded usually
+   * is not, so their model is a first approximation. This is the file itself,
+   * measured by the encoder that is running on it, and it replaces the model
+   * for that file as soon as it exists. Held for the life of the process: it
+   * describes a source, and the same source is commonly opened again.
+   *
+   * @type {Map<string, { costSec: number, version: number }>}
+   */
+  #observedDecodeCost = new Map();
+
   /**
    * @param {HlsSessionManagerOptions} options
    */
@@ -1064,13 +1192,20 @@ export class HlsSessionManager {
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
     videoEncoder = null,
     softwarePresetBenchmark = null,
+    decodeCostModel = null,
     getSourceStats = null,
     tonemapSupported = false,
     getCachedMediaInfo = null,
-    segmentFormatId = undefined
+    getCachedAudioTracks = null,
+    segmentFormatId = undefined,
+    stateDir = ""
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    // Where measurements about this host are kept between runs. Empty means
+    // beside the installed proxy; a deployment with somewhere persistent to
+    // write names it (--state-dir).
+    this.stateDir = typeof stateDir === "string" ? stateDir : "";
     // Output container (fMP4/CMAF or MPEG-TS). Everything container-specific —
     // muxer args, file naming, playlist header, per-segment correction — lives
     // in this module; nothing here branches on the format.
@@ -1078,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>.
@@ -1090,6 +1228,13 @@ export class HlsSessionManager {
     // used to pick the best preset per stream. Null when unavailable (hardware
     // encoder, or benchmark skipped/failed).
     this.softwarePresetBenchmark = Array.isArray(softwarePresetBenchmark) ? softwarePresetBenchmark : null;
+    // Host decode cost solved at startup from the calibration clips:
+    // `a × Mpixel/s + b × Mbit/s + c` seconds of decoding per second of video.
+    // A re-encode pays for this as well as for the encoder, and leaving it out
+    // is what made the budget offer rungs this host ran at a third of realtime.
+    // Null when the clips are missing or the fit was rejected — the budget then
+    // prices the encoder alone, as it did before.
+    this.decodeCostModel = decodeCostModel ?? null;
     // Whether this ffmpeg build can tone-map HDR→SDR (zscale + tonemap filters).
     // Gates the tonemap chain for HDR sources on the software path.
     this.tonemapSupported = Boolean(tonemapSupported);
@@ -1154,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
@@ -1208,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,
@@ -1346,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
@@ -1415,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
@@ -1450,13 +1621,17 @@ export class HlsSessionManager {
     // resolution, so encode exactly that box (capped to source by the scale
     // filter) with the default preset, and the runtime downswitch is skipped
     // for the session (budgetLadder stays null).
+    // What decoding this source costs, which every re-encode pays on top of
+    // the encoder. Read from the probe; null when it did not say enough.
+    const sourceDecode = sourceDecodeCharacteristics(mediaInfo);
     const chosenBudget = this.#chooseEncodeBudget({
       transcodeVideo,
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
       sourceWidth,
       sourceHeight,
-      outputFps
+      outputFps,
+      source: sourceDecode
     });
     // A forced resolution starts at exactly that size — the viewer asked for it
     // — but KEEPS the ladder beneath it. Discarding the ladder is what left a
@@ -1466,7 +1641,13 @@ export class HlsSessionManager {
     // picture that plays beats a correct label that freezes. The rung's NAME is
     // settled separately and does not move with a downshift, so the player goes
     // on addressing it by the height it chose.
-    const encodeBudget = forceManualQuality ? startAtLadderTop(chosenBudget, outputFps, this.softwarePresetBenchmark) : chosenBudget;
+    const encodeBudget = forceManualQuality
+      ? startAtLadderTop(chosenBudget, outputFps, this.softwarePresetBenchmark, {
+          decodeModel: this.decodeCostModel,
+          source: sourceDecode,
+          observedDecodeCostSec: this.#observedDecodeCost.get(`${sourceKey}:${fileIndex}`)?.costSec ?? null
+        })
+      : chosenBudget;
     const softwarePreset = encodeBudget?.preset ?? null;
     // Effective encode box: the budget's downscaled resolution when applied,
     // otherwise the client target (0 = keep source, handled by buildVideoArgs).
@@ -1504,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/
@@ -1514,6 +1701,15 @@ export class HlsSessionManager {
       // software hosts, else the client target). 0 = keep source.
       encodeWidth,
       encodeHeight,
+      // The NAME of this rung, fixed at the height that was asked for. It is
+      // deliberately not the height being encoded: a viewer who picked 480p on
+      // a host that then starts them at 360p, or steps down to it later, goes
+      // on addressing the rung as 480p — and a request under the old name must
+      // not build a second session at a height this host has just refused.
+      // Derived from `encodeHeight` when nothing was named, as before.
+      variantHeight: forceManualQuality && normalizedTargetHeight > 0
+        ? normalizedTargetHeight
+        : undefined,
       // Whether to insert the HDR→SDR tone-map chain (software path only).
       applyTonemap,
       // Realtime-budget runtime state (software encoder only). The ladder is the
@@ -1531,6 +1727,8 @@ export class HlsSessionManager {
       linkSlowSince: 0,
       sourceWidth,
       sourceHeight,
+      // Pixel rate and bitrate of the source, for pricing a re-encode of it.
+      sourceDecode,
       // Container start time (seconds); subtracted on the copy path so the
       // output timeline is 0-based even when the source starts at e.g. 0.1 s.
       sourceStartTime,
@@ -1629,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
@@ -1752,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)
     };
   }
 
@@ -2011,10 +2234,10 @@ export class HlsSessionManager {
    * (no video transcode, hardware encoder, or missing benchmark/source size) —
    * the encode then keeps the ceiling resolution and the default preset.
    *
-   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null, outputFps: number }} params
+   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null, outputFps: number, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} params
    * @returns {{ width: number, height: number, preset: string } | null}
    */
-  #chooseEncodeBudget({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight, outputFps }) {
+  #chooseEncodeBudget({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight, outputFps, source = null }) {
     if (!transcodeVideo || this.videoEncoder?.kind !== "software" || !this.softwarePresetBenchmark) {
       return null;
     }
@@ -2022,7 +2245,12 @@ export class HlsSessionManager {
     if (!ceiling) {
       return null;
     }
-    return chooseSoftwareEncodeSettings(this.softwarePresetBenchmark, { width: ceiling.w, height: ceiling.h }, outputFps);
+    return chooseSoftwareEncodeSettings(
+      this.softwarePresetBenchmark,
+      { width: ceiling.w, height: ceiling.h },
+      outputFps,
+      { decodeModel: this.decodeCostModel, source }
+    );
   }
 
   /**
@@ -2402,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" ||
@@ -2529,7 +2783,20 @@ export class HlsSessionManager {
     session.budgetSlowSince = 0;
     session.encodeWidth = rung.width;
     session.encodeHeight = rung.height;
-    session.softwarePreset = pickSoftwarePreset(this.softwarePresetBenchmark, rung.width * rung.height * fps);
+    // Priced the same way the offer and the starting rung are. Choosing the
+    // preset on the encoder alone treats decoding as free, which is how the
+    // check and the encode came to disagree in the first place — and here it
+    // matters most, because this runs on a host that has already failed to keep
+    // up and is spending one of its few downshifts.
+    session.softwarePreset = pickSoftwarePreset(
+      this.softwarePresetBenchmark,
+      rung.width * rung.height * fps,
+      {
+        decodeModel: this.decodeCostModel,
+        source: session.sourceDecode ?? null,
+        observedDecodeCostSec: this.#observedDecodeCostFor(session)
+      }
+    );
     // Restart at the current live-edge segment so the lighter profile takes over
     // from where the viewer is watching (hard-restart tier).
     const head = session.encodeStartIndex;
@@ -2589,6 +2856,10 @@ export class HlsSessionManager {
     // produce a file that is neither, which is the only reason a restart ever
     // had to wait for its predecessor to die.
     session.runSerial = (session.runSerial ?? 0) + 1;
+    // When THIS run began. ffmpeg's `speed=` is cumulative over a run, so a
+    // reading of it says something about the machine only once the run has left
+    // its own start behind — see #learnDecodeCost.
+    session.encodeRunStartedAt = Date.now();
     session.runDirPath = path.join(session.dirPath, `run-${session.runSerial}`);
     await mkdir(session.runDirPath, { recursive: true });
     // The restart backs off a segment or two from what was asked for, so the
@@ -2761,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.
@@ -2781,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
@@ -3362,6 +3657,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);
   }
 
@@ -3611,8 +3919,20 @@ export class HlsSessionManager {
    * @returns {number | null} Milliseconds, or null without a benchmark.
    */
   /**
-   * Where this host's recorded timings live: one file, always the same path,
-   * beside the proxy's own installation.
+   * Where this host's recorded timings live: `--state-dir` when the deployment
+   * names one, otherwise beside the installed proxy, which is where they have
+   * always been kept.
+   *
+   * The default is deliberately the old location and not the working directory:
+   * measured on the addon, both are inside the container's writable layer and
+   * both are discarded when an update rebuilds it, so moving there bought
+   * nothing — while for an ordinary `npm i -g` install the working directory is
+   * wherever the operator happened to launch from, which splits the history
+   * between runs and drops a file into someone's project.
+   *
+   * A deployment that HAS a persistent directory says so: the addon passes
+   * `/data`, the one path its supervisor keeps across updates. Naming it here
+   * would put Home Assistant into proxy code, which this repo does not do.
    *
    * Kept so a proxy that has just restarted is not back to knowing nothing —
    * the browser was shown an assumed rate for the whole of the first wait after
@@ -3624,7 +3944,10 @@ export class HlsSessionManager {
    * @returns {string}
    */
   #hostTimingsPath() {
-    return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "host-timings.json");
+    const stateDir = typeof this.stateDir === "string" && this.stateDir.length > 0
+      ? this.stateDir
+      : path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+    return path.join(stateDir, "host-timings.json");
   }
 
   /** Load them, if any were ever written. Never throws. */
@@ -3637,9 +3960,11 @@ export class HlsSessionManager {
       if (Array.isArray(raw?.sessionCreate)) {
         this.#sessionCreateLatencies = raw.sessionCreate.filter((value) => Number.isFinite(value) && value > 0);
       }
+      const asMs = (value) => (value === null ? "n/a" : `${value}ms`);
       logger.info(
-        `host timings loaded: first-segment ${this.expectedFirstSegmentMs() ?? "n/a"}ms, ` +
-        `session-create ${this.expectedSessionCreateMs() ?? "n/a"}ms`
+        `host timings loaded from ${this.#hostTimingsPath()}: ` +
+        `first-segment ${asMs(this.expectedFirstSegmentMs())}, ` +
+        `session-create ${asMs(this.expectedSessionCreateMs())}`
       );
     } catch {
       // No file yet, or it is unreadable. The synthetic figure answers instead.
@@ -3880,6 +4205,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.
    *
@@ -4000,12 +4351,348 @@ export class HlsSessionManager {
    * @returns {number[]}
    */
   #variantHeights(session) {
-    const heights = new Set(variantHeightsFor(Number(session.sourceHeight) || 0));
-    const own = this.variantHeightOf(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, 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);
     }
-    return [...heights].sort((left, right) => right - left);
+    const ordered = [...heights].sort((left, right) => right - left);
+    // 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(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
+    });
+    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;
+  }
+
+  /**
+   * What decoding THIS source costs, learned from the encoder already running
+   * on it — seconds of work per second of video, or null until it is known.
+   *
+   * @param {HlsSession} session
+   * @returns {number | null}
+   */
+  #observedDecodeCostFor(session) {
+    const entry = this.#observedDecodeCost.get(`${session.sourceKey}:${session.fileIndex}`);
+    return entry ? entry.costSec : null;
+  }
+
+  /**
+   * Take one reading of a running encode and turn it into the decode cost of
+   * this source.
+   *
+   * A re-encode pays for both halves — unpacking the source and packing the
+   * result — and the running session measures the SUM. The encode half is
+   * priced by the startup benchmark for the preset and pixel rate actually in
+   * use, so subtracting it leaves the half that no startup benchmark can know:
+   * this file's own codec, resolution and grain, on this machine, under
+   * whatever else it is doing.
+   *
+   * The MEDIAN of the recent readings is used, over a bounded window. Keeping
+   * the fastest instead makes the figure a ratchet: `speed=` is cumulative over
+   * a run, its maximum falls in the burst where the encoder races to the
+   * look-ahead cap with the pieces already on disk and nothing competing, and
+   * one such moment would re-admit — permanently — the very rung the field
+   * measured at 0.388-0.947x. The median moves in both directions and describes
+   * the machine as it usually is, which is what a viewer will meet.
+   *
+   * A reading is only taken from a run that has been going long enough to have
+   * left its own start behind: ffmpeg's `speed=` is cumulative, so a restart
+   * after a seek, a resume after a suspension, and the wait for the first
+   * pieces are all in the denominator of an early reading.
+   *
+   * @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
+    }
+    const runStartedAt = Number(session.encodeRunStartedAt);
+    if (!Number.isFinite(runStartedAt) || Date.now() - runStartedAt < DECODE_LEARNING_SETTLE_MS) {
+      return; // no run, or one still carrying its own start in the average
+    }
+    if (this.videoEncoder?.kind !== "software") {
+      return; // the benchmark that prices the encode half is libx264 only
+    }
+    const benchmark = this.softwarePresetBenchmark;
+    if (!Array.isArray(benchmark) || benchmark.length === 0) {
+      return;
+    }
+    const entry = benchmark.find((item) => item.preset === session.softwarePreset);
+    if (!entry || !(entry.pixelsPerSec > 0)) {
+      return;
+    }
+    const height = Number(session.encodeHeight) || 0;
+    const width = Number(session.encodeWidth) || 0;
+    const fps = Number(session.outputFps) || TRANSCODE_FPS;
+    if (height <= 0 || width <= 0) {
+      return;
+    }
+    const encodeCostSec = (width * height * fps) / entry.pixelsPerSec;
+    const decodeCostSec = 1 / speed - encodeCostSec;
+    if (!(decodeCostSec > 0)) {
+      // The encode half already accounts for everything measured. Nothing is
+      // left to attribute to decoding, and a zero or negative cost would say
+      // decoding is free, which is a claim this reading cannot support.
+      return;
+    }
+    const key = `${session.sourceKey}:${session.fileIndex}`;
+    const known = this.#observedDecodeCost.get(key);
+    const readings = [...(known?.readings ?? []), decodeCostSec].slice(-DECODE_LEARNING_READINGS);
+    const sorted = [...readings].sort((left, right) => left - right);
+    const costSec = sorted[Math.floor(sorted.length / 2)];
+    if (known && Math.abs(costSec - known.costSec) / known.costSec < DECODE_LEARNING_CHANGE) {
+      // The same answer as before. Storing it would bump the version and make
+      // every session recompute its offer, which is asked for on the path that
+      // serves every playlist, init and segment.
+      this.#observedDecodeCost.set(key, { ...known, readings });
+      return;
+    }
+    this.#observedDecodeCost.set(key, { costSec, readings, version: (known?.version ?? 0) + 1 });
+    logger.info(
+      `transcode: ${session.fileName} decodes at ${(1 / costSec).toFixed(2)}x on this host ` +
+        `(median of ${readings.length}, latest ${(1 / decodeCostSec).toFixed(2)}x from ${height}p ` +
+        `at ${speed.toFixed(2)}x, preset ${session.softwarePreset})`
+    );
+  }
+
+  /**
+   * The heights this session's file will be served at, largest first — the
+   * public form of the same answer the master playlist is built from.
+   *
+   * The browser asks because the master is not the only way quality changes: a
+   * stream without variants changes it by re-opening the session at a chosen
+   * height, and that list was being invented in the browser from the source
+   * height alone. It has to come from the host that would have to encode it.
+   *
+   * @param {HlsSession} session
+   * @returns {number[]}
+   */
+  offeredHeights(session) {
+    if (!session || session.state === "disposed") {
+      return [];
+    }
+    return this.#variantHeights(session);
+  }
+
+  /**
+   * The heights this host would serve a file at, answered from the PROBE alone
+   * — before any session exists.
+   *
+   * The viewer sees the quality menu the moment they open a file, so the list
+   * cannot wait for an encoder to exist. Everything it needs is already known
+   * by then: the source's size, rate and bitrate from the probe, and this
+   * host's two benchmarks from startup.
+   *
+   * Both branches are answered because only the browser knows which one it will
+   * take — it decides per track whether it can play the video as it is. With a
+   * COPIED video the source height costs no encoder and is always there; with a
+   * re-encoded one it is a prediction like every other rung.
+   *
+   * These are first figures, not final ones: what the encoder then really does
+   * with this file replaces them (`offeredHeights` on a live session).
+   *
+   * @param {{ width: number | null, height: number | null, fps: number | null, bitrateKbps: number | null }} mediaInfo
+   * @returns {{ copy: number[], transcode: number[] } | null}
+   */
+  predictOfferedHeights(mediaInfo) {
+    const sourceHeight = Math.round(Number(mediaInfo?.height) || 0);
+    const sourceWidth = Number(mediaInfo?.width) || 0;
+    if (sourceHeight <= 0 || sourceWidth <= 0) {
+      return null;
+    }
+    const fps = chooseOutputFps(Number(mediaInfo?.fps) || 0);
+    const source = sourceDecodeCharacteristics(mediaInfo);
+    const heights = variantHeightsFor(sourceHeight);
+    // What an encoder has already been seen to cost on this very file, when it
+    // has run before. Without it a second open of a file answers from the
+    // startup clips again, undoing the correction the first playback earned.
+    const observedDecodeCostSec = mediaInfo?.sourceKey !== undefined
+      ? (this.#observedDecodeCost.get(`${mediaInfo.sourceKey}:${mediaInfo.fileIndex}`)?.costSec ?? null)
+      : null;
+    const forBranch = (transcodeVideo) =>
+      this.#sustainableHeights({
+        heights,
+        observedDecodeCostSec,
+        // Nothing is running yet, so nothing is exempt from being predicted —
+        // except the copy itself, which the branch flag already covers.
+        ownHeight: 0,
+        sourceWidth,
+        sourceHeight,
+        fps,
+        source,
+        transcodeVideo
+      });
+    return { copy: forBranch(false), transcode: forBranch(true) };
+  }
+
+  /**
+   * Drop the rungs this host cannot hold at realtime.
+   *
+   * Every rung below the source height is a full re-encode — decode the whole
+   * source, encode a smaller picture — and on a weak host that is dearer than
+   * the copy it replaces. Measured 2026-08-14: 1080p was copied at 7.8-8.9x
+   * while the offered 240p rung ran at 0.388-0.947x, its first segment took
+   * 30 s and later ones were held 22 s, so choosing a LOWER quality is what
+   * broke playback. A rung that cannot be produced faster than it is watched
+   * must not be offered at all.
+   *
+   * The session's OWN height always stays: an encoder is already producing it,
+   * and removing it would point the player at a rung nobody is encoding.
+   *
+   * @param {{ heights: number[], ownHeight: number, sourceWidth: number, sourceHeight: number, fps: number, source: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, transcodeVideo: boolean }} params
+   * @returns {number[]}
+   */
+  #sustainableHeights({
+    heights,
+    ownHeight,
+    playingHeight = 0,
+    sourceWidth,
+    sourceHeight,
+    fps,
+    source,
+    transcodeVideo,
+    observedDecodeCostSec = null
+  }) {
+    const benchmark = this.softwarePresetBenchmark;
+    if (!Array.isArray(benchmark) || benchmark.length === 0 || sourceHeight <= 0 || sourceWidth <= 0) {
+      return heights;
+    }
+    /** @type {number[]} */
+    const kept = [];
+    /** @type {string[]} */
+    const dropped = [];
+    for (const height of heights) {
+      // The height an encoder is ALREADY producing, and the source's own height
+      // 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 ||
+        (height === sourceHeight && !transcodeVideo)
+      ) {
+        kept.push(height);
+        continue;
+      }
+      const width = Math.round(((sourceWidth / sourceHeight) * height) / 2) * 2;
+      const { speed, sustainable } = canSustainOutput({
+        benchmark,
+        decodeModel: this.decodeCostModel,
+        source,
+        outputPixelsPerSec: width * height * fps,
+        observedDecodeCostSec
+      });
+      if (sustainable) {
+        kept.push(height);
+        continue;
+      }
+      dropped.push(`${height}p=${speed === null ? "n/a" : `${speed.toFixed(2)}x`}`);
+    }
+    if (dropped.length > 0) {
+      logger.info(
+        `transcode: not offering ${dropped.join(" ")} — below realtime × ${REALTIME_SPEED_MARGIN} ` +
+          `(offering ${kept.map((height) => `${height}p`).join(" ")})`
+      );
+    }
+    return kept;
   }
 
   /**
@@ -4211,6 +4898,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
@@ -4499,19 +5196,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.
    *
@@ -5075,6 +5957,12 @@ export class HlsSessionManager {
       currentHeight: session.transcodeVideo
         ? (session.encodeHeight ?? session.sourceHeight ?? 0)
         : (session.sourceHeight ?? 0),
+      // The rungs still worth offering, as they stand NOW. The list the browser
+      // was given when the file opened came from the startup benchmarks; this
+      // one is corrected by what the encoder has since been seen to do with
+      // this very source, so a rung that turns out to be beyond the host
+      // disappears from the menu instead of being discovered by switching to it.
+      offeredHeights: this.offeredHeights(session),
       // What this host takes to create a session and to make a first segment.
       // Also on the playback plan, but the browser reads that once per file:
       // measured 2026-08-06 across four seeks, a proxy that had just restarted
@@ -5156,6 +6044,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.