@torrent-tv/proxy 2.86.0 → 2.87.1

package/docs/browser-proxy-contract.md

@@ -0,0 +1,94 @@
+# Browser–proxy playback contract
+
+This document records the HTTP contract used by the browser playback code and
+implemented by this proxy. The same paths and payloads pass through either the
+direct HTTP transport or the WebRTC data channel. It is a description of the
+current code, not a generated schema or a version negotiation protocol.
+
+## Source and file discovery
+
+| Request | Required input | Successful answer |
+|---|---|---|
+| `POST /api/sources` | `{ sourceType, source }` | `{ sourceKey }` identifies the registered source. |
+| `GET /api/sources/:sourceKey/files?maxWaitMs=N` | Registered `sourceKey`; optional wait budget | While magnet metadata is unavailable: `{ pending: true }`. When ready: `{ name, infoHash, files, items }`. `files` carries `fileIndex`, `name`, `relativePath`, `length`, and `kind`; `items` maps each video `fileIndex` to audio, subtitle, and image file indices. |
+| `GET /api/sources/:sourceKey/stats?fileIndex=N` | Registered source; optional file index | Current peer, transfer, header, and file progress readings. A reading may not contain every measurement; absent or `null` measurements are unknown. |
+| `POST /api/sources/:sourceKey/warm` | Optional `{ fileIndex, positionSeconds }`; an empty object warms source metadata and the first video | `{ started, swarm, edges, sidecars }` reports which preparation started. Work continues in the background. |
+| `GET /api/link-probe?bytes=N` | Positive byte count | A no-store binary body of zero bytes, capped at 2 MiB. The browser measures completed transfer time; an unavailable route leaves link speed unknown. |
+
+`pending: true` means the requested metadata or plan is not ready yet. The
+browser polls again. It does not mean that the torrent has no video or that the
+request failed. A non-pending file-list answer uses the proxy's file indices;
+the browser must keep those indices when opening a file.
+
+## Playback plan and transcode session
+
+`POST /api/playback-plan` takes `{ sourceKey, fileIndex, userAgent }`. Its answer
+contains `mode`, `directUrl`, codec and container names, duration and source
+dimensions, track inventories, paired sidecar files, `offeredHeights`, and
+`pending`. The browser uses the codec fields to make the direct-versus-transcode
+decision itself; `mode` is advisory.
+
+`sidecarSubtitles` lists subtitle files the proxy paired with this video. Each
+entry carries the torrent `fileIndex` and the proxy's filename-derived language
+and release metadata. The browser uses these entries to fetch subtitle files
+and to identify a remembered choice. `sidecarImages` is returned beside it but
+is not needed for playback. Older proxies and plans made with transcoding
+disabled may omit these fields; the browser treats a missing or non-array list
+as empty.
+
+The browser maps a missing `mode` to `direct`, uses its registered `/stream`
+URL when `directUrl` is absent, maps missing codec/container names to empty
+strings, maps missing duration or dimensions to `0`, and maps missing audio or
+subtitle track arrays to `[]`. It maps missing or non-object `offeredHeights` to
+`null`; for an object value, missing or invalid `copy` and `transcode` lists
+become empty arrays. `null` means no offer was supplied, while empty lists
+explicitly offer no heights for their respective playback branch. Only
+`pending: true` asks the browser to poll again.
+
+`POST /api/transcode-sessions` requires `sourceKey`, `fileIndex`, and
+`consumerId`. The browser also sends the requested audio/video transcode flags,
+the visible picture size, whether audio is requested as separate renditions,
+the start position, selected audio track, and segment format when known. The
+answer contains `sessionId`, `playlistPath`, `offeredHeights`, declared `tracks`,
+and `lookaheadSeconds`. `masterPath` and `variantHeight` are present only when
+the session has quality variants.
+
+The browser interprets `409` with `outcome: "output-unavailable"` as a refusal
+for this viewer's link and `outcome: "no-capacity"` as a proxy capacity
+refusal. Other non-success statuses remain errors; an error body only adds
+display detail and is not required for status handling.
+
+## Session control and media files
+
+| Request | Meaning |
+|---|---|
+| `POST /api/transcode-sessions/:id/seek` | `{ positionSeconds, consumerId, generation }` reports the viewer's seek. A successful answer is `204`; the proxy handles the seek server side. |
+| `GET /api/transcode-sessions/:id/progress?consumer=:id` | Reads current session progress and also keeps the viewer's session alive. The browser consumes available progress fields; an unreadable or failed answer does not imply that playback has ended. |
+| `POST /api/transcode-sessions/:id/net-report` | `{ consumerId, bufferedAheadSec, ... }` reports the viewer's buffer and optional state/link measurements. `consumerId` and non-negative `bufferedAheadSec` are required; missing `linkMbps` does not reject the report and leaves the last link reading intact. Missing `playing` becomes `false`; missing `waiting` is derived from the playback and buffer state. Missing `positionSeconds` leaves the position unchanged, missing `qualityMode` leaves the prior mode, `onScreen` defaults to `true`, and `inPictureInPicture` defaults to `false`. Success is `204`. |
+| `POST /api/transcode-sessions/:id/fragment-far` | Diagnostic fragment and buffer positions; does not change encoding. Best effort, success `204`. |
+| `POST /api/transcode-sessions/:id/release` | `{ consumerId, reason }` releases this viewer's session assignment. |
+| `GET /transcode/:id/:fileName` | HLS playlist, init, or media segment. A file that is still being produced is answered with retryable `503`, not `202`. |
+| `GET /transcode/:id/v/:height/warm` and `/transcode/:id/a/:track/warm` | Prepare the requested video height or audio track at a position. `204` means ready. Audio warm-up `404` means the proxy does not support this operation for that session. |
+| `GET /stream?sourceKey=…&fileIndex=N` | Direct file bytes with HTTP range support. |
+
+## Subtitles
+
+`GET /api/subtitles` requires `sourceKey` and `fileIndex`. Without `trackIndex`
+it reads a paired sidecar file. With `trackIndex`, it reads cues from an
+embedded text track and may take `consumerId` to subscribe that viewer to
+subsequent cue pushes. `since` asks for cues after a previously received
+cursor.
+
+`200` returns WebVTT. Embedded cue answers may include
+`X-Subtitle-Cursor`, `X-Subtitle-Covered-Clusters`, and
+`X-Subtitle-Indexed-Clusters`; language detection may include
+`X-Subtitle-Language` and `X-Subtitle-Language-Name`. While an embedded track
+is being extracted, the response is `202` with `{ pending: true }`; the browser
+waits and repeats the request. A missing cursor or language header means that
+the browser has no value to preserve or display yet. A failed sidecar or
+embedded-track request skips that track without failing video playback.
+
+Subtitle cue pushes are delivered through the established proxy connection,
+not by a separate browser polling route. After reconnect, the browser repeats
+the embedded-track request with `since` to restore the subscription and receive
+missed cues.

package/docs/container-architecture.md

@@ -1,213 +1,218 @@
-# Container & Track architecture
-
-Domain → Application → Interface, per RFC 9559 (Matroska) and ISO/IEC 14496-12 (MP4).
-
-## Two axes, and what is NOT a third
-
-Everything here is placed on exactly two axes: **which container** a track lives
-in, and **what kind of track** it is (video / audio / subtitle). A file lying
-beside the video — a dub as `<name>.mka`, subtitles as `<name>.ass` — is not a
-third kind of anything:
-
-- a `.mka` **is** Matroska. `ContainerFactory` sniffs it, `MatroskaContainer`
-  reads its `TrackEntry` list, and out comes an `AudioTrack` with its language,
-  title and flags. It differs from the picture's own file only in having no
-  video track. The same holds for `.m4a` and `Mp4Container`;
-- "external" is therefore not a TYPE. It is the answer to WHERE a track's bytes
-  are, and that is torrent knowledge — which this layer must not have
-  (`ContainerFactory`: no torrent knowledge; `ContainerOrchestrator`:
-  transport-agnostic). The pairing of a sidecar file with a picture lives in
-  `services/sidecar-files.js`, and the numbered list a viewer chooses from lives
-  in `services/audio-inventory.js`. Both are pure and both are application-layer.
-
-A class called `ExternalSubtitleFile` used to sit in `tracks/` asserting the
-opposite. It did not extend `ContainerTrack`, duplicated four of its fields, and
-was imported by nothing; it was deleted rather than extended. Nothing replaced
-it — a subtitle file beside the video is a `TextSubtitleTrack` whose bytes are
-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.
-
-**That split is closed.** `SubtitleTrack` carries `clusterPositions` and
-`samples` — byte POSITIONS — and the reading of those positions is now the
-container's: `MatroskaContainer.walkHeldClusters(plan, walked)` and
-`Mp4Container.readHeldSamples(track, harvested)`, beside `readTracks`,
-`readKeyframeIndex`, `readMediaInfo` and `cueTextOf`.
-
-The obstacle was real and this is how it was answered. The two readers want
-different read POLICIES over the same file: the track table fetches what is
-missing from the swarm, while the cue walk deliberately reads only what is
-already downloaded, so that turning subtitles on never pulls bytes the viewer is
-not waiting for. A container is now built with BOTH — `readRange` that fetches,
-`readHeld` that does not, and `isHeld` that says whether a range can be read
-without fetching — so one instance per file serves both readers and the per-file
-cache is kept.
-
-What the container is NOT given is the torrent. Those three functions are the
-whole of what the caller knows and the container does not, and reducing the
-torrent to them is what lets the reading live where the format is specified.
-`torrent-worker/subtitle-cues.js` supplies them (`containerOver`) and keeps only
-what is genuinely its own: the found-order cursor a browser follows, the
-per-file state, and one walk of a file at a time.
-
-## Layers
-
-```mermaid
-flowchart TB
-  subgraph Domain
-    C[Container<br/>abstract<br/>RFC9559 / 14496-12]
-    MC[MatroskaContainer]
-    MpC[Mp4Container]
-    AC[AviContainer]
-    CT[ContainerTrack<br/>isEnabled/isDefault/language]
-    VT[VideoTrack]
-    AT[AudioTrack]
-    ST[SubtitleTrack]
-    TST[TextSubtitleTrack<br/>S_TEXT/UTF8 tx3g wvtt]
-    IST[ImageSubtitleTrack<br/>PGS VobSub subp]
-    C --> MC & MpC & AC
-    CT --> VT & AT & ST
-    ST --> TST & IST
-    MC & MpC & AC -- readTracks --> CT
-  end
-  subgraph Application
-    CF[ContainerFactory<br/>detect 16 bytes]
-    CO[ContainerOrchestrator<br/>cache + getTracks/getKeyframeIndex]
-    SO[SubtitleOrchestrator<br/>cursor + per-file state]
-    SF[sidecar-files.js<br/>which file goes with which]
-    AI[audio-inventory.js<br/>one flat numbering]
-    CF --> CO
-    CO --> SO
-    SF --> AI
-    CO --> AI
-  end
-  subgraph Interface
-    PC[PlaybackController]
-    SC[SubtitleController]
-    R1[routes/api/playback-plan]
-    R2[routes/api/subtitles]
-    PC --> R1
-    SC --> R2
-    CO --> PC
-    SO --> SC
-  end
-```
-
-## Class responsibilities (spec-grounded)
-
-| Class | Spec section | Fields | Not responsible |
-|---|---|---|---|
-| `ContainerTrack` | RFC9559 TrackEntry common + ISO 14496-12 tkhd/mdhd/hdlr/elng | `trackNumber`, `declaredIndex`, `codecId`, `language`/`languageBcp47` (MUST rule), `name`, `isEnabled` (0xB9 / track_enabled), `isDefault`+`declaresDefault` (0x88) | Type-specific flags |
-| `VideoTrack` | RFC9559 Video, ISO 14496-12 tkhd width/height, stsd | `width/height/display*`, `fps`, `isHdr`, `bitDepth` | Subtitle flags |
-| `AudioTrack` | RFC9559 FlagOriginal 0x55AE, FlagCommentary 0x55AF, FlagVisualImpaired 0x55AC | `isOriginal/isCommentary/isVisualImpaired`, `channels/samplingFrequency` | FlagForced |
-| `SubtitleTrack` | RFC9559 FlagForced 0x55AA (subtitle-only), FlagHearingImpaired 0x55AB | `isForced/isHearingImpaired`, `clusterPositions`/`samples` | Video dims |
-| `TextSubtitleTrack` | `S_TEXT/UTF8, S_TEXT/ASS, tx3g, wvtt` | `toVtt()` convertible | Image tracks |
-| `sidecar-files.js` | — (torrent naming) | which files of a torrent are one picture's sound and subtitles | what is inside them |
-| `audio-inventory.js` | RFC9559 audio flags, merged against ffmpeg's numbering | one flat number per soundtrack → `(fileIndex, 0:a:N)` | display labels |
-| `ImageSubtitleTrack` | `S_HDMV/PGS, S_VOBSUB, subp, clcp` | kept for `declaredIndex` alignment | Conversion |
-| `MatroskaContainer` | RFC9559 SeekHead, Tracks, Cues, Clusters | single Tracks walk for all types, EBML via `ebml-reader.js` | HTTP |
-| `Mp4Container` | ISO 14496-12 moov/trak/tkhd/mdhd/hdlr/elng/stbl | `alternate_group` grouping, packed language, `tx3g` forced bits | Torrent |
-| `AviContainer` | RIFF AVI idx1 | `AVIIF_KEYFRAME` keyframe times | Tracks beyond video |
-
-`VideoTrack` never carries `isForced` — spec states FlagForced "Applies only to subtitles". Placing it in base would pollute video with irrelevant state.
-
-## Orchestrators & Controllers
-
-- `ContainerFactory.create({readRange,fileSize})` — sniffs 16 bytes, returns precise `Container` subclass. No torrent knowledge.
-- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getMediaInfo()` / `getKeyframeIndex()`. Transport-agnostic.
-- **The keyframe table is read once per file**, like the other two. `Container.readKeyframeIndex` memoizes and each format implements `parseKeyframeIndex`, so the wait belongs to the FILE: two sessions created in the same moment join one read rather than making two, which is exactly what two viewers opening one film do. A read that THREW is not remembered — the bytes it needed may simply not have arrived. Who asks: `torrent-worker/container-tracks.js` `containerKeyframesOf`, over the torrent, reached from the session manager by the `container-keyframes` command. The manager's own HTTP read remains for a manager wired without that path (every unit test).
-- `SubtitleOrchestrator` — wraps `torrent-worker/subtitle-cues.js` (`planFor`, `cuesHeldFor`, `warmSubtitleCues`) behind the `ContainerTrack` abstraction. Routes depend on this, not on the worker directly. The reading itself is the containers' — that module supplies the torrent's read policy and keeps the cursor.
-- `PlaybackController` / `SubtitleController` — thin interface adapters; `routes/api/*` delegate to them, handle HTTP headers (`X-Subtitle-Language`, `X-Subtitle-Cursor`) only.
-
-## Legacy
-
-Everything a container states about ITSELF is in its own class: the track table,
-the Cues, the keyframe times they name, the cluster positions, the blocks inside
-a cluster, the MP4 sample table. `services/container-index/` no longer exists.
-What was kept apart is `container/ebml-reader.js` — EBML element walking is the
-format's grammar rather than any of its statements.
-
-`ContainerFactory` is the one place that decides what a file IS. It sniffs the
-header, because that is what the muxer wrote while a name is what somebody
-typed, and it answers `readKeyframeIndex` for the same reason: doing it anywhere
-else meant a third place making that decision. `ContainerFactory.byName` exists
-for the one path that cannot sniff — the cue walk asks the swarm for nothing, so
-a file whose head is not downloaded has only its name.
-
-**Two readings of one file, and which answers.** ffmpeg's `-i` banner and the
-container's own table both describe a file's tracks, and the rule is stated once
-per media kind on `Container`. `alignWithBanner` lines them up by position and
-CHECKS each pair on language or title; one pair agreeing on neither, or a length
-that differs, drops the container reading whole, because a wrong flag is worse
-than a missing one. `mergeSubtitleFlags`, `mergeAudioFlags` and
-`mergeVideoFacts` then say which side answers for which field: flags the banner
-cannot express come from the container; the coded size and frame rate come from
-the probe, because the encoder receives what the decoder produced.
-
-Direct imports from routes are deprecated — use `orchestrators/` and
-`controllers/` instead.
-
-## Flags matrix
-
-| Flag | Matroska ID | Applies to | Base or subclass |
-|---|---|---|---|
-| `FlagEnabled` | 0xB9 default 1 | all | `ContainerTrack` |
-| `FlagDefault` | 0x88 default 1 | all | `ContainerTrack` (`declaresDefault`) |
-| `Language` | 0x22B59C | all | `ContainerTrack` |
-| `LanguageBCP47` | 0x22B59D MUST | all | `ContainerTrack` |
-| `FlagForced` | 0x55AA | subtitle only | `SubtitleTrack` |
-| `FlagHearingImpaired` | 0x55AB | subtitle | `SubtitleTrack` |
-| `FlagVisualImpaired` | 0x55AC | audio (descriptive) + subtitle | `AudioTrack`/`SubtitleTrack` |
-| `FlagOriginal` | 0x55AE | audio | `AudioTrack` |
-| `FlagCommentary` | 0x55AF | audio | `AudioTrack` |
-| `track_enabled` | tkhd 0x000001 | all | `ContainerTrack` |
-| `alternate_group` | tkhd | audio/video alternates | `ContainerTrack.alternateGroup` |
-| `elng` | 14496-12 §8.4.6 | all | `ContainerTrack.languageBcp47` |
+# Container & Track architecture
+
+Domain → Application → Interface, per RFC 9559 (Matroska) and ISO/IEC 14496-12 (MP4).
+
+## Two axes, and what is NOT a third
+
+Everything here is placed on exactly two axes: **which container** a track lives
+in, and **what kind of track** it is (video / audio / subtitle). A file lying
+beside the video — a dub as `<name>.mka`, subtitles as `<name>.ass` — is not a
+third kind of anything:
+
+- a `.mka` **is** Matroska. `ContainerFactory` sniffs it, `MatroskaContainer`
+  reads its `TrackEntry` list, and out comes an `AudioTrack` with its language,
+  title and flags. It differs from the picture's own file only in having no
+  video track. The same holds for `.m4a` and `Mp4Container`;
+- "external" is therefore not a TYPE. It is the answer to WHERE a track's bytes
+  are, and that is torrent knowledge — which this layer must not have
+  (`ContainerFactory`: no torrent knowledge; `ContainerOrchestrator`:
+  transport-agnostic). The pairing of a sidecar file with a picture lives in
+  `services/sidecar-files.js`, and the numbered list a viewer chooses from lives
+  in `services/media/audio-inventory.js`. Both are pure and both are application-layer.
+
+A class called `ExternalSubtitleFile` used to sit in `tracks/` asserting the
+opposite. It did not extend `ContainerTrack`, duplicated four of its fields, and
+was imported by nothing; it was deleted rather than extended. Nothing replaced
+it — a subtitle file beside the video is a `TextSubtitleTrack` whose bytes are
+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.
+
+**That split is closed.** `SubtitleTrack` carries `clusterPositions` and
+`samples` — byte POSITIONS — and the reading of those positions is now the
+container's: `MatroskaContainer.walkHeldClusters(plan, walked)` and
+`Mp4Container.readHeldSamples(track, harvested)`, beside `readTracks`,
+`readKeyframeIndex`, `readMediaInfo` and `cueTextOf`.
+
+The obstacle was real and this is how it was answered. The two readers want
+different read POLICIES over the same file: the track table fetches what is
+missing from the swarm, while the cue walk deliberately reads only what is
+already downloaded, so that turning subtitles on never pulls bytes the viewer is
+not waiting for. A container is now built with BOTH — `readRange` that fetches,
+`readHeld` that does not, and `isHeld` that says whether a range can be read
+without fetching — so one instance per file serves both readers and the per-file
+cache is kept.
+
+What the container is NOT given is the torrent. Those three functions are the
+whole of what the caller knows and the container does not, and reducing the
+torrent to them is what lets the reading live where the format is specified.
+`torrent-worker/subtitle-cues.js` supplies them (`containerOver`) and keeps only
+what is genuinely its own: the found-order cursor a browser follows, the
+per-file state, and one walk of a file at a time.
+
+## Layers
+
+```mermaid
+flowchart TB
+  subgraph Domain
+    C[Container<br/>abstract<br/>RFC9559 / 14496-12]
+    MC[MatroskaContainer]
+    MpC[Mp4Container]
+    AC[AviContainer]
+    CT[ContainerTrack<br/>isEnabled/isDefault/language]
+    VT[VideoTrack]
+    AT[AudioTrack]
+    ST[SubtitleTrack]
+    TST[TextSubtitleTrack<br/>S_TEXT/UTF8 tx3g wvtt]
+    IST[ImageSubtitleTrack<br/>PGS VobSub subp]
+    C --> MC & MpC & AC
+    CT --> VT & AT & ST
+    ST --> TST & IST
+    MC & MpC & AC -- readTracks --> CT
+  end
+  subgraph Application
+    CF[ContainerFactory<br/>detect 16 bytes]
+    KT[KeyframeTables<br/>one read per file, bounded wait]
+    CO[ContainerOrchestrator<br/>cache + getTracks/getKeyframeIndex]
+    SO[SubtitleOrchestrator<br/>cursor + per-file state]
+    SF[sidecar-files.js<br/>which file goes with which]
+    AI[audio-inventory.js<br/>one flat numbering]
+    CF --> CO
+    CO --> KT
+    CO --> SO
+    SF --> AI
+    CO --> AI
+  end
+  subgraph Interface
+    PC[PlaybackController]
+    SC[SubtitleController]
+    R1[routes/api/playback-plan]
+    R2[routes/api/subtitles]
+    PC --> R1
+    SC --> R2
+    CO --> PC
+    SO --> SC
+  end
+```
+
+## Class responsibilities (spec-grounded)
+
+| Class | Spec section | Fields | Not responsible |
+|---|---|---|---|
+| `ContainerTrack` | RFC9559 TrackEntry common + ISO 14496-12 tkhd/mdhd/hdlr/elng | `trackNumber`, `declaredIndex`, `codecId`, `language`/`languageBcp47` (MUST rule), `name`, `isEnabled` (0xB9 / track_enabled), `isDefault`+`declaresDefault` (0x88) | Type-specific flags |
+| `VideoTrack` | RFC9559 Video, ISO 14496-12 tkhd width/height, stsd | `width/height/display*`, `fps`, `isHdr`, `bitDepth` | Subtitle flags |
+| `AudioTrack` | RFC9559 FlagOriginal 0x55AE, FlagCommentary 0x55AF, FlagVisualImpaired 0x55AC | `isOriginal/isCommentary/isVisualImpaired`, `channels/samplingFrequency` | FlagForced |
+| `SubtitleTrack` | RFC9559 FlagForced 0x55AA (subtitle-only), FlagHearingImpaired 0x55AB | `isForced/isHearingImpaired`, `clusterPositions`/`samples` | Video dims |
+| `TextSubtitleTrack` | `S_TEXT/UTF8, S_TEXT/ASS, tx3g, wvtt` | `toVtt()` convertible | Image tracks |
+| `sidecar-files.js` | — (torrent naming) | which files of a torrent are one picture's sound and subtitles | what is inside them |
+| `audio-inventory.js` | RFC9559 audio flags, merged against ffmpeg's numbering | one flat number per soundtrack → `(fileIndex, 0:a:N)` | display labels |
+| `ImageSubtitleTrack` | `S_HDMV/PGS, S_VOBSUB, subp, clcp` | kept for `declaredIndex` alignment | Conversion |
+| `MatroskaContainer` | RFC9559 SeekHead, Tracks, Cues, Clusters | single Tracks walk for all types, EBML via `ebml-reader.js` | HTTP |
+| `Mp4Container` | ISO 14496-12 moov/trak/tkhd/mdhd/hdlr/elng/stbl | `alternate_group` grouping, packed language, `tx3g` forced bits | Torrent |
+| `AviContainer` | RIFF AVI idx1 | `AVIIF_KEYFRAME` keyframe times | Tracks beyond video |
+
+`VideoTrack` never carries `isForced` — spec states FlagForced "Applies only to subtitles". Placing it in base would pollute video with irrelevant state.
+
+## Orchestrators & Controllers
+
+- `ContainerFactory.create({readRange,fileSize})` — sniffs 16 bytes, returns precise `Container` subclass. No torrent knowledge.
+- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getMediaInfo()` / `getKeyframeIndex()`. Transport-agnostic.
+- **The keyframe table is read once per file, and the container is not what remembers it.** `Container.readKeyframeIndex` parses and returns; each format implements `parseKeyframeIndex`. It used to keep the answer, and that made this the one fact stored in two places — here and in the file's `KeyframeTable` on the main thread. That copy had no reader, and since the parse itself moved to the main thread there is no second thread for a second copy to sit in.
+- **`KeyframeTable` / `KeyframeTables` — the answer, and the policy around getting one.** The table is one object per file (`media/container/KeyframeTable.js`), held by everyone who reads that file rather than copied, so a read that lands after a session was made still reaches it. `media/KeyframeTables.js` reads it once per file whoever asks, joins the second asker to the read already running, bounds how long any one caller waits (`KEYFRAME_TABLE_BUDGET_MS`, measured), and never records a read that threw as an answer. Its reader is one function handed in at construction, so it knows nothing of torrents or HTTP. It is not `ContainerOrchestrator` because of the THREAD: that one needs byte ranges and lives in the worker, this one lives beside the sessions and reaches it across the channel.
+- **`answered` and `readable` are different questions.** `answered` says a reader came back; `readable` says it came back with times. A file that answered nothing must be re-encoded for ever (MPEG-TS: 669 real keyframes, no index of any kind); a file that has not answered is a shortage of bytes off the swarm. Held as loose fields in a bag of probe results nothing told them apart, and a passing shortage was written onto the file as a property of the bytes.
+- **The second reader is the packet probe** (`media/keyframe-probe.js`): it finds keyframes by decoding, for containers that state no index. It is never waited for, and `KeyframeTable.learn` keeps the fuller answer whichever arrives second — measured 2026-08-02, a scan found 77 keyframes in 45 s without finishing against all 570 in 0.8 s from the index.
+- `SubtitleOrchestrator` — wraps `torrent-worker/subtitle-cues.js` (`planFor`, `cuesHeldFor`, `warmSubtitleCues`) behind the `ContainerTrack` abstraction. Routes depend on this, not on the worker directly. The reading itself is the containers' — that module supplies the torrent's read policy and keeps the cursor.
+- `PlaybackController` / `SubtitleController` — thin interface adapters; `routes/api/*` delegate to them, handle HTTP headers (`X-Subtitle-Language`, `X-Subtitle-Cursor`) only.
+
+## Legacy
+
+Everything a container states about ITSELF is in its own class: the track table,
+the Cues, the keyframe times they name, the cluster positions, the blocks inside
+a cluster, the MP4 sample table. `services/container-index/` no longer exists.
+What was kept apart is `container/ebml-reader.js` — EBML element walking is the
+format's grammar rather than any of its statements.
+
+`ContainerFactory` is the one place that decides what a file IS. It sniffs the
+header, because that is what the muxer wrote while a name is what somebody
+typed, and it answers `readKeyframeIndex` for the same reason: doing it anywhere
+else meant a third place making that decision. `ContainerFactory.byName` exists
+for the one path that cannot sniff — the cue walk asks the swarm for nothing, so
+a file whose head is not downloaded has only its name.
+
+**Two readings of one file, and which answers.** ffmpeg's `-i` banner and the
+container's own table both describe a file's tracks, and the rule is stated once
+per media kind on `Container`. `alignWithBanner` lines them up by position and
+CHECKS each pair on language or title; one pair agreeing on neither, or a length
+that differs, drops the container reading whole, because a wrong flag is worse
+than a missing one. `mergeSubtitleFlags`, `mergeAudioFlags` and
+`mergeVideoFacts` then say which side answers for which field: flags the banner
+cannot express come from the container; the coded size and frame rate come from
+the probe, because the encoder receives what the decoder produced.
+
+Direct imports from routes are deprecated — use `orchestrators/` and
+`server/controllers/` instead.
+
+## Flags matrix
+
+| Flag | Matroska ID | Applies to | Base or subclass |
+|---|---|---|---|
+| `FlagEnabled` | 0xB9 default 1 | all | `ContainerTrack` |
+| `FlagDefault` | 0x88 default 1 | all | `ContainerTrack` (`declaresDefault`) |
+| `Language` | 0x22B59C | all | `ContainerTrack` |
+| `LanguageBCP47` | 0x22B59D MUST | all | `ContainerTrack` |
+| `FlagForced` | 0x55AA | subtitle only | `SubtitleTrack` |
+| `FlagHearingImpaired` | 0x55AB | subtitle | `SubtitleTrack` |
+| `FlagVisualImpaired` | 0x55AC | audio (descriptive) + subtitle | `AudioTrack`/`SubtitleTrack` |
+| `FlagOriginal` | 0x55AE | audio | `AudioTrack` |
+| `FlagCommentary` | 0x55AF | audio | `AudioTrack` |
+| `track_enabled` | tkhd 0x000001 | all | `ContainerTrack` |
+| `alternate_group` | tkhd | audio/video alternates | `ContainerTrack.alternateGroup` |
+| `elng` | 14496-12 §8.4.6 | all | `ContainerTrack.languageBcp47` |

package/docs/download-architecture.md

@@ -5,11 +5,11 @@ Two questions, kept apart, and neither of them is "which file".
 ## Two axes, and what is NOT a third
 
 **What somebody needs** — a claimant, a file, a byte range, a level of urgency.
-Stated in `services/demand/`. Knows nothing about WebTorrent, nothing about
+Stated in `services/torrent/demand/`. Knows nothing about WebTorrent, nothing about
 pieces, nothing about the piece store: it is numbers and rules, and it is
 testable without a torrent.
 
-**What the swarm is told** — one class, `services/download/SwarmSelection.js`,
+**What the swarm is told** — one class, `services/torrent/download/SwarmSelection.js`,
 which reads the register and calls `select`, `deselect` and `critical`. It is
 the only thing in this proxy that calls them.
 
@@ -24,14 +24,14 @@ being fetched for as long as the viewer took to choose one.
 
 ```mermaid
 flowchart TB
-  subgraph Statements["services/demand — what is wanted"]
+  subgraph Statements["services/torrent/demand — what is wanted"]
     W[Window<br/>claimant, file, bytes, urgency]
     U[Urgency<br/>BLOCKED NEAR AHEAD TAIL BEHIND]
     R[DemandRegister<br/>live windows by claimant]
     P[pieces.js<br/>the one bytes to pieces conversion]
   end
 
-  subgraph Swarm["services/download — what the swarm is told"]
+  subgraph Swarm["services/torrent/download — what the swarm is told"]
     S[SwarmSelection<br/>select / deselect / critical]
     G[registry<br/>one per torrent + the cross-torrent rule]
   end
@@ -56,7 +56,7 @@ flowchart TB
 ## Who the claimants are, and what each of them knows
 
 **The priority map** states what should be downloaded AHEAD of the viewers, once
-per file, built in `services/priority/` from where they are and from nothing
+per file, built in `services/viewer/` (`PriorityOrchestrator`) from where they are and from nothing
 else. It is the same map the encoding reads — the encoding reads it per OUTPUT
 and in segment numbers, this layer reads it per FILE and in bytes, and both
 scopes are right for what asks them (`encode-architecture.md`).
@@ -189,7 +189,7 @@ throughput at a time (`PIPELINE_MAX_DURATION = 1`).
 A withdrawn window is not in the download set at all, so there is nothing to
 fall through to.
 
-The condition is **global**, in `services/download/registry.js`, and not per
+The condition is **global**, in `services/torrent/download/registry.js`, and not per
 torrent: two films on one proxy share the link, so filling the tail of one while
 a viewer of the other has a still picture spends the same bandwidth twice over.
 
@@ -234,7 +234,7 @@ object; a zero says the thresholds are not what we are short of.
 
 - `claimWindow`, `releaseWindow`, `markCritical`, `clearCritical` in
   `piece-reader.js` — the reader no longer speaks to the library.
-- `#reassertReaderWindows` in `torrent-pool.js` — it read the piece store's
+- `#reassertReaderWindows` in `torrent/torrent-pool.js` — it read the piece store's
   MEMORY claims and rebuilt download claims from them, because WebTorrent
   deletes a selection once satisfied. `SwarmSelection.reconcile` does that from
   the register, which is where the statement lives.