@torrent-tv/proxy 2.101.43 → 2.102.1

package/bin/cli.js

@@ -406,7 +406,8 @@ try {
     // Late-bound for the same reason: what the connections carry beyond the
     // film is counted by the data-channel handler, built further down.
     serviceShare: () => dataChannelHandler?.serviceShare?.() ?? null,
-    onStateChanged: () => void stateReporter.changed()
+    onStateChanged: () => void stateReporter.changed(),
+    onChaptersChanged: (event) => dataChannelHandler?.publishChaptersChanged(event)
   });
   app = started.app;
   actualPort = started.port;

package/package.json

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

package/routes/api/sources/chapters/get.js

@@ -0,0 +1,8 @@
+/** Snapshot only; chapter discovery never delays playback preparation. */
+export function handleApiSourceChaptersGet(req, reply, { chapterController }) {
+  const sourceKey = String(req.params?.sourceKey ?? "");
+  const rawIndex = req.query?.fileIndex;
+  const fileIndex = typeof rawIndex === "string" && /^\d+$/.test(rawIndex) ? Number(rawIndex) : NaN;
+  const result = chapterController.get({ sourceKey, fileIndex });
+  return reply.header("Cache-Control", "no-store").code(result.status).send(result.body);
+}

package/server.js

@@ -12,6 +12,7 @@ import fastifyHelmet from "@fastify/helmet";
 import getPort from "get-port";
 import { createRequire } from "node:module";
 import { performance } from "node:perf_hooks";
+import { SourceWaitTrace } from "./utils/wait-trace.js";
 import { handleHealthGet } from "./routes/health/get.js";
 import { handleMediaGet } from "./routes/media/get.js";
 import { ProbeRequests } from "./services/media/ProbeRequests.js";
@@ -31,6 +32,9 @@ import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
 import { handleApiSourceFingerprintGet } from "./routes/api/sources/fingerprint/get.js";
 import { handleApiSourceContainerMetadataGet } from "./routes/api/sources/container-metadata/get.js";
 import { handleApiSourceCoverGet } from "./routes/api/sources/cover/get.js";
+import { handleApiSourceChaptersGet } from "./routes/api/sources/chapters/get.js";
+import { ChapterOrchestrator } from "./services/media/ChapterOrchestrator.js";
+import { ChapterController } from "./services/server/controllers/ChapterController.js";
 import { handleApiSourceWarmPost } from "./routes/api/sources/warm/post.js";
 import { handleApiSourceViewerPost } from "./routes/api/sources/viewer/post.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
@@ -127,7 +131,7 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
  */
 export async function startProxyServer({
-  host, port, transcodeAudio, ffmpegBin, memoryBytes, segmentFormat, stateDir, onSubtitleCues, diagnostics, budgetPolicy,
+  host, port, transcodeAudio, ffmpegBin, memoryBytes, segmentFormat, stateDir, onSubtitleCues, onChaptersChanged, diagnostics, budgetPolicy,
   deliverySink = false,
   // Whether a memory high-water earns a heap snapshot (`--heap-snapshots`).
   heapSnapshots = false,
@@ -154,6 +158,8 @@ export async function startProxyServer({
     bodyLimit: 256 * 1024 * 1024 // 256 MB
   });
   const forwardedSessionResponseStarts = new WeakMap();
+  const waitTrace = new SourceWaitTrace({ emit: value => logger.info(`[wait-trace] ${JSON.stringify(value)}`) });
+  waitTrace.install(app);
   const logForwardedSessionResponseStage = (stage, req) => {
     const startedAt = forwardedSessionResponseStarts.get(req);
     const requestId = req.headers["x-ttv-forwarded-request-id"];
@@ -172,7 +178,7 @@ export async function startProxyServer({
   await app.register(fastifyCors, {
     origin: true,
     methods: ["GET", "POST", "OPTIONS"],
-    allowedHeaders: ["Content-Type", "Range"]
+    allowedHeaders: ["Content-Type", "Range", "X-Ttv-Wait-Trace", "X-Ttv-Wait-Attempt", "X-Ttv-Wait-Operation"]
   });
 
   // Allow browser requests from an HTTPS page to this private-network proxy
@@ -217,6 +223,7 @@ export async function startProxyServer({
   // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
   // adapter keeps TorrentPool's interface, so nothing downstream changed.
   const torrentPool = new WorkerTorrentPool({
+    onObserved: fields => waitTrace.source(fields.sourceKey, "torrent-ready", fields),
     memoryBytes,
     stateDir,
     heapSnapshots,
@@ -224,6 +231,7 @@ export async function startProxyServer({
     onSourceForgotten: ({ sourceKey }) => {
       sourcePreparation?.forget(sourceKey);
       mediaReads.forget(sourceKey);
+      chapters.forget(sourceKey);
       probeReads.forget(sourceKey);
       subtitles.forget(sourceKey);
       keyframeTables.forget(sourceKey);
@@ -246,6 +254,8 @@ export async function startProxyServer({
     // only once the worker thread is up and a piece has verified, which is long
     // after the declarations below have run.
     onPiecesArrived: ({ sourceKey, fileIndexes, arrived }) => {
+      waitTrace.source(sourceKey, "held-bytes-changed", { fileIndexes, arrived: arrived?.slice?.(0, 32),
+        arrivedCount: arrived?.length });
       for (const fileIndex of fileIndexes) {
         mediaReads.bytesChanged(sourceKey, fileIndex);
         probeReads.bytesChanged(sourceKey, fileIndex);
@@ -382,6 +392,24 @@ export async function startProxyServer({
    * @param {object} [known] - The torrent handle when the caller already has it.
    * @returns {Promise<import("./services/media/SubtitleCues.js").HeldFile | null>}
    */
+  const chapters = new ChapterOrchestrator({
+    containers: containerOrchestrator,
+    subscribe: (sourceKey, fileIndex, listener) => mediaReads.subscribe(sourceKey, fileIndex, listener),
+    withdraw: (sourceKey, fileIndex) => {
+      mediaReads.retain(sourceKey, fileIndex, (_params, statement) => statement !== "chapters");
+      void downloadMaps.withdrawMetadata(sourceKey, fileIndex, "chapters").catch(error => logger.warn(`chapter demand withdrawal failed: ${error.message}`));
+    },
+    failed: (error) => logger.warn(`chapter request failed: ${error.message}`),
+    onChanged: (event) => onChaptersChanged?.(event),
+    fileFor: async (sourceKey, fileIndex) => {
+      if (!sourceRegistry.get(sourceKey)) return null;
+      const torrent = torrentPool.knownTorrent(sourceKey);
+      const file = torrent?.files?.[fileIndex];
+      if (!file) return torrent ? { invalid: true } : null;
+      return containerOver({ sourceKey, fileIndex });
+    }
+  });
+  const chapterController = new ChapterController({ sourceRegistry, chapters });
   const heldFileFor = async (sourceKey, fileIndex, known = null) => {
     let torrent = known;
     if (!torrent) {
@@ -849,6 +877,7 @@ export async function startProxyServer({
         } }),
       label: String(file.name ?? ""),
       fileOffset: file.offset,
+      onObserved: fields => waitTrace.source(sourceKey, "container-read", { fileIndex, requestId, ...fields }),
       onTracks: (tracks) => contentsOf(torrent).noteVideo(fileIndex, tracks.some((track) => track.type === "video")),
       onReadStart: () => ({ storage: mediaReads.revision(sourceKey, fileIndex), memory: mediaReads.memoryRevision(), demand: downloadMaps.epoch(sourceKey, fileIndex) }),
       onReadResult: async (statement, result, revision) => {
@@ -859,7 +888,9 @@ export async function startProxyServer({
             format: containerOrchestrator.known(sourceKey, fileIndex)?.formatName ?? "unrecognised" });
         }
         const finished = mediaReads.record(params, statement, result, revision.storage, revision.memory);
-        await downloadMaps.metadata({ sourceKey, fileIndex, statement: requestId ? `${statement}:${requestId}` : statement, result,
+        if (statement === "chapters" && result.passive) await downloadMaps.withdrawMetadata(sourceKey, fileIndex, statement);
+        else await downloadMaps.metadata({ sourceKey, fileIndex, statement: requestId ? `${statement}:${requestId}` : statement, result,
+          ...(statement === "chapters" ? { priority: 1, urgent: false, deadlineAt: null } : {}),
           ...(demand ? { priority: demand.priority, urgent: demand.urgent, deadlineAt: demand.deadlineAt, interval: demand, leadSeconds: demand.leadSeconds ?? 0 } : {}) });
         if (finished && result.kind === "result") {
           void downloadMaps.refresh(sourceKey, fileIndex).catch(error =>
@@ -894,6 +925,7 @@ export async function startProxyServer({
   });
   let sourcePreparation;
   const outputParts = wireOutputs({
+    observeWait: (sourceKey, event, fields) => waitTrace.source(sourceKey, event, fields),
     pinnedPreset,
     indexMemory,
     serviceShare,
@@ -1429,6 +1461,9 @@ export async function startProxyServer({
       probeReads.needs(requestId, start, end);
     }
   }));
+  app.get("/api/sources/:sourceKey/chapters", async (req, reply) =>
+    handleApiSourceChaptersGet(req, reply, { chapterController })
+  );
   app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
   // Off unless --delivery-sink was given; see the route for why it exists.
   app.get("/api/delivery-sink", async (req, reply) =>

package/services/encode/EncodeRuns.js

@@ -1106,6 +1106,7 @@ export class EncodeRuns {
     // proven, and it is cleared up when the run ends.
     // Told when this run closes its first piece; see the next stretch below.
     let atFirstPiece = null;
+    const observedStart = performance.now();
     const run = new EncodeRun({
       address: session.outputKey ?? session.id,
       encoder: this.#host.videoEncoder,
@@ -1196,6 +1197,10 @@ export class EncodeRuns {
           { code: "ERR_INCOMPLETE_MEDIA" });
         const published = this.#host.segmentFiles.publish(address, name, session.segmentFormat, { mediaRanges, bytes });
         if (!published) throw new Error(`Closed piece #${index} could not be stored.`);
+        if (index === safeIndex) this.#host.observeWait?.(session.file.sourceKey, "first-piece-published", {
+          output: address, segment: index, startedAt: observedStart, endedAt: performance.now(),
+          encoderWrittenAfterMs: Number.isFinite(writtenAt) ? writtenAt - run.startedAt : null,
+          namedAfterMs: Number.isFinite(namedAt) ? namedAt - run.startedAt : null });
         this.#leadingByOutput.get(address)?.delete(index);
         // WHERE A LATE PIECE'S TIME WENT: the encoder writing it, this process
         // getting to its name, or its publication waiting for the file after

package/services/media/ChapterOrchestrator.js

@@ -0,0 +1,104 @@
+/** Selected-file snapshots; retries belong to the shared media request queue. */
+import { chapterResult } from "./container/chapters.js";
+import { IndexMemoryUnavailable } from "./container/memory-unavailable.js";
+import { randomUUID } from "node:crypto";
+
+export class ChapterOrchestrator {
+  constructor({ containers, fileFor, subscribe = () => () => {}, withdraw = () => {}, now = Date.now, onChanged = () => {}, failed = () => {} }) {
+    Object.assign(this, { containers, fileFor, subscribe, withdraw, now, onChanged, failed });
+    this.files = new Map();
+  }
+
+  get(sourceKey, fileIndex) {
+    for (const old of this.files.values()) if (old.expires < this.now()) this.forget(old.sourceKey, old.fileIndex);
+    const key = `${sourceKey}:${fileIndex}`;
+    let entry = this.files.get(key);
+    if (!entry) {
+      entry = { sourceKey, fileIndex, generation: randomUUID(), reading: null, requested: false, bytes: 0 };
+      entry.dispose = () => {
+        entry.allocation?.release(entry.bytes + (entry.candidate?.length ?? 0));
+        entry.allocation?.dispose();
+        entry.bytes = 0;
+        entry.candidate = null;
+        entry.buffer = null;
+      };
+      this.files.set(key, entry);
+      entry.unsubscribe = this.subscribe(sourceKey, fileIndex, (event) => {
+        if (event.kind === "cancelled") this.forget(sourceKey, fileIndex);
+        else if (!entry.requested && event.kind === "bytes-changed") this.warm(entry);
+      });
+    }
+    entry.expires = this.now() + 3600000;
+    if (!entry.requested) this.warm(entry);
+    return { ...(entry.buffer ? JSON.parse(entry.buffer.toString("utf8")) : chapterResult("pending")), sourceKey, fileIndex,
+      generation: entry.generation, revision: entry.revision ?? 0 };
+  }
+
+  update(entry, result) {
+    if (this.files.get(`${entry.sourceKey}:${entry.fileIndex}`) !== entry) return;
+    let answer;
+    if (result.value?.version === 1) answer = result.value;
+    else if (result.kind === "needs-ranges") answer = chapterResult("pending", { missingRange: result.ranges[0] });
+    else if (result.kind === "needs-memory") answer = chapterResult("pending", { resource: "memory", requiredBytes: result.bytes });
+    else if (result.reason === "request-obsolete") return;
+    else if (["format-not-supported", "chapter-not-supported"].includes(result.reason)) {
+      answer = chapterResult("unsupported", { reason: result.chapterReason ?? result.reason });
+    } else answer = chapterResult("error", { reason: result.message ?? result.reason });
+    const buffer = result.value && entry.candidate ? entry.candidate : Buffer.from(JSON.stringify(answer));
+    const charged = buffer === entry.candidate ? buffer.length : 0;
+    if (entry.candidate && !charged) entry.allocation?.release(entry.candidate.length);
+    entry.candidate = null;
+    if (entry.buffer?.equals(buffer)) {
+      entry.allocation?.release(charged);
+      return;
+    }
+    entry.allocation?.release(entry.bytes);
+    entry.bytes = charged;
+    entry.buffer = buffer;
+    entry.revision = (entry.revision ?? 0) + 1;
+    this.onChanged({ sourceKey: entry.sourceKey, fileIndex: entry.fileIndex, revision: entry.revision });
+  }
+
+  warm(entry) {
+    if (entry.reading) return;
+    entry.reading = (async () => {
+      const params = await this.fileFor(entry.sourceKey, entry.fileIndex);
+      if (!params || this.files.get(`${entry.sourceKey}:${entry.fileIndex}`) !== entry) return;
+      entry.requested = true;
+      if (params.invalid) return this.update(entry, { kind: "terminal", reason: "file-index-not-found" });
+      const publish = params.onReadResult;
+      entry.allocation ??= params.packetMemory?.forRecord?.(entry, "declarations");
+      params.acceptChapterResult = (value) => {
+        const serialized = JSON.stringify(value);
+        const bytes = Buffer.byteLength(serialized);
+        if (entry.allocation?.reserve(bytes) === false) throw new IndexMemoryUnavailable(bytes);
+        entry.candidate = Buffer.from(serialized);
+      };
+      params.isCurrent = () => {
+        if (entry.expires <= this.now()) this.forget(entry.sourceKey, entry.fileIndex);
+        return this.files.get(`${entry.sourceKey}:${entry.fileIndex}`) === entry;
+      };
+      params.onReadResult = async (statement, result, revision) => {
+        await publish?.(statement, result, revision);
+        this.update(entry, result);
+      };
+      await this.containers.inspect(params, "chapters");
+    })().catch((error) => {
+      this.failed(error);
+      if (this.files.get(`${entry.sourceKey}:${entry.fileIndex}`) === entry) {
+        entry.requested = false;
+        this.update(entry, { kind: "terminal", reason: "chapter-request-failed", message: error.message });
+      }
+    }).finally(() => { entry.reading = null; });
+  }
+
+  forget(sourceKey, fileIndex) {
+    for (const [key, entry] of this.files) {
+      if (entry.sourceKey !== sourceKey || (fileIndex !== undefined && entry.fileIndex !== fileIndex)) continue;
+      this.files.delete(key);
+      entry.dispose();
+      entry.unsubscribe?.();
+      this.withdraw(entry.sourceKey, entry.fileIndex);
+    }
+  }
+}

package/services/media/ContainerOrchestrator.js

@@ -20,6 +20,7 @@ import { BytesUnavailable, isUnavailable, strictReader } from "./container/unava
 import { OSHASH_EDGE_BYTES, hasOshash, oshash } from "./oshash.js";
 import { IndexMemoryUnavailable } from "./container/memory-unavailable.js";
 import { OutsideReadableEdges } from "./container/work-tags.js";
+import { ChapterUnsupported } from "./container/chapters.js";
 import { logger } from "../../utils/logger.js";
 
 /**
@@ -139,7 +140,7 @@ export class ContainerOrchestrator {
 
   /** Read one statement without converting missing bytes into an empty answer. */
   async inspect(params, statement = "tracks") {
-    if (!["container", "tracks", "media-info", "keyframes", "packets", "source-navigation", "source-ranges", "fingerprint", "work-tags", "cover"].includes(statement)) {
+    if (!["container", "tracks", "media-info", "keyframes", "packets", "source-navigation", "source-ranges", "fingerprint", "work-tags", "cover", "chapters"].includes(statement)) {
       throw new TypeError(`Unknown media statement: ${statement}`);
     }
     const key = `${params.sourceKey}:${params.fileIndex}`;
@@ -155,13 +156,17 @@ export class ContainerOrchestrator {
     // table of the whole film it does not use (r38, torrent-tv/meta#178).
     const aside = this.#answersWithoutReading(key, statement);
     const previous = aside ? Promise.resolve() : this.#reads.get(key) ?? Promise.resolve();
-    const askedAt = Date.now();
+    const askedAt = performance.now();
     const reading = previous.catch(() => undefined).then(async () => {
       if (!isCurrent()) return { result: { kind: "terminal", reason: "request-obsolete", requestId: params.requestId } };
-      const startedAt = Date.now();
+      const startedAt = performance.now();
       const revision = params.onReadStart?.(statement);
       const result = await this.#inspectRead({ ...params, isCurrent }, statement);
-      params.onTimed?.(statement, startedAt - askedAt, Date.now() - startedAt);
+      const endedAt = performance.now();
+      params.onTimed?.(statement, startedAt - askedAt, endedAt - startedAt);
+      if (statement !== "source-ranges" || endedAt - askedAt >= 10) params.onObserved?.({ statement, askedAt,
+        startedAt, endedAt, queuedMs: startedAt - askedAt, readMs: endedAt - startedAt, cached: aside,
+        result: result.kind, reason: result.reason, ranges: result.ranges });
       return { result, revision };
     });
     if (!aside) this.#reads.set(key, reading);
@@ -232,11 +237,20 @@ export class ContainerOrchestrator {
         value = await container.readPacketIndex(params.packetInterval, { isCurrent: params.isCurrent, account: params.walkAccount });
         if (value === null) return { kind: "terminal", reason: "request-obsolete", requestId };
         await value?.prepareAudioDependencies?.(params.packetInterval, container.readRange);
+      } else if (statement === "chapters") {
+        value = await container.readChapters({ read: params.readHeld ?? params.readRange,
+          isCurrent: params.isCurrent,
+          ranges: params.heldRanges ? await params.heldRanges() : undefined });
+        if (params.isCurrent?.() === false) return { kind: "terminal", reason: "request-obsolete", requestId };
+        params.acceptChapterResult?.(value);
+        if (!value.complete && value.pending) return { kind: "needs-ranges", ranges: [[value.pending.start, value.pending.end]], value, requestId };
       } else {
         throw new TypeError(`Unknown media statement: ${statement}`);
       }
       return { kind: "result", value, requestId };
     } catch (error) {
+      if (statement === "chapters" && params.isCurrent?.() === false) return { kind: "terminal", reason: "request-obsolete", requestId };
+      if (error instanceof ChapterUnsupported) return { kind: "terminal", reason: "chapter-not-supported", chapterReason: error.message, requestId };
       if (error instanceof IndexMemoryUnavailable) {
         const result = { kind: "needs-memory", bytes: error.bytes, requestId };
         logger.info(`media request=${requestId} needs memory=${error.bytes}`);
@@ -248,7 +262,8 @@ export class ContainerOrchestrator {
         return { kind: "terminal", reason: "outside-edges", requestId };
       }
       if (isUnavailable(error)) {
-        const result = { kind: "needs-ranges", ranges: [[error.start, error.end]], requestId };
+        const result = { kind: "needs-ranges", ranges: [[error.start, error.end]], requestId,
+          ...(error.passive ? { passive: true } : {}) };
         logger.info(`media request=${requestId} needs bytes=${error.start}-${error.end}`);
         return result;
       }

package/services/media/container/Container.js

@@ -14,6 +14,7 @@
 
 import { isUnavailable, strictReader } from "./unavailable.js";
 import { textList } from "./work-tags.js";
+import { chapterResult } from "./chapters.js";
 
 /**
  * What one file declares about itself. Every field is either a value the
@@ -29,6 +30,10 @@ import { textList } from "./work-tags.js";
  */
 
 export class Container {
+  /** Read chapters only through the caller's non-fetching held-byte reader. */
+  async readChapters(_held) {
+    return chapterResult("unsupported", { reason: `chapter-container:${this.formatName}` });
+  }
   /**
    * One strict available-byte reader and one container per
    * file — the one `ContainerOrchestrator` keeps.

package/services/media/container/MatroskaContainer.js

@@ -34,6 +34,7 @@
 
 import { FFMPEG_STREAM_SEARCH_SECONDS } from "./ffmpeg-stream-search.js";
 import { Container } from "./Container.js";
+import { readMatroskaChapters } from "./matroska-chapters.js";
 import { VideoTrack } from "../tracks/VideoTrack.js";
 import { h264Configuration } from "./h264-configuration.js";
 import { hevcConfiguration } from "./hevc-configuration.js";
@@ -144,6 +145,9 @@ function readString(buf, el) {
  */
 
 export class MatroskaContainer extends Container {
+  async readChapters(held) {
+    return readMatroskaChapters(this, held);
+  }
   /** @type {Buffer | null} */
   #declarations = null;
 

package/services/media/container/Mp4Container.js

@@ -18,6 +18,7 @@
 
 import { Container } from "./Container.js";
 import { RetainedBytes } from "./RetainedBytes.js";
+import { readMp4Chapters } from "./mp4-chapters.js";
 import { VideoTrack } from "../tracks/VideoTrack.js";
 import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_FORMATS_MP4 } from "../tracks/TextSubtitleTrack.js";
@@ -265,6 +266,9 @@ function decoderSpecificInfoOf(buf, start, end) {
 
 export class Mp4Container extends Container {
   #tracks = null;
+  async readChapters(held) {
+    return readMp4Chapters(this, held);
+  }
   get formatName() {
     return "mp4";
   }

package/services/media/container/chapters.js

@@ -0,0 +1,104 @@
+/** File chapter declarations and bounded, non-fetching byte access. */
+import { BytesUnavailable, strictReader } from "./unavailable.js";
+
+export class ChapterUnsupported extends Error {
+  constructor(reason) { super(reason); this.name = "ChapterUnsupported"; }
+}
+
+export function chapterResult(state, extra = {}) {
+  return { version: 1, state, complete: state !== "pending", selectedEditionId: null,
+    editions: [], sections: [], tailContent: "unknown", ...extra };
+}
+
+/** Limits bound hostile metadata, not the media file's size. */
+export const CHAPTER_LIMITS = { entries: 4096, depth: 64, textBytes: 8192, readBytes: 8 * 1024 * 1024, elements: 100000 };
+
+export class ChapterBytes {
+  constructor(held, size) {
+    this.held = held;
+    this.size = size;
+    this.read = strictReader(held.read, size);
+    this.used = 0;
+    this.elements = 0;
+    this.window = null;
+    this.windowAt = 0;
+  }
+
+  async bytes(start, length) {
+    if (this.held.isCurrent?.() === false) throw new Error("Chapter request was withdrawn");
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(length) || start < 0 || length < 0 || start + length > this.size) {
+      throw new Error("Chapter byte range is outside the file");
+    }
+    if (length === 0) return Buffer.alloc(0);
+    if (this.window && start >= this.windowAt && start + length <= this.windowAt + this.window.length) {
+      return this.window.subarray(start - this.windowAt, start - this.windowAt + length);
+    }
+    const range = this.held.ranges?.find(([first, last]) => first <= start && last >= start + length - 1);
+    if (this.held.ranges && !range) {
+      const error = new BytesUnavailable(start, start + length - 1, 0);
+      error.passive = this.passiveMissing === true;
+      throw error;
+    }
+    // Header traversal must not copy adjacent video payloads into the metadata budget.
+    const span = length;
+    this.used += span;
+    if (this.used > CHAPTER_LIMITS.readBytes) throw new ChapterUnsupported("chapter-read-budget");
+    if (++this.elements % 64 === 0) await new Promise((resolve) => setImmediate(resolve));
+    try { this.window = await this.read(start, start + span - 1); }
+    catch (error) {
+      if (error?.name === "BytesUnavailable") error.passive = this.passiveMissing === true;
+      throw error;
+    }
+    this.windowAt = start;
+    return this.window.subarray(0, length);
+  }
+
+  step(depth = 0) {
+    if (this.held.isCurrent?.() === false) throw new Error("Chapter request was withdrawn");
+    if (++this.elements > CHAPTER_LIMITS.elements || depth > CHAPTER_LIMITS.depth) {
+      throw new ChapterUnsupported("chapter-structure-budget");
+    }
+  }
+}
+
+export function chapterSeconds(value, units) {
+  const seconds = Number(value / BigInt(units)) + Number(value % BigInt(units)) / units;
+  if (!Number.isFinite(seconds) || seconds > Number.MAX_SAFE_INTEGER) throw new Error("Chapter time is outside the supported numeric range");
+  return seconds;
+}
+
+export function classifyChapter(titles) {
+  const types = new Set();
+  for (const { text } of titles) {
+    const title = text.trim().toLowerCase();
+    if (/^(op(?:ening)?|opening credits|opening theme|オープニング)$/.test(title)) types.add("opening");
+    if (/^(ed|ending|ending theme|エンディング)$/.test(title)) types.add("ending");
+    if (/^(credits|end credits|closing credits|титры)$/.test(title)) types.add("credits");
+    if (/^(post[- ]credits?(?: scene)?|after[- ]credits?(?: scene)?)$/.test(title)) types.add("post-credits");
+  }
+  const inferred = types.size === 1;
+  return { type: inferred ? [...types][0] : "chapter",
+    classification: inferred ? "title-hint" : "unclassified",
+    confidence: inferred ? "unconfirmed" : "declared" };
+}
+
+/** Build navigation intervals without promoting inferred ends to file facts. */
+export function navigationSections(edition, duration = null) {
+  const out = [];
+  const walk = (chapters) => {
+    for (const chapter of chapters) {
+      if (chapter.enabled && !chapter.hidden) {
+        const next = chapters.filter((other) => other.startSeconds > chapter.startSeconds)
+          .reduce((end, other) => Math.min(end, other.startSeconds), Infinity);
+        const inferred = Number.isFinite(next) ? next : duration;
+        out.push({ ...chapter, children: undefined, ...classifyChapter(chapter.titles),
+          displayEndSeconds: chapter.endSeconds ?? inferred,
+          endSource: chapter.endSeconds !== null ? "declared" : inferred !== null ? "navigation" : "unknown",
+          automaticSkipAllowed: false, evidence: "file-chapter" });
+      }
+      walk(chapter.children);
+    }
+  };
+  walk(edition.chapters);
+  return out.sort((a, b) => a.startSeconds - b.startSeconds || a.order - b.order);
+}

package/services/media/container/matroska-chapters.js

@@ -0,0 +1,213 @@
+/** RFC 9559 §§5.1.7, 6.6, 11.1.1 and 20: chapter metadata only. */
+import { readVint } from "./ebml-reader.js";
+import { ChapterBytes, ChapterUnsupported, CHAPTER_LIMITS, chapterResult, chapterSeconds, navigationSections } from "./chapters.js";
+
+const SEGMENT = 0x18538067;
+const CHAPTERS = 0x1043a770;
+const SEEK_HEAD = 0x114d9b74;
+const CLUSTER = 0x1f43b675;
+const TOP_LEVEL = new Set([SEEK_HEAD, CHAPTERS, CLUSTER, 0x1549a966, 0x1654ae6b, 0x1c53bb6b, 0x1941a469, 0x1254c367]);
+
+async function header(reader, at, limit) {
+  reader.step();
+  const vint = async (position, marker) => {
+    const first = (await reader.bytes(position, 1))[0];
+    let n = 1;
+    while (n <= 8 && !(first & (0x80 >> (n - 1)))) n++;
+    if (n > (marker ? 4 : 8) || position + n > limit) throw new Error("Invalid chapter EBML header");
+    const bytes = await reader.bytes(position, n);
+    const value = readVint(bytes, 0, marker);
+    const mask = 2 ** (8 - n) - 1;
+    return { ...value, unknown: !marker && (bytes[0] & mask) === mask && bytes.subarray(1).every((byte) => byte === 255) };
+  };
+  const id = await vint(at, true);
+  const size = await vint(at + id.length, false);
+  const dataOffset = at + id.length + size.length;
+  const unknown = size.unknown;
+  const end = unknown ? null : dataOffset + size.value;
+  if (!Number.isSafeInteger(dataOffset) || (!unknown && (!Number.isSafeInteger(end) || end > limit))) throw new Error("Chapter element exceeds its parent");
+  return { id: id.value, at, dataOffset, end, size: unknown ? null : size.value };
+}
+
+async function* children(reader, master, depth = 0) {
+  reader.step(depth);
+  if (master.end === null) throw new Error("Unknown size is not valid for this chapter element");
+  for (let at = master.dataOffset; at < master.end;) {
+    const child = await header(reader, at, master.end);
+    if (child.end === null) throw new Error("Unknown-sized chapter child");
+    yield child;
+    at = child.end;
+  }
+}
+
+async function integer(reader, field, fallback = null) {
+  if (field.size > 8) throw new Error("Chapter integer exceeds eight bytes");
+  if (field.size === 0) return fallback;
+  const bytes = await reader.bytes(field.dataOffset, field.size);
+  let value = 0n;
+  for (const byte of bytes) value = value * 256n + BigInt(byte);
+  return value;
+}
+
+async function text(reader, field) {
+  if (field.size > CHAPTER_LIMITS.textBytes) throw new ChapterUnsupported("chapter-title-budget");
+  return new TextDecoder("utf-8", { fatal: true }).decode(await reader.bytes(field.dataOffset, field.size)).replace(/\0+$/, "");
+}
+
+async function display(reader, field, depth) {
+  let value = null;
+  const languages = [], bcp47 = [], countries = [];
+  for await (const part of children(reader, field, depth)) {
+    if (part.id === 0x85) value = await text(reader, part);
+    if (part.id === 0x437c) languages.push(await text(reader, part));
+    if (part.id === 0x437d) bcp47.push(await text(reader, part));
+    if (part.id === 0x437e) countries.push(await text(reader, part));
+  }
+  if (value === null) throw new Error("ChapterDisplay has no ChapString");
+  return { text: value, languages: bcp47.length ? bcp47 : languages.length ? languages : ["eng"],
+    countries: bcp47.length ? [] : countries, languageSource: bcp47.length ? "bcp47" : "matroska" };
+}
+
+async function atom(reader, field, editionId, parentId, count, depth) {
+  if (++count.value > CHAPTER_LIMITS.entries) throw new ChapterUnsupported("chapter-count-budget");
+  let uid = null, start = null, end = null, linkedSegment = null, linkedEdition = null;
+  let hidden = false, enabled = true;
+  const titles = [], childFields = [], trackNumbers = [], processCodecs = [];
+  for await (const part of children(reader, field, depth)) {
+    if (part.id === 0x73c4) uid = await integer(reader, part);
+    if (part.id === 0x91) start = await integer(reader, part, 0n);
+    if (part.id === 0x92) end = await integer(reader, part, 0n);
+    if (part.id === 0x98) hidden = (await integer(reader, part, 0n)) !== 0n;
+    if (part.id === 0x4598) enabled = (await integer(reader, part, 1n)) !== 0n;
+    if (part.id === 0x6e67) {
+      if (part.size !== 16) throw new Error("ChapterSegmentUUID must contain sixteen bytes");
+      linkedSegment = (await reader.bytes(part.dataOffset, part.size)).toString("hex");
+    }
+    if (part.id === 0x6ebc) linkedEdition = String(await integer(reader, part));
+    if (part.id === 0x80) titles.push(await display(reader, part, depth + 1));
+    if (part.id === 0xb6) childFields.push(part);
+    if (part.id === 0x8f) {
+      for await (const track of children(reader, part, depth + 1)) if (track.id === 0x89) trackNumbers.push(String(await integer(reader, track)));
+    }
+    if (part.id === 0x6944) {
+      let codec = 0n;
+      for await (const command of children(reader, part, depth + 1)) if (command.id === 0x6955) codec = await integer(reader, command, 0n);
+      processCodecs.push(String(codec));
+    }
+  }
+  if (uid === null || uid === 0n || start === null) throw new Error("ChapterAtom requires a nonzero ChapterUID and ChapterTimeStart");
+  if (end !== null && end < start) throw new Error("ChapterTimeEnd precedes ChapterTimeStart");
+  const id = `${editionId}:chapter:${uid}`;
+  const chapter = { id, uid: String(uid), editionId, parentId, order: count.value,
+    startNanoseconds: String(start), endNanoseconds: end === null ? null : String(end),
+    startSeconds: chapterSeconds(start, 1e9), endSeconds: end === null ? null : chapterSeconds(end, 1e9),
+    hidden, enabled, titles, linkedSegment, linkedEdition, trackNumbers, processCodecs, children: [] };
+  for (const child of childFields) {
+    const nested = await atom(reader, child, editionId, id, count, depth + 1);
+    if (BigInt(nested.startNanoseconds) < start || (end !== null && BigInt(nested.startNanoseconds) > end)) throw new Error("Nested chapter starts outside its parent");
+    chapter.children.push(nested);
+  }
+  return chapter;
+}
+
+async function editionsOf(reader, chapters) {
+  const editions = [], count = { value: 0 };
+  for await (const field of children(reader, chapters)) {
+    if (field.id !== 0x45b9) continue;
+    let uid = null, hidden = false, isDefault = false, ordered = false;
+    const atoms = [];
+    for await (const part of children(reader, field, 1)) {
+      if (part.id === 0x45bc) uid = await integer(reader, part);
+      if (part.id === 0x45bd) hidden = (await integer(reader, part, 0n)) !== 0n;
+      if (part.id === 0x45db) isDefault = (await integer(reader, part, 0n)) !== 0n;
+      if (part.id === 0x45dd) ordered = (await integer(reader, part, 0n)) !== 0n;
+      if (part.id === 0xb6) atoms.push(part);
+    }
+    const id = uid === null ? `matroska:edition-at:${field.at}` : `matroska:edition:${uid}`;
+    const edition = { id, uid: uid === null ? null : String(uid), hidden, isDefault, ordered, chapters: [] };
+    for (const part of atoms) edition.chapters.push(await atom(reader, part, id, null, count, 2));
+    if (!edition.chapters.length) throw new Error("EditionEntry has no ChapterAtom");
+    editions.push(edition);
+  }
+  if (!editions.length) throw new Error("Chapters has no EditionEntry");
+  const ids = new Set();
+  const check = (chapters) => {
+    for (const chapter of chapters) {
+      if (ids.has(chapter.uid)) throw new Error("Duplicate ChapterUID");
+      ids.add(chapter.uid); check(chapter.children);
+    }
+  };
+  for (const edition of editions) check(edition.chapters);
+  return editions;
+}
+
+export async function readMatroskaChapters(container, held) {
+  const reader = new ChapterBytes(held, container.fileSize);
+  let at = 0, segment = null;
+  while (at < reader.size) {
+    const field = await header(reader, at, reader.size);
+    if (field.id === SEGMENT) { segment = field; break; }
+    if (field.end === null) throw new Error("Unknown-sized element before Segment");
+    at = field.end;
+  }
+  if (!segment) throw new Error("Matroska Segment is missing");
+  const limit = segment.end ?? reader.size;
+  const visits = new Set();
+  const seekHeads = [];
+  const seek = async (field) => {
+    if (visits.has(field.at)) return null;
+    visits.add(field.at);
+    for await (const entry of children(reader, field)) {
+      if (entry.id !== 0x4dbb) continue;
+      let id = null, position = null;
+      for await (const part of children(reader, entry)) {
+        if (part.id === 0x53ab) id = await integer(reader, part);
+        if (part.id === 0x53ac) position = await integer(reader, part, 0n);
+      }
+      if (id === null || position === null) throw new Error("Incomplete chapter Seek entry");
+      if (id !== BigInt(CHAPTERS) && id !== BigInt(SEEK_HEAD)) continue;
+      const offset = segment.dataOffset + Number(position);
+      if (!Number.isSafeInteger(offset) || offset < segment.dataOffset || offset >= limit) throw new Error("Chapter SeekPosition is outside Segment");
+      reader.passiveMissing = false;
+      const target = await header(reader, offset, limit);
+      if (BigInt(target.id) !== id) throw new Error("Chapter SeekID does not match its target");
+      if (target.id === CHAPTERS) return target;
+      seekHeads.push(target);
+    }
+    return null;
+  };
+  let chapters = null;
+  let passedCluster = false;
+  at = segment.dataOffset;
+  while (at < limit && !chapters) {
+    // Without a declared location, traversing unavailable media must not
+    // download every Cluster just to discover whether chapters follow it.
+    reader.passiveMissing = passedCluster;
+    const field = await header(reader, at, limit);
+    reader.passiveMissing = false;
+    if (field.id === CHAPTERS) { chapters = field; break; }
+    if (field.id === CLUSTER) passedCluster = true;
+    if (field.id === SEEK_HEAD) {
+      chapters = await seek(field);
+      while (!chapters && seekHeads.length) chapters = await seek(seekHeads.shift());
+      if (chapters) break;
+    }
+    if (field.end !== null) { at = field.end; continue; }
+    if (field.id !== CLUSTER) throw new Error("Unknown-sized non-Cluster element inside Segment");
+    // An unknown-sized Cluster ends at the next Segment-level element (RFC 8794 §6.2).
+    at = field.dataOffset;
+    reader.passiveMissing = true;
+    while (at < limit) {
+      const child = await header(reader, at, limit);
+      if (TOP_LEVEL.has(child.id)) break;
+      if (child.end === null) throw new ChapterUnsupported("unknown-sized-cluster-child");
+      at = child.end;
+    }
+  }
+  if (!chapters) return chapterResult("absent");
+  const editions = await editionsOf(reader, chapters);
+  const selected = editions.find((edition) => edition.isDefault) ?? editions[0];
+  if (selected.ordered) return chapterResult("unsupported", { reason: "ordered-edition-playback", editions, selectedEditionId: selected.id });
+  return chapterResult("available", { editions, selectedEditionId: selected.id,
+    sections: navigationSections(selected, container.mediaInfo?.durationSeconds ?? null) });
+}

package/services/media/container/mp4-chapters.js

@@ -0,0 +1,310 @@
+/** QuickTime Chapter Lists and ISO/IEC 14496-12 sample tables/edit lists. */
+import { isUnavailable } from "./unavailable.js";
+import { ChapterBytes, ChapterUnsupported, CHAPTER_LIMITS, chapterResult, chapterSeconds, navigationSections } from "./chapters.js";
+
+async function box(reader, at, end) {
+  reader.step();
+  const bytes = await reader.bytes(at, 8);
+  let size = bytes.readUInt32BE(0), header = 8;
+  if (size === 1) { size = Number((await reader.bytes(at + 8, 8)).readBigUInt64BE()); header = 16; }
+  if (size === 0) size = end - at;
+  if (!Number.isSafeInteger(size) || size < header || at + size > end) throw new Error("Chapter box exceeds its parent");
+  return { type: bytes.toString("latin1", 4, 8), at, dataOffset: at + header, end: at + size };
+}
+
+async function boxes(reader, start, end) {
+  const result = [];
+  for (let at = start; at < end;) {
+    if (end - at < 8) throw new Error("Truncated chapter box header");
+    const child = await box(reader, at, end);
+    result.push(child);
+    at = child.end;
+  }
+  return result;
+}
+
+const one = (list, type) => list.find((field) => field.type === type);
+async function inside(reader, parent) { return parent ? boxes(reader, parent.dataOffset, parent.end) : []; }
+async function payload(reader, field, count) {
+  if (!field || field.dataOffset + count > field.end) throw new Error("Truncated chapter field");
+  return reader.bytes(field.dataOffset, count);
+}
+async function table(reader, field, width, prefix = 8) {
+  const head = await payload(reader, field, prefix);
+  const count = head.readUInt32BE(prefix - 4);
+  if (count > CHAPTER_LIMITS.entries) throw new ChapterUnsupported("chapter-sample-table-budget");
+  if (field.dataOffset + prefix + width * count !== field.end) throw new Error("Chapter sample table size mismatch");
+  return { head, count, bytes: await reader.bytes(field.dataOffset + prefix, count * width) };
+}
+
+function titleOf(bytes) {
+  if (bytes.length > CHAPTER_LIMITS.textBytes) throw new ChapterUnsupported("chapter-title-budget");
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder("utf-16be", { fatal: true }).decode(bytes.subarray(2));
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return new TextDecoder("utf-16le", { fatal: true }).decode(bytes.subarray(2));
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/\0+$/, "");
+}
+
+const MAC_LANGUAGES = new Map([[0, "eng"], [1, "fra"], [2, "deu"], [3, "ita"],
+  [4, "nld"], [5, "swe"], [6, "spa"], [7, "dan"], [8, "por"], [9, "nor"], [13, "fin"], [32, "rus"]]);
+
+function trackTitle(bytes, format, languageCode) {
+  if (bytes.length > CHAPTER_LIMITS.textBytes) throw new ChapterUnsupported("chapter-title-budget");
+  const bom = bytes.length >= 2 && ((bytes[0] === 0xfe && bytes[1] === 0xff) || (bytes[0] === 0xff && bytes[1] === 0xfe));
+  if (format === "tx3g" || bom || (languageCode >= 0x400 && languageCode !== 0x7fff)) return titleOf(bytes);
+  if (!MAC_LANGUAGES.has(languageCode)) throw new ChapterUnsupported(`chapter-text-encoding:${languageCode}`);
+  return new TextDecoder(languageCode === 32 ? "x-mac-cyrillic" : "macintosh", { fatal: true }).decode(bytes).replace(/\0+$/, "");
+}
+
+function chapter(id, start, end, title, language = "und", order = 0) {
+  return { id, parentId: null, order, startSeconds: start, endSeconds: end,
+    titles: [{ text: title, languages: [language], countries: [], languageSource: "mp4" }], hidden: false, enabled: true, children: [] };
+}
+
+async function nero(reader, field) {
+  const initial = await payload(reader, field, 4);
+  const version = initial[0];
+  if (version > 1) throw new ChapterUnsupported("chpl-version");
+  const prefix = version === 1 ? 9 : 5;
+  const count = (await payload(reader, field, prefix))[prefix - 1];
+  let at = field.dataOffset + prefix;
+  const chapters = [];
+  for (let index = 0; index < count; index++) {
+    if (at + 9 > field.end) throw new Error("Truncated chpl entry");
+    const head = await reader.bytes(at, 9);
+    const time = head.readBigUInt64BE(0), length = head[8];
+    at += 9;
+    if (at + length > field.end) throw new Error("Truncated chpl title");
+    chapters.push({ ...chapter(`mp4:chpl:${index}`, chapterSeconds(time, 10000000), null,
+      titleOf(await reader.bytes(at, length)), "und", index), timeTicks: String(time), timeScale: 10000000 });
+    at += length;
+  }
+  if (at !== field.end) throw new Error("Unexpected bytes after chpl entries");
+  return { id: "mp4:chpl", source: "chpl", ordered: false, chapters };
+}
+
+async function timedHeader(reader, field) {
+  const first = await payload(reader, field, 4);
+  if (first[0] > 1) throw new ChapterUnsupported("mp4-time-header-version");
+  const wide = first[0] === 1;
+  const data = await payload(reader, field, wide ? 32 : 20);
+  const scale = data.readUInt32BE(wide ? 20 : 12);
+  const duration = wide ? data.readBigUInt64BE(24) : BigInt(data.readUInt32BE(16));
+  if (scale === 0) throw new Error("Zero chapter time scale");
+  return { scale, duration, wide };
+}
+
+async function trackInfo(reader, field) {
+  const parts = await inside(reader, field);
+  const tkhd = one(parts, "tkhd");
+  const first = await payload(reader, tkhd, 4);
+  if (first[0] > 1) throw new ChapterUnsupported("tkhd-version");
+  const data = await payload(reader, tkhd, first[0] === 1 ? 24 : 16);
+  const id = data.readUInt32BE(first[0] === 1 ? 20 : 12);
+  const enabled = (first.readUIntBE(1, 3) & 1) !== 0;
+  const references = await inside(reader, one(parts, "tref"));
+  const refs = [];
+  for (const ref of references.filter((item) => item.type === "chap")) {
+    const size = ref.end - ref.dataOffset;
+    if (size % 4 || size / 4 > CHAPTER_LIMITS.entries) throw new Error("Invalid chap references");
+    const values = await payload(reader, ref, size);
+    for (let at = 0; at < size; at += 4) refs.push(values.readUInt32BE(at));
+  }
+  return { id, enabled, refs, parts };
+}
+
+async function sizesOf(reader, fields) {
+  const stsz = one(fields, "stsz");
+  if (stsz) {
+    const head = await payload(reader, stsz, 12);
+    const uniform = head.readUInt32BE(4), count = head.readUInt32BE(8);
+    if (count > CHAPTER_LIMITS.entries) throw new ChapterUnsupported("chapter-sample-count");
+    if (stsz.dataOffset + 12 + (uniform ? 0 : 4 * count) !== stsz.end) throw new Error("Invalid chapter stsz");
+    const values = uniform ? null : await reader.bytes(stsz.dataOffset + 12, count * 4);
+    return Array.from({ length: count }, (_, index) => uniform || values.readUInt32BE(index * 4));
+  }
+  const compact = one(fields, "stz2");
+  const head = await payload(reader, compact, 12);
+  const width = head[7], count = head.readUInt32BE(8);
+  if (![4, 8, 16].includes(width)) throw new Error("Invalid stz2 field size");
+  if (count > CHAPTER_LIMITS.entries) throw new ChapterUnsupported("chapter-sample-count");
+  const length = Math.ceil(width * count / 8);
+  if (compact.dataOffset + 12 + length !== compact.end) throw new Error("Invalid chapter stz2");
+  const values = await reader.bytes(compact.dataOffset + 12, length);
+  return Array.from({ length: count }, (_, index) => width === 16 ? values.readUInt16BE(index * 2)
+    : width === 8 ? values[index] : index % 2 ? values[index >> 1] & 15 : values[index >> 1] >> 4);
+}
+
+async function editMap(reader, parts, movieScale, trackScale, trackDuration) {
+  const edts = await inside(reader, one(parts, "edts"));
+  const elst = one(edts, "elst");
+  if (!elst) return [{ media: 0, movie: 0, duration: chapterSeconds(trackDuration, trackScale), index: 0 }];
+  const version = (await payload(reader, elst, 4))[0];
+  if (version > 1) throw new ChapterUnsupported("chapter-edit-version");
+  const width = version === 1 ? 20 : 12;
+  const entries = await table(reader, elst, width);
+  let movie = 0;
+  const result = [];
+  for (let index = 0; index < entries.count; index++) {
+    const at = index * width;
+    const duration = chapterSeconds(version === 1 ? entries.bytes.readBigUInt64BE(at) : BigInt(entries.bytes.readUInt32BE(at)), movieScale);
+    const media = version === 1 ? entries.bytes.readBigInt64BE(at + 8) : BigInt(entries.bytes.readInt32BE(at + 4));
+    const rate = version === 1 ? at + 16 : at + 8;
+    if (entries.bytes.readInt16BE(rate) !== 1 || entries.bytes.readInt16BE(rate + 2) !== 0) throw new ChapterUnsupported("chapter-edit-rate");
+    if (media < -1n) throw new Error("Invalid chapter edit media time");
+    if (media !== -1n) result.push({ media: chapterSeconds(media, trackScale), movie, duration, index });
+    movie += duration;
+  }
+  return result;
+}
+
+async function quicktime(reader, track, movieScale) {
+  const mdia = await inside(reader, one(track.parts, "mdia"));
+  const timing = await timedHeader(reader, one(mdia, "mdhd"));
+  const mdhd = await payload(reader, one(mdia, "mdhd"), timing.wide ? 34 : 22);
+  const lang = mdhd.readUInt16BE(timing.wide ? 32 : 20);
+  let language = lang ? String.fromCharCode(((lang >> 10) & 31) + 96, ((lang >> 5) & 31) + 96, (lang & 31) + 96) : "und";
+  if (lang < 0x400) language = MAC_LANGUAGES.get(lang) ?? "und";
+  if (!/^[a-z]{3}$/.test(language)) language = "und";
+  const elng = one(mdia, "elng");
+  if (elng) {
+    await payload(reader, elng, 4);
+    language = titleOf(await reader.bytes(elng.dataOffset + 4, elng.end - elng.dataOffset - 4)) || language;
+  }
+  const minf = await inside(reader, one(mdia, "minf"));
+  const dinf = await inside(reader, one(minf, "dinf"));
+  const dref = one(dinf, "dref");
+  const dataRefs = dref ? await boxes(reader, dref.dataOffset + 8, dref.end) : [];
+  if (dref && (await payload(reader, dref, 8)).readUInt32BE(4) !== dataRefs.length) throw new Error("Chapter data reference count mismatch");
+  const fields = await inside(reader, one(minf, "stbl"));
+  const stsd = one(fields, "stsd");
+  if (!stsd) throw new Error("Chapter track has no sample descriptions");
+  const descriptions = await boxes(reader, stsd.dataOffset + 8, stsd.end);
+  if ((await payload(reader, stsd, 8)).readUInt32BE(4) !== descriptions.length) throw new Error("Chapter sample description count mismatch");
+  if (!descriptions.length) throw new Error("Chapter track has no sample description");
+  for (const description of descriptions) {
+    if (!["text", "tx3g"].includes(description.type)) throw new ChapterUnsupported(`chapter-sample-format:${description.type}`);
+    const reference = (await payload(reader, description, 8)).readUInt16BE(6);
+    const source = dataRefs[reference - 1];
+    if (!source || !["url ", "alis"].includes(source.type) || ((await payload(reader, source, 4)).readUIntBE(1, 3) & 1) === 0) {
+      throw new ChapterUnsupported("external-chapter-data-reference");
+    }
+  }
+  const sizes = await sizesOf(reader, fields);
+  const durations = await table(reader, one(fields, "stts"), 8);
+  const times = [];
+  let ticks = 0n;
+  for (let index = 0; index < durations.count; index++) {
+    const count = durations.bytes.readUInt32BE(index * 8), delta = BigInt(durations.bytes.readUInt32BE(index * 8 + 4));
+    if (times.length + count > sizes.length) throw new Error("stts exceeds chapter sample count");
+    for (let sample = 0; sample < count; sample++) { times.push({ start: ticks, end: ticks + delta }); ticks += delta; }
+  }
+  if (times.length !== sizes.length) throw new Error("stts does not cover chapter samples");
+  const ctts = one(fields, "ctts");
+  if (ctts) {
+    const offsets = await table(reader, ctts, 8);
+    if (offsets.head[0] > 1) throw new ChapterUnsupported("chapter-ctts-version");
+    let sample = 0;
+    for (let index = 0; index < offsets.count; index++) {
+      const count = offsets.bytes.readUInt32BE(index * 8);
+      const offset = BigInt(offsets.head[0] === 1 ? offsets.bytes.readInt32BE(index * 8 + 4) : offsets.bytes.readUInt32BE(index * 8 + 4));
+      if (sample + count > times.length) throw new Error("ctts exceeds chapter samples");
+      for (let n = 0; n < count; n++, sample++) { times[sample].start += offset; times[sample].end += offset; }
+    }
+    if (sample !== times.length) throw new Error("ctts does not cover chapter samples");
+  }
+  const chunksField = one(fields, "stco") ?? one(fields, "co64");
+  const wide = chunksField?.type === "co64";
+  const chunks = await table(reader, chunksField, wide ? 8 : 4);
+  const runs = await table(reader, one(fields, "stsc"), 12);
+  const locations = [];
+  const formats = [];
+  let run = 0, sample = 0;
+  const runAt = (index) => ({ first: runs.bytes.readUInt32BE(index * 12), count: runs.bytes.readUInt32BE(index * 12 + 4), description: runs.bytes.readUInt32BE(index * 12 + 8) });
+  if (chunks.count && (!runs.count || runAt(0).first !== 1)) throw new Error("Invalid first chapter chunk mapping");
+  for (let index = 0; index < runs.count; index++) {
+    const current = runAt(index);
+    if (!current.count || current.description < 1 || current.description > descriptions.length || current.first > chunks.count || (index && current.first <= runAt(index - 1).first)) throw new Error("Invalid chapter chunk mapping");
+  }
+  for (let index = 0; index < chunks.count; index++) {
+    if (run + 1 < runs.count && runAt(run + 1).first === index + 1) run++;
+    let at = wide ? Number(chunks.bytes.readBigUInt64BE(index * 8)) : chunks.bytes.readUInt32BE(index * 4);
+    for (let n = 0; n < runAt(run).count; n++, sample++) {
+      if (sample >= sizes.length || !Number.isSafeInteger(at) || at < 0 || at + sizes[sample] > reader.size) throw new Error("Chapter sample outside file or count");
+      locations.push(at); formats.push(descriptions[runAt(run).description - 1].type); at += sizes[sample];
+    }
+  }
+  if (locations.length !== sizes.length) throw new Error("Chunk table does not cover chapter samples");
+  const edits = await editMap(reader, track.parts, movieScale, timing.scale, timing.duration);
+  const chapters = [];
+  for (let index = 0; index < sizes.length; index++) {
+    if (sizes[index] < 2 || sizes[index] > CHAPTER_LIMITS.textBytes + 65536) throw new ChapterUnsupported("chapter-text-sample-size");
+    const head = await reader.bytes(locations[index], 2);
+    const length = head.readUInt16BE();
+    if (length + 2 > sizes[index]) throw new Error("Chapter text exceeds sample");
+    const title = trackTitle(await reader.bytes(locations[index] + 2, length), formats[index], lang);
+    const start = chapterSeconds(times[index].start, timing.scale), end = chapterSeconds(times[index].end, timing.scale);
+    for (const edit of edits) {
+      if (end <= edit.media || start >= edit.media + edit.duration) continue;
+      chapters.push(chapter(`mp4:track:${track.id}:sample:${index}:edit:${edit.index}`,
+        edit.movie + Math.max(start - edit.media, 0), edit.movie + Math.min(end - edit.media, edit.duration), title, language, chapters.length));
+    }
+  }
+  return { id: `mp4:track:${track.id}`, source: "quicktime", ordered: false, chapters };
+}
+
+export async function readMp4Chapters(container, held) {
+  const cached = container.moovHeld;
+  const originalRead = held.read;
+  const ranges = held.ranges ? [...held.ranges] : undefined;
+  if (cached?.offset !== undefined) ranges?.push([cached.offset, cached.offset + cached.moov.length - 1]);
+  const reader = new ChapterBytes({ ...held, ranges, read: (start, end) => {
+    if (cached?.offset !== undefined && start >= cached.offset && end < cached.offset + cached.moov.length) return Promise.resolve(cached.moov.subarray(start - cached.offset, end - cached.offset + 1));
+    return originalRead(start, end);
+  } }, container.fileSize);
+  let moov = null;
+  for (let at = 0; at < reader.size;) {
+    const field = await box(reader, at, reader.size);
+    if (field.type === "moov") { moov = field; break; }
+    at = field.end;
+  }
+  if (!moov) return chapterResult("absent");
+  const parts = await inside(reader, moov);
+  const udta = await inside(reader, one(parts, "udta"));
+  const chpl = one(udta, "chpl");
+  const editions = [];
+  if (chpl) editions.push(await nero(reader, chpl));
+  let pending = null;
+  try {
+    const tracks = [];
+    for (const field of parts.filter((part) => part.type === "trak")) tracks.push(await trackInfo(reader, field));
+    const referrer = tracks.find((track) => track.enabled && track.refs.length);
+    if (referrer) {
+      const track = tracks.find((item) => item.id === referrer.refs[0]);
+      if (!track) throw new Error("Referenced chapter track is missing");
+      const extensions = await inside(reader, one(parts, "mvex"));
+      for (const defaults of extensions.filter((item) => item.type === "trex")) {
+        if ((await payload(reader, defaults, 8)).readUInt32BE(4) === track.id) {
+          // Fragment samples are not described by the initial sample tables.
+          throw new ChapterUnsupported("chapter-fragmented-track");
+        }
+      }
+      const timing = await timedHeader(reader, one(parts, "mvhd"));
+      editions.unshift(await quicktime(reader, track, timing.scale));
+    }
+  } catch (error) {
+    if (!editions.length) throw error;
+    if (isUnavailable(error)) pending = { state: "pending", start: error.start, end: error.end };
+    else throw error;
+  }
+  const selected = editions[0];
+  if (!selected || !selected.chapters.length) return chapterResult(pending ? "pending" : "absent", { editions, pending,
+    selectedEditionId: selected?.id ?? null });
+  let duration = container.mediaInfo?.durationSeconds ?? null;
+  if (duration === null && one(parts, "mvhd")) {
+    const timing = await timedHeader(reader, one(parts, "mvhd"));
+    if (timing.duration !== (timing.wide ? 0xffffffffffffffffn : 0xffffffffn)) duration = chapterSeconds(timing.duration, timing.scale);
+  }
+  return chapterResult("available", { editions, selectedEditionId: selected.id, complete: pending === null,
+    pending, representationsDisagree: editions.length > 1 && JSON.stringify(editions[0].chapters.map((item) => [item.startSeconds, item.titles[0].text])) !== JSON.stringify(editions[1].chapters.map((item) => [item.startSeconds, item.titles[0].text])),
+    sections: navigationSections(selected, duration) });
+}

package/services/server/controllers/ChapterController.js

@@ -0,0 +1,9 @@
+/** HTTP validation without torrent startup or media parsing. */
+export class ChapterController {
+  constructor({ sourceRegistry, chapters }) { this.sourceRegistry = sourceRegistry; this.chapters = chapters; }
+  get({ sourceKey, fileIndex }) {
+    if (!this.sourceRegistry.get(sourceKey)) return { status: 404, body: { code: "SOURCE_NOT_FOUND", error: "Source key was not found." } };
+    if (!Number.isSafeInteger(fileIndex) || fileIndex < 0) return { status: 400, body: { error: "fileIndex must be a non-negative integer." } };
+    return { status: 200, body: { ...this.chapters.get(sourceKey, fileIndex), capability: "supported" } };
+  }
+}

package/services/server/wire-outputs.js

@@ -177,6 +177,7 @@ function buildHttpBaseUrl(host, port) {
  * @returns {object} The components, and the settings they read.
  */
 export function wireOutputs({
+    observeWait = null,
     enabled,
     ffmpegBin,
     localBindHost,
@@ -363,6 +364,7 @@ export function wireOutputs({
     get segmentDurationSec() { return parts.segmentDurationSec; },
     readsThroughCache: () => parts.inputCacheAvailable === true,
     segmentFiles,
+    observeWait,
     get videoEncoder() { return parts.encoders.current; },
     get encoders() { return parts.encoders; },
     invalidateWaits: (output) => parts.serving.invalidateWaits(output),

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

@@ -31,12 +31,14 @@ export class WorkerTorrentPool {
   /** Stand-ins by source key, so repeat calls return the same object. */
   #torrents = new Map();
   #pending = new Map();
+  #observed;
 
   /**
    * @param {{ memoryBytes?: number, stateDir?: string }} [options]
    * @param {object | null} [client] - The worker interface; tests supply a fake.
    */
   constructor(options = {}, client = null) {
+    this.#observed = options.onObserved;
     this.#client = client ?? new TorrentWorkerClient({ ...options, onSourceForgotten: event => {
       this.forget(event.sourceKey);
       options.onSourceForgotten?.(event);
@@ -51,13 +53,16 @@ export class WorkerTorrentPool {
    * @returns {Promise<object>}
    */
   async getTorrent(sourceType, source) {
+    const startedAt = performance.now();
     const sourceKey = await deriveSourceKey(sourceType, source);
+    const observed = outcome => this.#observed?.({ sourceKey, startedAt, endedAt: performance.now(), outcome });
     const existing = this.#torrents.get(sourceKey);
     if (existing) {
+      observed("cached");
       return existing;
     }
     const joined = this.#pending.get(sourceKey);
-    if (joined) return joined;
+    if (joined) return joined.finally(() => observed("joined"));
     const pending = this.#client.getTorrent({ sourceKey, sourceType, source }).then(torrent => {
       if (this.#pending.get(sourceKey) !== pending) {
         const error = new Error("Source was forgotten while its metadata was being read.");
@@ -66,7 +71,10 @@ export class WorkerTorrentPool {
       }
       this.#torrents.set(sourceKey, torrent);
       return torrent;
-    }).finally(() => { if (this.#pending.get(sourceKey) === pending) this.#pending.delete(sourceKey); });
+    }).finally(() => {
+      observed(this.#torrents.has(sourceKey) ? "ready" : "error");
+      if (this.#pending.get(sourceKey) === pending) this.#pending.delete(sourceKey);
+    });
     this.#pending.set(sourceKey, pending);
     return pending;
   }

package/services/transport/data-channel-handler.js

@@ -713,6 +713,17 @@ export function createDataChannelHandler({
    * @type {Map<string, Map<string, DataChannel | null>>}
    */
   const viewersOnConnection = new Map();
+  // One selected chapter file per channel; removed with the channel.
+  const chapterChannels = new Map();
+
+  function publishChaptersChanged(event) {
+    for (const [channel, selected] of chapterChannels) {
+      if (selected.sourceKey === event.sourceKey && selected.fileIndex === event.fileIndex) {
+        try { send(channel, { type: "chapters-changed", ...event }); }
+        catch (error) { log(`[dc] chapter notification failed: ${error.message}`); }
+      }
+    }
+  }
 
   /**
    * The connections a viewer is still named on, oldest first.
@@ -799,6 +810,7 @@ export function createDataChannelHandler({
    * @returns {void}
    */
   function forgetChannel(channel) {
+    chapterChannels.delete(channel);
     for (const viewers of viewersOnConnection.values()) {
       for (const [consumerId, on] of viewers) {
         if (on === channel) {
@@ -1162,6 +1174,16 @@ export function createDataChannelHandler({
       return;
     }
 
+    const chapterPath = /^\/api\/sources\/([^/]+)\/chapters$/.exec(path);
+    if (method === "GET" && chapterPath) {
+      const rawIndex = new URLSearchParams(query ?? "").get("fileIndex");
+      const fileIndex = rawIndex !== null && /^\d+$/.test(rawIndex) ? Number(rawIndex) : NaN;
+      if (Number.isSafeInteger(fileIndex) && fileIndex >= 0) {
+        try { chapterChannels.set(channel, { sourceKey: decodeURIComponent(chapterPath[1]), fileIndex }); }
+        catch (error) { log(`[dc] chapter source key cannot be decoded: ${error.message}`); }
+      }
+    }
+
 
     const queryInfo = query ? `?${query}` : "";
     const bodyInfo =
@@ -1464,7 +1486,8 @@ export function createDataChannelHandler({
     handleChannel,
     publishSubtitleCues,
     /** What the film costs viewers' links beyond itself, per byte of film, or null. */
-    serviceShare: () => deliveryShares.serviceShare()
+    serviceShare: () => deliveryShares.serviceShare(),
+    publishChaptersChanged
   };
 }
 

package/utils/wait-trace.js

@@ -0,0 +1,68 @@
+/** Bounded, opt-in startup observations. No torrent or application imports. */
+export class SourceWaitTrace {
+  constructor({ emit, now = () => performance.now() }) {
+    Object.assign(this, { emit, now, sources: new Map(), requests: new WeakMap() });
+  }
+
+  write(context, event, fields = {}) {
+    this.emit({ version: 1, clock: "proxy-main", wait: context.wait, attempt: context.attempt,
+      operation: context.operation, event, at: this.now(), ...fields });
+  }
+
+  remember(sourceKey, context) {
+    if (typeof sourceKey !== "string" || !sourceKey) return;
+    for (const [key, value] of this.sources) if (this.now() - value.seen > 60_000) this.sources.delete(key);
+    if (this.sources.size >= 64 && !this.sources.has(sourceKey)) this.sources.delete(this.sources.keys().next().value);
+    this.sources.set(sourceKey, { ...context, seen: this.now() });
+  }
+
+  source(sourceKey, event, fields = {}) {
+    const context = this.sources.get(sourceKey);
+    if (!context || this.now() - context.seen > 60_000) return;
+    this.write({ ...context, operation: null }, event, { sourceKey, ...fields });
+  }
+
+  install(app) {
+    app.addHook("onRequest", async (req, reply) => {
+      const wait = req.headers["x-ttv-wait-trace"];
+      const operation = req.headers["x-ttv-wait-operation"];
+      const attempt = Number(req.headers["x-ttv-wait-attempt"]);
+      if (typeof wait !== "string" || !/^[a-zA-Z0-9.-]{1,80}$/.test(wait) ||
+        typeof operation !== "string" || !/^b[0-9]{1,12}$/.test(operation) ||
+        !Number.isSafeInteger(attempt) || attempt < 0) return;
+      const context = { wait, attempt, operation, startedAt: this.now() };
+      this.requests.set(req, context);
+      this.write(context, "http-start", { method: req.method, path: req.url,
+        requestId: req.headers["x-ttv-forwarded-request-id"] ?? req.id });
+      let finished = false;
+      const end = outcome => {
+        if (finished) return;
+        finished = true;
+        this.write(context, "http-end", { outcome, status: reply.statusCode, duration: this.now() - context.startedAt });
+      };
+      reply.raw.once("finish", () => end("finished"));
+      reply.raw.once("close", () => end(reply.raw.writableFinished ? "finished" : "closed"));
+    });
+    app.addHook("preHandler", async req => {
+      const context = this.requests.get(req);
+      if (!context) return;
+      const match = /^\/api\/sources\/([^/?]+)/.exec(req.url);
+      const sourceKey = req.body?.sourceKey ?? req.query?.sourceKey ?? (match ? decodeURIComponent(match[1]) : null);
+      this.remember(sourceKey, context);
+      this.write(context, "http-handler", { sourceKey });
+    });
+    app.addHook("preSerialization", async (req, _reply, payload) => {
+      const context = this.requests.get(req);
+      if (context) {
+        this.remember(payload?.sourceKey, context);
+        this.write(context, "http-serialize");
+      }
+      return payload;
+    });
+    app.addHook("onSend", async (req, _reply, payload) => {
+      const context = this.requests.get(req);
+      if (context) this.write(context, "http-send");
+      return payload;
+    });
+  }
+}