@torrent-tv/proxy 2.72.1 → 2.73.0

package/services/container/Mp4Container.js

@@ -22,6 +22,57 @@ import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_FORMATS_MP4 } from "../tracks/TextSubtitleTrack.js";
 import { ImageSubtitleTrack } from "../tracks/ImageSubtitleTrack.js";
 
+/**
+ * One box header, per ISO/IEC 14496-12 §4.2.
+ *
+ * @param {Buffer} buf
+ * @param {number} off
+ * @returns {{ type: string, size: number, dataOffset: number, end: number } | null}
+ */
+function readBox(buf, off) {
+  if (off + 8 > buf.length) return null;
+  let sz = buf.readUInt32BE(off);
+  const tp = buf.toString("latin1", off + 4, off + 8);
+  let hb = 8;
+  if (sz === 1) { if (off + 16 > buf.length) return null; sz = Number(buf.readBigUInt64BE(off + 8)); hb = 16; }
+  if (sz < hb) return null;
+  return { type: tp, size: sz, dataOffset: off + hb, end: off + sz };
+}
+
+/**
+ * Every direct child box of the given type.
+ *
+ * @param {Buffer} buf
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {Array<{ type: string, size: number, dataOffset: number, end: number }>}
+ */
+function childrenOf(buf, start, end, type) {
+  const out = [];
+  let p = start;
+  while (p + 8 <= end) {
+    const b = readBox(buf, p);
+    if (!b) break;
+    if (b.type === type) out.push(b);
+    p = b.end;
+  }
+  return out;
+}
+
+/**
+ * The first direct child box of the given type, or null.
+ *
+ * @param {Buffer} buf
+ * @param {number} s
+ * @param {number} e
+ * @param {string} t
+ * @returns {{ type: string, size: number, dataOffset: number, end: number } | null}
+ */
+function childOf(buf, s, e, t) {
+  return childrenOf(buf, s, e, t)[0] ?? null;
+}
+
 export class Mp4Container extends Container {
   get formatName() {
     return "mp4";
@@ -79,12 +130,21 @@ export class Mp4Container extends Container {
     return tracks;
   }
 
-  async #readVideoAudioTracks() {
-    // Lightweight: scan moov for trak with hdlr vide/soun. We reuse readMp4SubtitlePlan's findMoov
-    // by reimplementing a minimal header walk here.
+  /**
+   * The `moov` box, read whole.
+   *
+   * Held on the instance because every question this class answers is inside
+   * it, and the box can be tens of megabytes off a torrent — reading it once
+   * per file is the difference between one fetch and one per question.
+   *
+   * @returns {Promise<{ moov: Buffer, header: number } | null>}
+   */
+  async #moovBuffer() {
+    if (this.moovHeld !== undefined) {
+      return this.moovHeld;
+    }
     const PROBE = 64;
     const MAX_MOOV = 32 * 1024 * 1024;
-    // find moov offset
     let at = 0;
     let moovBox = null;
     while (at < this.fileSize) {
@@ -102,37 +162,106 @@ export class Mp4Container extends Container {
       if (type === "moov") { moovBox = { offset: at, size, header }; break; }
       at += size;
     }
-    if (!moovBox || moovBox.size > MAX_MOOV) return [];
+    if (!moovBox || moovBox.size > MAX_MOOV) {
+      this.moovHeld = null;
+      return null;
+    }
     const moov = await this.readRange(moovBox.offset, Math.min(this.fileSize - 1, moovBox.offset + moovBox.size - 1));
-    if (!moov) return [];
+    this.moovHeld = moov ? { moov, header: moovBox.header } : null;
+    return this.moovHeld;
+  }
+
+  /**
+   * Duration from `mvhd` and the presentation offset from the first track's
+   * edit list, per ISO/IEC 14496-12 §8.2.2 and §8.6.6.
+   *
+   * An edit entry whose `media_time` is -1 is an EMPTY edit: it presents
+   * nothing for `segment_duration`, which shifts everything after it later by
+   * that much. That shift is what a player reports as the file's start, and it
+   * is the only way an MP4 states one — a file without such an edit begins at
+   * zero, which is a declaration, not an absence.
+   *
+   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
+   */
+  async readMediaInfo() {
+    if (this.mediaInfo) {
+      return this.mediaInfo;
+    }
+    /** @type {import("./Container.js").ContainerMediaInfo} */
+    const info = { format: this.formatName, durationSeconds: null, startTimeSeconds: null };
+    this.mediaInfo = info;
+    const held = await this.#moovBuffer();
+    if (!held) {
+      return info;
+    }
+    const { moov, header } = held;
+    const mvhd = childOf(moov, header, moov.length, "mvhd");
+    let movieTimescale = 0;
+    if (mvhd) {
+      const version = moov[mvhd.dataOffset];
+      // version 0: creation(4) modification(4) timescale(4) duration(4)
+      // version 1: creation(8) modification(8) timescale(4) duration(8)
+      const at = version === 1 ? mvhd.dataOffset + 20 : mvhd.dataOffset + 12;
+      if (at + 8 <= moov.length) {
+        movieTimescale = moov.readUInt32BE(at);
+        const duration = version === 1 ? Number(moov.readBigUInt64BE(at + 4)) : moov.readUInt32BE(at + 4);
+        if (movieTimescale > 0 && duration > 0) {
+          info.durationSeconds = duration / movieTimescale;
+        }
+      }
+    }
+    info.startTimeSeconds = movieTimescale > 0
+      ? Mp4Container.#emptyEditSeconds(moov, header, movieTimescale)
+      : null;
+    return info;
+  }
+
+  /**
+   * The presentation shift of the first empty edit, in seconds; 0 when no track
+   * declares one.
+   *
+   * @param {Buffer} moov
+   * @param {number} header
+   * @param {number} movieTimescale
+   * @returns {number}
+   */
+  static #emptyEditSeconds(moov, header, movieTimescale) {
+    let shift = 0;
+    for (const trak of childrenOf(moov, header, moov.length, "trak")) {
+      const edts = childOf(moov, trak.dataOffset, trak.end, "edts");
+      const elst = edts && childOf(moov, edts.dataOffset, edts.end, "elst");
+      if (!elst) {
+        continue;
+      }
+      const version = moov[elst.dataOffset];
+      const count = moov.readUInt32BE(elst.dataOffset + 4);
+      if (count < 1) {
+        continue;
+      }
+      const entry = elst.dataOffset + 8;
+      const segmentDuration = version === 1
+        ? Number(moov.readBigUInt64BE(entry))
+        : moov.readUInt32BE(entry);
+      const mediaTime = version === 1
+        ? Number(moov.readBigInt64BE(entry + 8))
+        : moov.readInt32BE(entry + 4);
+      if (mediaTime === -1 && segmentDuration > 0) {
+        shift = Math.max(shift, segmentDuration / movieTimescale);
+      }
+    }
+    return shift;
+  }
+
+  async #readVideoAudioTracks() {
+    const held = await this.#moovBuffer();
+    if (!held) return [];
+    const { moov, header: moovHeader } = held;
 
     const result = [];
     let videoIdx = -1;
     let audioIdx = -1;
-    // iterate trak boxes inside moov
-    const readBox = (buf, off) => {
-      if (off + 8 > buf.length) return null;
-      let sz = buf.readUInt32BE(off);
-      const tp = buf.toString("latin1", off + 4, off + 8);
-      let hb = 8;
-      if (sz === 1) { if (off + 16 > buf.length) return null; sz = Number(buf.readBigUInt64BE(off + 8)); hb = 16; }
-      if (sz < hb) return null;
-      return { type: tp, size: sz, dataOffset: off + hb, end: off + sz };
-    };
-    const childrenOf = (buf, start, end, type) => {
-      const out = [];
-      let p = start;
-      while (p + 8 <= end) {
-        const b = readBox(buf, p);
-        if (!b) break;
-        if (b.type === type) out.push(b);
-        p = b.end;
-      }
-      return out;
-    };
-    const childOf = (buf, s, e, t) => childrenOf(buf, s, e, t)[0] ?? null;
 
-    const moovContentStart = moovBox.header;
+    const moovContentStart = moovHeader;
     const moovEnd = moov.length;
     for (const trak of childrenOf(moov, moovContentStart, moovEnd, "trak")) {
       const mdia = childOf(moov, trak.dataOffset, trak.end, "mdia");

package/services/container-index/ebml-reader.js

@@ -101,6 +101,36 @@ export function readUint(buffer, offset, size) {
   return value;
 }
 
+/**
+ * An EBML float, which RFC 9559 §11.3.3 allows to be 4 or 8 bytes, big-endian
+ * IEEE 754, and 0 bytes for the value zero.
+ *
+ * Needed because Matroska writes `Duration` as a float, not as an integer:
+ * reading it with {@link readUint} yields the bit pattern rather than the
+ * number. Any other size is malformed and answered with null rather than a
+ * guess.
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @param {number} size
+ * @returns {number | null}
+ */
+export function readFloat(buffer, offset, size) {
+  if (size === 0) {
+    return 0;
+  }
+  if (offset + size > buffer.length) {
+    return null;
+  }
+  if (size === 4) {
+    return buffer.readFloatBE(offset);
+  }
+  if (size === 8) {
+    return buffer.readDoubleBE(offset);
+  }
+  return null;
+}
+
 /**
  * Depth-first search for the first element with `id`, descending only into the
  * container ids listed in `descendInto`.

package/services/hls-session-manager.js

@@ -974,7 +974,7 @@ function computeProgressMetrics(processedSeconds, totalSeconds, startPositionSec
  * @param {string | URL} inputUrl - URL of the stream to probe.
  * @returns {Promise<{ durationSeconds: number | null, width: number | null, height: number | null, fps: number | null, startTime: number, isHdr: boolean }>}
  */
-async function probeInputMediaInfo(ffmpegBin, inputUrl, { expectVideo = true } = {}) {
+async function probeInputMediaInfo(ffmpegBin, inputUrl) {
   return new Promise((resolve) => {
     const ffmpeg = spawn(ffmpegBin, ["-hide_banner", "-loglevel", "info", "-i", inputUrl, "-f", "null", "-"], {
       stdio: ["ignore", "ignore", "pipe"],
@@ -1014,14 +1014,15 @@ async function probeInputMediaInfo(ffmpegBin, inputUrl, { expectVideo = true } =
       // before any decoding. Bail as soon as both are present instead of letting
       // `-f null -` decode the whole stream until the 8 s timeout.
       //
-      // A file with NO picture never prints that stream line, so waiting for it
-      // means waiting out the whole timeout — every time, on the path where a
-      // viewer is changing soundtrack and the browser refuses a switch that is
-      // not ready in time. `Duration:` carries the start time this is asked for,
-      // and it is the last thing such a file has to say about itself.
+      // This probe asks about the PICTURE and nothing else now: a file with no
+      // video track is read by the container layer, which answers from 64 KB of
+      // header. It used to take an `expectVideo: false` for exactly that case,
+      // and the branch cost 8121 ms of every cold start (2026-09-03) because
+      // the exit still waited for a parsed DURATION, which a partly downloaded
+      // file prints as `N/A`.
       const duration = parseFfmpegDurationSeconds(stderr);
       const dims = parseFfmpegVideoDimensions(stderr);
-      if (duration != null && (dims.width != null || !expectVideo)) {
+      if (duration != null && dims.width != null) {
         clearTimeout(timeoutId);
         if (!ffmpeg.killed) {
           ffmpeg.kill("SIGTERM");
@@ -1757,6 +1758,7 @@ export class HlsSessionManager {
     tonemapSupported = false,
     getCachedMediaInfo = null,
     getCachedAudioTracks = null,
+    getContainerMediaInfo = null,
     fetchWholeFile = null,
     segmentFormatId = undefined,
     stateDir = "",
@@ -1777,6 +1779,13 @@ export class HlsSessionManager {
     // 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;
+    // What a file declares about itself, read by the container layer from the
+    // same header its track table comes from: format, duration, and where its
+    // own timeline begins. The last of those is why this exists — a soundtrack
+    // shipped as its own file has a timeline of its own, and asking ffmpeg for
+    // it meant reading a header this proxy had already read.
+    this.getContainerMediaInfo =
+      typeof getContainerMediaInfo === "function" ? getContainerMediaInfo : null;
     // Fetch one whole file of a source, as a bounded read rather than a
     // selection. Used to pull a soundtrack that ships beside the picture onto
     // the disk while the swarm has capacity to spare — see
@@ -2004,6 +2013,11 @@ export class HlsSessionManager {
     const sessionDir = createSessionDirPath(sessionId);
     const inputUrl = new URL("/stream", `${this.localBaseUrl}/`);
     inputUrl.searchParams.set("sourceKey", sourceKey);
+    // Whose read this is. The stream route counts the bytes it delivers against
+    // this session, and that count is what tells a waiting browser the proxy is
+    // alive while nothing has been encoded yet — the encoder's own progress
+    // cannot move before its first frame is decoded.
+    inputUrl.searchParams.set("session", sessionId);
     // A soundtrack shipped as its own file is encoded FROM that file, and an
     // audio rendition carries nothing else — so it reads the sidecar directly and
     // needs no second input at all. The muxed case, where a browser takes its
@@ -2019,6 +2033,7 @@ export class HlsSessionManager {
     if (!readsSidecarAlone && audioSource.isSidecar) {
       audioInputUrl = new URL("/stream", `${this.localBaseUrl}/`);
       audioInputUrl.searchParams.set("sourceKey", sourceKey);
+      audioInputUrl.searchParams.set("session", sessionId);
       audioInputUrl.searchParams.set("fileIndex", String(audioSource.fileIndex));
     }
 
@@ -2069,9 +2084,25 @@ export class HlsSessionManager {
     // the sound sits at a fixed offset from it for the whole film. Measured from
     // the file rather than assumed to be zero, because assuming it is exactly
     // the fault being avoided.
+    //
+    // NOT awaited. Creating a session used to stop here until the answer came
+    // back, and on a cold start the answer needs the sidecar's header off the
+    // swarm — 8121 ms of every session created, measured three times out of
+    // three on 2026-09-03. What is known now is used now; the reading runs
+    // behind, and `#startEncodeRun` takes the freshest value at spawn time, the
+    // same way it already re-reads `session.keyframeTimes`.
+    //
+    // Unknown means "no difference between the two timelines", not "the
+    // soundtrack starts at zero". The shift exists to correct a difference
+    // between two containers; asserting one that has not been read is inventing
+    // a number, while assuming none leaves the sound exactly where a release
+    // remuxed from a single source puts it.
     const audioFileStartTime = audioSource.isSidecar
-      ? await this.#sidecarStartTimeSeconds(sourceKey, audioSource.fileIndex)
+      ? (this.#sidecarStartTimeNow(sourceKey, audioSource.fileIndex) ?? sourceStartTime)
       : sourceStartTime;
+    if (audioSource.isSidecar) {
+      this.#warmSidecarStartTime(sourceKey, audioSource.fileIndex);
+    }
     const inputStartTime = readsSidecarAlone ? audioFileStartTime : sourceStartTime;
     // Tone-map an HDR source to SDR only when re-encoding video on the software
     // path and this ffmpeg has the filters. Hardware encoders keep their own
@@ -2388,6 +2419,11 @@ export class HlsSessionManager {
       // from a separate file.
       inputStartTime,
       audioFileStartTime,
+      // Whether this session's ONE input is the sidecar itself, which is what an
+      // audio rendition of a separately shipped soundtrack is. Stored rather
+      // than re-derived, because the derivation needs `audioOnly` and the
+      // sidecar test together and was already written two different ways.
+      readsSidecarAlone,
       // 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
@@ -5194,11 +5230,26 @@ export class HlsSessionManager {
     const startSeconds = Number.isFinite(positionSecondsOverride)
       ? positionSecondsOverride
       : this.runStartTimeFor(session, safeIndex);
+    // Where a sidecar soundtrack's own timeline begins, taken FRESH: the
+    // session may have been created before that file's header could be read,
+    // and this run is the first moment the answer matters. Same shape as
+    // `session.keyframeTimes`, which is likewise read again on every call so a
+    // background reading that has since finished is picked up.
+    const hasSidecarSound =
+      Number.isInteger(session.audioFileIndex) && session.audioFileIndex !== session.fileIndex;
+    const sidecarStartNow = hasSidecarSound
+      ? this.#sidecarStartTimeNow(session.sourceKey, session.audioFileIndex)
+      : null;
+    const audioFileStartTime = sidecarStartNow !== null
+      ? sidecarStartNow
+      : (Number.isFinite(session.audioFileStartTime) ? session.audioFileStartTime : 0);
     // The start time of the file this run READS, which is the picture's own for
     // every session except one whose soundtrack is a separate file.
-    const sourceStartTime = Number.isFinite(session.inputStartTime)
-      ? session.inputStartTime
-      : (Number.isFinite(session.sourceStartTime) ? session.sourceStartTime : 0);
+    const sourceStartTime = session.readsSidecarAlone === true && sidecarStartNow !== null
+      ? sidecarStartNow
+      : (Number.isFinite(session.inputStartTime)
+        ? session.inputStartTime
+        : (Number.isFinite(session.sourceStartTime) ? session.sourceStartTime : 0));
     // Cut where this session's grid says, whoever is producing the frames. The
     // times are measured from the start of THIS run; the same list serves as
     // the cut points and, when re-encoding, as the keyframes to force — one
@@ -5336,7 +5387,7 @@ export class HlsSessionManager {
     // files begin at their own container start time, and those need not be the
     // same number; the difference is what keeps the two aligned.
     const audioTimelineShift = audioInputUrl
-      ? (Number.isFinite(session.audioFileStartTime) ? session.audioFileStartTime : 0) - sourceStartTime
+      ? audioFileStartTime - sourceStartTime
       : 0;
     /**
      * Add the second input, if there is one, with its own seek.
@@ -9235,40 +9286,82 @@ export class HlsSessionManager {
   /**
    * Where a sidecar soundtrack's own timeline begins, in seconds.
    *
-   * One short probe of that file, kept for as long as the process lives: a
-   * container's start time is a property of the file and cannot change. It is
-   * asked only when such a track is actually chosen, so a torrent whose extra
-   * soundtracks nobody plays costs nothing for them.
+   * What has already been read, without reading anything. The answer to
+   * "is it known yet", which is what a caller who must not wait needs.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex - The SIDECAR's file.
+   * @returns {number | null} Null when nobody has read it yet.
+   */
+  #sidecarStartTimeNow(sourceKey, fileIndex) {
+    if (!(this.sidecarStartTimes instanceof Map)) {
+      this.sidecarStartTimes = new Map();
+    }
+    const held = this.sidecarStartTimes.get(`${sourceKey}:${fileIndex}`);
+    return Number.isFinite(held) ? held : null;
+  }
+
+  /**
+   * Start reading where a sidecar soundtrack's timeline begins, if nobody has.
+   *
+   * Read by the container layer from the file's own header — the same 64 KB,
+   * the same reader and the same per-file cache the audio menu's track list
+   * comes from. A container states this, so it is read from the container and
+   * not measured from the media.
+   *
+   * Until 2.73.0 the session spawned an ffmpeg against the proxy's own
+   * `/stream` for it and waited up to eight seconds for the banner. Field
+   * 2026-09-03: that read cost 8121 ms of a cold start, three times out of
+   * three, while the container layer had read the same header of the same file
+   * in 8 ms in the same second. The eight seconds were not even spent on the
+   * answer — the early exit was gated on a DURATION, and a partly downloaded
+   * file prints `Duration: N/A` with the start time on that very line.
+   *
+   * Runs behind whoever asked, so no viewer waits for it. Once per file per
+   * process: a container's start time is a property of the file and cannot
+   * change. A reading that comes back without an answer is NOT remembered — the
+   * file may simply not have been downloaded far enough yet, and the next
+   * session asks again.
    *
    * @param {string} sourceKey
    * @param {number} fileIndex - The SIDECAR's file.
-   * @returns {Promise<number>}
+   * @returns {void}
    */
-  async #sidecarStartTimeSeconds(sourceKey, fileIndex) {
+  #warmSidecarStartTime(sourceKey, fileIndex) {
+    if (typeof this.getContainerMediaInfo !== "function") {
+      return;
+    }
     if (!(this.sidecarStartTimes instanceof Map)) {
       this.sidecarStartTimes = new Map();
     }
+    if (!(this.sidecarStartTimeReads instanceof Set)) {
+      this.sidecarStartTimeReads = new Set();
+    }
     const key = `${sourceKey}:${fileIndex}`;
-    const held = this.sidecarStartTimes.get(key);
-    if (Number.isFinite(held)) {
-      return held;
-    }
-    const url = new URL("/stream", `${this.localBaseUrl}/`);
-    url.searchParams.set("sourceKey", sourceKey);
-    url.searchParams.set("fileIndex", String(fileIndex));
-    let startTime = 0;
-    try {
-      const info = await probeInputMediaInfo(this.ffmpegBin, url.toString(), { expectVideo: false });
-      startTime = Number.isFinite(info?.startTime) ? info.startTime : 0;
-    } catch (error) {
-      logger.info(
-        `transcode: the start time of soundtrack file ${fileIndex} could not be probed ` +
-        `(${error instanceof Error ? error.message : String(error)}) — taken as 0`
-      );
-      startTime = 0;
+    if (this.sidecarStartTimes.has(key) || this.sidecarStartTimeReads.has(key)) {
+      return;
     }
-    this.sidecarStartTimes.set(key, startTime);
-    return startTime;
+    this.sidecarStartTimeReads.add(key);
+    void Promise.resolve(this.getContainerMediaInfo({ sourceKey, fileIndex }))
+      .then((info) => {
+        if (info && Number.isFinite(info.startTimeSeconds)) {
+          this.sidecarStartTimes.set(key, info.startTimeSeconds);
+          logger.info(
+            `transcode: soundtrack file ${fileIndex}'s own timeline starts at ` +
+            `${info.startTimeSeconds.toFixed(6)}s, read from its header`
+          );
+        }
+      })
+      .catch((error) => {
+        logger.info(
+          `transcode: the start of soundtrack file ${fileIndex}'s timeline could not be read ` +
+          `(${error instanceof Error ? error.message : String(error)}) — the two timelines are ` +
+          "taken to agree until it can be"
+        );
+      })
+      .finally(() => {
+        this.sidecarStartTimeReads.delete(key);
+      });
   }
 
   /**
@@ -10292,6 +10385,28 @@ export class HlsSessionManager {
    * @param {string} sessionId
    * @returns {Promise<object | null>}
    */
+  /**
+   * Count bytes the swarm has delivered to one session's own input read.
+   *
+   * Called by the `/stream` route for every fragment it writes to an encoder.
+   * Cheap on purpose — one addition, no clock, no log — because it runs per
+   * fragment on the path that feeds ffmpeg.
+   *
+   * @param {string} sessionId
+   * @param {number} bytes
+   * @returns {void}
+   */
+  noteInputBytes(sessionId, bytes) {
+    if (!sessionId || !(bytes > 0)) {
+      return;
+    }
+    const session = this.sessionsById.get(sessionId);
+    if (!session) {
+      return;
+    }
+    session.inputBytes = (session.inputBytes ?? 0) + bytes;
+  }
+
   async getSessionProgress(sessionId) {
     if (!isSafeSessionId(sessionId)) {
       return null;
@@ -10344,6 +10459,21 @@ export class HlsSessionManager {
         worstSupplyWaitSec: session.supplyFigures?.worstWaitSec
       })?.seconds ?? null,
       processedSeconds: session.progress.processedSeconds,
+      // Bytes this session's own reads have received from the swarm.
+      //
+      // The second proof that a session is alive, and the only one available
+      // before its first frame exists: `processedSeconds` cannot move until the
+      // decoder has a frame, so on a cold start it stands at the start position
+      // for as long as the first piece takes to arrive. Field 2026-09-03 — one
+      // piece took 46.3 s while the swarm delivered 55.9 MB across the torrent,
+      // `processedSeconds` frozen at 171.3 throughout, and the browser declared
+      // the proxy dead 0.4 s before the piece landed.
+      //
+      // Counted per SESSION and not per torrent, deliberately: in that same
+      // episode the torrent received 55.9 MB while the picture's own reads
+      // received 4.5 MB of it, so a torrent-wide figure would have called a
+      // starved session healthy.
+      inputBytes: session.inputBytes ?? 0,
       startPositionSeconds: session.progress.startPositionSeconds ?? 0,
       totalSeconds: session.progress.totalSeconds,
       percent: session.progress.percent,

package/services/orchestrators/ContainerOrchestrator.js

@@ -61,6 +61,28 @@ export class ContainerOrchestrator {
     }
   }
 
+  /**
+   * What the file declares about itself as a whole — format, duration, and
+   * where its own timeline begins.
+   *
+   * Read once per file, like the track table beside it, and from the same 64 KB
+   * of header. A `null` field means the container does not declare it, which is
+   * a final answer about the container.
+   *
+   * @param {object} params - same as getContainer
+   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo|null>}
+   */
+  async getMediaInfo(params) {
+    const container = await this.getContainer(params);
+    if (!container) return null;
+    try {
+      return await container.readMediaInfo();
+    } catch (e) {
+      logger.warn(`container: readMediaInfo failed for "${params.label}": ${e?.message ?? e}`);
+      return null;
+    }
+  }
+
   /**
    * @param {object} params - same as getContainer
    * @returns {Promise<{times:number[],tolerance:number}|null>}