@torrent-tv/proxy 2.88.3 → 2.88.5

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 2.88.5
+
+- **Fix**: Reject closed non-final fragments that do not reach their next declared cut, using measured coded-frame coverage. Remove such previously cached fragments from the inventory so missing media can be produced again instead of indefinitely blocking startup.
+- **Fix**: Compute playback start from measured download, remaining per-run processing and client delivery deadlines, without browser-capacity admission, speculative rate recovery or a capped search. Slow positive service returns a finite delay and locally held input is not downloaded again.
+- **New**: Ship short audio samples and measure per-codec copying and AAC processing at startup. Initial audio sample/byte-work rates and output sizes are refined by actual progress and segment measurements.
+- **Fix**: Apply measured coded-frame join boundaries to video as well as audio, and expose current per-track operations for the waiting overlay.
+
+## 2.88.4
+
+- **Fix**: A copied soundtrack whose rate no figure states no longer refuses the video on any measured link. The container now states each audio track's codec configuration (Matroska `CodecPrivate`, MP4 `esds`), and a copied AAC-LC or AC-3 track weighs the bound its codec allows (`known`); without one it weighs the rate the file states (`estimated`); and a track with neither is re-encoded to stereo AAC even for a browser that plays it. Field case: the next episode opened on a remembered `Rus Sound` dub was refused at 80 Mbit/s.
+- **Fix**: The soundtrack's mode is decided when it is chosen — when a file is opened, including the next episode with a remembered track, and when the page prepares a switch, where `transcode=0|1` now says whether its browser plays that track — and the viewer is recorded as receiving the output actually sent. Switching no longer carries the previous track's mode onto the new track, and a later reading of the file does not change a soundtrack already being sent.
+- **Fix**: A re-encoded soundtrack counts as 128 kbit/s `estimated` rather than `known`: ffmpeg's AAC encoder treats `-b:a` as a target, and the output frequency is not fixed.
+- **Fix**: A late sidecar header merges into its inventory entry by rule: a stated field replaces the old one, an empty one keeps it, and the codec configuration is replaced only whole, kept when the new reading says less, and withdrawn on a contradiction.
+- **Fix**: The learned cost of a soundtrack is keyed by its file, track and mode, so a copy's speed no longer prices an encode and a sidecar's first track no longer shares the picture's first track's price.
+- **Fix**: A refusal names the part of the load that has no figure, and carries the number of soundtracks the viewer can choose from.
+
 ## 2.88.3
 
 - **Fix**: Forecast audio continuity from coded-frame timestamps and durations using the browser's frame-join boundary. Adjacent AAC fragments that Chrome buffers continuously no longer cause an impossible-start forecast; actual gaps and missing deliveries still prevent an unsafe start. Verified against captured segment metadata and independent Chrome SourceBuffer appends.

package/assets/calibration/audio/NOTICE.md

@@ -0,0 +1,19 @@
+# Audio calibration samples
+
+These files contain deterministic synthetic pink noise, encoded at build time
+by `scripts/build-audio-samples.mjs`. They contain no recorded third-party audio.
+The manifest records the actual duration, channels, sample rate and byte count
+reported by ffprobe. They are distributed under the package's GPL-3.0-or-later
+license.
+
+Startup reads each packaged sample once for packet copying and once for AAC
+processing. It neither generates input files nor loops them. The operation
+timeout is the existing encoder benchmark timeout; it is not an ETA coefficient.
+
+Process startup is measured separately from FFmpeg's reported processing time;
+its printed clock precision bounds runtime uncertainty. Input reading is
+included in processing. For encoding, the
+reference work scales by input audio samples (channels multiplied by sample
+rate); for copying, a declared source bitrate scales encoded-byte work. These
+are approximate initial rates, replaced by actual per-output progress. Unknown
+dimensions retain the measured reference rather than fabricated metadata.

package/assets/calibration/audio/manifest.json

@@ -0,0 +1,98 @@
+[
+  {
+    "codec": "aac",
+    "file": "aac.m4a",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 66060
+  },
+  {
+    "codec": "ac3",
+    "file": "ac3.ac3",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 96000
+  },
+  {
+    "codec": "eac3",
+    "file": "eac3.eac3",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 96000
+  },
+  {
+    "codec": "dts",
+    "file": "dts.dts",
+    "durationSeconds": 4.0051,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 706500
+  },
+  {
+    "codec": "flac",
+    "file": "flac.flac",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 723158
+  },
+  {
+    "codec": "opus",
+    "file": "opus.opus",
+    "durationSeconds": 4.0065,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 32457
+  },
+  {
+    "codec": "vorbis",
+    "file": "vorbis.ogg",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 42108
+  },
+  {
+    "codec": "truehd",
+    "file": "truehd.thd",
+    "durationSeconds": null,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 589492
+  },
+  {
+    "codec": "mp3",
+    "file": "mp3.mp3",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 64748
+  },
+  {
+    "codec": "mp2",
+    "file": "mp2.mp2",
+    "durationSeconds": 4.008,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 192384
+  },
+  {
+    "codec": "alac",
+    "file": "alac.m4a",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 712871
+  },
+  {
+    "codec": "pcm",
+    "file": "pcm.wav",
+    "durationSeconds": 4,
+    "channels": 2,
+    "samplingFrequency": 48000,
+    "bytes": 768078
+  }
+]

package/biome.json

@@ -178,6 +178,7 @@
                       "!../learned-median.js",
                       "!../torrent-cost.js",
                       "!../encoder-readings.js",
+                      "!../audio-work-rate.js",
                       "!../contention.js",
                       "!../args.js",
                       "!../encode-run-state.js",

package/docs/browser-proxy-contract.md

@@ -1,133 +1,155 @@
-# 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, shape }`. `files` carries `fileIndex`, `name`, `relativePath`, `length`, and `kind`; `items` maps each video `fileIndex` to audio, subtitle, and image file indices and carries `episode` — what the name states in the release's own numbering (`season`, `episodes`, `part`, `special`, `showHint`, `titleHint`) or `null`. `shape` is `single`, `series` or `undetermined` (2.88.0); an older proxy sends neither field. |
-| `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`,
-`audioTracksPending`, and `pending`. The browser uses the codec fields to make
-the direct-versus-transcode decision itself; `mode` is advisory.
-
-When `audioTracksPending` is `true`, one or more sidecar headers were still
-unavailable. The browser may call `POST /api/playback-plan/audio-tracks` with
-`{ sourceKey, fileIndex }`; the answer contains the current `audioTracks` and
-`pending`. A resolved header updates metadata on the already-published first
-track for that sidecar. It never changes track indices or the number of HLS
-renditions in the active plan.
-
-`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. `playbackReadiness` is the proxy's versioned forecast used to release the startup wait; missing or unsupported versions do not authorize playback. 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. `linkMbps` is the smoothed estimate used by the quality budget; `linkSampleMbps` and `linkSampleAt` carry the newest raw delivery measurement and its sample time for the readiness forecast. `bufferLimitSeconds` states the browser's accepted forward-buffer ceiling. Missing optional values do not reject the report or erase the last known value. 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. |
-
-### Playback readiness forecast
-
-The progress response may include `playbackReadiness`:
-
-| Field | Meaning |
-|---|---|
-| `version` | Forecast contract version. The browser releases its startup wait only for version `1` with `ready: true`. |
-| `ready` | The proxy's simulated buffer trajectory can cover the remaining playback while preserving the measured interruption reserve, starting now. |
-| `delaySeconds` | When `ready` is false, the predicted minimum delay from now to a safe start; `null` means the current measurements do not support a finite forecast. |
-| `bufferedSeconds` | Client buffer reported to the proxy. |
-| `reserveSeconds` | Maximum interruption reserve across the required video and selected audio outputs, derived from each output's measured supply waits and next segment duration. |
-| `neededSeconds` | Reserve shortfall at the current client buffer. |
-| `reason` | Machine-readable result of the forecast. |
-| `preparedSegments` | Number of already-produced output segments available across required tracks. |
-| `bufferedAtStartSeconds` | Forecast playable buffer at the proposed start time, when a finite delay is available. |
-
-The forecast considers the video output and the selected audio output when audio
-is delivered separately. A mixed output can depend on more than one source
-file. Repeated source files are counted once; distinct files keep separate
-remaining-work estimates and share the measured download rate of their torrent.
-The browser reports buffer state and delivery measurements, but does not
-calculate or override readiness.
-
-Service work is the integral of a nonnegative measured-rate forecast. The latest
-rate relaxes over the observed measurement span toward the lower of its latest
-value and the recent mean; the measurement history covers the output look-ahead.
-A positive measured rate cannot become permanently zero from an old declining
-linear fit. A measured zero remains zero until a new measurement arrives.
-The reported loader limit is bounded below by the browser buffer already held.
-During startup waiting the browser refreshes stale delivery measurements through
-the existing link probe and reports their age to avoid clock-offset errors.
-
-## 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.
+# 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, shape }`. `files` carries `fileIndex`, `name`, `relativePath`, `length`, and `kind`; `items` maps each video `fileIndex` to audio, subtitle, and image file indices and carries `episode` — what the name states in the release's own numbering (`season`, `episodes`, `part`, `special`, `showHint`, `titleHint`) or `null`. `shape` is `single`, `series` or `undetermined` (2.88.0); an older proxy sends neither field. |
+| `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`,
+`audioTracksPending`, and `pending`. The browser uses the codec fields to make
+the direct-versus-transcode decision itself; `mode` is advisory.
+
+When `audioTracksPending` is `true`, one or more sidecar headers were still
+unavailable. The browser may call `POST /api/playback-plan/audio-tracks` with
+`{ sourceKey, fileIndex }`; the answer contains the current `audioTracks` and
+`pending`. A resolved header updates metadata on the already-published first
+track for that sidecar. It never changes track indices or the number of HLS
+renditions in the active plan.
+
+Each `audioTracks` entry may carry `bitrateKbps`, the average rate the file
+states for the track, and `peakKbps`, the most the track's codec configuration
+allows it to carry (AAC-LC with 1024-sample frames, and AC-3; any other
+configuration has none). Both may be `null`. The browser does not need them;
+the proxy uses them to decide how the track is produced. A late header keeps a
+known value and withdraws `peakKbps` only when it contradicts the configuration
+it was computed from.
+
+`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`,
+`soundtrack`, and `lookaheadSeconds`. `masterPath` and `variantHeight` are
+present only when the session has quality variants.
+
+`transcodeAudio` states whether the browser can play the selected track as it
+is. The proxy decides the actual mode: it copies a track the browser plays
+when the track has a `peakKbps` or a `bitrateKbps`, and otherwise re-encodes it
+to stereo AAC at 128 kbit/s, including a track the browser could play.
+`soundtrack` is `{ trackIndex, transcode }`, the track this viewer is sent and
+whether it is re-encoded. Older proxies omit it.
+
+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. For
+`output-unavailable`, `figures.verdict` is `"no safe bound"` when a part of the
+load has no figure; `figures.videoClass` and `figures.audioClass` are
+`"unknown"` for that part, and `figures.soundtracks` is the number of
+soundtracks the viewer can choose from.
+
+## 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. `playbackReadiness` is the proxy's versioned forecast used to release the startup wait; missing or unsupported versions do not authorize playback. 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. `linkMbps` is the smoothed estimate used by the quality budget; `linkSampleMbps` and `linkSampleAt` carry the newest raw delivery measurement and its sample time for the readiness forecast. `bufferLimitSeconds` states the browser's accepted forward-buffer ceiling. Missing optional values do not reject the report or erase the last known value. 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. Audio warm-up takes an optional `transcode=0\|1`: whether the browser cannot play THAT track's codec as it is. The proxy decides the track's mode by the rule used when a file is opened; without the parameter it assumes the browser needs what it needed for its current track. |
+| `GET /stream?sourceKey=…&fileIndex=N` | Direct file bytes with HTTP range support. |
+
+### Playback readiness forecast
+
+The progress response may include `playbackReadiness`:
+
+| Field | Meaning |
+|---|---|
+| `version` | Forecast contract version. The browser releases its startup wait only for version `1` with `ready: true`. |
+| `ready` | The measured service model meets the remaining presentation deadlines and real client tracks cover the current position. Browser capacity is not an admission condition. |
+| `delaySeconds` | When `ready` is false, the predicted minimum delay from now to a safe start; `null` means the current measurements do not support a finite forecast. |
+| `measuredAt`, `predictedStartAt` | Proxy-clock observation and conditional start time, in milliseconds. The UI counts down using its own elapsed clock, without comparing clocks across machines. |
+| `operations` | Required video/audio operations, their source/output codecs, current speed and processed position. |
+| `preparedUntilSeconds` | Continuous proxy media predicted to be available at the forecast start. |
+| `bufferedSeconds` | Client buffer reported to the proxy. |
+| `reserveSeconds` | Maximum interruption reserve across the required video and selected audio outputs, derived from each output's measured supply waits and next segment duration. |
+| `neededSeconds` | Reserve shortfall at the current client buffer. |
+| `reason` | Machine-readable result of the forecast. |
+| `preparedSegments` | Number of already-produced output segments available across required tracks. |
+| `bufferedAtStartSeconds` | Forecast playable buffer at the proposed start time, when a finite delay is available. |
+
+The forecast considers the video output and the selected audio output when audio
+is delivered separately. A mixed output can depend on more than one source
+file. Repeated source files are counted once; distinct files keep separate
+remaining-work estimates and share the measured download rate of their torrent.
+The browser reports buffer state and delivery measurements, but does not
+calculate or override readiness.
+
+Service work is the integral of a nonnegative measured-rate forecast. The latest
+rate relaxes over the observed measurement span toward the lower of its latest
+value and the recent mean; the measurement history covers the output look-ahead.
+A positive measured rate cannot become permanently zero from an old declining
+linear fit. A measured zero remains zero until a new measurement arrives.
+The reported loader limit is bounded below by the browser buffer already held.
+During startup waiting the browser refreshes stale delivery measurements through
+the existing link probe and reports their age to avoid clock-offset errors.
+
+## 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/playback-start-forecast.md

@@ -0,0 +1,56 @@
+# Playback start forecast
+
+For resource r, measured service is S_r(t) = rate_r * t. New observations
+replace the conditional future rate; polling cannot invent acceleration,
+exponential recovery or a new physical measurement.
+
+Source work uses the file's measured byte density, missing local byte ranges
+and the observed torrent download rate. Shared input ranges are downloaded
+once. Files on the same torrent share a queue; distinct torrents use distinct
+observed services. Local input reading is included in effective processing
+speed, rather than charged again as a separate disk or memory delay.
+
+Each output's remaining processing work subtracts progress only within its
+actual live run intervals. Initial video rates use existing codec/size/encoder
+calibration. Initial audio rates use short packaged per-codec measurements and
+sample work (encoding) or encoded bytes (copying). Actual output progress
+replaces these initial rates. Startup is charged once, separately from processing
+throughput, and disappears once actual run progress establishes processing.
+
+Input arrival and processing overlap. With arrival time D(m), processing rate
+e and previous completion C, completion for an interval [a,b] is
+
+    max(C + (b-a)/e, sup_m(D(m) + (b-m)/e)).
+
+Between service boundaries these functions are linear, so only endpoints are
+needed. Client delivery follows production and shares the observed link queue.
+Measured client ranges and prepared media establish each track's deadlines.
+
+The minimum start delay for this conditional trajectory is
+
+    max(0, max_j(completion_j - presentation_deadline_j)).
+
+This covers the remaining finite movie, including rates below real time. Slow
+positive service gives a finite preproduction delay; it is not rejected by a
+browser-capacity threshold or a capped search. Observed supply-interruption
+coverage is held in prepared proxy media and client media, without requiring
+the browser to hold it all.
+
+Critical review: future rates can change, average byte density is an initial
+mapping rather than an exact packet index, initial audio sample-work scaling
+does not model every decoder's nonlinear cost, and client receive/append time
+is not separately measured. These are approximation limits, not hidden weights.
+Actual progress, segment sizes and link observations refine the prediction.
+The client countdown uses elapsed local monotonic time; expiration cannot
+authorize playback. Only the proxy's readiness and real track coverage can.
+
+Zero service, missing media facts and a genuine timestamp gap remain explicit
+noncomputable states. The UI reports their causes instead of an estimating
+placeholder or a fabricated duration. Small coded-frame joins follow measured
+frame durations and Chromium's continuous-track rule, not a hand-picked margin.
+
+A closed non-final fragment is reusable only if its measured coded-frame
+coverage reaches its next declared cut. Interrupted one-frame fragments are
+excluded on publication and when reading an existing cache, so the production
+schedule treats their media as unfinished work. The final fragment uses its
+actual media end rather than the container's approximate duration.

package/package.json

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

package/routes/api/transcode-sessions/post.js

@@ -139,6 +139,11 @@ export async function handleApiTranscodeSessionsPost(req, reply, { viewerRequest
       // track that never arrives is otherwise noticed only by its absence,
       // minutes later, as a black picture with working sound.
       tracks: renditions.declaredTracks(session),
+      // The soundtrack this viewer is sent and whether it is re-encoded — the
+      // proxy's decision, which can differ from what the page asked for: a
+      // track no figure states a rate for is re-encoded even for a browser that
+      // would play it, so its load on the viewer's link can be asked about.
+      soundtrack: renditions.soundtrackOf(session, consumerId),
       // How far ahead of the viewer this proxy lets the encoder run, in seconds
       // of playback. The browser sizes its own forward buffer from it, so the
       // two sides agree by construction instead of each carrying a constant of

package/routes/transcode/audio-warm/get.js

@@ -1,6 +1,13 @@
 /**
- * @file GET /transcode/:sessionId/a/:track/warm?position=<seconds> — prepare an
- * audio track before the player is told to change to it.
+ * @file GET /transcode/:sessionId/a/:track/warm?position=<seconds>[&transcode=0|1]
+ * — prepare an audio track before the player is told to change to it.
+ *
+ * `transcode` is the page's statement about THIS track: `1` when its browser
+ * cannot play the track's codec as it stands, `0` when it can. The proxy then
+ * decides how the track is produced by the same rule as when a file is opened
+ * — a track nothing states a rate for is re-encoded even for a browser that
+ * would play it. Left out, the page is taken to need what it needs for the
+ * track it is on.
  *
  * The picture keeps playing while a quality rung is warmed (`variant-warm`),
  * and a track change deserves the same: the player discards the audio it holds
@@ -44,13 +51,17 @@ export async function handleTranscodeAudioWarmGet(req, reply, { renditions, serv
     return reply.code(400).send({ error: "A consumer is required." });
   }
 
+  const statedNeed = req.query?.transcode;
+  const browserPlays = statedNeed === "0" ? true : statedNeed === "1" ? false : null;
+
   let prepared;
   try {
     prepared = await renditions.prepareAudioTrack(
       baseSessionId,
       trackIndex,
       positionSeconds,
-      consumerId
+      consumerId,
+      browserPlays
     );
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);