@torrent-tv/proxy 2.72.2 → 2.73.0

package/services/torrent-worker/container-tracks.js

@@ -224,6 +224,140 @@ export async function containerAudioTracksOf(torrent, fileIndex, sourceKey, opti
 /** Bytes of a file's head worth fetching before its track table is read. */
 export const CONTAINER_HEAD_BYTES = HEAD_BYTES;
 
+/**
+ * How much of the file to pull in under the viewer's resume position.
+ *
+ * One piece of a video torrent is 4-16 MB and a resume lands anywhere inside
+ * one, so anything smaller would still leave the encoder waiting for the piece
+ * it starts in. Eight megabytes covers that piece and usually the next.
+ */
+const RESUME_REGION_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Where a position in seconds falls in a file, in bytes.
+ *
+ * Proportional, and therefore approximate on a variable bitrate — which is what
+ * it is for: a prefetch that puts the swarm to work on roughly the right place
+ * while the plan and the session are still being built. The encoder's own read
+ * asks for the exact bytes a moment later and corrects it.
+ *
+ * A position past the end is clamped to the end rather than refused: a resume
+ * position can outlive the file it was recorded against, and reading the last
+ * bytes is harmless where reading past them is an error.
+ *
+ * @param {number} fileLength
+ * @param {number} durationSeconds
+ * @param {number} positionSeconds
+ * @returns {number}
+ */
+export function resumeByteOffset(fileLength, durationSeconds, positionSeconds) {
+  if (!(fileLength > 0) || !(durationSeconds > 0) || !(positionSeconds > 0)) {
+    return 0;
+  }
+  const within = Math.min(positionSeconds, durationSeconds);
+  return Math.min(fileLength - 1, Math.floor((fileLength * within) / durationSeconds));
+}
+
+/**
+ * Start fetching the region a viewer is about to resume at.
+ *
+ * Where that region IS can only be worked out from two numbers the file itself
+ * holds — its length and its duration — so this belongs beside the container
+ * read rather than in the route: the route knows a position in seconds and
+ * nothing else. The conversion is proportional and therefore approximate on a
+ * variable bitrate; it is a prefetch, and the encoder's own read corrects it.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {number} positionSeconds
+ * @param {{ prefetchEdges?: () => Promise<unknown>, fetchRegion?: (start: number, bytes: number) => Promise<unknown> }} options
+ * @returns {Promise<boolean>} Whether a region was asked for.
+ */
+export async function warmResumePosition(torrent, fileIndex, sourceKey, positionSeconds, options = {}) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !(positionSeconds > 0) || typeof options.fetchRegion !== "function") {
+    return false;
+  }
+  const info = await containerMediaInfoOf(torrent, fileIndex, sourceKey, options);
+  const duration = info?.durationSeconds;
+  if (!Number.isFinite(duration) || duration <= 0) {
+    logger.info(
+      `warm ${sourceKey.slice(0, 8)}: "${String(file.name).slice(0, 40)}" does not declare its ` +
+      "duration, so where the viewer's position falls in it cannot be worked out — " +
+      "the region under it is left to the encoder's own read"
+    );
+    return false;
+  }
+  const at = resumeByteOffset(file.length, duration, positionSeconds);
+  logger.info(
+    `warm ${sourceKey.slice(0, 8)}: fetching ${(RESUME_REGION_BYTES / (1024 * 1024)).toFixed(0)}MB under the ` +
+    `viewer's position ${positionSeconds.toFixed(1)}s of ${duration.toFixed(1)}s, which is ` +
+    `${(at / (1024 * 1024)).toFixed(1)}MB into "${String(file.name).slice(0, 40)}"`
+  );
+  await options.fetchRegion(at, RESUME_REGION_BYTES);
+  return true;
+}
+
+/**
+ * What one file declares about itself: format, duration, and where its own
+ * timeline begins.
+ *
+ * The same header the track table is read from, and the container instance is
+ * cached per file, so asking for this after the tracks costs no read at all.
+ * It exists because the alternative was a second reader: the session manager
+ * used to spawn an ffmpeg over the proxy's own HTTP to learn where a sidecar
+ * soundtrack's timeline begins, and that read cost 8121 ms in the field on
+ * 2026-09-03 while this layer had read the same header in 8 ms in the same
+ * second.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ prefetchEdges?: () => Promise<unknown> }} [options]
+ * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
+ */
+export async function containerMediaInfoOf(torrent, fileIndex, sourceKey, options = {}) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+    return null;
+  }
+  if (typeof options.prefetchEdges === "function") {
+    try {
+      await options.prefetchEdges();
+    } catch {
+      // A prefetch that failed is not a reason to skip the read: the read
+      // fetches what it needs itself, only more slowly.
+    }
+  }
+  const readRange = async (start, end) =>
+    readFetching(file, start, Math.min(end, file.length - 1));
+  try {
+    const info = await containerOrchestrator.getMediaInfo({
+      sourceKey,
+      fileIndex,
+      readRange,
+      fileSize: file.length,
+      label: String(file.name ?? "")
+    });
+    if (info) {
+      logger.info(
+        `container-info: "${String(file.name).slice(0, 40)}" is ${info.format}, ` +
+        `${info.durationSeconds === null ? "duration not declared" : `${info.durationSeconds.toFixed(3)}s`}, ` +
+        `${info.startTimeSeconds === null
+          ? "start of its timeline not declared"
+          : `its timeline starts at ${info.startTimeSeconds.toFixed(6)}s`}`
+      );
+    }
+    return info;
+  } catch (error) {
+    logger.warn(
+      `container-info: "${String(file.name).slice(0, 40)}" could not be read: ${error?.message ?? error}`
+    );
+    return null;
+  }
+}
+
 /**
  * Forget one file's tracks, or every file of a source.
  *

package/services/torrent-worker/fastest-wires.js

@@ -24,6 +24,19 @@
  * instead of staying with whoever got it first.
  */
 
+/**
+ * How short a piece's remaining tail must be for a second copy of it to be
+ * worth asking for.
+ *
+ * Sixteen blocks is 256 KB against the 4-16 MB piece they hold up. The figure
+ * comes from what was measured rather than chosen for roundness: the tails a
+ * blocked reader waits on were 2 to 14 blocks of 512 on 2026-08-19, and 3 of
+ * 512 in the field failure of 2026-09-03 that took 46.3 s. Above this the piece
+ * is still arriving normally and duplicating would spend the shared link on
+ * bytes already on their way.
+ */
+const SHORT_TAIL_BLOCKS = 16;
+
 /**
  * The library's own request entry. Internal, so its absence must be noticed
  * rather than swallowed: without it this lever silently does nothing.
@@ -269,6 +282,15 @@ export function duplicateTailFor(torrent, pieceIndex) {
     return { duplicated: 0, missing: missing.length, wires: candidates.length };
   }
 
+  // A tail this short is what a blocked read is actually waiting on, and a
+  // second copy of it costs a few dozen kilobytes. A longer one is a piece
+  // still arriving normally, where duplicating would spend the shared link on
+  // bytes that are already coming — measured 2026-08-19, the tails a reader
+  // waits on are 2 to 14 blocks of 512.
+  if (missing.length > SHORT_TAIL_BLOCKS) {
+    return { duplicated: 0, missing: missing.length, wires: candidates.length };
+  }
+
   let duplicated = 0;
   // One block per wire: that is what the pipelines can usefully take at once,
   // and it needs no number of its own.
@@ -281,13 +303,14 @@ export function duplicateTailFor(torrent, pieceIndex) {
     // or it would free a THIRD wire's block as well.
     if (torrent._request(candidates[index], pieceIndex, false) === true) {
       duplicated += 1;
-      continue;
     }
-    // The wire's pipeline is full. The block stays in the piece's cancellation
-    // stack and will be handed to whoever asks next, which is harmless — it is
-    // already in flight elsewhere — but there is no point asking the remaining
-    // wires, whose pipelines are no emptier.
-    break;
+    // A refusal means THAT wire's pipeline is full, and says nothing about the
+    // next one's — pipelines are per wire. This used to stop the whole pass on
+    // the first refusal, on the stated reasoning that the remaining wires were
+    // "no emptier", which is an assumption about other peers' queues that
+    // nothing here measures. The block whose reservation was freed stays in the
+    // piece's cancellation stack and is handed to whoever asks next, which is
+    // harmless: it is already in flight elsewhere.
   }
   return { duplicated, missing: missing.length, wires: candidates.length };
 }

package/services/torrent-worker/piece-reader.js

@@ -950,11 +950,18 @@ export async function* readFragments({
           const result = askFastestWiresFor(torrent, pieceIndex);
           if (result.asked === 0) {
             tailWhenNothingPlaced = describePieceTail(torrent, pieceIndex);
-            // Nothing could be placed the ordinary way, which means every block
-            // is spoken for. That is exactly when a second copy of the last
-            // blocks is worth asking for.
-            duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
           }
+          // Every attempt, not only the ones where nothing else could be placed.
+          // The ordinary steering asks for whatever blocks are still free; the
+          // read, meanwhile, ends when the LAST block arrives, and that block is
+          // reserved to one wire whether or not other blocks could be asked for.
+          // Field 2026-09-03: 46.3 s on one piece, ordinary requests placed on
+          // 54 of 87 attempts throughout, and a tail of 3 blocks of 512 held by
+          // wires at 51-99 KB/s to the end — while duplication, which ran only
+          // on the 33 attempts that placed nothing, managed 5 blocks in the
+          // whole wait. `duplicateTailFor` bounds itself by the tail's length,
+          // so a piece that is merely still arriving is left alone.
+          duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
           pushed = {
             asked: pushed.asked + result.asked,
             refusedWhileReserved:

package/services/torrent-worker/pool-adapter.js

@@ -204,6 +204,41 @@ export class WorkerTorrentPool {
     return Array.isArray(answer?.tracks) ? answer.tracks : [];
   }
 
+  /**
+   * Start fetching the region a viewer is about to resume at. Named in seconds
+   * here; the worker turns it into bytes, where the file's duration is readable.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} positionSeconds
+   * @returns {Promise<boolean>}
+   */
+  async warmResumePosition(torrent, fileIndex, positionSeconds) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return false;
+    }
+    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds });
+    return answer?.started === true;
+  }
+
+  /**
+   * What one file declares about itself: format, duration, and where its own
+   * timeline begins.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
+   */
+  async getContainerMediaInfo(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    const answer = await this.#client.getContainerMediaInfo({ sourceKey, fileIndex });
+    return answer?.info ?? null;
+  }
+
   /**
    * The audio tracks one file declares, in the order ffmpeg numbers them
    * `0:a:N`.

package/services/torrent-worker/protocol.js

@@ -81,6 +81,18 @@ export const Command = {
    * file beside it, which is the same question about a different file.
    */
   CONTAINER_TRACKS: "container-tracks",
+  /**
+   * What a file declares about itself as a whole — format, duration, and where
+   * its own timeline begins. Read from the same header, by the same reader, as
+   * the track table above; the alternative was a second ffmpeg over the proxy's
+   * own HTTP reading the same bytes again.
+   */
+  CONTAINER_MEDIA_INFO: "container-media-info",
+  /**
+   * Start fetching the region a viewer is about to resume at, named in seconds
+   * and turned into bytes here, where the file's own duration can be read.
+   */
+  WARM_POSITION: "warm-position",
   /** Cues of one subtitle track, from the clusters already downloaded. */
   SUBTITLE_CUES: "subtitle-cues",
   /** Shut the client down, optionally deleting downloaded data. */

package/services/torrent-worker/worker.js

@@ -28,7 +28,12 @@ import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf, warmSubtitleCues } from "./subtitle-cues.js";
-import { CONTAINER_HEAD_BYTES, containerTracksOf } from "./container-tracks.js";
+import {
+  CONTAINER_HEAD_BYTES,
+  containerMediaInfoOf,
+  containerTracksOf,
+  warmResumePosition
+} from "./container-tracks.js";
 import { fillFileInBackground } from "./background-fill.js";
 import { Command, Event } from "./protocol.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js";
@@ -418,6 +423,45 @@ async function runCommand(command, params, id) {
       };
     }
 
+    case Command.CONTAINER_MEDIA_INFO: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return {
+        info: await containerMediaInfoOf(torrent, params.fileIndex, params.sourceKey, {
+          // Same reason as the track table above: the file this is asked about
+          // is often one nobody has played yet, so its head has to be fetched
+          // before there is anything to read.
+          prefetchEdges: () =>
+            pool.prefetchFileEdges(torrent, params.fileIndex, {
+              headBytes: CONTAINER_HEAD_BYTES,
+              tailBytes: 0,
+              timeoutMs: 60_000
+            })
+        })
+      };
+    }
+
+    case Command.WARM_POSITION: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return {
+        started: await warmResumePosition(
+          torrent,
+          params.fileIndex,
+          params.sourceKey,
+          params.positionSeconds,
+          {
+            prefetchEdges: () =>
+              pool.prefetchFileEdges(torrent, params.fileIndex, {
+                headBytes: CONTAINER_HEAD_BYTES,
+                tailBytes: 0,
+                timeoutMs: 60_000
+              }),
+            fetchRegion: (start, bytes) =>
+              pool.prefetchFileRegion(torrent, params.fileIndex, start, bytes)
+          }
+        )
+      };
+    }
+
     case Command.SUBTITLE_CUES: {
       const torrent = await requireTorrent(params.sourceKey);
       const held = await cuesHeldFor(torrent, params.fileIndex, params.sourceKey, params.trackNumber);

package/test/container-media-info.test.js

@@ -0,0 +1,228 @@
+/**
+ * @file What a file declares about ITSELF — format, duration, and where its own
+ * timeline begins — read from its header by the container layer.
+ *
+ * These fixtures are built byte by byte rather than produced by ffmpeg, on
+ * purpose: a test that runs a real encoder measures the machine it runs on, and
+ * two such tests in this suite have failed four times in one day for exactly
+ * that reason (roadmap item 54). The numbers here are checked against ffmpeg
+ * ONCE, by hand, and the result is recorded rather than re-measured on every
+ * run — 2026-09-03, a Matroska file offset by 0.130435 s: ffmpeg reported
+ * `Duration: 00:00:02.13, start: 0.130000` and this reader answered
+ * `durationSeconds 2.131, startTimeSeconds 0.13`, which is the same number at
+ * the precision each prints. The same file as MP4: `start: 0.000000` from
+ * ffmpeg, 0 from this reader.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MatroskaContainer } from "../services/container/MatroskaContainer.js";
+import { Mp4Container } from "../services/container/Mp4Container.js";
+import { AviContainer } from "../services/container/AviContainer.js";
+
+/**
+ * An EBML element: its id bytes, a four-byte size, then the payload.
+ *
+ * @param {number[]} idBytes
+ * @param {Buffer} payload
+ * @returns {Buffer}
+ */
+function ebml(idBytes, payload) {
+  const size = Buffer.alloc(4);
+  // Four-byte size form: `0001xxxx` in the leading byte marks the width.
+  size.writeUInt32BE(payload.length);
+  size[0] |= 0x10;
+  return Buffer.concat([Buffer.from(idBytes), size, payload]);
+}
+
+/** @param {number} value @param {number} bytes @returns {Buffer} */
+function uint(value, bytes) {
+  const out = Buffer.alloc(bytes);
+  out.writeUIntBE(value, 0, bytes);
+  return out;
+}
+
+/** @param {number} value @returns {Buffer} */
+function float64(value) {
+  const out = Buffer.alloc(8);
+  out.writeDoubleBE(value);
+  return out;
+}
+
+const ID_EBML_HEADER = [0x1a, 0x45, 0xdf, 0xa3];
+const ID_SEGMENT = [0x18, 0x53, 0x80, 0x67];
+const ID_SEEK_HEAD = [0x11, 0x4d, 0x9b, 0x74];
+const ID_SEEK = [0x4d, 0xbb];
+const ID_SEEK_ID = [0x53, 0xab];
+const ID_SEEK_POSITION = [0x53, 0xac];
+const ID_INFO = [0x15, 0x49, 0xa9, 0x66];
+const ID_TIMESTAMP_SCALE = [0x2a, 0xd7, 0xb1];
+const ID_DURATION = [0x44, 0x89];
+const ID_CLUSTER = [0x1f, 0x43, 0xb6, 0x75];
+const ID_TIMESTAMP = [0xe7];
+const ID_VOID = [0xec];
+
+/**
+ * A reader over a buffer, in the shape the container layer takes.
+ *
+ * @param {Buffer} bytes
+ * @returns {(start: number, end: number) => Promise<Buffer>}
+ */
+function readerOver(bytes) {
+  return async (start, end) => bytes.subarray(start, Math.min(end + 1, bytes.length));
+}
+
+test("a Matroska file states its duration in ticks and its start in the first cluster", async () => {
+  const info = ebml(ID_INFO, Buffer.concat([
+    ebml(ID_TIMESTAMP_SCALE, uint(1_000_000, 3)),
+    // 2131 ticks of a millisecond each.
+    ebml(ID_DURATION, float64(2131))
+  ]));
+  const cluster = ebml(ID_CLUSTER, ebml(ID_TIMESTAMP, uint(130, 1)));
+  const file = Buffer.concat([
+    ebml(ID_EBML_HEADER, Buffer.alloc(4)),
+    ebml(ID_SEGMENT, Buffer.concat([info, cluster]))
+  ]);
+
+  const container = new MatroskaContainer({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.equal(read.format, "matroska");
+  assert.ok(Math.abs(read.durationSeconds - 2.131) < 1e-9, `duration was ${read.durationSeconds}`);
+  assert.ok(Math.abs(read.startTimeSeconds - 0.13) < 1e-9, `start was ${read.startTimeSeconds}`);
+});
+
+test("a cluster past the head window is found through the SeekHead", async () => {
+  // Everything before the cluster is padded past the 64 KB the head read covers,
+  // which is the case this second path exists for: a file whose Tracks element
+  // is large enough to push the first cluster out of reach.
+  const info = ebml(ID_INFO, ebml(ID_TIMESTAMP_SCALE, uint(1_000_000, 3)));
+  const padding = ebml(ID_VOID, Buffer.alloc(70 * 1024));
+  const cluster = ebml(ID_CLUSTER, ebml(ID_TIMESTAMP, uint(2500, 2)));
+  // The SeekHead is written first, so its own length is known before the
+  // position it names can be computed — build it with a placeholder, measure,
+  // then write the real position.
+  const seekHeadFor = (position) => ebml(ID_SEEK_HEAD, ebml(ID_SEEK, Buffer.concat([
+    ebml(ID_SEEK_ID, Buffer.from(ID_CLUSTER)),
+    ebml(ID_SEEK_POSITION, uint(position, 4))
+  ])));
+  const seekHeadLength = seekHeadFor(0).length;
+  const clusterPosition = seekHeadLength + info.length + padding.length;
+  const segmentPayload = Buffer.concat([seekHeadFor(clusterPosition), info, padding, cluster]);
+  const file = Buffer.concat([
+    ebml(ID_EBML_HEADER, Buffer.alloc(4)),
+    ebml(ID_SEGMENT, segmentPayload)
+  ]);
+
+  const container = new MatroskaContainer({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.ok(Math.abs(read.startTimeSeconds - 2.5) < 1e-9, `start was ${read.startTimeSeconds}`);
+});
+
+test("a Matroska file that declares no duration says so, rather than saying zero", async () => {
+  const cluster = ebml(ID_CLUSTER, ebml(ID_TIMESTAMP, uint(0, 1)));
+  const file = Buffer.concat([
+    ebml(ID_EBML_HEADER, Buffer.alloc(4)),
+    ebml(ID_SEGMENT, cluster)
+  ]);
+
+  const container = new MatroskaContainer({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.equal(read.durationSeconds, null);
+  assert.equal(read.startTimeSeconds, 0);
+});
+
+/**
+ * An ISO/IEC 14496-12 box.
+ *
+ * @param {string} type
+ * @param {Buffer} payload
+ * @returns {Buffer}
+ */
+function box(type, payload) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(payload.length + 8);
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, payload]);
+}
+
+test("an MP4 states its duration in mvhd and its start in an empty edit", async () => {
+  const mvhd = box("mvhd", Buffer.concat([
+    Buffer.alloc(4), // version 0 + flags
+    Buffer.alloc(8), // creation, modification
+    uint(1000, 4), // timescale: ticks per second
+    uint(2000, 4), // duration: two seconds
+    Buffer.alloc(80)
+  ]));
+  const elst = box("elst", Buffer.concat([
+    Buffer.alloc(4), // version 0 + flags
+    uint(1, 4), // one entry
+    uint(130, 4), // segment_duration: 0.130 s at the movie timescale
+    Buffer.from([0xff, 0xff, 0xff, 0xff]), // media_time -1: an EMPTY edit
+    uint(0x00010000, 4) // media_rate 1.0
+  ]));
+  const trak = box("trak", box("edts", elst));
+  const file = Buffer.concat([
+    box("ftyp", Buffer.from("isom", "latin1")),
+    box("moov", Buffer.concat([mvhd, trak]))
+  ]);
+
+  const container = new Mp4Container({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.equal(read.format, "mp4");
+  assert.ok(Math.abs(read.durationSeconds - 2) < 1e-9, `duration was ${read.durationSeconds}`);
+  assert.ok(Math.abs(read.startTimeSeconds - 0.13) < 1e-9, `start was ${read.startTimeSeconds}`);
+});
+
+test("an MP4 with no edit list begins at zero, and that is an answer", async () => {
+  const mvhd = box("mvhd", Buffer.concat([
+    Buffer.alloc(4),
+    Buffer.alloc(8),
+    uint(600, 4),
+    uint(1200, 4),
+    Buffer.alloc(80)
+  ]));
+  const file = Buffer.concat([
+    box("ftyp", Buffer.from("isom", "latin1")),
+    box("moov", mvhd)
+  ]);
+
+  const container = new Mp4Container({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.ok(Math.abs(read.durationSeconds - 2) < 1e-9, `duration was ${read.durationSeconds}`);
+  assert.equal(read.startTimeSeconds, 0);
+});
+
+test("an AVI states its length as microseconds per frame times the frame count", async () => {
+  const avih = Buffer.concat([
+    Buffer.from("avih", "latin1"),
+    uint(56, 4),
+    Buffer.from(new Uint8Array(new Uint32Array([
+      40_000, // dwMicroSecPerFrame: 25 fps
+      0, 0, 0,
+      50 // dwTotalFrames: two seconds of them
+    ]).buffer)),
+    Buffer.alloc(36)
+  ]);
+  const file = Buffer.concat([
+    Buffer.from("RIFF", "latin1"),
+    uint(0, 4),
+    Buffer.from("AVI ", "latin1"),
+    Buffer.from("LIST", "latin1"),
+    uint(avih.length + 4, 4),
+    Buffer.from("hdrl", "latin1"),
+    avih
+  ]);
+
+  const container = new AviContainer({ readRange: readerOver(file), fileSize: file.length });
+  const read = await container.readMediaInfo();
+
+  assert.equal(read.format, "avi");
+  assert.ok(Math.abs(read.durationSeconds - 2) < 1e-9, `duration was ${read.durationSeconds}`);
+  assert.equal(read.startTimeSeconds, 0);
+});

package/test/resume-warm.test.js

@@ -0,0 +1,39 @@
+/**
+ * @file Where a viewer's resume position falls in the file, in bytes.
+ *
+ * The warm-up fetches a file's two edges, because that is what the codec probe
+ * reads. The region the VIEWER will resume at was asked for by nobody until the
+ * encoder opened its input — field 2026-09-03, 53 s after the Retry button on a
+ * cold torrent, and the piece it then needed took another 46.3 s to arrive.
+ * Turning the position into an offset is the only arithmetic in that path, so it
+ * is the only part with anything to get wrong.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resumeByteOffset } from "../services/torrent-worker/container-tracks.js";
+
+test("a position halfway through a film is halfway through its file", () => {
+  assert.equal(resumeByteOffset(1000, 100, 50), 500);
+});
+
+test("the field case lands where the encoder went looking", () => {
+  // The measured session: 171.338 s into a 23:41 episode of 541 MB, and the
+  // read that blocked was at 63 MB.
+  const at = resumeByteOffset(541 * 1024 * 1024, 23 * 60 + 41, 171.338);
+  const megabytes = at / (1024 * 1024);
+  assert.ok(megabytes > 60 && megabytes < 68, `landed at ${megabytes.toFixed(1)}MB`);
+});
+
+test("a position past the end reads the end, rather than past it", () => {
+  const length = 1000;
+  const at = resumeByteOffset(length, 100, 10_000);
+  assert.equal(at, length - 1);
+});
+
+test("nothing is known, nothing is guessed", () => {
+  assert.equal(resumeByteOffset(0, 100, 50), 0, "no file length");
+  assert.equal(resumeByteOffset(1000, 0, 50), 0, "no duration — the container did not declare one");
+  assert.equal(resumeByteOffset(1000, 100, 0), 0, "the viewer is at the beginning, where the edges already are");
+});