@torrent-tv/proxy 2.72.1 → 2.73.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 2.73.0
+
+- **New**: `Container.readMediaInfo()` — what a file declares about ITSELF: its format, its duration, and where its own timeline begins. Matroska reads Duration and TimestampScale from `Info` and takes the start from the first Cluster's timestamp (RFC 9559 states no start-time element, so that IS the start); MP4 reads `mvhd` and the empty edit of `elst` (ISO/IEC 14496-12 §8.6.6); AVI multiplies microseconds per frame by the frame count. `null` means the container does not declare the field, which is a final answer rather than "ask someone else".
+- **Fix**: Session creation no longer spends eight seconds learning where a soundtrack shipped as its own file begins. It spawned an ffmpeg against this proxy's own `/stream` and waited out the probe's whole 8 s budget — measured in the field on 2026-09-03 at 8078 ms, 8112 ms and 8121 ms, three cold starts out of three. The container layer had read the same header of the same file **in 8 ms, in the same second**: two readers of one header, a thousandfold apart. Worse, the eight seconds bought nothing — the probe's early exit is gated on a parsed DURATION, and a partially downloaded file prints `Duration: N/A` with the start time on that very line, so the answer was in hand from the first second. The value now comes from the container reading, and creating a session does not wait for it at all: what is known is used, the reading runs behind, and the encode run takes the freshest value at spawn — the same shape `session.keyframeTimes` already had. Where the file has not said, the two timelines are taken to AGREE rather than assumed to differ, because asserting an offset nobody has read is inventing a number.
+- **Chore**: Checked against ffmpeg by hand rather than assumed. A Matroska file offset by 0.130435 s: ffmpeg reported `Duration: 00:00:02.13, start: 0.130000`, this reader `durationSeconds 2.131, startTimeSeconds 0.13`. The same content as MP4: `start: 0.000000` against 0. Six checks in `test/container-media-info.test.js` build their fixtures byte by byte instead of running an encoder, so the suite measures the parsing and not the machine.
+- **New**: `/progress` carries `inputBytes` — the bytes the swarm has delivered to THIS session's own input read. It is the only sign of life a session can give before its first frame exists, because `processedSeconds` cannot move until the decoder has one. Field 2026-09-03: a cold retry blocked 46.3 s on a single piece with `processedSeconds` frozen at the start position throughout, and the browser declared the proxy dead 0.4 s before the piece landed. Counted per SESSION and never per torrent — 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.
+- **New**: `POST /api/sources/:key/warm` accepts `positionSeconds` and fetches the region under it. The warm-up fetched a file's two EDGES, because that is what the codec probe reads; the region the viewer will actually resume at was asked for by nobody until the encoder opened its input — 53 s after the Retry button in the field case, and it then took another 46 s. Where that region lies is worked out from the file's own length and duration, which is the first thing `readMediaInfo` is used for beyond its own purpose. Started after the edges and never awaited by them: the edges gate the playback plan.
+- **Fix**: A blocked reader's tail is duplicated on every attempt, not only on the attempts where no ordinary request could be placed. A read ends when its LAST block arrives, and that block is reserved to one wire whether or not other blocks are still free to ask for. Field 2026-09-03: 46.3 s on one piece, ordinary requests placed on 54 of 87 attempts, a tail of 3 blocks of 512 held by wires at 51-99 KB/s to the very end, and duplication — which ran only on the attempts that placed nothing — managed 5 blocks in the whole wait. Bounded by the tail's own length: 16 blocks (256 KB) against a 4-16 MB piece, above which the piece is still arriving normally and a second copy would spend the shared link on bytes already on their way.
+- **Fix**: One wire refusing a duplicate no longer ends the pass. Pipelines are per wire; stopping at the first refusal rested on the stated reasoning that the remaining wires were "no emptier", which is an assumption about other peers' queues that nothing here measures.
+- **Chore**: `docs/container-architecture.md` states the boundary outright — a fact the container declares is read from the container, a fact only the media has is measured from the media — with the three jobs that stay ffmpeg's and the measurements behind each. It also records why byte access does not belong on a track, and names the one thing that is genuinely split (a subtitle track carries byte positions while the reading of them lives in the worker) together with the obstacle to closing it: the track table fetches what is missing while the cue walk deliberately reads only what is downloaded, and one container instance holds one reader.
+
+## 2.72.2
+
+- **Fix**: A claim for room in the piece store could never end. Two waits inside one function shared a single field for when the wait began — the wait for the disk, and the wait for a piece that may be evicted — and each of them zeroed that field on giving up, which restarted the other's clock. Measured 2026-09-03: the claim cycled for ever, five seconds per side, `grewWaitingForDisk` and `waitedForPins` each climbing once every five seconds while `blockedByPins` stayed at 0, so the refusal the store is supposed to end with was unreachable. A claim's patience is now held by the claim itself and not by the store, which is also correct with several claimants: one caller giving up used to reset the wait of every other. A claim that cannot be met now fails after 5 s — measured 5025 ms — with `Every resident piece is pinned and nothing moved`.
+- **Chore**: The whole suite can finish again. `test/piece-store-reservations.test.js` did not fail on the defect above, it HUNG, so `node --test` never completed at all and no release since 2.72.0 had been covered by a full run. The three checks that drive a held disk write now carry a 30 s bound, so a return of this defect is a failure in seconds rather than a stoppage.
+- **Chore**: Two further checks in that file were failing and nobody could see it, because the file stopped before reaching them. Measured on the unmodified code, both fail there identically, so neither is from this release. One asked whether the claim was waiting by reading `waitedForPins` alone, while the store was demonstrably waiting for the disk and counting `waitedForDisk`; it now accepts either. The other gave the store three blocks and then required a piece to be admitted while a block was in flight, which is a full store by the store's own accounting — it has four now, so what the check measures is what it was written for: a completing spill must not put the stale copy back on disk.
+
 ## 2.72.1
 
 - **Fix**: Subtitles on an embedded ASS track were shown to the viewer as the whole dialogue row — `21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the Sixth Heaven.` — because one function both unwrapped the container's framing and stripped the codec's markup, and decided which framing it held by counting commas. Matroska writes eight fields before the text and takes the two timing fields out into the block's own timestamp (`matroska.org/technical/subtitles.html`); a row in a `.ass` FILE has nine and states its own column order in `[Events]`. The function expected the file's shape, found nine fields where it wanted more than nine, and returned the row untouched. The test that covered this passed because its fixture carried the file's two timestamps — a shape that never occurs on that path.

package/docs/container-architecture.md

@@ -28,6 +28,72 @@ read from another file, and a raw `.srt` needs no `Container` subclass because
 it has no track table and no index to read: the whole file is the payload, and
 `SubtitleController` already reads it as such.
 
+## Who answers what — the rule
+
+A fact the container DECLARES is read from the container. A fact only the media
+itself has is measured from the media, which means ffmpeg.
+
+That is the whole boundary, and it is not about speed. Speed is a consequence:
+this layer asks for the smallest region that holds the answer — 64 KB of header,
+the Cues block, a sample table — while ffmpeg cannot be asked for a bounded
+region at all. Its input analysis pulls megabytes before it will say anything,
+and over a torrent those megabytes may not exist yet. Measured 2026-09-03 on one
+`.mka`: this layer read its header in **8 ms**, and an ffmpeg reading the same
+header of the same file through the proxy's own `/stream`, in the same second,
+took **8121 ms** — and spent all of it waiting for a DURATION its caller did not
+want, because its early exit is gated on one.
+
+So ffmpeg keeps exactly three jobs, and nothing else:
+
+1. producing media — the encode run;
+2. measuring THIS MACHINE — encoder detection and its strict test, decode
+   calibration, the contention penalty;
+3. answering what the container does not declare — above all keyframe positions
+   in a container with no index, where a packet scan is the only source. Even
+   there the container is asked FIRST: measured, the container index gave 570
+   keyframes in 0.8 s from two point reads of 16 KB, while a scan of the same
+   file found 77 in 45 s and did not finish.
+
+`null` in `ContainerMediaInfo` means the container does not declare the field.
+That is a final answer about the container, and the point at which a caller may
+go to the media — not "unknown, ask again".
+
+## Where byte access lives, and why not on a track
+
+A `ContainerTrack` is a DECLARATION. It carries no `readRange` and no file
+identity, and it should not: byte access is the `Container`'s, injected as
+`readRange(start, end)` and bound to one file.
+
+The obvious-looking improvement — hand the track a reader so it can fetch its own
+bytes — was reviewed on 2026-09-03 and is **not** the right shape:
+
+- for video and audio, this layer never reads the payload at all. It goes to
+  ffmpeg by URL, where seeking and gigabytes belong. A `readRange` on a
+  `VideoTrack` would be a capability with no consumer, inviting reads of a size
+  this path is not built for;
+- tracks cross the worker boundary as PLAIN OBJECTS (`plainTrack()`), because a
+  class instance does not survive it as a class. A back-reference to a container
+  cannot cross either, so such a track would be able to read its own bytes only
+  on the thread where the container is already at hand.
+
+What IS split, and is worth closing: `SubtitleTrack` carries `clusterPositions`
+and `samples` — byte POSITIONS — while the reading of those positions lives in
+`torrent-worker/subtitle-cues.js`, which builds a `readRange` of its own. Two
+halves of one action in two layers.
+
+The shape that closes it is `Container.readCuesOf(track)` — the container already
+holds `readRange`, and the series `readTracks` / `readKeyframeIndex` /
+`readMediaInfo` / `cueTextOf` is exactly where "ask the container" belongs.
+
+**It is not done yet, and the obstacle is real rather than effort.** The two
+readers want different read POLICIES over the same file: the track table fetches
+what is missing from the swarm (`readFetching`), while the cue walk deliberately
+reads only what is already downloaded (`readHeld`) so that turning subtitles on
+never pulls bytes the viewer is not waiting for. One container instance per file
+holds one `readRange`, so as things stand it cannot serve both. Resolving that —
+a read policy per call, or something else — is the design question to answer
+before the move, and answering it in passing would settle it by accident.
+
 ## Layers
 
 ```mermaid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.72.1",
+  "version": "2.73.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/warm/post.js

@@ -49,6 +49,13 @@ export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torr
   const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
   const requestedIndex = Number(body.fileIndex);
   const fileIndex = Number.isInteger(requestedIndex) && requestedIndex >= 0 ? requestedIndex : null;
+  // Where the viewer is about to resume, if they are resuming. The edges below
+  // are what the codec probe reads; this is what the VIEWER will read, and until
+  // now nothing asked for it before the encoder did.
+  const requestedPosition = Number(body.positionSeconds);
+  const positionSeconds = Number.isFinite(requestedPosition) && requestedPosition > 0
+    ? requestedPosition
+    : 0;
 
   // Adding the torrent is what announces to the trackers and starts connecting
   // to peers, and it is also what a magnet needs in order to fetch its
@@ -77,6 +84,18 @@ export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torr
       const message = error instanceof Error ? error.message : String(error);
       logger.warn(`warm ${sourceKey.slice(0, 8)}: file edges failed: ${message}`);
     });
+    // Started AFTER the edges, and not awaited by them either: the edges gate
+    // the playback plan, so they must not queue behind a region nobody is
+    // reading yet. This one only has to arrive before the encoder does, and the
+    // encoder is a plan and a session away.
+    if (positionSeconds > 0 && typeof torrentPool.warmResumePosition === "function") {
+      Promise.resolve(torrentPool.warmResumePosition(torrent, fileIndex, positionSeconds)).catch(
+        (error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.warn(`warm ${sourceKey.slice(0, 8)}: the viewer's position failed: ${message}`);
+        }
+      );
+    }
   }
 
   // The files that carry this episode's OTHER soundtracks and its subtitles.

package/routes/stream/get.js

@@ -78,7 +78,7 @@ async function waitForTorrent(torrentPool, sourceType, source) {
  * @param {{ sourceRegistry: ReturnType<import("../../store/source-registry.js").createSourceRegistry>, torrentPool: import("../../services/torrent-pool.js").TorrentPool }} deps
  * @returns {Promise<void>}
  */
-export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool }) {
+export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool, noteInputBytes = null }) {
   const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
   const fileIndex = Number(fileIndexRaw);
   const { sourceType, source } = getSourceParams(req.query, sourceRegistry);
@@ -172,6 +172,12 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
   const windowBytes =
     Number.isFinite(windowBytesRaw) && windowBytesRaw > 0 ? windowBytesRaw : undefined;
 
+  // Which transcode session this read feeds, when it feeds one. Put on the URL
+  // by the session that builds it, because this route otherwise knows only a
+  // file — and two sessions can read one file, so the file cannot stand in for
+  // the session.
+  const sessionId = typeof req.query.session === "string" ? req.query.session : "";
+
   const fragments = typeof file.createFragmentReader === "function"
     ? file.createFragmentReader({ start, end, windowBytes })
     : null;
@@ -201,6 +207,17 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
           reply.raw.write(fragment.bytes, (error) => (error ? reject(error) : resolve()));
         });
         sent += fragment.bytes.length;
+        // Say so, if this read belongs to a transcode session. It is the only
+        // proof that a session which has produced nothing yet is nevertheless
+        // being fed: the encoder's own progress cannot move until its first
+        // frame is decoded, and a viewer waiting for that first frame was being
+        // told the proxy had died while the swarm was delivering to it. Field
+        // 2026-09-03: 46.3 s on one piece, `processedSeconds` frozen at the
+        // start position throughout, and the browser gave up 0.4 s before the
+        // piece landed.
+        if (noteInputBytes) {
+          noteInputBytes(sessionId, fragment.bytes.length);
+        }
         // Only now are these bytes gone: the piece can be unpinned, and the
         // slot it occupies reused. Releasing before this point corrupts the
         // response silently.

package/server.js

@@ -193,6 +193,23 @@ export async function startProxyServer({
     // The file's audio tracks, for the master playlist's rendition group. Already
     // probed for the browser's audio menu; read from there rather than probed again.
     getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params),
+    // What a file declares about itself, read by the container layer from the
+    // same header its track table comes from. This is how the session learns
+    // where a soundtrack shipped as its own file begins — it used to spawn an
+    // ffmpeg over this proxy's own HTTP to ask the same question of the same
+    // bytes, and that read cost 8.1 s of every cold start (field 2026-09-03).
+    getContainerMediaInfo: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record || typeof torrentPool.getContainerMediaInfo !== "function") {
+        return null;
+      }
+      try {
+        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+        return await torrentPool.getContainerMediaInfo(torrent, fileIndex);
+      } catch {
+        return null;
+      }
+    },
     // Pull one whole file onto the disk. Used for a soundtrack that ships beside
     // the picture, once the encoder is as far ahead of the viewer as it is
     // allowed to get — the one moment the swarm's capacity is demonstrably
@@ -260,7 +277,14 @@ export async function startProxyServer({
     })
   );
   app.get("/stream", async (req, reply) =>
-    handleStreamGet(req, reply, { sourceRegistry, torrentPool })
+    handleStreamGet(req, reply, {
+      sourceRegistry,
+      torrentPool,
+      // So a session that has produced nothing yet can still show it is being
+      // fed. The route knows only files; the session id rides on the URL the
+      // session itself built.
+      noteInputBytes: (sessionId, bytes) => hlsSessionManager.noteInputBytes(sessionId, bytes)
+    })
   );
   app.post("/api/transcode-sessions", async (req, reply) =>
     handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager, sourceRegistry, torrentPool })

package/services/container/AviContainer.js

@@ -36,6 +36,42 @@ export class AviContainer extends Container {
     })];
   }
 
+  /**
+   * Duration from the main AVI header, per the RIFF AVI specification: the
+   * header states microseconds per frame and the total number of frames, and
+   * their product is the length.
+   *
+   * An AVI has no edit list and no timeline offset of any kind, so its start is
+   * zero — a declaration of the format itself, 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: 0 };
+    this.mediaInfo = info;
+    const head = await this.readRange(0, Math.min(4095, this.fileSize - 1));
+    if (!head || !isAvi(head)) {
+      return info;
+    }
+    // RIFF("AVI ") -> LIST("hdrl") -> avih. The avih chunk's payload begins with
+    // dwMicroSecPerFrame and its fifth field is dwTotalFrames.
+    const at = head.indexOf("avih", 0, "latin1");
+    if (at < 0 || at + 8 + 20 > head.length) {
+      return info;
+    }
+    const payload = at + 8;
+    const microsecondsPerFrame = head.readUInt32LE(payload);
+    const totalFrames = head.readUInt32LE(payload + 16);
+    if (microsecondsPerFrame > 0 && totalFrames > 0) {
+      info.durationSeconds = (microsecondsPerFrame * totalFrames) / 1e6;
+    }
+    return info;
+  }
+
   async readKeyframeIndex() {
     const r = await readAviKeyframeTimes(this.readRange, this.fileSize);
     if (!r) return null;

package/services/container/Container.js

@@ -12,6 +12,19 @@
  *  - AVI RIFF §: LIST hdrl, idx1
  */
 
+/**
+ * What one file declares about itself. Every field is either a value the
+ * container states or `null`, which means the container does not state it —
+ * a defined absence, not "nobody has looked yet".
+ *
+ * @typedef {object} ContainerMediaInfo
+ * @property {string} format - "matroska" | "mp4" | "avi" | "unknown".
+ * @property {number | null} durationSeconds
+ * @property {number | null} startTimeSeconds - Where this file's own timeline
+ *   begins. Two files of one release need not agree on it, and the difference
+ *   is what keeps a soundtrack shipped separately aligned with its picture.
+ */
+
 export class Container {
   /**
    * @param {object} params
@@ -52,6 +65,34 @@ export class Container {
     return null;
   }
 
+  /**
+   * What this file DECLARES about itself as a whole, as distinct from what its
+   * individual tracks declare.
+   *
+   * The rule this method exists to hold: a fact the container declares is read
+   * from the container; a fact only the media itself has is measured from the
+   * media. Both halves used to be asked of ffmpeg, so the same header was read
+   * twice — measured 2026-09-03, this layer read one `.mka` header in 8 ms while
+   * a second ffmpeg read the same header over HTTP for 8121 ms, in the same
+   * second, on the same file.
+   *
+   * `null` is not "unknown, ask someone else". It means the container does not
+   * declare the field, which is a final answer about the container and the point
+   * at which a caller may go to the media — see `docs/container-architecture.md`.
+   *
+   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
+   */
+  async readMediaInfo() {
+    if (!this.mediaInfo) {
+      this.mediaInfo = {
+        format: this.formatName,
+        durationSeconds: null,
+        startTimeSeconds: null
+      };
+    }
+    return this.mediaInfo;
+  }
+
   /**
    * Subtitle-specific: where cues live (Matroska cluster positions or MP4 sample ranges).
    * Returned via track objects' clusterPositions/samples, so base has no extra method — tracks carry it.

package/services/container/MatroskaContainer.js

@@ -22,9 +22,29 @@ import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_CODECS_MATROSKA } from "../tracks/TextSubtitleTrack.js";
 import { ImageSubtitleTrack } from "../tracks/ImageSubtitleTrack.js";
 import { ContainerTrack } from "../tracks/ContainerTrack.js";
-import { findElement, iterateElements, readUint } from "../container-index/ebml-reader.js";
+import { findElement, iterateElements, readFloat, readUint } from "../container-index/ebml-reader.js";
 
 const HEAD_BYTES = 64 * 1024;
+const ID_SEGMENT = 0x18538067;
+const ID_SEEK_HEAD = 0x114d9b74;
+const ID_SEEK = 0x4dbb;
+const ID_SEEK_ID = 0x53ab;
+const ID_SEEK_POSITION = 0x53ac;
+const ID_INFO = 0x1549a966;
+const ID_TIMESTAMP_SCALE = 0x2ad7b1;
+const ID_DURATION = 0x4489;
+const ID_CLUSTER = 0x1f43b675;
+const ID_TIMESTAMP = 0xe7;
+const ID_SIMPLE_BLOCK = 0xa3;
+const ID_BLOCK_GROUP = 0xa0;
+/** RFC 9559 §5.1.2.1: nanoseconds per tick when Info omits TimestampScale. */
+const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+/**
+ * How much to read at a cluster whose position came from the SeekHead. A
+ * cluster's Timestamp is the first child every muxer writes, so this only has
+ * to cover the element header and that one field.
+ */
+const CLUSTER_PROBE_BYTES = 4 * 1024;
 const ID_TRACKS = 0x1654ae6b;
 const ID_TRACK_ENTRY = 0xae;
 const ID_TRACK_NUMBER = 0xd7;
@@ -70,6 +90,171 @@ export class MatroskaContainer extends Container {
     return isMatroska(head);
   }
 
+  /**
+   * Duration and the start of this file's own timeline, per RFC 9559 §5.1.2.
+   *
+   * Duration is stated in `Info` as a FLOAT in ticks, so it needs the file's
+   * `TimestampScale` to become seconds. The start of the timeline is not stated
+   * anywhere — Matroska has no such element — so it is the timestamp of the
+   * first Cluster, which is what the first frame is placed against.
+   *
+   * @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 head = await this.readRange(0, Math.min(HEAD_BYTES - 1, this.fileSize - 1));
+    if (!head || !isMatroska(head)) {
+      return info;
+    }
+    const segment = findElement(head, ID_SEGMENT, []);
+    if (!segment) {
+      return info;
+    }
+    const scale = MatroskaContainer.#timestampScaleOf(head, segment.dataOffset);
+    const infoElement = findElement(head, ID_INFO, [], segment.dataOffset);
+    if (infoElement) {
+      const infoEnd = Math.min(head.length, infoElement.dataOffset + infoElement.size);
+      for (const field of iterateElements(head, infoElement.dataOffset, infoEnd)) {
+        if (field.id !== ID_DURATION) {
+          continue;
+        }
+        const ticks = readFloat(head, field.dataOffset, field.size);
+        if (ticks !== null && ticks > 0) {
+          info.durationSeconds = (ticks * scale) / 1e9;
+        }
+        break;
+      }
+    }
+    info.startTimeSeconds = await this.#firstClusterSeconds(head, segment.dataOffset, scale);
+    return info;
+  }
+
+  /**
+   * `TimestampScale` from Info, or the specification's default.
+   *
+   * @param {Buffer} head
+   * @param {number} segmentDataOffset
+   * @returns {number} Nanoseconds per tick.
+   */
+  static #timestampScaleOf(head, segmentDataOffset) {
+    const infoElement = findElement(head, ID_INFO, [], segmentDataOffset);
+    if (!infoElement) {
+      return DEFAULT_TIMESTAMP_SCALE;
+    }
+    const infoEnd = Math.min(head.length, infoElement.dataOffset + infoElement.size);
+    for (const field of iterateElements(head, infoElement.dataOffset, infoEnd)) {
+      if (field.id === ID_TIMESTAMP_SCALE) {
+        const scale = readUint(head, field.dataOffset, field.size);
+        return scale > 0 ? scale : DEFAULT_TIMESTAMP_SCALE;
+      }
+    }
+    return DEFAULT_TIMESTAMP_SCALE;
+  }
+
+  /**
+   * The timestamp of the first Cluster, in seconds.
+   *
+   * Tried in the head window first, because a muxer writes the first cluster
+   * straight after Tracks and both usually fit; a file whose Tracks element is
+   * large enough to push it out is answered from the SeekHead instead, with one
+   * short read at the position it names.
+   *
+   * @param {Buffer} head
+   * @param {number} segmentDataOffset
+   * @param {number} scale - Nanoseconds per tick.
+   * @returns {Promise<number | null>} Null when no cluster could be read.
+   */
+  async #firstClusterSeconds(head, segmentDataOffset, scale) {
+    /**
+     * @param {Buffer} buffer
+     * @param {number} dataOffset
+     * @param {number} end
+     * @returns {number | null}
+     */
+    const timestampIn = (buffer, dataOffset, end) => {
+      for (const field of iterateElements(buffer, dataOffset, end)) {
+        if (field.id === ID_TIMESTAMP) {
+          const ticks = readUint(buffer, field.dataOffset, field.size);
+          return Number.isFinite(ticks) ? (ticks * scale) / 1e9 : null;
+        }
+        // Timestamp is written before any frame. Stopping at the first one keeps
+        // this from walking a cluster's whole payload, which is megabytes and
+        // usually not in the buffer at all.
+        if (field.id === ID_SIMPLE_BLOCK || field.id === ID_BLOCK_GROUP) {
+          return null;
+        }
+      }
+      return null;
+    };
+
+    for (const element of iterateElements(head, segmentDataOffset, head.length)) {
+      if (element.id !== ID_CLUSTER) {
+        continue;
+      }
+      return timestampIn(head, element.dataOffset, Math.min(head.length, element.dataOffset + element.size));
+    }
+
+    const position = MatroskaContainer.#seekPositionOf(head, segmentDataOffset, ID_CLUSTER);
+    if (position === null) {
+      return null;
+    }
+    const at = segmentDataOffset + position;
+    if (at >= this.fileSize) {
+      return null;
+    }
+    const chunk = await this.readRange(at, Math.min(this.fileSize - 1, at + CLUSTER_PROBE_BYTES - 1));
+    if (!chunk) {
+      return null;
+    }
+    for (const element of iterateElements(chunk, 0, chunk.length)) {
+      if (element.id !== ID_CLUSTER) {
+        continue;
+      }
+      return timestampIn(chunk, element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
+    }
+    return null;
+  }
+
+  /**
+   * Where the SeekHead says an element lives, relative to the Segment's payload.
+   *
+   * @param {Buffer} head
+   * @param {number} segmentDataOffset
+   * @param {number} wantedId
+   * @returns {number | null}
+   */
+  static #seekPositionOf(head, segmentDataOffset, wantedId) {
+    const seekHead = findElement(head, ID_SEEK_HEAD, [], segmentDataOffset);
+    if (!seekHead) {
+      return null;
+    }
+    const seekHeadEnd = Math.min(head.length, seekHead.dataOffset + seekHead.size);
+    for (const seek of iterateElements(head, seekHead.dataOffset, seekHeadEnd)) {
+      if (seek.id !== ID_SEEK) {
+        continue;
+      }
+      const seekEnd = Math.min(seekHeadEnd, seek.dataOffset + seek.size);
+      let targetId = null;
+      let position = null;
+      for (const field of iterateElements(head, seek.dataOffset, seekEnd)) {
+        if (field.id === ID_SEEK_ID) {
+          targetId = readUint(head, field.dataOffset, field.size);
+        } else if (field.id === ID_SEEK_POSITION) {
+          position = readUint(head, field.dataOffset, field.size);
+        }
+      }
+      if (targetId === wantedId && position !== null) {
+        return position;
+      }
+    }
+    return null;
+  }
+
   async readTracks() {
     const head = await this.readRange(0, Math.min(HEAD_BYTES - 1, this.fileSize - 1));
     if (!head || !isMatroska(head)) return [];