@torrent-tv/proxy 2.9.53 → 2.9.54

package/services/segment-formats/fmp4.js

@@ -0,0 +1,82 @@
+/**
+ * @file fMP4 (CMAF) segment format — `.m4s` 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 { readTrackTimescales, stampSegmentStartTime } from "./mp4-boxes.js";
+
+const INIT_FILE_NAME = "init.mp4";
+const SEGMENT_PATTERN = /^segment-(\d{5})\.m4s$/;
+
+/**
+ * @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.m4s"
+    ];
+  },
+
+  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")}.m4s`;
+  },
+
+  isSegmentFileName(fileName) {
+    return SEGMENT_PATTERN.test(fileName);
+  },
+
+  segmentIndexFromName(fileName) {
+    const match = SEGMENT_PATTERN.exec(fileName);
+    return match ? Number(match[1]) : -1;
+  },
+
+  /**
+   * 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,
+
+  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));
+  }
+};

package/services/segment-formats/index.js

@@ -0,0 +1,77 @@
+/**
+ * @file Selectable HLS segment container formats.
+ *
+ * Everything that differs between fMP4/CMAF and MPEG-TS output lives behind one
+ * interface, so `hls-session-manager` never branches on the container: it holds
+ * a format object and asks it. Adding a container means adding a module here,
+ * not editing the session manager.
+ *
+ * The choice is per-proxy (CLI `--segment-format`), mirroring how Jellyfin lets
+ * the operator pick the transcoding container. fMP4 is the default; MPEG-TS is
+ * the fallback for hosts or players where fMP4 misbehaves.
+ */
+
+import { fmp4Format } from "./fmp4.js";
+import { mpegtsFormat } from "./mpegts.js";
+
+/**
+ * @typedef {Object} PrepareSegmentContext
+ * @property {number} startSeconds - Position of this segment on the 0-based
+ *   output timeline, from the session's segment-boundary table.
+ * @property {Buffer | null} initBytes - The init segment being served for this
+ *   session, when the format has one (fMP4 needs it to read track timescales).
+ */
+
+/**
+ * One container format's complete behaviour.
+ *
+ * @typedef {Object} SegmentFormat
+ * @property {string} id - Stable identifier, also the CLI value ("fmp4" | "mpegts").
+ * @property {string | null} initFileName - Init segment name, or null when the
+ *   format has none (MPEG-TS).
+ * @property {string | null} initContentType - MIME type for the init segment.
+ * @property {string} segmentContentType - MIME type for a media segment.
+ * @property {number} playlistVersion - `#EXT-X-VERSION` the playlist must declare.
+ * @property {() => string[]} muxerArgs - ffmpeg arguments selecting this
+ *   container (including `-hls_segment_filename`).
+ * @property {() => string[]} playlistHeaderLines - Extra playlist header lines
+ *   (e.g. `#EXT-X-MAP` for fMP4); empty for formats that need none.
+ * @property {(index: number) => string} segmentFileName - File name for a
+ *   zero-based segment index.
+ * @property {(fileName: string) => boolean} isSegmentFileName - Whether a name
+ *   is one of this format's media segments.
+ * @property {(fileName: string) => number} segmentIndexFromName - Index encoded
+ *   in a segment file name, or -1.
+ * @property {boolean} needsSegmentRewrite - Whether a segment must be read into
+ *   memory and passed through `prepareSegmentBytes` before being served. False
+ *   lets the caller stream straight from disk.
+ * @property {(bytes: Buffer, context: PrepareSegmentContext) => Buffer}
+ *   prepareSegmentBytes - Correct a segment before serving. Identity for
+ *   formats that need nothing.
+ */
+
+/** @type {Readonly<Record<string, SegmentFormat>>} */
+const FORMATS = Object.freeze({
+  [fmp4Format.id]: fmp4Format,
+  [mpegtsFormat.id]: mpegtsFormat
+});
+
+/** The container used unless the operator selects otherwise. */
+export const DEFAULT_SEGMENT_FORMAT_ID = fmp4Format.id;
+
+/** Identifiers accepted by {@link resolveSegmentFormat}, for CLI help/validation. */
+export const SEGMENT_FORMAT_IDS = Object.freeze(Object.keys(FORMATS));
+
+/**
+ * Resolve a format by id, falling back to the default for an unknown or absent
+ * value (a bad CLI value must not stop the proxy from starting).
+ *
+ * @param {string | undefined | null} id
+ * @returns {SegmentFormat}
+ */
+export function resolveSegmentFormat(id) {
+  if (typeof id === "string" && Object.hasOwn(FORMATS, id)) {
+    return FORMATS[id];
+  }
+  return FORMATS[DEFAULT_SEGMENT_FORMAT_ID];
+}

package/services/segment-formats/mp4-boxes.js

@@ -0,0 +1,160 @@
+/**
+ * @file Minimal ISO Base Media File Format (ISO/IEC 14496-12) box reader/writer.
+ *
+ * Only what the fMP4 segment format needs: read the per-track media timescale
+ * out of an init segment, and rewrite each fragment's
+ * `tfdt` (TrackFragmentBaseMediaDecodeTime) so a segment states where it sits
+ * on the media timeline. Deliberately tiny and dependency-free — it never
+ * descends into `mdat` (the payload), so cost is proportional to the header,
+ * not to the segment size.
+ */
+
+/**
+ * Container boxes whose payload is a sequence of child boxes. Anything else is
+ * treated as a leaf, so `mdat` (the media payload) is never walked into.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const CONTAINER_BOXES = new Set(["moov", "trak", "mdia", "minf", "stbl", "edts", "moof", "traf"]);
+
+/**
+ * Walk the box tree, invoking `visit` for every box encountered.
+ *
+ * @param {Buffer} buffer
+ * @param {(type: string, bodyStart: number, bodyEnd: number) => void} visit
+ *   `bodyStart`/`bodyEnd` delimit the box payload (header excluded).
+ * @param {number} [start=0]
+ * @param {number} [end=buffer.length]
+ * @returns {void}
+ */
+export function walkBoxes(buffer, visit, start = 0, end = buffer.length) {
+  let offset = start;
+  while (offset + 8 <= end) {
+    let size = buffer.readUInt32BE(offset);
+    const type = buffer.toString("latin1", offset + 4, offset + 8);
+    let headerSize = 8;
+    if (size === 1) {
+      // 64-bit `largesize` follows the type.
+      if (offset + 16 > end) {
+        return;
+      }
+      size = Number(buffer.readBigUInt64BE(offset + 8));
+      headerSize = 16;
+    } else if (size === 0) {
+      // "to end of file"
+      size = end - offset;
+    }
+    if (size < headerSize || offset + size > end) {
+      return; // truncated or malformed — stop rather than read out of bounds
+    }
+    visit(type, offset + headerSize, offset + size);
+    if (CONTAINER_BOXES.has(type)) {
+      walkBoxes(buffer, visit, offset + headerSize, offset + size);
+    }
+    offset += size;
+  }
+}
+
+/**
+ * Media timescale (ticks per second) of every track in an init segment, keyed
+ * by track id. `tfdt` values are expressed in this unit, so it is required to
+ * convert a wall-clock position into a `baseMediaDecodeTime`.
+ *
+ * Read from each track's `tkhd` (track id) + `mdia/mdhd` (timescale) pair;
+ * within a `trak` the `tkhd` always precedes the `mdhd`, so a single ordered
+ * pass pairs them correctly.
+ *
+ * @param {Buffer} initSegment
+ * @returns {Map<number, number>} trackId → timescale
+ */
+export function readTrackTimescales(initSegment) {
+  const timescales = new Map();
+  let currentTrackId = null;
+  walkBoxes(initSegment, (type, bodyStart) => {
+    if (type === "tkhd") {
+      const version = initSegment[bodyStart];
+      // v1 widens creation/modification time to 64 bit, moving track_id by 8.
+      const trackIdOffset = version === 1 ? bodyStart + 20 : bodyStart + 12;
+      if (trackIdOffset + 4 <= initSegment.length) {
+        currentTrackId = initSegment.readUInt32BE(trackIdOffset);
+      }
+    } else if (type === "mdhd" && currentTrackId !== null) {
+      const version = initSegment[bodyStart];
+      const timescaleOffset = version === 1 ? bodyStart + 20 : bodyStart + 12;
+      if (timescaleOffset + 4 <= initSegment.length) {
+        timescales.set(currentTrackId, initSegment.readUInt32BE(timescaleOffset));
+      }
+      currentTrackId = null;
+    }
+  });
+  return timescales;
+}
+
+/**
+ * Rewrite every fragment's `tfdt` so the segment declares that it starts at
+ * `startSeconds` on the media timeline.
+ *
+ * WHY THIS IS NEEDED — ffmpeg's HLS/fMP4 output writes `tfdt = 0` in every
+ * seek-restart run and records the run's start offset in an `elst` (edit list)
+ * inside that run's init segment instead. That is self-consistent only while
+ * the init and the segments come from the SAME run. We serve one init for the
+ * whole session (the player fetches `#EXT-X-MAP` once and never re-fetches it),
+ * so a post-seek segment read against the cached init loses its offset entirely
+ * and appears to start at ~0 — the player finds nothing at the position it
+ * seeked to, discards the segment and re-requests it, forever. Verified in the
+ * field 2026-08-01: segments 402/403 re-fetched in a loop for over two minutes
+ * at full link speed with the buffer stuck at 0 s, while the transcode itself
+ * was healthy. No ffmpeg muxer/flag combination avoids this — HLS and DASH
+ * muxers, `-copyts`, `-output_ts_offset`, `-itsoffset`, `-avoid_negative_ts`,
+ * `-movflags -use_edts/+dash/+frag_discont/+global_sidx` were all measured and
+ * all produce `tfdt = 0`.
+ *
+ * Stamping the true value restores what CMAF (ISO/IEC 23000-19) requires of an
+ * independently-addressable segment anyway: it carries its own position, so it
+ * is valid against any init for the same tracks.
+ *
+ * Mutates a copy; the caller's buffer is untouched.
+ *
+ * @param {Buffer} segment
+ * @param {number} startSeconds - Position of this segment on the 0-based output timeline.
+ * @param {Map<number, number>} trackTimescales - From {@link readTrackTimescales}.
+ * @returns {Buffer} The segment with corrected `tfdt` values.
+ */
+export function stampSegmentStartTime(segment, startSeconds, trackTimescales) {
+  if (!Number.isFinite(startSeconds) || startSeconds < 0 || trackTimescales.size === 0) {
+    return segment;
+  }
+  const stamped = Buffer.from(segment);
+  // `tfhd` carries the track id and always precedes the `tfdt` inside the same
+  // `traf`, so an ordered pass pairs each `tfdt` with its track's timescale.
+  let currentTrackId = null;
+  walkBoxes(stamped, (type, bodyStart, bodyEnd) => {
+    if (type === "tfhd") {
+      if (bodyStart + 8 <= bodyEnd) {
+        currentTrackId = stamped.readUInt32BE(bodyStart + 4);
+      }
+      return;
+    }
+    if (type !== "tfdt" || currentTrackId === null) {
+      return;
+    }
+    const timescale = trackTimescales.get(currentTrackId);
+    if (!timescale) {
+      return;
+    }
+    const version = stamped[bodyStart];
+    const value = Math.round(startSeconds * timescale);
+    if (version === 1) {
+      if (bodyStart + 12 <= bodyEnd) {
+        stamped.writeBigUInt64BE(BigInt(value), bodyStart + 4);
+      }
+    } else if (bodyStart + 8 <= bodyEnd) {
+      // A 32-bit field cannot express beyond ~2^32 ticks; leave it rather than
+      // write a wrapped value (the player would land somewhere arbitrary).
+      if (value <= 0xffffffff) {
+        stamped.writeUInt32BE(value, bodyStart + 4);
+      }
+    }
+  });
+  return stamped;
+}

package/services/segment-formats/mpegts.js

@@ -0,0 +1,60 @@
+/**
+ * @file MPEG-TS segment format — self-contained `.ts` segments, no init segment.
+ *
+ * This is the pre-fMP4 behaviour (recovered from the switch commit `dd1ce09`),
+ * kept as a selectable alternative rather than deleted. Each segment carries
+ * its own parameter sets and its own timestamps, so it is valid on its own —
+ * there is no shared init segment that a seek-restart can invalidate, and
+ * therefore none of the timeline problems the fMP4 path has to correct for.
+ *
+ * Trade-off vs fMP4: higher container overhead, and encoders that do not repeat
+ * SPS/PPS (CM4 `h264_v4l2m2m`) emit segments after the first with no parameter
+ * sets, which is exactly why fMP4 became the default.
+ *
+ * See {@link SegmentFormat} in `./index.js` for the interface contract.
+ */
+
+const SEGMENT_PATTERN = /^segment-(\d{5})\.ts$/;
+
+/**
+ * @type {import("./index.js").SegmentFormat}
+ */
+export const mpegtsFormat = {
+  id: "mpegts",
+  // No init segment: every `.ts` segment is self-describing.
+  initFileName: null,
+  initContentType: null,
+  segmentContentType: "video/mp2t",
+  playlistVersion: 3,
+
+  muxerArgs() {
+    return ["-hls_segment_filename", "segment-%05d.ts"];
+  },
+
+  playlistHeaderLines() {
+    return []; // no `#EXT-X-MAP`
+  },
+
+  segmentFileName(index) {
+    return `segment-${String(index).padStart(5, "0")}.ts`;
+  },
+
+  isSegmentFileName(fileName) {
+    return SEGMENT_PATTERN.test(fileName);
+  },
+
+  segmentIndexFromName(fileName) {
+    const match = SEGMENT_PATTERN.exec(fileName);
+    return match ? Number(match[1]) : -1;
+  },
+
+  /**
+   * MPEG-TS segments carry their own timestamps and need no correction, so they
+   * are streamed straight from disk (no read-into-memory step).
+   */
+  needsSegmentRewrite: false,
+
+  prepareSegmentBytes(bytes) {
+    return bytes;
+  }
+};