@torrent-tv/proxy 2.87.10 → 2.87.11

package/services/encode/segment-formats/fmp4.js

@@ -1,437 +1,437 @@
-/**
- * @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,
-  readVideoSampleSize,
-  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";
-// What a piece is called while it is still being written. See
-// `makingFileNameTemplate`.
-const MAKING_PATTERN = /^making-([0-9a-z]+)-(\d{5})\.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. */
-  /**
-   * The name ffmpeg is told to write a piece under WHILE IT IS MAKING IT.
-   *
-   * Not the name it is served under. A piece being written is not a piece, and
-   * under its final name it is indistinguishable from one — which is how half a
-   * segment came to be served: the proof of completeness was "the next file
-   * exists", true of one writer walking forward and false the moment two runs
-   * share an output, because the next file is then written by another process.
-   * Field 2026-09-08: `segment-00057.mp4` served at 2 268 361 bytes and then at
-   * 4 510 940, and the browser refused the whole one for the rest of the session.
-   *
-   * With a working name, the served name appears only when the encoder has said
-   * the piece is closed, and existence under it IS the proof — one rule, the
-   * same for every branch, and true whether or not our own process is alive.
-   *
-   * @returns {string}
-   */
-  makingFileNameTemplate(tag) {
-    return `making-${String(tag ?? "0").replace(/[^0-9a-z]/g, "")}-%05d.mp4`;
-  },
-
-  /**
-   * Which run is writing this working name, or null when the name is not one.
-   *
-   * The tag is what makes clearing up after a dead run possible without
-   * guessing: several runs write into one directory, so "the unfinished pieces"
-   * is only a well-formed question per run. It used to be answered by looking
-   * for the highest SERVED name inside the stretch the ended run was given and
-   * judging its bytes — a guess, and under the naming rule above it would remove
-   * a complete piece somebody else had closed.
-   *
-   * @param {string} name
-   * @returns {string | null}
-   */
-  makingTagOf(name) {
-    const match = MAKING_PATTERN.exec(String(name ?? "").trim());
-    return match ? match[1] : null;
-  },
-
-  /**
-   * The name a piece just closed under a working name is served as, or null when
-   * the name is not one of ours.
-   *
-   * @param {string} makingName
-   * @returns {string | null}
-   */
-  servedNameOf(makingName) {
-    const match = MAKING_PATTERN.exec(String(makingName ?? "").trim());
-    return match ? this.segmentFileName(Number(match[2])) : null;
-  },
-
-  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;
-  },
-
-  /**
-   * Whether this piece is whole, judged against ITS OWN header.
-   *
-   * A piece that disagrees with the session's cached header is one of two very
-   * different things, and they call for opposite actions: the piece may be
-   * short, or the HEADER may be the odd one out. A self-contained piece carries
-   * a `moov` of its own, so it can be compared with itself, and that comparison
-   * tells them apart without knowing anything about encoders.
-   *
-   * WHAT THIS REPLACED, because the difference is five minutes of a frozen
-   * picture. The action used to be chosen by "is any run of this session
-   * alive?" — a question about the SESSION, asked about a fact of the BYTES. A
-   * run anywhere in the film meant "still being written; waiting for it", and
-   * nothing re-judged or re-made the piece afterwards, so one misjudgement
-   * became permanent. Field 2026-09-14: `segment-00033.mp4` of a copied
-   * picture, already served whole to one viewer at 5 099 421 bytes, was refused
-   * to a second viewer for five minutes — four holds of sixty seconds each,
-   * then 503 — while the run in force was at #192 and beyond. That viewer's
-   * picture stood still 196.2 s and then a further 56.2 s.
-   *
-   * The run question is also unanswerable and does not need asking: a piece
-   * being written is called `making-<tag>-NNNNN.mp4` and takes its served name
-   * by a rename, which is atomic. A file under its served name is never being
-   * written and never half-read.
-   *
-   * The same file read back off the disk declares one track in its header and
-   * carries one in its fragments, so what fired in the field was not the piece.
-   * Until a reading names what it was, the verdict carries every count it made.
-   *
-   * @param {Buffer} raw - The piece as it is on disk, header and all.
-   * @param {Buffer} bytes - Its media part, the header already removed.
-   * @param {Buffer | null} sessionHeader - What the session serves as its init.
-   * @returns {{ whole: boolean, serve: boolean, fragmentTracks: number,
-   *   ownTracks: number, sessionTracks: number, because: string } | null} Null
-   *   where there is nothing to compare against, which is not a verdict.
-   */
-  judgeTracks(raw, bytes, sessionHeader) {
-    if (!sessionHeader || sessionHeader.length === 0) {
-      return null;
-    }
-    const sessionTracks = readTrackTimescales(sessionHeader).size;
-    if (sessionTracks === 0) {
-      return null;
-    }
-    const fragmentTracks = countFragmentTracks(bytes);
-    if (fragmentTracks >= sessionTracks) {
-      return null;
-    }
-    const ownHeader = this.extractInit(raw);
-    const ownTracks = ownHeader ? readTrackTimescales(ownHeader).size : 0;
-    const agreesWithItself = ownTracks > 0 && fragmentTracks >= ownTracks;
-    return {
-      whole: agreesWithItself,
-      serve: agreesWithItself,
-      fragmentTracks,
-      ownTracks,
-      sessionTracks,
-      because: agreesWithItself
-        ? "it agrees with its own header, so the session's is the odd one out; serving it"
-        : "it disagrees with its own header, so it was closed short; removing it to be made again"
-    };
-  },
-
-  /**
-   * 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;
-  },
-
-  /**
-   * The picture size this init segment describes, or null when it describes no
-   * picture.
-   *
-   * Asked because one init serves the session's whole life while an encode run
-   * can be restarted with other settings, and a run that changes the SIZE makes
-   * every fragment after it undecodable against the init already in the
-   * player's hands.
-   *
-   * @param {Buffer | null} initBytes
-   * @returns {{ width: number, height: number } | null}
-   */
-  initVideoSize(initBytes) {
-    if (!initBytes || initBytes.length === 0) {
-      return null;
-    }
-    return readVideoSampleSize(initBytes);
-  },
-
-  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,
+  readVideoSampleSize,
+  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";
+// What a piece is called while it is still being written. See
+// `makingFileNameTemplate`.
+const MAKING_PATTERN = /^making-([0-9a-z]+)-(\d{5})\.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. */
+  /**
+   * The name ffmpeg is told to write a piece under WHILE IT IS MAKING IT.
+   *
+   * Not the name it is served under. A piece being written is not a piece, and
+   * under its final name it is indistinguishable from one — which is how half a
+   * segment came to be served: the proof of completeness was "the next file
+   * exists", true of one writer walking forward and false the moment two runs
+   * share an output, because the next file is then written by another process.
+   * Field 2026-09-08: `segment-00057.mp4` served at 2 268 361 bytes and then at
+   * 4 510 940, and the browser refused the whole one for the rest of the session.
+   *
+   * With a working name, the served name appears only when the encoder has said
+   * the piece is closed, and existence under it IS the proof — one rule, the
+   * same for every branch, and true whether or not our own process is alive.
+   *
+   * @returns {string}
+   */
+  makingFileNameTemplate(tag) {
+    return `making-${String(tag ?? "0").replace(/[^0-9a-z]/g, "")}-%05d.mp4`;
+  },
+
+  /**
+   * Which run is writing this working name, or null when the name is not one.
+   *
+   * The tag is what makes clearing up after a dead run possible without
+   * guessing: several runs write into one directory, so "the unfinished pieces"
+   * is only a well-formed question per run. It used to be answered by looking
+   * for the highest SERVED name inside the stretch the ended run was given and
+   * judging its bytes — a guess, and under the naming rule above it would remove
+   * a complete piece somebody else had closed.
+   *
+   * @param {string} name
+   * @returns {string | null}
+   */
+  makingTagOf(name) {
+    const match = MAKING_PATTERN.exec(String(name ?? "").trim());
+    return match ? match[1] : null;
+  },
+
+  /**
+   * The name a piece just closed under a working name is served as, or null when
+   * the name is not one of ours.
+   *
+   * @param {string} makingName
+   * @returns {string | null}
+   */
+  servedNameOf(makingName) {
+    const match = MAKING_PATTERN.exec(String(makingName ?? "").trim());
+    return match ? this.segmentFileName(Number(match[2])) : null;
+  },
+
+  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;
+  },
+
+  /**
+   * Whether this piece is whole, judged against ITS OWN header.
+   *
+   * A piece that disagrees with the session's cached header is one of two very
+   * different things, and they call for opposite actions: the piece may be
+   * short, or the HEADER may be the odd one out. A self-contained piece carries
+   * a `moov` of its own, so it can be compared with itself, and that comparison
+   * tells them apart without knowing anything about encoders.
+   *
+   * WHAT THIS REPLACED, because the difference is five minutes of a frozen
+   * picture. The action used to be chosen by "is any run of this session
+   * alive?" — a question about the SESSION, asked about a fact of the BYTES. A
+   * run anywhere in the film meant "still being written; waiting for it", and
+   * nothing re-judged or re-made the piece afterwards, so one misjudgement
+   * became permanent. Field 2026-09-14: `segment-00033.mp4` of a copied
+   * picture, already served whole to one viewer at 5 099 421 bytes, was refused
+   * to a second viewer for five minutes — four holds of sixty seconds each,
+   * then 503 — while the run in force was at #192 and beyond. That viewer's
+   * picture stood still 196.2 s and then a further 56.2 s.
+   *
+   * The run question is also unanswerable and does not need asking: a piece
+   * being written is called `making-<tag>-NNNNN.mp4` and takes its served name
+   * by a rename, which is atomic. A file under its served name is never being
+   * written and never half-read.
+   *
+   * The same file read back off the disk declares one track in its header and
+   * carries one in its fragments, so what fired in the field was not the piece.
+   * Until a reading names what it was, the verdict carries every count it made.
+   *
+   * @param {Buffer} raw - The piece as it is on disk, header and all.
+   * @param {Buffer} bytes - Its media part, the header already removed.
+   * @param {Buffer | null} sessionHeader - What the session serves as its init.
+   * @returns {{ whole: boolean, serve: boolean, fragmentTracks: number,
+   *   ownTracks: number, sessionTracks: number, because: string } | null} Null
+   *   where there is nothing to compare against, which is not a verdict.
+   */
+  judgeTracks(raw, bytes, sessionHeader) {
+    if (!sessionHeader || sessionHeader.length === 0) {
+      return null;
+    }
+    const sessionTracks = readTrackTimescales(sessionHeader).size;
+    if (sessionTracks === 0) {
+      return null;
+    }
+    const fragmentTracks = countFragmentTracks(bytes);
+    if (fragmentTracks >= sessionTracks) {
+      return null;
+    }
+    const ownHeader = this.extractInit(raw);
+    const ownTracks = ownHeader ? readTrackTimescales(ownHeader).size : 0;
+    const agreesWithItself = ownTracks > 0 && fragmentTracks >= ownTracks;
+    return {
+      whole: agreesWithItself,
+      serve: agreesWithItself,
+      fragmentTracks,
+      ownTracks,
+      sessionTracks,
+      because: agreesWithItself
+        ? "it agrees with its own header, so the session's is the odd one out; serving it"
+        : "it disagrees with its own header, so it was closed short; removing it to be made again"
+    };
+  },
+
+  /**
+   * 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;
+  },
+
+  /**
+   * The picture size this init segment describes, or null when it describes no
+   * picture.
+   *
+   * Asked because one init serves the session's whole life while an encode run
+   * can be restarted with other settings, and a run that changes the SIZE makes
+   * every fragment after it undecodable against the init already in the
+   * player's hands.
+   *
+   * @param {Buffer | null} initBytes
+   * @returns {{ width: number, height: number } | null}
+   */
+  initVideoSize(initBytes) {
+    if (!initBytes || initBytes.length === 0) {
+      return null;
+    }
+    return readVideoSampleSize(initBytes);
+  },
+
+  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));
+  }
+};