@torrent-tv/proxy 2.74.1 → 2.75.0

package/services/container/Mp4Container.js

@@ -16,7 +16,6 @@
  */
 
 import { Container } from "./Container.js";
-import { isMp4, readMp4KeyframeTimes } from "../container-index/mp4.js";
 import { VideoTrack } from "../tracks/VideoTrack.js";
 import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_FORMATS_MP4 } from "../tracks/TextSubtitleTrack.js";
@@ -98,6 +97,20 @@ export class Mp4Container extends Container {
     return isMp4(head);
   }
 
+  /**
+   * The keyframe times this container's own index states, in ascending seconds.
+   *
+   * Static so a caller that has bytes and no container can ask; the instance
+   * form is {@link Container#readKeyframeIndex}.
+   *
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
+   * @param {number} fileSize
+   * @returns {Promise<number[]|null>} Null where the container has no index.
+   */
+  static readKeyframeTimes(readRange, fileSize) {
+    return readMp4KeyframeTimes(readRange, fileSize);
+  }
+
   /**
    * This container's text subtitle tracks, with every cue's time and byte
    * range — ISO/IEC 14496-12 §8.5 and §8.7.
@@ -562,31 +575,6 @@ const TEXT_FORMATS = new Set(["tx3g", "text", "wvtt"]);
 
 
 
-/**
- * Walk the top level of the file to find `moov`, reading only box headers.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
- * @param {number} fileSize
- * @returns {Promise<{ offset: number, size: number } | null>}
- */
-async function findMoov(readRange, fileSize) {
-  let at = 0;
-  while (at < fileSize) {
-    const probe = await readRange(at, Math.min(fileSize - 1, at + PROBE_BYTES - 1));
-    if (!probe || probe.length < HEADER_BYTES) {
-      return null;
-    }
-    const box = readBox(probe, 0);
-    if (!box) {
-      return null;
-    }
-    if (box.type === "moov") {
-      return { offset: at, size: box.size };
-    }
-    at += box.size;
-  }
-  return null;
-}
 
 /**
  * Sample durations, expanded from the run-length table.
@@ -896,3 +884,361 @@ function decodeSubtitleSample(bytes, format) {
   const length = bytes.readUInt16BE(0);
   return bytes.toString("utf8", 2, Math.min(bytes.length, 2 + length)).trim();
 }
+
+// ---------------------------------------------------------------------------
+// ISO/IEC 14496-12 speaking about MP4: stss, stts, ctts and the edit list.
+// Here because the class is the only way in.
+// ---------------------------------------------------------------------------
+/**
+ * @file Keyframe index for MP4/MOV, read without downloading the file.
+ *
+ * MP4 keeps its tables in a `moov` box: `stss` lists which samples are sync
+ * samples (keyframes) by number, and `stts` gives each sample's duration, so
+ * the two together turn "sample #N" into "second T". `moov` sits either at the
+ * start (files written for streaming) or at the end (the common case for a
+ * plain mux); box headers state their own size, so it is found by stepping over
+ * top-level boxes rather than scanning bytes — a couple of 64-byte reads even
+ * when `mdat` is gigabytes.
+ *
+ * Same purpose as the Matroska reader: on the video-COPY path the segment
+ * boundaries ARE the source's keyframes, and inventing an even grid instead
+ * makes players walk the whole file or present audio with no picture.
+ */
+
+// A 64-bit box size is signalled by a 32-bit size of 1, the real size following
+// in the next 8 bytes.
+// Enough to read any box header while walking the top level.
+// Cap on the moov read. A feature-length file indexes to a few hundred KB;
+// beyond this is not a normal index and not worth pulling over a torrent.
+
+/**
+ * Whether this looks like MP4/MOV — every real file opens with an `ftyp` box.
+ *
+ * @param {Buffer} head
+ * @returns {boolean}
+ */
+function isMp4(head) {
+  return head.length >= 12 && head.toString("latin1", 4, 8) === "ftyp";
+}
+
+/**
+ * Read a box header at `offset`.
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @returns {{ type: string, size: number, headerBytes: number } | null}
+ */
+function readBoxHeader(buffer, offset) {
+  if (offset + HEADER_BYTES > buffer.length) {
+    return null;
+  }
+  const size32 = buffer.readUInt32BE(offset);
+  const type = buffer.toString("latin1", offset + 4, offset + 8);
+  if (size32 === LARGE_SIZE_MARKER) {
+    if (offset + LARGE_HEADER_BYTES > buffer.length) {
+      return null;
+    }
+    // High word is zero for any file we can practically handle.
+    const high = buffer.readUInt32BE(offset + 8);
+    const low = buffer.readUInt32BE(offset + 12);
+    return { type, size: high * 4294967296 + low, headerBytes: LARGE_HEADER_BYTES };
+  }
+  return { type, size: size32, headerBytes: HEADER_BYTES };
+}
+
+/**
+ * Walk the top-level boxes to find `moov`, reading only each box header.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ offset: number, size: number, headerBytes: number } | null>}
+ */
+async function findMoov(readRange, fileSize) {
+  let offset = 0;
+  while (offset < fileSize) {
+    const probe = await readRange(offset, Math.min(fileSize - 1, offset + PROBE_BYTES - 1));
+    if (!probe || probe.length < HEADER_BYTES) {
+      return null;
+    }
+    const header = readBoxHeader(probe, 0);
+    // Size 0 means "extends to end of file" — legal only for the last box, and
+    // never for one we would step over.
+    if (!header || header.size <= 0) {
+      return null;
+    }
+    if (header.type === "moov") {
+      return { offset, size: header.size, headerBytes: header.headerBytes };
+    }
+    offset += header.size;
+  }
+  return null;
+}
+
+/**
+ * Find the first box of `type` directly inside a range of an already-read buffer.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ dataOffset: number, end: number } | null}
+ */
+function findBox(buffer, start, end, type) {
+  let offset = start;
+  while (offset + HEADER_BYTES <= end) {
+    const header = readBoxHeader(buffer, offset);
+    if (!header || header.size <= 0) {
+      return null;
+    }
+    if (header.type === type) {
+      return { dataOffset: offset + header.headerBytes, end: Math.min(end, offset + header.size) };
+    }
+    offset += header.size;
+  }
+  return null;
+}
+
+/**
+ * All boxes of `type` directly inside a range.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ dataOffset: number, end: number }[]}
+ */
+function findAllBoxes(buffer, start, end, type) {
+  const found = [];
+  let offset = start;
+  while (offset + HEADER_BYTES <= end) {
+    const header = readBoxHeader(buffer, offset);
+    if (!header || header.size <= 0) {
+      break;
+    }
+    if (header.type === type) {
+      found.push({ dataOffset: offset + header.headerBytes, end: Math.min(end, offset + header.size) });
+    }
+    offset += header.size;
+  }
+  return found;
+}
+
+/**
+ * Turn sample numbers into seconds using the time-to-sample table.
+ *
+ * `stts` is run-length encoded — pairs of (sample count, per-sample duration) —
+ * so one walk yields every sample's start time without expanding the table.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} stts
+ * @param {number} timescale - Ticks per second.
+ * @param {Set<number>} wanted - Sample numbers (1-based).
+ * @returns {number[]} Seconds, ascending.
+ */
+function resolveSampleTimes(buffer, stts, timescale, wanted, offsets = null) {
+  const entryCount = buffer.readUInt32BE(stts.dataOffset + 4);
+  const times = [];
+  let sampleNumber = 1;
+  let ticks = 0;
+  let cursor = stts.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + 8 <= stts.end; entry += 1) {
+    const count = buffer.readUInt32BE(cursor);
+    const delta = buffer.readUInt32BE(cursor + 4);
+    for (let index = 0; index < count; index += 1) {
+      if (wanted.has(sampleNumber)) {
+        // `CT(n) = DT(n) + CTTS(n)` — ISO/IEC 14496-12 §8.6.1.3. The offset is
+        // what turns decode order into the order frames are shown in, and it is
+        // the timeline ffmpeg cuts on.
+        times.push((ticks + (offsets?.get(sampleNumber) ?? 0)) / timescale);
+      }
+      ticks += delta;
+      sampleNumber += 1;
+    }
+    cursor += 8;
+  }
+  return times;
+}
+
+/**
+ * Composition offsets for the sample numbers asked for.
+ *
+ * `ctts` is run-length encoded like `stts`, and version 1 carries SIGNED
+ * offsets — which is what the version exists for: a frame may be shown before
+ * it is decoded. Reading them as unsigned turns a small negative offset into
+ * roughly four billion ticks.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} ctts
+ * @param {Set<number>} wanted - Sample numbers (1-based).
+ * @returns {Map<number, number>} Sample number to offset in media ticks.
+ */
+function readCompositionOffsets(buffer, ctts, wanted) {
+  const version = buffer[ctts.dataOffset];
+  const entryCount = buffer.readUInt32BE(ctts.dataOffset + 4);
+  const offsets = new Map();
+  let sampleNumber = 1;
+  let cursor = ctts.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + 8 <= ctts.end; entry += 1) {
+    const count = buffer.readUInt32BE(cursor);
+    const offset = version === 1 ? buffer.readInt32BE(cursor + 4) : buffer.readUInt32BE(cursor + 4);
+    for (let index = 0; index < count; index += 1) {
+      if (wanted.has(sampleNumber)) {
+        offsets.set(sampleNumber, offset);
+      }
+      sampleNumber += 1;
+    }
+    cursor += 8;
+  }
+  return offsets;
+}
+
+/**
+ * How far the edit list shifts this track's composition timeline, in media
+ * ticks.
+ *
+ * ISO/IEC 14496-12 §8.6.6.3: `media_time` is the start of the edit within the
+ * media, in the MEDIA timescale and in composition time, while
+ * `segment_duration` is in the MOVIE timescale — two different units in one
+ * structure, which is why only the first is read here. `media_time = -1` is an
+ * empty edit: it inserts blank presentation time and starts no media, so the
+ * first real edit is the one that matters.
+ *
+ * Measured 2026-08-19: every LostFilm MP4 that carries a composition offset
+ * also carries an edit list cancelling it exactly, which is why decode times
+ * have been right on those files. `Firefly.S01E03` has the offset and NO edit
+ * list, and its times were 62.1 ms early on all 34 keyframes checked.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} elst
+ * @returns {number} Ticks to subtract; zero when nothing is shifted.
+ */
+function readEditShift(buffer, elst) {
+  const version = buffer[elst.dataOffset];
+  const entryCount = buffer.readUInt32BE(elst.dataOffset + 4);
+  const wide = version === 1;
+  const entryBytes = wide ? 20 : 12;
+  let cursor = elst.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + entryBytes <= elst.end; entry += 1) {
+    const mediaTime = wide
+      ? Number(buffer.readBigInt64BE(cursor + 8))
+      : buffer.readInt32BE(cursor + 4);
+    if (mediaTime >= 0) {
+      return mediaTime;
+    }
+    cursor += entryBytes;
+  }
+  return 0;
+}
+
+/**
+ * Whether this track's handler says it carries video.
+ *
+ * The standard identifies a track by its `hdlr`, and nothing else does. Picking
+ * "the first track that happens to carry sync samples" worked only because the
+ * seven releases measured all put video first; a file whose audio track carries
+ * them, or one that leads with a cover-art video track, would be read from the
+ * wrong place. That is the same defect that was fixed in the Matroska reader on
+ * 2026-08-18, arrived at from the other side.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} mdia
+ * @returns {boolean}
+ */
+function isVideoTrack(buffer, mdia) {
+  const hdlr = findBox(buffer, mdia.dataOffset, mdia.end, "hdlr");
+  if (!hdlr || hdlr.dataOffset + 12 > hdlr.end) {
+    return false;
+  }
+  // FullBox header (4) then a reserved pre_defined (4), then the handler type.
+  return buffer.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) === "vide";
+}
+
+/**
+ * Read the keyframe times of an MP4/MOV file.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<number[] | null>} Ascending seconds, or null when the file
+ *   carries no usable index (fragmented MP4, truncated or damaged `moov`).
+ */
+async function readMp4KeyframeTimes(readRange, fileSize) {
+  const moovBox = await findMoov(readRange, fileSize);
+  if (!moovBox || moovBox.size > MAX_MOOV_BYTES) {
+    return null;
+  }
+
+  const moov = await readRange(moovBox.offset, Math.min(fileSize - 1, moovBox.offset + moovBox.size - 1));
+  if (!moov || moov.length < moovBox.headerBytes) {
+    return null;
+  }
+
+  // Examine every track, and take the one whose HANDLER says it is video. A
+  // track with no `stss` has every sample a keyframe, so it constrains nothing
+  // and is skipped even when it is the video one.
+  for (const trak of findAllBoxes(moov, moovBox.headerBytes, moov.length, "trak")) {
+    const mdia = findBox(moov, trak.dataOffset, trak.end, "mdia");
+    if (!mdia || !isVideoTrack(moov, mdia)) {
+      continue;
+    }
+    const mdhd = findBox(moov, mdia.dataOffset, mdia.end, "mdhd");
+    if (!mdhd) {
+      continue;
+    }
+    // mdhd layout: version(1) + flags(3), then creation/modification times —
+    // 32-bit each in version 0, 64-bit in version 1 — then the timescale.
+    const version = moov[mdhd.dataOffset];
+    const timescaleOffset = version === 1 ? mdhd.dataOffset + 20 : mdhd.dataOffset + 12;
+    if (timescaleOffset + 4 > mdhd.end) {
+      continue;
+    }
+    const timescale = moov.readUInt32BE(timescaleOffset);
+    if (!timescale) {
+      continue;
+    }
+
+    const minf = findBox(moov, mdia.dataOffset, mdia.end, "minf");
+    const stbl = minf && findBox(moov, minf.dataOffset, minf.end, "stbl");
+    if (!stbl) {
+      continue;
+    }
+    const stss = findBox(moov, stbl.dataOffset, stbl.end, "stss");
+    const stts = findBox(moov, stbl.dataOffset, stbl.end, "stts");
+    if (!stss || !stts) {
+      continue;
+    }
+
+    const syncCount = moov.readUInt32BE(stss.dataOffset + 4);
+    const wanted = new Set();
+    for (let index = 0; index < syncCount; index += 1) {
+      const at = stss.dataOffset + 8 + index * 4;
+      if (at + 4 > stss.end) {
+        break;
+      }
+      wanted.add(moov.readUInt32BE(at));
+    }
+    if (wanted.size === 0) {
+      continue;
+    }
+
+    // The two terms that turn decode times into the timeline ffmpeg cuts on.
+    // Both are optional: a file without them is one whose decode and
+    // composition orders already agree, and then nothing is added or taken.
+    const ctts = findBox(moov, stbl.dataOffset, stbl.end, "ctts");
+    const offsets = ctts ? readCompositionOffsets(moov, ctts, wanted) : null;
+    const edts = findBox(moov, trak.dataOffset, trak.end, "edts");
+    const elst = edts && findBox(moov, edts.dataOffset, edts.end, "elst");
+    const editShift = elst ? readEditShift(moov, elst) : 0;
+
+    const times = resolveSampleTimes(moov, stts, timescale, wanted, offsets);
+    if (times.length > 0) {
+      // A shift applied after the division would be in the wrong units: the
+      // edit's `media_time` is in MEDIA ticks, like everything else here.
+      const shifted = editShift === 0 ? times : times.map((time) => time - editShift / timescale);
+      // A negative time is not a position in the file. It happens when an edit
+      // starts later than a keyframe the table lists, and those frames are not
+      // presented at all.
+      return shifted.filter((time) => time >= 0);
+    }
+  }
+  return null;
+}

package/services/hls-session-manager.js

@@ -17,7 +17,7 @@ import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { logger } from "../utils/logger.js";
-import { readKeyframeIndex } from "./container-index/index.js";
+import { ContainerFactory } from "./container/ContainerFactory.js";
 import { readMachineState, readProcessCpuSeconds, readProxyCpuSeconds, readSystemCpu, shareOfMachine } from "./host-load.js";
 import { speedFromReadings } from "./encoder-readings.js";
 import { availableShareFrom, correctForAvailability } from "./available-share.js";
@@ -2997,7 +2997,7 @@ export class HlsSessionManager {
       }
     };
 
-    const result = await readKeyframeIndex({ readRange, fileSize, label: logName });
+    const result = await ContainerFactory.readKeyframeIndex({ readRange, fileSize, label: logName });
     this.keyframeIndexCache.set(cacheKey, result);
     return result;
   }

package/services/playback-planner.js

@@ -9,12 +9,11 @@
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
 import { Container } from "./container/Container.js";
-import { buildAudioInventory, mergeContainerAudioFlags } from "./audio-inventory.js";
+import { buildAudioInventory } from "./audio-inventory.js";
 import { countVideoFiles, matchSidecarFiles } from "./sidecar-files.js";
 import {
   parseFfmpegDurationSeconds,
   parseFfmpegStartTimeSeconds,
-  parseFfmpegVideoDimensions,
   parseFfmpegBitDepth,
   parseFfmpegBitrateKbps,
   parseFfmpegVideoFps,
@@ -431,7 +430,7 @@ export function createPlaybackPlanner({
       // The picture's head is already downloaded — the codec probe just read it
       // — so this is a parse and not a wait, but it is bounded like the rest.
       const declared = await declaredAudioOf(fileIndex, "the picture");
-      const merged = mergeContainerAudioFlags(banner, declared);
+      const merged = Container.mergeAudioFlags(banner, declared);
       embedded = merged.tracks;
       logger.info(
         merged.aligned
@@ -650,10 +649,40 @@ export function createPlaybackPlanner({
           `${codecsDetected ? `${videoCodec || "-"}/${audioCodec || "-"}` : "codecs NOT detected (will be polled again)"}`
       );
 
+      // The picture's own facts come from two readings and only one was ever
+      // used: every figure the encode is planned from came from ffmpeg's
+      // banner, while the `VideoTrack` the container declares was read and used
+      // for nothing but a line in the log.
+      let declaredVideo = null;
+      if (typeof torrentPool?.getDeclaredVideoTrack === "function") {
+        try {
+          declaredVideo = await torrentPool.getDeclaredVideoTrack(torrent, fileIndex);
+        } catch (error) {
+          logger.info(`video track: could not be read (${error?.message ?? error})`);
+        }
+      }
       // `mode` is advisory only (audio-codec based). The browser makes the
       // authoritative decision independently per stream via canPlayType /
       // mediaCapabilities, transcoding only what it cannot play.
       const requiresTranscode = audioCodec.length > 0 && !DIRECT_AUDIO_CODECS.has(audioCodec);
+      // The two readings of the picture, lined up. Which one answers is decided
+      // per field by what each IS — see `Container.mergeVideoFacts`.
+      const videoFacts = Container.mergeVideoFacts(
+        {
+          width: videoWidth,
+          height: videoHeight,
+          fps: parseFfmpegVideoFps(probe.stderr),
+          isHdr: parseFfmpegHdr(probe.stderr),
+          bitDepth: parseFfmpegBitDepth(probe.stderr)
+        },
+        declaredVideo
+      );
+      if (videoFacts.disagreements.length > 0) {
+        logger.info(
+          `video track: the file and the probe disagree — ${videoFacts.disagreements.join("; ")}; ` +
+          "the size and frame rate are the probe's, the bit depth and HDR the file's"
+        );
+      }
       const plan = {
         mode: requiresTranscode ? "hls" : "direct",
         directUrl,
@@ -664,8 +693,8 @@ export function createPlaybackPlanner({
         durationSeconds,
         // Source coded resolution — drives the browser's manual quality menu
         // (list of forced resolutions <= source). 0 when unknown.
-        videoWidth,
-        videoHeight,
+        videoWidth: videoFacts.width ?? 0,
+        videoHeight: videoFacts.height ?? 0,
         // Full track inventory for the browser's audio/subtitle menus. The audio
         // half spans the picture's own tracks AND the soundtracks shipped as
         // files beside it, under one numbering — see `buildInventory`.
@@ -683,15 +712,15 @@ export function createPlaybackPlanner({
         // does, as the host learns what this source costs. Stripped on the way
         // out — it is not part of the plan the browser is given.
         mediaInfoForOffer: {
-          width: videoWidth,
-          height: videoHeight,
-          fps: parseFfmpegVideoFps(probe.stderr),
+          width: videoFacts.width,
+          height: videoFacts.height,
+          fps: videoFacts.fps,
           bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
           // Which family of the decode measurement prices this source. A video
           // that has to be re-encoded is one the browser could not play, so it
           // is usually NOT H.264, and H.264 constants are wrong for it.
           codec: videoCodec,
-          bitDepth: parseFfmpegBitDepth(probe.stderr),
+          bitDepth: videoFacts.bitDepth,
           // Which file this is, so the offer can be answered from what an
           // encoder has already learned about THIS source rather than from the
           // startup clips — the same correction a live session applies.
@@ -708,7 +737,6 @@ export function createPlaybackPlanner({
         cache.set(cacheKey, plan);
         // Cache the full media info from THIS probe's banner (same helpers the
         // session manager uses) so createSession can skip its own probe.
-        const dims = parseFfmpegVideoDimensions(probe.stderr);
         mediaInfoCache.set(cacheKey, {
           // The codecs, because the session manager asks this cache which
           // tracks the output will carry — and they were never stored here. It
@@ -722,13 +750,13 @@ export function createPlaybackPlanner({
           videoCodec: plan.videoCodec,
           audioCodec: plan.audioCodec,
           durationSeconds: parseFfmpegDurationSeconds(probe.stderr),
-          width: dims.width,
-          height: dims.height,
+          width: videoFacts.width,
+          height: videoFacts.height,
           bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
-          fps: parseFfmpegVideoFps(probe.stderr),
+          fps: videoFacts.fps,
           startTime: parseFfmpegStartTimeSeconds(probe.stderr),
-          isHdr: parseFfmpegHdr(probe.stderr),
-          bitDepth: parseFfmpegBitDepth(probe.stderr)
+          isHdr: videoFacts.isHdr,
+          bitDepth: videoFacts.bitDepth
         });
         // Warm the file-body start for the transcode session that follows.
         // Fire-and-forget: never delays the plan response.