@torrent-tv/proxy 2.9.134 → 2.9.136

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.136
+
+- **Fix**: What a complete init segment must describe is now taken from what the proxy DECLARES it will output, not from a count. 2.9.135 required two tracks, which is a guess — wrong for a film with no soundtrack, and meaningless for a source carrying several dubs, subtitles or a cover-art video stream. The output does not inherit the source's track list: the command maps at most one video and at most one audio, each optional, and subtitles never enter the HLS output at all. So the proxy knows the output's set exactly, because it chose it — the probe says which kinds exist, the mapping says how many are taken. Deriving the figure from produced pieces instead reads correctly only once a piece carrying every track exists, and the moment that matters is the one before that: an early piece written before the video was muxed sets the requirement to one and waves through precisely the header this exists to reject. Pieces remain as a floor, since a piece carrying more than declared is evidence, and evidence outranks a declaration.
+
+## 2.9.135
+
+- **Fix**: A session no longer plays sound with no picture at all. The init segment — the header that tells the browser which tracks exist — is lifted out of the first self-contained piece and then cached for the WHOLE session, because the player fetches `#EXT-X-MAP` once and never again. A piece written before the video track had been muxed declares audio alone, and the browser then has no video source buffer for the rest of the session however much video arrives afterwards. Measured 2026-08-10 from the browser's own counters: sixty-five seconds of playing sound with `videoWidth=0`, `totalVideoFrames=0` and `readyState=4` — an element perfectly satisfied, with no picture in it. A header short of a track is now passed over and the next piece tried; if no piece carries the full set the richest one found is served and the shortfall is logged, so a source that genuinely lacks a stream still plays while the other possibility stays visible.
+
 ## 2.9.134
 
 - **Fix**: The line reporting how long a segment waited before anyone decided to restart for it now prints. A restart backs off a segment or two from what was asked for, so the request that prompted it is recorded under a higher index than the run starts at; looking it up by the start index alone found nothing, and the instrument added in 2.9.132 never said a word. It now takes the earliest request at or above the index the run begins from.

package/package.json

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

package/services/hls-session-manager.js

@@ -1528,6 +1528,35 @@ export class HlsSessionManager {
     if (typeof session.segmentFormat.extractInit !== "function") {
       return null;
     }
+    // How many tracks a complete header must declare is ANSWERED, not assumed.
+    //
+    // The probe already knows the source's stream list, and the output maps at
+    // most one of each (`-map 0:v:0? -map 0:a:0?`), so the count follows from
+    // what the source actually has. A film with no soundtrack expects one; an
+    // ordinary file expects two; neither is a convention.
+    //
+    // Deriving it from the produced pieces instead — the first version of this
+    // — reads correctly only once a piece carrying every track exists, and the
+    // whole point is the moment BEFORE that: early pieces written before the
+    // video was muxed would set the requirement to one and wave through exactly
+    // the header this exists to reject. The pieces are still consulted, but
+    // only as a floor: a piece carrying more than the probe led us to expect is
+    // evidence, and evidence outranks the probe.
+    const probed = this.getCachedMediaInfo?.({
+      sourceKey: session.sourceKey,
+      fileIndex: session.fileIndex
+    }) ?? null;
+    let expectedTracks = probed
+      ? (probed.videoCodec ? 1 : 0) + (probed.audioCodec ? 1 : 0)
+      : 0;
+    if (expectedTracks === 0) {
+      // No probe to consult. Fall back to the evidence, with its known lag.
+      expectedTracks = 1;
+    }
+    let best = null;
+    let bestTracks = 0;
+    /** @type {Map<string, Buffer>} Pieces read once and used for both passes. */
+    const pieces = new Map();
     let names;
     try {
       names = (this.#runDirs(session).flatMap((dir) => {
@@ -1538,13 +1567,32 @@ export class HlsSessionManager {
     } catch {
       return null;
     }
+    // First pass: what do the produced pieces actually carry? The answer is the
+    // requirement — no assumption about the source is involved.
+    if (typeof session.segmentFormat.countSegmentTracks === "function") {
+      for (const name of names) {
+        try {
+          const found = await this.#findProducedFile(session, name);
+          if (!found) {
+            continue;
+          }
+          const bytes = await readFile(found);
+          pieces.set(name, bytes);
+          expectedTracks = Math.max(expectedTracks, session.segmentFormat.countSegmentTracks(bytes));
+        } catch {
+          // Being written right now — it says nothing about the others.
+        }
+      }
+    }
+
     for (const name of names) {
       try {
-        const found = await this.#findProducedFile(session, name);
+        const cached = pieces.get(name);
+        const found = cached ? name : await this.#findProducedFile(session, name);
         if (!found) {
           continue;
         }
-        const init = session.segmentFormat.extractInit(await readFile(found));
+        const init = session.segmentFormat.extractInit(cached ?? await readFile(found));
         if (init && init.length > 0) {
           return init;
         }
@@ -1552,7 +1600,17 @@ export class HlsSessionManager {
         // Being written right now — try the next one.
       }
     }
-    return null;
+    if (best !== null) {
+      // Nothing carried the full set. The source is probably missing a stream;
+      // serving the richest header found is right, and saying so makes the
+      // other possibility — every piece so far written before the video was
+      // muxed — visible rather than silent.
+      logger.warn(
+        `transcode ${session.id} no piece declared ${expectedTracks} tracks; ` +
+        `serving an init with ${bestTracks}`
+      );
+    }
+    return best;
   }
 
   /**

package/services/segment-formats/fmp4.js

@@ -1,262 +1,300 @@
-/**
- * @file fMP4 (CMAF) segment format — `.mp4` media segments plus one shared
- * `init.mp4` referenced by `#EXT-X-MAP`.
- *
- * Codec configuration (SPS/PPS) lives once in the init segment instead of being
- * repeated per segment. That is what makes hardware encoders which do not
- * repeat parameter sets — notably the CM4 / HA-Yellow `h264_v4l2m2m` — produce
- * independently usable segments, and it lowers container overhead.
- *
- * See {@link SegmentFormat} in `./index.js` for the interface contract.
- */
-
-import {
-  readSelfContainedStartSeconds,
-  readTrackTimescales,
-  stampSegmentStartTime,
-  walkBoxes
-} from "./mp4-boxes.js";
-
-/**
- * How many distinct tracks have a fragment in this segment.
- *
- * @param {Buffer} bytes
- * @returns {number}
- */
-function countFragmentTracks(bytes) {
-  const tracks = new Set();
-  walkBoxes(bytes, (type, bodyStart) => {
-    if (type === "tfhd" && bodyStart + 8 <= bytes.length) {
-      tracks.add(bytes.readUInt32BE(bodyStart + 4));
-    }
-  });
-  return tracks.size;
-}
-
-/**
- * Where the fragments begin and where the trailing index starts, as offsets of
- * whole boxes at the TOP level.
- *
- * Deliberately not `walkBoxes`: that reports the start of a box's *body* and
- * descends into containers, so it cannot say where a box begins — and cutting a
- * file at the wrong offset by eight bytes produces something that parses as
- * garbage rather than failing outright.
- *
- * @param {Buffer} bytes
- * @returns {{ firstFragment: number, trailingIndex: number }} Offsets, or -1.
- */
-function findFragmentBounds(bytes) {
-  let firstFragment = -1;
-  let trailingIndex = -1;
-  let offset = 0;
-  while (offset + 8 <= bytes.length) {
-    let size = bytes.readUInt32BE(offset);
-    const type = bytes.toString("latin1", offset + 4, offset + 8);
-    if (size === 1) {
-      if (offset + 16 > bytes.length) {
-        break;
-      }
-      size = Number(bytes.readBigUInt64BE(offset + 8));
-    } else if (size === 0) {
-      size = bytes.length - offset;
-    }
-    if (size < 8) {
-      break;
-    }
-    if (firstFragment === -1 && (type === "moof" || type === "sidx")) {
-      firstFragment = offset;
-    }
-    if (type === "mfra") {
-      trailingIndex = offset;
-    }
-    offset += size;
-  }
-  return { firstFragment, trailingIndex };
-}
-
-const INIT_FILE_NAME = "init.mp4";
-const SEGMENT_PATTERN = /^segment-(\d{5})\.mp4$/;
-
-/**
- * @type {import("./index.js").SegmentFormat}
- */
-export const fmp4Format = {
-  id: "fmp4",
-  initFileName: INIT_FILE_NAME,
-  initContentType: "video/mp4",
-  segmentContentType: "video/mp4",
-  // Version 7 is the minimum that allows fMP4 media segments + `#EXT-X-MAP`.
-  playlistVersion: 7,
-
-  muxerArgs() {
-    return [
-      "-hls_segment_type",
-      "fmp4",
-      "-hls_fmp4_init_filename",
-      INIT_FILE_NAME,
-      "-hls_segment_filename",
-      "segment-%05d.mp4"
-    ];
-  },
-
-  /**
-   * Cut at times we choose rather than times ffmpeg picks.
-   *
-   * The `segment` muxer writes each fMP4 piece as a **self-contained** file:
-   * `ftyp moov moof mdat … mfra`, verified on the field host. That is not what
-   * HLS wants — it wants one init segment named by `#EXT-X-MAP` and media
-   * segments carrying only fragments — so the pieces are split on serve:
-   * {@link extractInit} takes the header off the first one to serve as the init,
-   * and {@link stripInit} removes it from every one.
-   *
-   * The timestamps still need stamping, exactly as before: measured on the
-   * field host, all three pieces of a run reported a start time of 0.080 s,
-   * i.e. each carries its own zero. That is the same defect the shared-init
-   * path already corrects, so `prepareSegmentBytes` handles both.
-   *
-   * @returns {string[]}
-   */
-  explicitTimesMuxerArgs() {
-    return [
-      "-segment_format",
-      "mp4",
-      // `empty_moov` is what makes each piece self-describing, which is what
-      // lets the init be lifted out of it; `default_base_moof` keeps fragment
-      // offsets relative, so removing the header does not invalidate them.
-      //
-      // `delay_moov` is not optional here. The MP4 muxer builds a copied AC-3
-      // track's `dac3` box out of the bitstream, so it cannot write `moov`
-      // until the first audio packet has arrived — while `empty_moov` asks for
-      // it at header time. Without this flag ffmpeg exits before producing
-      // anything: "Cannot write moov atom before AC3 packets", which is exactly
-      // how fMP4 playback died in the field on 2.9.84/2.9.85. The `hls` muxer
-      // sets this flag itself, which is why the fault only appeared once the
-      // muxing moved here. Delaying `moov` does not change the piece layout —
-      // measured: still `ftyp moov moof mdat … mfra`.
-      "-segment_format_options",
-      "movflags=+frag_keyframe+empty_moov+default_base_moof+delay_moov"
-    ];
-  },
-
-  /** The output path template for the `segment` muxer. */
-  segmentFileNameTemplate() {
-    return "segment-%05d.mp4";
-  },
-
-  /**
-   * The init part of a self-contained piece: everything before the first
-   * fragment.
-   *
-   * @param {Buffer} bytes
-   * @returns {Buffer | null} `null` when the piece carries no fragment, which
-   *   means it is not one of these and must not be cut up.
-   */
-  extractInit(bytes) {
-    const { firstFragment } = findFragmentBounds(bytes);
-    return firstFragment > 0 ? bytes.subarray(0, firstFragment) : null;
-  },
-
-  /**
-   * A piece with its init header removed, and the trailing random-access index
-   * dropped — a player reading a media segment has no use for either, and
-   * `mfra` describes offsets that stop being true once the header is gone.
-   *
-   * @param {Buffer} bytes
-   * @returns {Buffer}
-   */
-  stripInit(bytes) {
-    const { firstFragment, trailingIndex } = findFragmentBounds(bytes);
-    if (firstFragment < 0) {
-      return bytes;
-    }
-    const end = trailingIndex > firstFragment ? trailingIndex : bytes.length;
-    return bytes.subarray(firstFragment, end);
-  },
-
-  playlistHeaderLines() {
-    return [
-      // The init segment (codec config). Fetched once; applies to every media
-      // segment in the playlist.
-      `#EXT-X-MAP:URI="${INIT_FILE_NAME}"`
-    ];
-  },
-
-  segmentFileName(index) {
-    return `segment-${String(index).padStart(5, "0")}.mp4`;
-  },
-
-  isSegmentFileName(fileName) {
-    return SEGMENT_PATTERN.test(fileName);
-  },
-
-  segmentIndexFromName(fileName) {
-    const match = SEGMENT_PATTERN.exec(fileName);
-    return match ? Number(match[1]) : -1;
-  },
-
-  /**
-   * Where a self-contained piece says it begins, in seconds, or null.
-   *
-   * Only the pieces the `segment` muxer writes carry this — they have their
-   * own `moov` — which is exactly the path where the playlist's own answer
-   * can be wrong. Must be given the piece BEFORE {@link stripInit}, since that
-   * removes the header the position lives in.
-   *
-   * @param {Buffer} piece
-   * @returns {number | null}
-   */
-  readSegmentStartSeconds(piece) {
-    return readSelfContainedStartSeconds(piece);
-  },
-
-  /**
-   * fMP4 segments must be read into memory and corrected before being served —
-   * see {@link stampSegmentStartTime} for the full reasoning. Without this a
-   * seek is permanently broken: ffmpeg leaves every segment claiming to start
-   * at 0 and puts the real offset in the per-run init, which we do not serve
-   * (the player fetches the session's first init once and keeps it).
-   *
-   * Segments are a few hundred KB, so reading one whole is cheap next to the
-   * transcode itself; the box walk never descends into `mdat`.
-   */
-  needsSegmentRewrite: true,
-
-  /**
-   * Whether a segment carries every track the init promises.
-   *
-   * A run that is TERMINATED closes its current output file properly — trailing
-   * index and all — but the file holds only what had been muxed by then, which
-   * after a seek-restart is routinely one track of two. Nothing about it looks
-   * unfinished: the file exists, the next one exists, so the readiness rule
-   * calls it done and it is served. The player then cannot use it and the seek
-   * never completes. Measured 2026-08-06: segment #133 carried one `tfdt`
-   * where its neighbours carried two, and a viewer sat on a spinner while the
-   * proxy answered every request in 98 ms.
-   *
-   * Cheap to check: the fragments are already walked to stamp them.
-   *
-   * @param {Buffer} bytes - The media segment, init header already removed.
-   * @param {Buffer | null} initBytes
-   * @returns {boolean} False only when a track is provably missing.
-   */
-  hasEveryTrack(bytes, initBytes) {
-    if (!initBytes || initBytes.length === 0) {
-      return true;
-    }
-    const expected = readTrackTimescales(initBytes);
-    if (expected.size === 0) {
-      return true;
-    }
-    return countFragmentTracks(bytes) >= expected.size;
-  },
-
-  prepareSegmentBytes(bytes, { startSeconds, initBytes }) {
-    if (!initBytes || initBytes.length === 0) {
-      // No init cached yet — nothing to read timescales from. The player always
-      // fetches `#EXT-X-MAP` before any segment, so this is not reachable in
-      // practice; serve unmodified rather than guess a timescale.
-      return bytes;
-    }
-    return stampSegmentStartTime(bytes, startSeconds, readTrackTimescales(initBytes));
-  }
-};
+/**
+ * @file fMP4 (CMAF) segment format — `.mp4` media segments plus one shared
+ * `init.mp4` referenced by `#EXT-X-MAP`.
+ *
+ * Codec configuration (SPS/PPS) lives once in the init segment instead of being
+ * repeated per segment. That is what makes hardware encoders which do not
+ * repeat parameter sets — notably the CM4 / HA-Yellow `h264_v4l2m2m` — produce
+ * independently usable segments, and it lowers container overhead.
+ *
+ * See {@link SegmentFormat} in `./index.js` for the interface contract.
+ */
+
+import {
+  readSelfContainedStartSeconds,
+  readTrackTimescales,
+  stampSegmentStartTime,
+  walkBoxes
+} from "./mp4-boxes.js";
+
+/**
+ * How many distinct tracks have a fragment in this segment.
+ *
+ * @param {Buffer} bytes
+ * @returns {number}
+ */
+function countFragmentTracks(bytes) {
+  const tracks = new Set();
+  walkBoxes(bytes, (type, bodyStart) => {
+    if (type === "tfhd" && bodyStart + 8 <= bytes.length) {
+      tracks.add(bytes.readUInt32BE(bodyStart + 4));
+    }
+  });
+  return tracks.size;
+}
+
+/**
+ * Where the fragments begin and where the trailing index starts, as offsets of
+ * whole boxes at the TOP level.
+ *
+ * Deliberately not `walkBoxes`: that reports the start of a box's *body* and
+ * descends into containers, so it cannot say where a box begins — and cutting a
+ * file at the wrong offset by eight bytes produces something that parses as
+ * garbage rather than failing outright.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ firstFragment: number, trailingIndex: number }} Offsets, or -1.
+ */
+function findFragmentBounds(bytes) {
+  let firstFragment = -1;
+  let trailingIndex = -1;
+  let offset = 0;
+  while (offset + 8 <= bytes.length) {
+    let size = bytes.readUInt32BE(offset);
+    const type = bytes.toString("latin1", offset + 4, offset + 8);
+    if (size === 1) {
+      if (offset + 16 > bytes.length) {
+        break;
+      }
+      size = Number(bytes.readBigUInt64BE(offset + 8));
+    } else if (size === 0) {
+      size = bytes.length - offset;
+    }
+    if (size < 8) {
+      break;
+    }
+    if (firstFragment === -1 && (type === "moof" || type === "sidx")) {
+      firstFragment = offset;
+    }
+    if (type === "mfra") {
+      trailingIndex = offset;
+    }
+    offset += size;
+  }
+  return { firstFragment, trailingIndex };
+}
+
+const INIT_FILE_NAME = "init.mp4";
+const SEGMENT_PATTERN = /^segment-(\d{5})\.mp4$/;
+
+/**
+ * @type {import("./index.js").SegmentFormat}
+ */
+export const fmp4Format = {
+  id: "fmp4",
+  initFileName: INIT_FILE_NAME,
+  initContentType: "video/mp4",
+  segmentContentType: "video/mp4",
+  // Version 7 is the minimum that allows fMP4 media segments + `#EXT-X-MAP`.
+  playlistVersion: 7,
+
+  muxerArgs() {
+    return [
+      "-hls_segment_type",
+      "fmp4",
+      "-hls_fmp4_init_filename",
+      INIT_FILE_NAME,
+      "-hls_segment_filename",
+      "segment-%05d.mp4"
+    ];
+  },
+
+  /**
+   * Cut at times we choose rather than times ffmpeg picks.
+   *
+   * The `segment` muxer writes each fMP4 piece as a **self-contained** file:
+   * `ftyp moov moof mdat … mfra`, verified on the field host. That is not what
+   * HLS wants — it wants one init segment named by `#EXT-X-MAP` and media
+   * segments carrying only fragments — so the pieces are split on serve:
+   * {@link extractInit} takes the header off the first one to serve as the init,
+   * and {@link stripInit} removes it from every one.
+   *
+   * The timestamps still need stamping, exactly as before: measured on the
+   * field host, all three pieces of a run reported a start time of 0.080 s,
+   * i.e. each carries its own zero. That is the same defect the shared-init
+   * path already corrects, so `prepareSegmentBytes` handles both.
+   *
+   * @returns {string[]}
+   */
+  explicitTimesMuxerArgs() {
+    return [
+      "-segment_format",
+      "mp4",
+      // `empty_moov` is what makes each piece self-describing, which is what
+      // lets the init be lifted out of it; `default_base_moof` keeps fragment
+      // offsets relative, so removing the header does not invalidate them.
+      //
+      // `delay_moov` is not optional here. The MP4 muxer builds a copied AC-3
+      // track's `dac3` box out of the bitstream, so it cannot write `moov`
+      // until the first audio packet has arrived — while `empty_moov` asks for
+      // it at header time. Without this flag ffmpeg exits before producing
+      // anything: "Cannot write moov atom before AC3 packets", which is exactly
+      // how fMP4 playback died in the field on 2.9.84/2.9.85. The `hls` muxer
+      // sets this flag itself, which is why the fault only appeared once the
+      // muxing moved here. Delaying `moov` does not change the piece layout —
+      // measured: still `ftyp moov moof mdat … mfra`.
+      "-segment_format_options",
+      "movflags=+frag_keyframe+empty_moov+default_base_moof+delay_moov"
+    ];
+  },
+
+  /** The output path template for the `segment` muxer. */
+  segmentFileNameTemplate() {
+    return "segment-%05d.mp4";
+  },
+
+  /**
+   * The init part of a self-contained piece: everything before the first
+   * fragment.
+   *
+   * @param {Buffer} bytes
+   * @returns {Buffer | null} `null` when the piece carries no fragment, which
+   *   means it is not one of these and must not be cut up.
+   */
+  extractInit(bytes) {
+    const { firstFragment } = findFragmentBounds(bytes);
+    return firstFragment > 0 ? bytes.subarray(0, firstFragment) : null;
+  },
+
+  /**
+   * A piece with its init header removed, and the trailing random-access index
+   * dropped — a player reading a media segment has no use for either, and
+   * `mfra` describes offsets that stop being true once the header is gone.
+   *
+   * @param {Buffer} bytes
+   * @returns {Buffer}
+   */
+  stripInit(bytes) {
+    const { firstFragment, trailingIndex } = findFragmentBounds(bytes);
+    if (firstFragment < 0) {
+      return bytes;
+    }
+    const end = trailingIndex > firstFragment ? trailingIndex : bytes.length;
+    return bytes.subarray(firstFragment, end);
+  },
+
+  playlistHeaderLines() {
+    return [
+      // The init segment (codec config). Fetched once; applies to every media
+      // segment in the playlist.
+      `#EXT-X-MAP:URI="${INIT_FILE_NAME}"`
+    ];
+  },
+
+  segmentFileName(index) {
+    return `segment-${String(index).padStart(5, "0")}.mp4`;
+  },
+
+  isSegmentFileName(fileName) {
+    return SEGMENT_PATTERN.test(fileName);
+  },
+
+  segmentIndexFromName(fileName) {
+    const match = SEGMENT_PATTERN.exec(fileName);
+    return match ? Number(match[1]) : -1;
+  },
+
+  /**
+   * Where a self-contained piece says it begins, in seconds, or null.
+   *
+   * Only the pieces the `segment` muxer writes carry this — they have their
+   * own `moov` — which is exactly the path where the playlist's own answer
+   * can be wrong. Must be given the piece BEFORE {@link stripInit}, since that
+   * removes the header the position lives in.
+   *
+   * @param {Buffer} piece
+   * @returns {number | null}
+   */
+  readSegmentStartSeconds(piece) {
+    return readSelfContainedStartSeconds(piece);
+  },
+
+  /**
+   * fMP4 segments must be read into memory and corrected before being served —
+   * see {@link stampSegmentStartTime} for the full reasoning. Without this a
+   * seek is permanently broken: ffmpeg leaves every segment claiming to start
+   * at 0 and puts the real offset in the per-run init, which we do not serve
+   * (the player fetches the session's first init once and keeps it).
+   *
+   * Segments are a few hundred KB, so reading one whole is cheap next to the
+   * transcode itself; the box walk never descends into `mdat`.
+   */
+  needsSegmentRewrite: true,
+
+  /**
+   * Whether a segment carries every track the init promises.
+   *
+   * A run that is TERMINATED closes its current output file properly — trailing
+   * index and all — but the file holds only what had been muxed by then, which
+   * after a seek-restart is routinely one track of two. Nothing about it looks
+   * unfinished: the file exists, the next one exists, so the readiness rule
+   * calls it done and it is served. The player then cannot use it and the seek
+   * never completes. Measured 2026-08-06: segment #133 carried one `tfdt`
+   * where its neighbours carried two, and a viewer sat on a spinner while the
+   * proxy answered every request in 98 ms.
+   *
+   * Cheap to check: the fragments are already walked to stamp them.
+   *
+   * @param {Buffer} bytes - The media segment, init header already removed.
+   * @param {Buffer | null} initBytes
+   * @returns {boolean} False only when a track is provably missing.
+   */
+  hasEveryTrack(bytes, initBytes) {
+    if (!initBytes || initBytes.length === 0) {
+      return true;
+    }
+    const expected = readTrackTimescales(initBytes);
+    if (expected.size === 0) {
+      return true;
+    }
+    return countFragmentTracks(bytes) >= expected.size;
+  },
+
+  /**
+   * How many tracks an init segment declares.
+   *
+   * The init is extracted from the first self-contained piece and then cached
+   * for the WHOLE session — the player fetches `#EXT-X-MAP` once and never
+   * again. So an init taken from a piece written before the video track was
+   * muxed describes audio alone, and the browser then has no video source
+   * buffer for the rest of the session however much video arrives afterwards.
+   * Measured 2026-08-10: sixty-five seconds of playing sound with
+   * `videoWidth=0`, `totalVideoFrames=0` and `readyState=4` — an element
+   * perfectly happy, with no picture in it.
+   *
+   * @param {Buffer} initBytes
+   * @returns {number}
+   */
+  /**
+   * How many distinct tracks this piece's own fragments carry.
+   *
+   * Needs no knowledge of the source: whatever a produced piece contains, it
+   * contains. Comparing the richest piece against a candidate header is what
+   * lets an init be judged without assuming how many tracks a file "should"
+   * have — a film with no soundtrack and a file with two audio tracks are both
+   * answered correctly, and neither is guessed at.
+   *
+   * @param {Buffer} bytes
+   * @returns {number}
+   */
+  countSegmentTracks(bytes) {
+    return countFragmentTracks(bytes);
+  },
+
+  countInitTracks(initBytes) {
+    if (!initBytes || initBytes.length === 0) {
+      return 0;
+    }
+    return readTrackTimescales(initBytes).size;
+  },
+
+  prepareSegmentBytes(bytes, { startSeconds, initBytes }) {
+    if (!initBytes || initBytes.length === 0) {
+      // No init cached yet — nothing to read timescales from. The player always
+      // fetches `#EXT-X-MAP` before any segment, so this is not reachable in
+      // practice; serve unmodified rather than guess a timescale.
+      return bytes;
+    }
+    return stampSegmentStartTime(bytes, startSeconds, readTrackTimescales(initBytes));
+  }
+};