@torrent-tv/proxy 2.87.10 → 2.87.12

package/openspec/changes/track-selection/specs/track-selection/spec.md

@@ -1,41 +1,41 @@
-# track-selection — delta spec
-
-## ADDED Requirements
-
-### Requirement: The playback plan lists every track
-The playback plan SHALL include `audioTracks` and `subtitleTracks` arrays
-parsed from the probe: for each track its type-relative index (what
-`-map 0:a:N` / `0:s:N` selects), codec, language tag, `title` metadata,
-default disposition, and — for subtitles — a `textBased` flag. Output-side
-streams of the probe run MUST NOT leak into the inventory.
-
-#### Scenario: MKV with an embedded subtitle
-- **WHEN** the plan is requested for an MKV with one video, one audio and one
-  ASS subtitle stream
-- **THEN** the plan lists exactly one audio track and one subtitle track with
-  `textBased: true`
-
-### Requirement: Audio track selection
-`POST /api/transcode-sessions` SHALL accept `audioTrackIndex` (type-relative,
-default 0) and the session SHALL map that audio track. The index SHALL be
-part of the session identity so different tracks never share a session.
-
-#### Scenario: Second audio track
-- **WHEN** a session is created with `audioTrackIndex: 1`
-- **THEN** ffmpeg maps `0:a:1` and a later request with `audioTrackIndex: 0`
-  gets a different session
-
-### Requirement: Embedded subtitles as WebVTT
-`GET /api/subtitles?sourceKey&fileIndex&trackIndex` SHALL stream the chosen
-embedded TEXT subtitle track converted to WebVTT, starting the response as
-soon as ffmpeg produces output. A track that produces no output (image-based
-or broken) SHALL return 422 before any body. Extraction MUST stop when the
-client disconnects.
-
-#### Scenario: Text track extracted
-- **WHEN** the client requests a text subtitle track
-- **THEN** the response is `text/vtt` starting with `WEBVTT` and real cues
-
-#### Scenario: Image-based track refused
-- **WHEN** the client requests a PGS/VobSub track
-- **THEN** the proxy responds 422 with an explanatory error
+# track-selection — delta spec
+
+## ADDED Requirements
+
+### Requirement: The playback plan lists every track
+The playback plan SHALL include `audioTracks` and `subtitleTracks` arrays
+parsed from the probe: for each track its type-relative index (what
+`-map 0:a:N` / `0:s:N` selects), codec, language tag, `title` metadata,
+default disposition, and — for subtitles — a `textBased` flag. Output-side
+streams of the probe run MUST NOT leak into the inventory.
+
+#### Scenario: MKV with an embedded subtitle
+- **WHEN** the plan is requested for an MKV with one video, one audio and one
+  ASS subtitle stream
+- **THEN** the plan lists exactly one audio track and one subtitle track with
+  `textBased: true`
+
+### Requirement: Audio track selection
+`POST /api/transcode-sessions` SHALL accept `audioTrackIndex` (type-relative,
+default 0) and the session SHALL map that audio track. The index SHALL be
+part of the session identity so different tracks never share a session.
+
+#### Scenario: Second audio track
+- **WHEN** a session is created with `audioTrackIndex: 1`
+- **THEN** ffmpeg maps `0:a:1` and a later request with `audioTrackIndex: 0`
+  gets a different session
+
+### Requirement: Embedded subtitles as WebVTT
+`GET /api/subtitles?sourceKey&fileIndex&trackIndex` SHALL stream the chosen
+embedded TEXT subtitle track converted to WebVTT, starting the response as
+soon as ffmpeg produces output. A track that produces no output (image-based
+or broken) SHALL return 422 before any body. Extraction MUST stop when the
+client disconnects.
+
+#### Scenario: Text track extracted
+- **WHEN** the client requests a text subtitle track
+- **THEN** the response is `text/vtt` starting with `WEBVTT` and real cues
+
+#### Scenario: Image-based track refused
+- **WHEN** the client requests a PGS/VobSub track
+- **THEN** the proxy responds 422 with an explanatory error

package/openspec/changes/track-selection/tasks.md

@@ -1,20 +1,20 @@
-# Tasks: Track inventory, audio selection and embedded-subtitle extraction
-
-## 1. Implementation
-
-- [x] 1.1 playback-planner: input-section stream scanner (index, codec,
-      language, title, default, textBased); `audioTracks`/`subtitleTracks`
-      in the plan (verified against real ffmpeg output from the owner's MKV:
-      hevc + flac + ass(eng) parsed, output streams excluded)
-- [x] 1.2 hls-session-manager: `audioTrackIndex` option → `-map 0:a:N`,
-      part of the session key; transcode-sessions route passthrough
-- [x] 1.3 routes/api/subtitles/get.js: streaming WebVTT extraction, 422 on
-      no-output tracks, kill on client disconnect, 30 min cap (verified:
-      real cues extracted from the embedded ASS track over the LAN proxy)
-- [x] 1.4 torrent-pool: mask the announce query string (passkey)
-
-## 2. Release
-
-- [ ] 2.1 `npm run patch` (2.9.26; needs npm 2FA), then ha-addon 0.2.48
-- [ ] 2.2 After the addon updates: verify plan lists tracks and
-      /api/subtitles serves VTT from the addon proxy
+# Tasks: Track inventory, audio selection and embedded-subtitle extraction
+
+## 1. Implementation
+
+- [x] 1.1 playback-planner: input-section stream scanner (index, codec,
+      language, title, default, textBased); `audioTracks`/`subtitleTracks`
+      in the plan (verified against real ffmpeg output from the owner's MKV:
+      hevc + flac + ass(eng) parsed, output streams excluded)
+- [x] 1.2 hls-session-manager: `audioTrackIndex` option → `-map 0:a:N`,
+      part of the session key; transcode-sessions route passthrough
+- [x] 1.3 routes/api/subtitles/get.js: streaming WebVTT extraction, 422 on
+      no-output tracks, kill on client disconnect, 30 min cap (verified:
+      real cues extracted from the embedded ASS track over the LAN proxy)
+- [x] 1.4 torrent-pool: mask the announce query string (passkey)
+
+## 2. Release
+
+- [ ] 2.1 `npm run patch` (2.9.26; needs npm 2FA), then ha-addon 0.2.48
+- [ ] 2.2 After the addon updates: verify plan lists tracks and
+      /api/subtitles serves VTT from the addon proxy

package/openspec/changes/transcode-quality/.openspec.yaml

@@ -1,2 +1,2 @@
-schema: spec-driven
-created: 2026-07-07
+schema: spec-driven
+created: 2026-07-07

package/openspec/changes/transcode-quality/proposal.md

@@ -1,51 +1,51 @@
-# Proposal: Transcode quality — source fps, realtime budget, HDR, manual quality
-
-## Why
-
-The transcode pipeline was tuned for "make it play at all" and left several
-quality/robustness gaps flagged in the project analysis: output was hard-
-locked to 24 fps (25/30 fps content played with resampling judder); the
-encoder profile could be slower than realtime on weak hosts (stalls instead
-of graceful degradation); 10-bit/HDR sources transcoded to 8-bit H.264
-without tone mapping (washed-out colours); and the viewer had no way to force
-a resolution. This change is the transcode-stage batch (proxy side; the
-manual-quality menu also needs the server UI).
-
-## What Changes
-
-- **Source fps** (DONE): the output frame rate is inherited from the source
-  (rounded to an integer, capped at 30), replacing the fixed 24. The
-  fixed-GOP encoders keep the fps↔GOP relationship exact so keyframes stay on
-  the segment grid; time-based-keyframe encoders (nvenc) just use it as the
-  rate; VAAPI/QSV already inherited.
-- **Realtime budget** (planned): the startup benchmark picks the
-  encoder/preset/resolution/fps combination whose predicted throughput stays
-  above realtime; a source that would not encode in time is downscaled
-  (720/540p) rather than refused, and a sustained runtime `speed<1` triggers
-  a restart with a lighter profile. `-maxrate`/`-bufsize` cap bitrate spikes.
-- **HDR tone mapping** (planned): detect 10-bit/HDR (pix_fmt,
-  color_transfer smpte2084/HLG) and insert a tone-map chain when re-encoding
-  to 8-bit H.264, so colours are not washed out. Depends on the ffmpeg build
-  having the tonemap filters.
-- **Manual quality** (planned): a player Quality menu — Auto (current
-  viewport/DPR behaviour) plus forced resolutions — the proxy already
-  honours a requested target height.
-
-## Capabilities
-
-### New Capabilities
-
-- `transcode-quality`: output frame rate, realtime encode budget, HDR tone
-  mapping, and explicit quality selection.
-
-### Modified Capabilities
-
-<!-- none -->
-
-## Impact
-
-- `services/encode/hwaccel.js` (fps, benchmark, tonemap args),
-  `services/hls-session-manager.js` (fps probe, runtime speed watch),
-  `services/playback-planner.js` (HDR/fps in the plan);
-  server player UI for the Quality menu; ha-addon bump.
-- Released as a batch (proxy 2.9.29 + addon) after the pieces land.
+# Proposal: Transcode quality — source fps, realtime budget, HDR, manual quality
+
+## Why
+
+The transcode pipeline was tuned for "make it play at all" and left several
+quality/robustness gaps flagged in the project analysis: output was hard-
+locked to 24 fps (25/30 fps content played with resampling judder); the
+encoder profile could be slower than realtime on weak hosts (stalls instead
+of graceful degradation); 10-bit/HDR sources transcoded to 8-bit H.264
+without tone mapping (washed-out colours); and the viewer had no way to force
+a resolution. This change is the transcode-stage batch (proxy side; the
+manual-quality menu also needs the server UI).
+
+## What Changes
+
+- **Source fps** (DONE): the output frame rate is inherited from the source
+  (rounded to an integer, capped at 30), replacing the fixed 24. The
+  fixed-GOP encoders keep the fps↔GOP relationship exact so keyframes stay on
+  the segment grid; time-based-keyframe encoders (nvenc) just use it as the
+  rate; VAAPI/QSV already inherited.
+- **Realtime budget** (planned): the startup benchmark picks the
+  encoder/preset/resolution/fps combination whose predicted throughput stays
+  above realtime; a source that would not encode in time is downscaled
+  (720/540p) rather than refused, and a sustained runtime `speed<1` triggers
+  a restart with a lighter profile. `-maxrate`/`-bufsize` cap bitrate spikes.
+- **HDR tone mapping** (planned): detect 10-bit/HDR (pix_fmt,
+  color_transfer smpte2084/HLG) and insert a tone-map chain when re-encoding
+  to 8-bit H.264, so colours are not washed out. Depends on the ffmpeg build
+  having the tonemap filters.
+- **Manual quality** (planned): a player Quality menu — Auto (current
+  viewport/DPR behaviour) plus forced resolutions — the proxy already
+  honours a requested target height.
+
+## Capabilities
+
+### New Capabilities
+
+- `transcode-quality`: output frame rate, realtime encode budget, HDR tone
+  mapping, and explicit quality selection.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- `services/encode/hwaccel.js` (fps, benchmark, tonemap args),
+  `services/hls-session-manager.js` (fps probe, runtime speed watch),
+  `services/playback-planner.js` (HDR/fps in the plan);
+  server player UI for the Quality menu; ha-addon bump.
+- Released as a batch (proxy 2.9.29 + addon) after the pieces land.

package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md

@@ -1,139 +1,139 @@
-# transcode-quality — delta spec
-
-## ADDED Requirements
-
-### Requirement: Output frame rate follows the source
-When re-encoding video, the proxy SHALL NOT force a fixed 24 fps. The output
-rate SHALL follow the source, and the fps handling SHALL depend on how the
-chosen encoder places keyframes:
-
-- Frame-count-GOP encoders (software libx264, v4l2m2m) SHALL use an INTEGER
-  output rate — source rate rounded and capped — with the `fps` filter and
-  the GOP length (`segmentDuration × fps`) using that same integer, so a
-  keyframe lands on every segment boundary and segments do not drift off the
-  synthetic playlist's uniform grid. When the source rate is unknown they
-  SHALL fall back to the default rate.
-- Time-based-keyframe encoders (nvenc, vaapi, qsv) SHALL inherit the exact
-  source rate with no fps filter (their keyframes are forced by output time,
-  so any rate segments correctly); no rounding, no cap.
-
-#### Scenario: 25 fps source on the software encoder
-- **WHEN** a 25 fps video is re-encoded with libx264 and 4-second segments
-- **THEN** the output is 25 fps and the GOP is 100 frames (keyframe every
-  segment)
-
-#### Scenario: High-fps source on the software encoder
-- **WHEN** a 60 fps video is re-encoded with libx264/v4l2m2m
-- **THEN** the output rate is capped at 30 fps (speed guard)
-
-#### Scenario: Fractional source on a hardware time-based encoder
-- **WHEN** a 23.976 fps video is re-encoded with nvenc/vaapi/qsv
-- **THEN** the exact source rate is kept (no fps filter) and segments are
-  still cut on time
-
-#### Scenario: Unknown source rate
-- **WHEN** the source frame rate cannot be probed on the software path
-- **THEN** the output falls back to the default rate and playback still
-  segments correctly
-
-### Requirement: Software encode fits a realtime budget at startup
-
-For the software encoder, the proxy SHALL choose the output resolution and
-libx264 preset a startup benchmark predicts this host can encode faster than
-realtime (with a margin), rather than always encoding at the client-requested
-resolution. The client-requested box, capped to the source resolution (never
-upscaled), is the ceiling; the proxy SHALL pick the highest resolution rung at
-or below that ceiling that clears the realtime margin, then the highest-quality
-preset that still clears it at that resolution. When even the lowest rung
-cannot clear the margin, the proxy SHALL use the lowest rung (best effort). The
-realtime need SHALL be computed from the session's actual output frame rate.
-Hardware encoders and the no-benchmark case SHALL keep the ceiling resolution
-and the default preset.
-
-#### Scenario: Weak host, source above realtime capacity
-- **WHEN** the software benchmark shows the host cannot encode the source-capped
-  resolution faster than realtime (e.g. 720p60→30 that runs below 1×)
-- **THEN** the proxy downscales to the highest ladder rung that clears the
-  realtime margin (e.g. 480p) instead of encoding sub-realtime at full size
-
-#### Scenario: Capable host
-- **WHEN** the benchmark shows ample headroom at the ceiling resolution
-- **THEN** the proxy keeps the ceiling resolution and spends the headroom on a
-  higher-quality (slower) preset
-
-#### Scenario: Hardware encoder
-- **WHEN** a hardware encoder is selected
-- **THEN** no benchmark-based downscale is applied and the ceiling resolution
-  is used
-
-### Requirement: Software encode downswitches at runtime when CPU-bound
-
-The proxy SHALL, for the software encoder, step the output resolution one rung
-down the ladder and restart the encode at the segment currently being watched
-when a transcode runs below realtime for a sustained window. Before downscaling
-it SHALL determine whether the limit is the encoder or a download-starved
-input — comparing the torrent download rate with the source's average byte rate
-(a fully-downloaded file is never download-bound) — and SHALL NOT downscale when
-the limit is the download (it SHALL log that instead). The downswitch SHALL be
-bounded by a sustained-slow window, a post-action cooldown, a maximum number of
-steps, and a resolution floor, and SHALL reset its slow window on every encode
-(re)start. There SHALL be no automatic upswitch in this version.
-
-#### Scenario: Sustained CPU-bound transcode
-- **WHEN** a software transcode's encoder speed stays below realtime for the
-  sustained window while the input download keeps up
-- **THEN** the proxy downscales one rung and restarts at the current segment,
-  up to the step cap / resolution floor
-
-#### Scenario: Download-limited, not CPU-limited
-- **WHEN** the encoder speed is below realtime but the torrent cannot download
-  the source's byte rate and the file is not fully downloaded
-- **THEN** the proxy does not downscale and logs that the download is the limit
-
-#### Scenario: No thrash after a switch
-- **WHEN** a downswitch (or a viewer seek) has just restarted the encode
-- **THEN** the slow window is reset and no further downswitch occurs until a new
-  sustained-slow window elapses after the cooldown
-
-### Requirement: Manual quality forces a constant resolution
-
-The viewer SHALL be able to force a specific output resolution instead of Auto.
-When a resolution is forced the proxy SHALL encode exactly that box (capped to
-the source, never upscaled) with the realtime budget disabled — no startup
-auto-downscale and no runtime downswitch — so the resolution stays constant for
-the whole session. The browser SHALL offer Auto plus resolutions at or below the
-source height, built from the source resolution reported in the playback plan.
-Selecting a quality SHALL re-open the stream at the new resolution with the
-playback position preserved. Auto SHALL keep the current realtime-budget
-behaviour.
-
-#### Scenario: Forced resolution is constant
-- **WHEN** the viewer forces a resolution (e.g. 480p)
-- **THEN** the proxy encodes at that resolution for the whole session, with no
-  budget downscale or runtime downswitch, and playback resumes at the same
-  position
-
-#### Scenario: Auto
-- **WHEN** the viewer selects Auto
-- **THEN** the proxy applies the realtime budget (startup selection + runtime
-  downswitch) as before
-
-### Requirement: HDR sources are tone-mapped when re-encoded to SDR
-
-The proxy SHALL apply an HDR→BT.709 SDR tone-map chain when re-encoding an HDR
-source (a BT.2020 PQ `smpte2084` or HLG `arib-std-b67` transfer) to 8-bit SDR on
-the software path, so the output is not washed-out — provided this ffmpeg build
-has the required filters. The proxy SHALL detect filter availability (`zscale`
-and `tonemap`) at startup and, when either is missing, SHALL fall back to a
-plain 8-bit convert without failing playback.
-
-#### Scenario: HDR source, filters available
-- **WHEN** an HDR source is re-encoded on the software path and the build has
-  `zscale` + `tonemap`
-- **THEN** the tone-map chain is inserted and the output is BT.709 SDR (not
-  washed-out)
-
-#### Scenario: HDR source, filters missing
-- **WHEN** an HDR source is re-encoded but the build lacks `zscale`/`tonemap`
-- **THEN** playback still proceeds with a plain 8-bit convert (no tone map) and
-  the limitation is logged
+# transcode-quality — delta spec
+
+## ADDED Requirements
+
+### Requirement: Output frame rate follows the source
+When re-encoding video, the proxy SHALL NOT force a fixed 24 fps. The output
+rate SHALL follow the source, and the fps handling SHALL depend on how the
+chosen encoder places keyframes:
+
+- Frame-count-GOP encoders (software libx264, v4l2m2m) SHALL use an INTEGER
+  output rate — source rate rounded and capped — with the `fps` filter and
+  the GOP length (`segmentDuration × fps`) using that same integer, so a
+  keyframe lands on every segment boundary and segments do not drift off the
+  synthetic playlist's uniform grid. When the source rate is unknown they
+  SHALL fall back to the default rate.
+- Time-based-keyframe encoders (nvenc, vaapi, qsv) SHALL inherit the exact
+  source rate with no fps filter (their keyframes are forced by output time,
+  so any rate segments correctly); no rounding, no cap.
+
+#### Scenario: 25 fps source on the software encoder
+- **WHEN** a 25 fps video is re-encoded with libx264 and 4-second segments
+- **THEN** the output is 25 fps and the GOP is 100 frames (keyframe every
+  segment)
+
+#### Scenario: High-fps source on the software encoder
+- **WHEN** a 60 fps video is re-encoded with libx264/v4l2m2m
+- **THEN** the output rate is capped at 30 fps (speed guard)
+
+#### Scenario: Fractional source on a hardware time-based encoder
+- **WHEN** a 23.976 fps video is re-encoded with nvenc/vaapi/qsv
+- **THEN** the exact source rate is kept (no fps filter) and segments are
+  still cut on time
+
+#### Scenario: Unknown source rate
+- **WHEN** the source frame rate cannot be probed on the software path
+- **THEN** the output falls back to the default rate and playback still
+  segments correctly
+
+### Requirement: Software encode fits a realtime budget at startup
+
+For the software encoder, the proxy SHALL choose the output resolution and
+libx264 preset a startup benchmark predicts this host can encode faster than
+realtime (with a margin), rather than always encoding at the client-requested
+resolution. The client-requested box, capped to the source resolution (never
+upscaled), is the ceiling; the proxy SHALL pick the highest resolution rung at
+or below that ceiling that clears the realtime margin, then the highest-quality
+preset that still clears it at that resolution. When even the lowest rung
+cannot clear the margin, the proxy SHALL use the lowest rung (best effort). The
+realtime need SHALL be computed from the session's actual output frame rate.
+Hardware encoders and the no-benchmark case SHALL keep the ceiling resolution
+and the default preset.
+
+#### Scenario: Weak host, source above realtime capacity
+- **WHEN** the software benchmark shows the host cannot encode the source-capped
+  resolution faster than realtime (e.g. 720p60→30 that runs below 1×)
+- **THEN** the proxy downscales to the highest ladder rung that clears the
+  realtime margin (e.g. 480p) instead of encoding sub-realtime at full size
+
+#### Scenario: Capable host
+- **WHEN** the benchmark shows ample headroom at the ceiling resolution
+- **THEN** the proxy keeps the ceiling resolution and spends the headroom on a
+  higher-quality (slower) preset
+
+#### Scenario: Hardware encoder
+- **WHEN** a hardware encoder is selected
+- **THEN** no benchmark-based downscale is applied and the ceiling resolution
+  is used
+
+### Requirement: Software encode downswitches at runtime when CPU-bound
+
+The proxy SHALL, for the software encoder, step the output resolution one rung
+down the ladder and restart the encode at the segment currently being watched
+when a transcode runs below realtime for a sustained window. Before downscaling
+it SHALL determine whether the limit is the encoder or a download-starved
+input — comparing the torrent download rate with the source's average byte rate
+(a fully-downloaded file is never download-bound) — and SHALL NOT downscale when
+the limit is the download (it SHALL log that instead). The downswitch SHALL be
+bounded by a sustained-slow window, a post-action cooldown, a maximum number of
+steps, and a resolution floor, and SHALL reset its slow window on every encode
+(re)start. There SHALL be no automatic upswitch in this version.
+
+#### Scenario: Sustained CPU-bound transcode
+- **WHEN** a software transcode's encoder speed stays below realtime for the
+  sustained window while the input download keeps up
+- **THEN** the proxy downscales one rung and restarts at the current segment,
+  up to the step cap / resolution floor
+
+#### Scenario: Download-limited, not CPU-limited
+- **WHEN** the encoder speed is below realtime but the torrent cannot download
+  the source's byte rate and the file is not fully downloaded
+- **THEN** the proxy does not downscale and logs that the download is the limit
+
+#### Scenario: No thrash after a switch
+- **WHEN** a downswitch (or a viewer seek) has just restarted the encode
+- **THEN** the slow window is reset and no further downswitch occurs until a new
+  sustained-slow window elapses after the cooldown
+
+### Requirement: Manual quality forces a constant resolution
+
+The viewer SHALL be able to force a specific output resolution instead of Auto.
+When a resolution is forced the proxy SHALL encode exactly that box (capped to
+the source, never upscaled) with the realtime budget disabled — no startup
+auto-downscale and no runtime downswitch — so the resolution stays constant for
+the whole session. The browser SHALL offer Auto plus resolutions at or below the
+source height, built from the source resolution reported in the playback plan.
+Selecting a quality SHALL re-open the stream at the new resolution with the
+playback position preserved. Auto SHALL keep the current realtime-budget
+behaviour.
+
+#### Scenario: Forced resolution is constant
+- **WHEN** the viewer forces a resolution (e.g. 480p)
+- **THEN** the proxy encodes at that resolution for the whole session, with no
+  budget downscale or runtime downswitch, and playback resumes at the same
+  position
+
+#### Scenario: Auto
+- **WHEN** the viewer selects Auto
+- **THEN** the proxy applies the realtime budget (startup selection + runtime
+  downswitch) as before
+
+### Requirement: HDR sources are tone-mapped when re-encoded to SDR
+
+The proxy SHALL apply an HDR→BT.709 SDR tone-map chain when re-encoding an HDR
+source (a BT.2020 PQ `smpte2084` or HLG `arib-std-b67` transfer) to 8-bit SDR on
+the software path, so the output is not washed-out — provided this ffmpeg build
+has the required filters. The proxy SHALL detect filter availability (`zscale`
+and `tonemap`) at startup and, when either is missing, SHALL fall back to a
+plain 8-bit convert without failing playback.
+
+#### Scenario: HDR source, filters available
+- **WHEN** an HDR source is re-encoded on the software path and the build has
+  `zscale` + `tonemap`
+- **THEN** the tone-map chain is inserted and the output is BT.709 SDR (not
+  washed-out)
+
+#### Scenario: HDR source, filters missing
+- **WHEN** an HDR source is re-encoded but the build lacks `zscale`/`tonemap`
+- **THEN** playback still proceeds with a plain 8-bit convert (no tone map) and
+  the limitation is logged

package/openspec/changes/transcode-quality/tasks.md

@@ -1,63 +1,63 @@
-# Tasks: Transcode quality
-
-## 1. Source fps
-
-- [x] 1.1 hwaccel: `chooseOutputFps` (integer, capped); `buildVideoArgs`
-      takes `fps`, threaded into the filter + frame-count GOP (software,
-      v4l2m2m) and the filter only (nvenc); VAAPI/QSV unchanged (already
-      inherit); startup test-encode/benchmark keep the fixed rate
-- [x] 1.2 hls-session-manager: parse source fps from the probe, compute
-      `session.outputFps`, pass it into `buildVideoArgs`
-- [x] 1.3 Unit-verify fps choice and fps↔GOP consistency (25→100, 24→96,
-      default→96); syntax checks
-
-## 2. Realtime budget
-
-- [x] 2.1 Startup: benchmark picks resolution + preset within a realtime
-      margin; downscale below the client-target ceiling instead of refusing
-      (`chooseSoftwareEncodeSettings`/`buildResolutionLadder` in hwaccel;
-      `#chooseEncodeBudget` + `encodeWidth`/`encodeHeight` in the session
-      manager; fixed the needed-pixels calc to use the session's `outputFps`
-      not the fixed `TRANSCODE_FPS`). Verified on the FIFA host profile
-      (720p60→480p) + strong/weak/no-benchmark profiles.
-- [x] 2.2 Runtime `speed<1` watch → step down the resolution ladder + restart
-      at the current segment (hard-restart tier). Gate on CPU-bound only:
-      compare `getFileStats().downloadSpeed` with the source byte-rate so a
-      download-starved input is NOT misread as an encoder limit (don't degrade
-      quality for a download bottleneck — log it instead). Hysteresis +
-      cooldown + floor + max steps; slow window reset on every (re)start; no
-      upswitch in v1 (oscillation risk). `#enforceRealtimeBudget` +
-      `#classifyTranscodeBound` + `#applyBudgetDownshift` in the session
-      manager; `getSourceStats` injected from server.js.
-      NOTE (follow-up 2.2b): seamless switch via `EXT-X-DISCONTINUITY` /
-      parallel encoder tier keyed by host resources — the hard restart can blip
-      at the switch point.
-- [ ] 2.3 `-maxrate`/`-bufsize`
-
-## 3. HDR tone mapping
-
-- [x] 3.1 Detect HDR from the probe (PQ `smpte2084` / HLG `arib-std-b67`
-      transfer); insert a `zscale`+`tonemap` (hable) BT.2020→BT.709 SDR chain
-      when re-encoding video on the software path (after the downscale).
-- [x] 3.2 Guard on tonemap-filter availability: startup `detectTonemapSupport`
-      checks `ffmpeg -filters` for `zscale` + `tonemap`; when missing, HDR
-      falls back to the plain 8-bit convert (washed-out but plays). Logged.
-      NOTE (follow-up 3.3): hardware-encoder tone mapping (tonemap_vaapi / npp /
-      opencl) — software path only for now.
-
-## 4. Manual quality
-
-- [x] 4.1 Proxy honours a forced resolution: `manualQuality` flag on the
-      transcode-session request encodes the requested box exactly (capped to
-      source, budget + runtime downswitch disabled); `manualQuality` in the
-      session key; playback plan reports source `videoWidth`/`videoHeight`.
-- [x] 4.2 Server Quality menu (Auto + forced resolutions <= source). Custom
-      media-chrome submenu mirroring the audio menu; selection re-opens the
-      stream at the forced resolution with the position preserved (reuses the
-      audio-switch machinery); shared settings button shows for audio OR
-      quality.
-
-## 5. Release
-
-- [ ] 5.1 Batch release: proxy 2.9.29 + ha-addon bump; field-test on the
-      owner's hardware (25/30 fps content plays without judder; seek intact)
+# Tasks: Transcode quality
+
+## 1. Source fps
+
+- [x] 1.1 hwaccel: `chooseOutputFps` (integer, capped); `buildVideoArgs`
+      takes `fps`, threaded into the filter + frame-count GOP (software,
+      v4l2m2m) and the filter only (nvenc); VAAPI/QSV unchanged (already
+      inherit); startup test-encode/benchmark keep the fixed rate
+- [x] 1.2 hls-session-manager: parse source fps from the probe, compute
+      `session.outputFps`, pass it into `buildVideoArgs`
+- [x] 1.3 Unit-verify fps choice and fps↔GOP consistency (25→100, 24→96,
+      default→96); syntax checks
+
+## 2. Realtime budget
+
+- [x] 2.1 Startup: benchmark picks resolution + preset within a realtime
+      margin; downscale below the client-target ceiling instead of refusing
+      (`chooseSoftwareEncodeSettings`/`buildResolutionLadder` in hwaccel;
+      `#chooseEncodeBudget` + `encodeWidth`/`encodeHeight` in the session
+      manager; fixed the needed-pixels calc to use the session's `outputFps`
+      not the fixed `TRANSCODE_FPS`). Verified on the FIFA host profile
+      (720p60→480p) + strong/weak/no-benchmark profiles.
+- [x] 2.2 Runtime `speed<1` watch → step down the resolution ladder + restart
+      at the current segment (hard-restart tier). Gate on CPU-bound only:
+      compare `getFileStats().downloadSpeed` with the source byte-rate so a
+      download-starved input is NOT misread as an encoder limit (don't degrade
+      quality for a download bottleneck — log it instead). Hysteresis +
+      cooldown + floor + max steps; slow window reset on every (re)start; no
+      upswitch in v1 (oscillation risk). `#enforceRealtimeBudget` +
+      `#classifyTranscodeBound` + `#applyBudgetDownshift` in the session
+      manager; `getSourceStats` injected from server.js.
+      NOTE (follow-up 2.2b): seamless switch via `EXT-X-DISCONTINUITY` /
+      parallel encoder tier keyed by host resources — the hard restart can blip
+      at the switch point.
+- [ ] 2.3 `-maxrate`/`-bufsize`
+
+## 3. HDR tone mapping
+
+- [x] 3.1 Detect HDR from the probe (PQ `smpte2084` / HLG `arib-std-b67`
+      transfer); insert a `zscale`+`tonemap` (hable) BT.2020→BT.709 SDR chain
+      when re-encoding video on the software path (after the downscale).
+- [x] 3.2 Guard on tonemap-filter availability: startup `detectTonemapSupport`
+      checks `ffmpeg -filters` for `zscale` + `tonemap`; when missing, HDR
+      falls back to the plain 8-bit convert (washed-out but plays). Logged.
+      NOTE (follow-up 3.3): hardware-encoder tone mapping (tonemap_vaapi / npp /
+      opencl) — software path only for now.
+
+## 4. Manual quality
+
+- [x] 4.1 Proxy honours a forced resolution: `manualQuality` flag on the
+      transcode-session request encodes the requested box exactly (capped to
+      source, budget + runtime downswitch disabled); `manualQuality` in the
+      session key; playback plan reports source `videoWidth`/`videoHeight`.
+- [x] 4.2 Server Quality menu (Auto + forced resolutions <= source). Custom
+      media-chrome submenu mirroring the audio menu; selection re-opens the
+      stream at the forced resolution with the position preserved (reuses the
+      audio-switch machinery); shared settings button shows for audio OR
+      quality.
+
+## 5. Release
+
+- [ ] 5.1 Batch release: proxy 2.9.29 + ha-addon bump; field-test on the
+      owner's hardware (25/30 fps content plays without judder; seek intact)