From d49d027020da7fa3e542d2abb29ce943d445aa52 Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sat, 15 Aug 2026 16:39:53 +0200
Subject: [PATCH] docs(player): allocate UR-074/DR-162 for the streaming
 bitrate cap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The feature shipped tagged against DR-160, which a parallel session had
claimed for picture-in-picture in the meantime. Renumbered to DR-162
across the Rust and frontend TRACES comments (the PiP tags in
VideoPlayer.svelte, pictureInPicture.ts and nativeVideo.ts keep DR-160)
and regenerated bindings.ts.

Adds the requirement rows the tags point at: UR-074 for the user need, and
DR-162 covering why the cap has to reach the PlaybackInfo negotiation and
not only the transcode URL, why the ceiling is process-wide, and why the
Settings default persists while the in-player override does not. Notes
that this gives UR-070 its resume-at-the-same-point mechanism while the
server-offered rendition list that requirement also asks for stays
proposed. UT-156/157 record what the tests pin.

docs/specs/streaming-bitrate-cap.md carries the layer assignment — the
step definitions, the video/audio split, the resolution pairing and the
reload decision are all Rust; the frontend holds a serde token and the
labels it was handed.

TRACES: UR-074 | DR-162 | UT-156, UT-157
---
 docs/requirements.md                          |   5 +
 docs/specs/streaming-bitrate-cap.md           | 146 ++++++++++++++++++
 src-tauri/src/commands/player/mod.rs          |   4 +-
 src-tauri/src/commands/player/settings.rs     |  12 +-
 src-tauri/src/lib.rs                          |   2 +-
 src-tauri/src/repository/online.rs            |  22 +--
 src-tauri/src/settings.rs                     |  10 +-
 src/lib/api/bindings.ts                       |  10 +-
 .../VideoPlayer.scrubRegression.test.ts       |   4 +
 src/lib/components/player/VideoPlayer.svelte  |   8 +-
 .../player/VideoPlayer.touchScrub.test.ts     |   4 +
 src/lib/player/index.ts                       |   2 +-
 src/routes/settings/+page.svelte              |   6 +-
 13 files changed, 197 insertions(+), 38 deletions(-)
 create mode 100644 docs/specs/streaming-bitrate-cap.md

diff --git a/docs/requirements.md b/docs/requirements.md
index 1082758e..b9bb4afc 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -84,6 +84,7 @@ For a narrative overview of the system design, see
 | UR-071 | Media the viewer is watching can be **kept**, by a whole-file download that runs in the background independently of playback and at its own quality, so it is unaffected by bitrate changes. Where the streamed bytes already are that file (direct play), they are kept rather than fetched twice. A completed download is then played from disk rather than streamed again | Medium | Proposed |
 | UR-073 | Watched state is something the viewer can **set**, not only something playback records. Any episode, season, series or movie can be marked watched — or unwatched again — from where it is shown, without sitting through it or erasing its history wholesale. Marking a season or series covers the episodes inside it, and works with the server unreachable | Medium | Done |
 | UR-072 | Each page opens where a page should open. Moving to a new screen starts at the top of it, and going Back returns the viewer to the place they left — their position in a long library grid or home screen, not the top of it. A page never inherits the scroll position of the page before it | Medium | Done |
+| UR-074 | Video streaming can be held to a **bandwidth budget the viewer sets**, rather than spent at whatever rate the server would otherwise send. A ceiling chosen once — from the source's own bitrate down to a rung that still plays on a poor connection — governs every video the app opens, live TV included, and survives a restart, so a metered connection is not quietly drained by the next thing played. A single video can be moved to a different ceiling from the player, resuming where it was, without disturbing that default | Medium | Done |
 
 ---
 
@@ -322,6 +323,7 @@ Internal architecture, components, and application logic.
 | DR-155 | A watch position set on another device reaches this one. The resume check reads the local `user_data` row and nothing else, but `mirror_user_data` — the only path by which server `UserData` lands in that table — mirrored `is_favorite` alone, and returned early whenever that field was absent, which is exactly the shape of an ordinary watched episode. So `playback_position_ticks` was write-only from this device's perspective: watch 40 minutes in a browser, open JellyTau, and it resumed from whatever *this* device last saw or offered no resume at all — the same user-visible symptom as DR-150's Android bug, from an unrelated cause, which is why resume read as broadly flaky. The mirror now carries the position alongside the favourite flag under the same `pending_sync = 0` conflict rule, so a local position still waiting to be pushed is never pulled *backwards* by a server that has not yet heard where we got to; `COALESCE(excluded.x, user_data.x)` means a field the server omitted keeps its stored value rather than being nulled, and a row with neither field is still skipped rather than fabricated as zeroes. Mirroring alone was not sufficient: `get_item` — the call the player route makes — returned the cached copy on a hit and never consulted the server, so for an already-cached item the mirror never ran. It now refreshes in the background on a cache hit (`race_with_refresh`, the reusable form of what `get_items` already did inline), which is why browsing a season picked up other devices' state while opening the episode directly did not. The refreshed value lands for the next read, the cache-first race still answering immediately | Backend | UR-025, UR-002 | Done |
 | DR-156 | A page no longer inherits the previous page's scroll position. The shell keeps its scrollers alive across navigation by design — the root layout, the home page and the library layout each own a `flex-1 overflow-y-auto` box that outlives the route inside it, which is what lets `BottomUi` be a flex sibling rather than a measured overlay — but the element therefore never remounts and its `scrollTop` survives the route change. SvelteKit's own scroll restoration could not help: it saves and restores `window` scroll, and in this app the window never scrolls at all, so there was no scroll handling of any kind. The symptom was that opening an item from half-way down a library grid dropped the viewer half-way down the detail page, and returning to the grid landed at the top of it — exactly backwards. `ScrollMemory` (pure, one instance per container, keyed on path + query so a genre-filtered grid keeps its own place) records the offset a route is left at in `beforeNavigate` and decides in `afterNavigate`: `link`/`goto`/`form` reset to the top, `popstate` restores that route's saved offset, and the initial `enter` is left alone. Deciding does not consume the offset, so a route returned to more than once restores each time. Applied via the `scrollContainer` action on all three scrollers | UI | UR-072 | Done |
 | DR-160 | Picture-in-picture works on the path that actually plays video. PiP shrinks the whole *Activity*, so `canEnterPip` demanded a native ExoPlayer `SurfaceView` be attached and rendering — `isPlayingVideo() && getSurfaceView() != null && isVideoSurfaceAttached()`. But the native path sits behind `experimentalNativeVideo`, which defaulted to **off**, so in the shipping configuration video played in the WebView's `<video>` element and all three conditions were false. `enterPip` bailed with "Not entering PiP: no local video playing" every single time: the button was offered (gated only on OS capability) and could not work, however it was pressed. The manager now accepts either surface. The frontend reports the element through `AndroidPictureInPicture.setHtml5VideoState(active, width, height, playing)` — intrinsic size because the PiP window's aspect ratio came from the letterboxed surface's measured bounds, which do not exist here, and play state because `ExoPlayer.isPlaying` is false on this path and the PiP play/pause action would be frozen on "Play" mid-playback. Two behaviours invert when the WebView *is* the video: it must stay visible in PiP rather than be hidden (`hideWebView` is now gated on the native path — hiding it would leave an empty black window), and the play/pause `RemoteAction` has to reach the element, so the receiver dispatches `jellytau-pip-play`/`jellytau-pip-pause` DOM events instead of driving ExoPlayer. `jellytau-pip-entered`/`-exited` let the player strip its own chrome, since controls, title and gradients would otherwise be rendered into a window a couple of inches wide. The `<video>` is deregistered on teardown so PiP is never offered over a video that has gone | UI | UR-041 | Done (pending device verification) |
+| DR-162 | Video streams are opened against a **bandwidth ceiling the user chose**, instead of a fixed allowance nobody could change. Every video URL carried `MaxStreamingBitrate=20000000`/`VideoBitrate=18000000`, `PlaybackInfo` negotiated at 20 Mbps, and the device profile advertised `999999999` — so on a metered or slow connection the only lever was not watching. `StreamingQuality` is a ladder of ceilings (Original, 20/10/8/4/2/1 Mbps, 720 kbps) in which a step is not a label but a bundle of transcode parameters: the total ceiling, the audio share of it, and the resolution that budget can carry. It lives in Rust because those numbers are Jellyfin encoding vocabulary — the frontend names a variant and reads labels back over `player_get_streaming_qualities`, the same arrangement as the EQ preset curves. The video bitrate is the total *minus* the audio share, so the two together honour the cap rather than overshooting it by the size of the audio track, and `MaxHeight` falls with the ladder so a small budget is not spent on pixels it cannot afford. The cap has to reach the **negotiation**, not only the transcode URL: `max_static_bitrate` in the device profile is what makes the server refuse to direct-play a source fatter than the ceiling, and without it a 30 Mbps remux is handed over untouched and every URL parameter downstream is moot — which is why it is applied at all four places that decide bandwidth (the HLS builder, `PlaybackInfo`, `open_live_stream`, and the background-audio handoff, which takes the lower of the cap and its own 384 kbps). The ceiling is process-wide rather than a field on `OnlineRepository`, mirroring `INCLUDE_CATALOG_BROWSE`: it is a preference about *this device's connection*, it must survive a repository rebuilt on re-login, and every builder plus the negotiation have to agree on it or the cap leaks. Settings owns the durable default and is the only writer to `app_settings` — persisted unlike the rest of `VideoSettings`, because a limit set for a metered connection that silently reverts to uncapped on the next launch spends the user's data with no changed setting to show for it — and it is restored at startup from the async runtime, defaulting to uncapped if the read fails so a database problem degrades to the old behaviour rather than to an arbitrary limit. The in-player menu is the per-video override: a cap is a property of the stream the server is producing, so it cannot be applied to one already in flight — `player_set_stream_quality` re-opens the stream at the new quality and resumes at the current position, reloading a native backend itself and handing HTML5 a URL for the same `reloadSource` primitive the audio-track switch uses, so no strategy branch lives in the UI. It deliberately does not persist. This gives UR-070 its resume-at-the-same-point mechanism; the server-offered per-item rendition list that requirement also asks for remains proposed | Playback | UR-074, UR-070 | Done |
 | DR-161 | Native video is the default, so picture-in-picture has a real surface. DR-160 makes PiP work on the HTML5 path, but that path can only ever shrink the *UI* into the PiP window; showing the video itself needs the SurfaceView behind the WebView, which is what `experimentalNativeVideo` gates. The flag now defaults to on when the user has never chosen, with an explicit stored choice still winning in both directions so anyone who turned it off keeps it off. This is a deliberate acceptance of risk: the flag existed because the native path was an unfinished spike, and `VideoPlayer.scrubRegression.test.ts` documents its history — a native init that flipped to HTML5 mid-lifecycle and left seeks going down one path while ExoPlayer played on another. Those tests pin the **flag-off** interim override (native response overridden to HTML5, backend stopped once), which the default no longer selects, so they now mock the flag off rather than inherit it: they still guard that path, but they no longer describe what ships. The native scrub/seek path is consequently not covered by the suite and needs device verification | UI | UR-041, UR-003 | Needs device verification |
 | DR-159 | The background-audio handoff stops leaking its relative timeline. The handoff plays the episode as a *relative* stream — the audio-only URL is built with `StartTimeTicks` = the position the screen was locked at, so ExoPlayer's zero is the handoff point — and `background_audio_base` holds the offset that turns one back into a real position. The base was a **display-only** correction, applied in exactly two places (the lockscreen scrubber and the internal truncation maths) while every other consumer worked in the relative timeline treating the number as absolute. Each crossing threw away exactly `base` seconds, which is why the jump-back distance varied with where the screen was locked and read as random. Three crossings were live: progress reporting to Jellyfin sent the relative position every 30s, so the server was told `real − base` — and since DR-155 now mirrors the server's position back and refreshes on a cache hit, that regressed value returned as the resume point (lock at 40 min, listen to 90, reopen at 50); lockscreen seeks went out absolute and came back relative, against a chunked length-less transcode that cannot honour a seek at all, so a clamped seek landed at stream zero; and media3's own `seekToDefaultPosition`/`seekBack`/`seekForward` bypassed the `ForwardingPlayer` wrapper entirely, reaching the real ExoPlayer — `Util.handlePlayButtonAction` seeking an ended player to the relative zero being the same mechanism as DR-129's truncation bug through a different door. The fix converts **once, at the boundary**: `JellyTauPlayer`'s position tick adds the base (and shifts the duration with it, since the stream's own length is only what remains) before either `nativeOnPositionUpdate` or the lockscreen sees it, so position updates, progress reports, the frontend and the truncation check all speak the episode's timeline and none needs to know a handoff happened. The base is consequently *removed* from `claim_stream_resume`, `truncated_stream_resume_position` and `player_exit_background_audio`, where adding it now double-counts, and the lockscreen's `positionOffsetMs` addition goes with it (the field remains, read-only, as the tick's input). Inbound seeks go the other way: `seek_absolute` is the new boundary for every outside seek, re-opening the stream at the requested position via `resume_stream_at` when a handoff is active — which is what `onSeekTo` had claimed for months in a comment describing code that did not exist — and an ordinary seek otherwise. `seekToDefaultPosition` is swallowed rather than forwarded, since Rust already owns what "play after the stream ended" means and the `play()` that follows reaches it. Exit reads the position *before* clearing either base, or a tick landing in between hands back a relative one | Player | UR-040, UR-005, UR-025 | Done (pending device verification) |
 | DR-158 | A watched toggle, on the episode row, the season header, the series and movie hero, and the Episode Focus View. Both halves of the backend already existed and neither had a caller: `mark_played` (`POST /PlayedItems`) was reachable only from the sync drain replaying rows the *reporter* had queued, and `clear_watch_history` (`DELETE /PlayedItems`) only from the destructive "erase this series' history" button — so the sole way to mark something watched was to play it. Jellyfin applies both recursively over a season or series, so the container case needs no client-side fan-out *online*. Offline it does: `storage_set_watched` writes the item **and its descendants** (drawn from `items` by `parent_id`/`album_id`/`season_id`/`series_id`, so an uncached id selects nothing and the statement no-ops instead of raising a foreign-key error), because otherwise marking a season watched with no server would tick the season and leave every episode inside it unwatched. It is deliberately separate from `storage_mark_played`, which stays the single-item "this finished playing" path that increments `play_count`. Un-marking clears the resume position as well as the flag, matching the server. `QueuedOp::MarkUnplayed` gives the queue the missing direction — pushing as `clear_watch_history` — so the toggle works offline both ways rather than only one; without it un-marking would have been the half that needed a connection. The button is an everyday toggle, so unlike `ClearHistoryButton` it does not confirm, and it holds an optimistic state because the caller's `watched` prop only catches up after a reload (a season means a round trip, during which the button would otherwise appear to ignore the tap) | UI | UR-073 | Done |
@@ -413,6 +415,7 @@ Internal architecture, components, and application logic.
 | UR-071 | IR-032 | DR-123, DR-124, DR-125, DR-126, DR-127, DR-128, DR-133, DR-134, DR-135, DR-136, DR-137, DR-138 |
 | UR-072 | - | DR-156 |
 | UR-073 | - | DR-158 |
+| UR-074 | - | DR-162 |
 
 ---
 
@@ -565,6 +568,8 @@ Internal architecture, components, and application logic.
 | UT-152 | Caching a server result mirrors its watch position locally — including for an item carrying a position but no favourite flag — without inventing a row for an item the server reported no user data for, and without pulling a still-unsynced local position backwards | DR-155 | Done |
 | UT-155 | A seek during a background-audio handoff re-opens the stream at the requested absolute position (`StartTimeTicks`) and rebases the handoff to it, while a seek outside a handoff stays an ordinary seek and invents no base | DR-159 | Done |
 | UT-154 | `mark_unplayed` parses to `QueuedOp::MarkUnplayed` and is rejected without an item id, and a queued un-mark drains to the server as `clear_watch_history` | DR-158 | Done |
+| UT-156 | A capped step reaches the transcode URL as all four of its parts (total ceiling, the video/audio split summing to the cap, and a `MaxHeight`), the uncapped default keeps the historical 20/18 Mbps allowance and constrains no resolution, and the background-audio handoff takes the lower of the cap and its own 384 kbps | DR-162 | Done |
+| UT-157 | The quality ladder is internally consistent — video + audio equals the cap at every step, audio never consumes the budget, only `Original` is uncapped — descends in bitrate, resolution and audio share together, and round-trips through the serde token it is persisted as | DR-162 | Done |
 | UT-153 | Scroll handling per navigation kind: a forward move always lands at the top even when the previous page was scrolled and even when the target was visited before, Back restores that route's own saved offset (and the top when it has none), offsets are kept per route rather than shared, a repeated Back still restores, and the initial load leaves the container alone | DR-156 | Done |
 | UT-142 | The audio codecs offered for video direct play: a Dolby device's real `MediaCodecList` output drops `ac3`/`eac3`, AMR and raw PCM are dropped too, a fully-supported list is passed through untouched, a list with nothing decodable still claims `aac`, and stray spacing or casing does not decide whether the user gets sound | DR-148 | Done |
 | UT-143 | Subtitle URLs resolve to plain strings before they reach the markup (never a Promise), unresolvable tracks are dropped, a stale selection collapses to "Off", and a server-default track is never auto-selected | UR-020, DR-023 | Done |
diff --git a/docs/specs/streaming-bitrate-cap.md b/docs/specs/streaming-bitrate-cap.md
new file mode 100644
index 00000000..8823f12a
--- /dev/null
+++ b/docs/specs/streaming-bitrate-cap.md
@@ -0,0 +1,146 @@
+# Spec: streaming bitrate cap
+
+**Status:** Implemented
+**Requirements:** UR-074 → DR-162 (partially serves UR-070)
+**UX spec:** n/a — the controls reuse existing patterns (Settings → Video Playback, and the player's track menus).
+
+## Summary
+
+The viewer picks a bandwidth ceiling for video — from `Original` (no client
+limit) down to 720 kbps — and every video the app opens is fetched within it,
+live TV included. The choice is made once in Settings and persists across
+restarts; a single video can be moved to another ceiling from the player, which
+re-opens the stream and resumes where it was without changing the saved default.
+
+## Motivation
+
+Every video URL the app built carried a fixed allowance —
+`MaxStreamingBitrate=20000000`, `VideoBitrate=18000000` — the `PlaybackInfo`
+negotiation asked for 20 Mbps, and the device profile advertised
+`999999999`, which invites the server to direct-play a source of any size. On a
+metered or slow connection there was no lever at all short of not watching.
+
+The related UR-070 asks for something adjacent but different: a list of the
+renditions *the server can produce for this item*. That needs per-item
+`MediaSources` negotiation and is still proposed. What was missing first is
+cruder and more valuable: a device-wide budget that holds regardless of what is
+playing.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| What a quality step *is* — total ceiling, audio share, resolution cap | Rust | Jellyfin encoding vocabulary. It changes if Jellyfin's transcoder or parameter binding changes, not if the UI is redesigned. Exactly the shape of `EqPreset::gains()`. |
+| Splitting the ceiling between video and audio | Rust | A domain rule about what the server is being asked to produce; getting it wrong overshoots the user's cap. |
+| Choosing `MaxHeight` for a bitrate | Rust | An encoding judgement (how many pixels a budget can carry), not a display preference. |
+| Where the cap is applied (URL builders, `PlaybackInfo`, live TV, audio handoff) | Rust | All four are backend concerns, and the frontend must not have to know that a cap has more than one enforcement point. |
+| Whether a mid-playback change needs a stream reload, and performing it | Rust | Same decision the audio-track switch already delegates: the backend knows the playback mode and owns the queue. |
+| Persisting the default | Rust | Application state in `app_settings`, alongside every other durable setting. |
+| Rendering the picker, menu placement, which control is highlighted | Frontend | Pure presentation. |
+
+The frontend holds one string — the serde token for the chosen variant — and
+labels/details it received from Rust. It never encodes a bitrate, a resolution
+or a parameter name.
+
+## Design
+
+`StreamingQuality` (`src-tauri/src/settings.rs`) is the ladder: `Original`,
+`Mbps20`, `Mbps10`, `Mbps8`, `Mbps4`, `Mbps2`, `Mbps1`, `Kbps720`, serialised
+camelCase (`"mbps10"`). Each step answers `max_bitrate()`, `audio_bitrate()`,
+`video_bitrate()` (= total − audio), `max_height()`, `label()`, `detail()`.
+
+The active ceiling is a process-wide `RwLock<StreamingQuality>` in
+`repository/online.rs`, read by every builder. Process-wide rather than a field
+on `OnlineRepository` because it is a preference about *this device's
+connection*: it must survive a repository rebuilt on re-login, and the URL
+builders and the negotiation have to agree on it or the cap leaks. This mirrors
+`offline::INCLUDE_CATALOG_BROWSE`.
+
+Enforcement points — all four are required:
+
+| Point | What the cap sets |
+|-------|-------------------|
+| `get_video_stream_url` (HLS transcode) | `MaxStreamingBitrate`, `VideoBitrate`, `AudioBitrate`, `MaxHeight` |
+| `get_playback_info` | request `MaxStreamingBitrate`, and the device profile's `MaxStreamingBitrate`/`MaxStaticBitrate` |
+| `open_live_stream` | `MaxStreamingBitrate` |
+| `build_audio_only_stream_url_for_video` | `min(cap audio, 384 kbps)` |
+
+The negotiation is the one that matters most. `MaxStaticBitrate` is what makes
+the server refuse to *direct play* a source fatter than the ceiling; without it
+a 30 Mbps remux is served untouched and no URL parameter downstream can reduce
+it.
+
+IPC:
+
+```rust
+player_get_streaming_qualities() -> Vec<(StreamingQuality, String, String)>  // variant, label, detail
+player_set_stream_quality(repository_handle, quality, use_html5,
+                          current_position, media_source_id, audio_stream_index)
+    -> StreamQualityResponse           // #[serde(tag = "strategy")]: native | reloadStream
+```
+
+`VideoSettings` gains `streaming_quality` (`#[serde(default)]`, so settings
+persisted before the field existed load as uncapped).
+`player_set_video_settings` applies it and writes it to `app_settings`;
+`restore_streaming_quality` reads it back in the Tauri `setup` hook via
+`tauri::async_runtime::spawn`, defaulting to uncapped if anything fails.
+
+`StreamQualityResponse` keeps its Rust field names on the wire (`new_url`) —
+tauri-specta only camelCases the `strategy` tag. The facade
+(`playerController.setStreamQuality`) dispatches `reloadSource` for
+`reloadStream` and does nothing for `native`, because the backend has already
+reloaded itself.
+
+Mid-playback the change applies to the current video **and** becomes the process
+ceiling for what follows, but it is not persisted: the in-player menu is a "this
+film, this connection" control and Settings owns the durable default.
+
+## Out of scope
+
+- Per-item rendition lists from the server's `MediaSources` (UR-070's other half).
+- Connection-aware caps (separate WiFi/cellular ceilings). One cap, all connections.
+- Adaptive/automatic selection from measured throughput.
+- Download quality, which already has its own preset vocabulary (UR-071/DR-123).
+
+## Acceptance criteria
+
+- [x] `bun run check` passes.
+- [x] `cargo fmt` clean, `cargo clippy` clean, Rust tests pass.
+- [x] `bun run test` passes.
+- [x] `bun run check:boundary` passes — no bitrate/resolution numbers in `src/`.
+- [x] New code carries `// TRACES:` comments.
+- [x] `bindings.ts` regenerated from Rust.
+- [x] A capped step changes what the URL asks for; the uncapped default is byte-identical to the previous behaviour.
+
+## Testing
+
+Rust (`cargo test`):
+
+- `test_video_stream_url_applies_bitrate_cap` — all four parameters at `Mbps2`.
+- `test_video_stream_url_uncapped_keeps_legacy_allowance` — `Original` is unchanged and adds no `MaxHeight`.
+- `test_audio_only_stream_url_takes_the_lower_of_cap_and_default`.
+- `test_streaming_quality_budget_is_internally_consistent`, `..._ladder_descends`, `..._round_trips_through_json`.
+
+The ceiling is process-wide, so tests that depend on it serialise on a guard
+(`QualityFixture`) that restores `Original` on drop — including the two
+pre-existing stream-URL tests, which would otherwise see another test's cap.
+
+`get_playback_info` and `open_live_stream` need a live server and are not unit
+tested; their behaviour is the enum's `max_bitrate()`, which is.
+
+## TRACES
+
+- `StreamingQuality`, `VideoSettings.streaming_quality` — `UR-074 | DR-162`
+- URL builders / negotiation / live TV — `UR-004, UR-074 | DR-140, DR-162`
+- Audio-only handoff — `UR-040, UR-074 | DR-162`
+- Commands, facade, Settings UI, player menu — `UR-074 | DR-162`
+- Tests — `UT-156`, `UT-157`
+
+## Notes for the implementer
+
+- `videoBitRate` with a capital R is the *download* endpoint's binding quirk
+  (DR-123). The streaming endpoint used here binds `VideoBitrate`/
+  `MaxStreamingBitrate` as spelled above — do not "correct" one to the other.
+- A parallel Claude session may be active in this repo; `git diff` before
+  repairing unexpected changes. DR-160/161 were claimed by such a session while
+  this feature was in flight, which is why it is DR-162.
diff --git a/src-tauri/src/commands/player/mod.rs b/src-tauri/src/commands/player/mod.rs
index cdd0cd2e..bc2ab566 100644
--- a/src-tauri/src/commands/player/mod.rs
+++ b/src-tauri/src/commands/player/mod.rs
@@ -347,7 +347,7 @@ pub enum AudioTrackSwitchResponse {
 /// Mirrors [`AudioTrackSwitchResponse`]: the backend decides whether the caller
 /// has to reload anything, so no strategy branch lives in the UI.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 #[derive(specta::Type, Debug, Serialize)]
 #[serde(tag = "strategy", rename_all = "camelCase")]
 pub enum StreamQualityResponse {
@@ -1485,7 +1485,7 @@ pub async fn player_switch_audio_track(
 /// durable default belongs to Settings. `player_set_video_settings` is the one
 /// that writes to the database.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 #[tauri::command]
 #[specta::specta]
 pub async fn player_set_stream_quality(
diff --git a/src-tauri/src/commands/player/settings.rs b/src-tauri/src/commands/player/settings.rs
index 58199dcf..6e278c3e 100644
--- a/src-tauri/src/commands/player/settings.rs
+++ b/src-tauri/src/commands/player/settings.rs
@@ -1,6 +1,6 @@
 //! Audio and video playback settings commands.
 //!
-//! TRACES: UR-022, UR-027, UR-031, UR-032, UR-033, UR-074 | DR-025, DR-030, DR-034, DR-035, DR-036, DR-160, IR-020
+//! TRACES: UR-022, UR-027, UR-031, UR-032, UR-033, UR-074 | DR-025, DR-030, DR-034, DR-035, DR-036, DR-162, IR-020
 
 use std::sync::Arc;
 
@@ -22,7 +22,7 @@ use crate::utils::lock::MutexSafe;
 /// reverts to uncapped on the next launch spends their data allowance without
 /// ever showing them a changed setting.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 const STREAMING_QUALITY_KEY: &str = "streaming_quality";
 
 #[tauri::command]
@@ -82,7 +82,7 @@ pub async fn player_set_video_settings(
 
     // The bandwidth ceiling is read by the repository's URL builders and by the
     // PlaybackInfo negotiation, neither of which can see this wrapper.
-    // TRACES: UR-074 | DR-160
+    // TRACES: UR-074 | DR-162
     crate::repository::online::set_streaming_quality(validated.streaming_quality);
     persist_streaming_quality(&db, validated.streaming_quality).await;
 
@@ -104,7 +104,7 @@ pub async fn player_set_video_settings(
 /// frontend reads them here rather than encoding them — the same arrangement as
 /// [`player_get_eq_presets`].
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 #[tauri::command]
 #[specta::specta]
 pub async fn player_get_streaming_qualities(
@@ -119,7 +119,7 @@ pub async fn player_get_streaming_qualities(
 /// setting has already been applied in memory, and refusing the whole call
 /// because the write failed would leave the UI showing a cap that *is* active.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 async fn persist_streaming_quality(db: &State<'_, DatabaseWrapper>, quality: StreamingQuality) {
     let db_service = {
         let database = db.0.lock_safe();
@@ -155,7 +155,7 @@ async fn persist_streaming_quality(db: &State<'_, DatabaseWrapper>, quality: Str
 /// default — uncapped — in place, so a database problem degrades to the old
 /// behaviour rather than to an arbitrary limit.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 pub async fn restore_streaming_quality(app: &tauri::AppHandle) {
     let db_service = {
         let Some(db) = app.try_state::<DatabaseWrapper>() else {
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 8c96edbb..85b35c15 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1252,7 +1252,7 @@ pub fn run() {
             // are uncapped — the pre-existing behaviour — and no playback can
             // have started this early anyway (login happens after setup).
             //
-            // TRACES: UR-074 | DR-160
+            // TRACES: UR-074 | DR-162
             {
                 let handle = app.handle().clone();
                 tauri::async_runtime::spawn(async move {
diff --git a/src-tauri/src/repository/online.rs b/src-tauri/src/repository/online.rs
index d076b4c2..e7947a49 100644
--- a/src-tauri/src/repository/online.rs
+++ b/src-tauri/src/repository/online.rs
@@ -23,7 +23,7 @@ use crate::utils::lock::RwLockSafe;
 /// Set from `player_set_video_settings` / `player_set_stream_quality`, and
 /// restored from the database at startup.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 static STREAMING_QUALITY: RwLock<StreamingQuality> = RwLock::new(StreamingQuality::Original);
 
 /// Apply a bandwidth ceiling to every subsequently-opened video stream.
@@ -32,14 +32,14 @@ static STREAMING_QUALITY: RwLock<StreamingQuality> = RwLock::new(StreamingQualit
 /// property of the URL the server is transcoding for, so changing it mid-stream
 /// requires re-opening at the new quality (`player_set_stream_quality`).
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 pub fn set_streaming_quality(quality: StreamingQuality) {
     *STREAMING_QUALITY.write_safe() = quality;
 }
 
 /// The ceiling currently applied to new video streams.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 pub fn streaming_quality() -> StreamingQuality {
     *STREAMING_QUALITY.read_safe()
 }
@@ -421,7 +421,7 @@ impl OnlineRepository {
     /// that suits the budget. `Original` keeps the historical 20/18 Mbps
     /// allowance, which is a transcode ceiling rather than a user-facing limit.
     ///
-    /// TRACES: UR-004, UR-074 | DR-140, DR-160 | UT-130, UT-156
+    /// TRACES: UR-004, UR-074 | DR-140, DR-162 | UT-130, UT-156
     pub async fn get_video_stream_url(
         &self,
         item_id: &str,
@@ -537,7 +537,7 @@ impl OnlineRepository {
             // Audio-only is already far under any video cap, but a user on the
             // bottom rungs of the ladder asked for *less traffic*, so take the
             // lower of the two rather than always 384 kbps.
-            // TRACES: UR-074 | DR-160
+            // TRACES: UR-074 | DR-162
             (
                 "MaxStreamingBitrate",
                 streaming_quality().audio_bitrate().min(384_000).to_string(),
@@ -1473,7 +1473,7 @@ impl MediaRepository for OnlineRepository {
         // downstream is moot. `Original` keeps the historical "no ceiling"
         // sentinel so the default path negotiates exactly as before.
         //
-        // TRACES: UR-074 | DR-160
+        // TRACES: UR-074 | DR-162
         let quality = streaming_quality();
         let negotiated_bitrate = quality.max_bitrate().unwrap_or(999_999_999) as i64;
         if let Some(cap) = quality.max_bitrate() {
@@ -1714,7 +1714,7 @@ impl MediaRepository for OnlineRepository {
             is_playback: true,
             // Live TV is video like any other, so the user's cap applies here
             // too — a channel opened at the source bitrate would walk straight
-            // past a limit set for the connection. TRACES: UR-074 | DR-160
+            // past a limit set for the connection. TRACES: UR-074 | DR-162
             max_streaming_bitrate: streaming_quality().max_bitrate().unwrap_or(20_000_000),
         };
 
@@ -2466,7 +2466,7 @@ mod tests {
     /// streaming ceiling, and restores the uncapped default afterwards — without
     /// it, a capped test running concurrently changes what an uncapped one sees.
     ///
-    /// TRACES: UR-074 | DR-160
+    /// TRACES: UR-074 | DR-162
     static QUALITY_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
 
     struct QualityFixture(#[allow(dead_code)] std::sync::MutexGuard<'static, ()>);
@@ -2490,7 +2490,7 @@ mod tests {
     /// can carry. Capping only `MaxStreamingBitrate` would leave the server
     /// encoding 1080p into 2 Mbps.
     ///
-    /// TRACES: UR-074 | DR-160 | UT-156
+    /// TRACES: UR-074 | DR-162 | UT-156
     #[tokio::test]
     async fn test_video_stream_url_applies_bitrate_cap() {
         let _fixture = QualityFixture::set(StreamingQuality::Mbps2);
@@ -2512,7 +2512,7 @@ mod tests {
     /// The uncapped default must keep the exact transcode allowance this
     /// endpoint has always used, and must not start constraining resolution.
     ///
-    /// TRACES: UR-074 | DR-160 | UT-156
+    /// TRACES: UR-074 | DR-162 | UT-156
     #[tokio::test]
     async fn test_video_stream_url_uncapped_keeps_legacy_allowance() {
         let _fixture = QualityFixture::set(StreamingQuality::Original);
@@ -2535,7 +2535,7 @@ mod tests {
     /// The background-audio handoff is already cheap, but someone who capped the
     /// connection at 720 kbps asked for less traffic than its fixed 384 kbps.
     ///
-    /// TRACES: UR-040, UR-074 | DR-160 | UT-156
+    /// TRACES: UR-040, UR-074 | DR-162 | UT-156
     #[tokio::test]
     async fn test_audio_only_stream_url_takes_the_lower_of_cap_and_default() {
         {
diff --git a/src-tauri/src/settings.rs b/src-tauri/src/settings.rs
index 5036d7d4..3d087937 100644
--- a/src-tauri/src/settings.rs
+++ b/src-tauri/src/settings.rs
@@ -161,7 +161,7 @@ impl AudioSettings {
 /// bitrate so the encoder does not spend a small budget on pixels it cannot
 /// afford. See docs/specs/streaming-bitrate-cap.md.
 ///
-/// TRACES: UR-074 | DR-160
+/// TRACES: UR-074 | DR-162
 #[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
 pub enum StreamingQuality {
@@ -296,7 +296,7 @@ pub struct VideoSettings {
     /// `#[serde(default)]` so settings JSON persisted before this field existed
     /// loads as the previous behaviour (uncapped).
     ///
-    /// TRACES: UR-074 | DR-160
+    /// TRACES: UR-074 | DR-162
     #[serde(default)]
     pub streaming_quality: StreamingQuality,
 }
@@ -601,7 +601,7 @@ mod tests {
     /// exceed, so video + audio must fit inside the total — a video bitrate set
     /// to the full cap would overshoot it by the size of the audio track.
     ///
-    /// TRACES: UR-074 | DR-160 | UT-157
+    /// TRACES: UR-074 | DR-162 | UT-157
     #[test]
     fn test_streaming_quality_budget_is_internally_consistent() {
         for quality in StreamingQuality::ALL {
@@ -637,7 +637,7 @@ mod tests {
     /// must fall with it — a lower bitrate paired with a higher resolution would
     /// spend the smaller budget on more pixels, which is backwards.
     ///
-    /// TRACES: UR-074 | DR-160 | UT-157
+    /// TRACES: UR-074 | DR-162 | UT-157
     #[test]
     fn test_streaming_quality_ladder_descends() {
         let steps = StreamingQuality::ALL;
@@ -664,7 +664,7 @@ mod tests {
     /// The persisted form is the serde token, and it must survive a round trip —
     /// a rename here silently resets everyone's saved cap to uncapped.
     ///
-    /// TRACES: UR-074 | DR-160 | UT-157
+    /// TRACES: UR-074 | DR-162 | UT-157
     #[test]
     fn test_streaming_quality_round_trips_through_json() {
         for quality in StreamingQuality::ALL {
diff --git a/src/lib/api/bindings.ts b/src/lib/api/bindings.ts
index 93c10998..8935beaa 100644
--- a/src/lib/api/bindings.ts
+++ b/src/lib/api/bindings.ts
@@ -205,7 +205,7 @@ async playerGetVideoSettings() : Promise<VideoSettings> {
  * frontend reads them here rather than encoding them — the same arrangement as
  * [`player_get_eq_presets`].
  * 
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 async playerGetStreamingQualities() : Promise<([StreamingQuality, string, string])[]> {
     return await TAURI_INVOKE("player_get_streaming_qualities");
@@ -226,7 +226,7 @@ async playerGetStreamingQualities() : Promise<([StreamingQuality, string, string
  * durable default belongs to Settings. `player_set_video_settings` is the one
  * that writes to the database.
  * 
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 async playerSetStreamQuality(repositoryHandle: string, quality: StreamingQuality, useHtml5: boolean, currentPosition: number | null, mediaSourceId: string | null, audioStreamIndex: number | null) : Promise<StreamQualityResponse> {
     return await TAURI_INVOKE("player_set_stream_quality", { repositoryHandle, quality, useHtml5, currentPosition, mediaSourceId, audioStreamIndex });
@@ -2897,7 +2897,7 @@ export type StreamKind = "audio" | "video" | "subtitle" |
  * Mirrors [`AudioTrackSwitchResponse`]: the backend decides whether the caller
  * has to reload anything, so no strategy branch lives in the UI.
  * 
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 export type StreamQualityResponse = 
 /**
@@ -2922,7 +2922,7 @@ export type StreamQualityResponse =
  * bitrate so the encoder does not spend a small budget on pixels it cannot
  * afford. See docs/specs/streaming-bitrate-cap.md.
  * 
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 export type StreamingQuality = 
 /**
@@ -3057,7 +3057,7 @@ autoPlayMaxEpisodes?: number;
  * `#[serde(default)]` so settings JSON persisted before this field existed
  * loads as the previous behaviour (uncapped).
  * 
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 streamingQuality?: StreamingQuality }
 /**
diff --git a/src/lib/components/player/VideoPlayer.scrubRegression.test.ts b/src/lib/components/player/VideoPlayer.scrubRegression.test.ts
index 3535f0d5..40f92d89 100644
--- a/src/lib/components/player/VideoPlayer.scrubRegression.test.ts
+++ b/src/lib/components/player/VideoPlayer.scrubRegression.test.ts
@@ -82,6 +82,10 @@ vi.mock("$lib/api/bindings", () => ({
     playerCancelSleepTimer: (...a: any[]) => playerCancelSleepTimer(...(a as [])),
     playerSetSubtitleTrack: vi.fn(async () => ({})),
     playerSwitchAudioTrack: vi.fn(async () => ({})),
+    // The player loads the streaming-quality picker on mount; without these the
+    // mock throws and every test in the file fails before it starts.
+    playerGetStreamingQualities: vi.fn(async () => []),
+    playerGetVideoSettings: vi.fn(async () => ({ streamingQuality: "original" })),
     storageGetSeriesAudioPreference: vi.fn(async () => null),
     storageSaveSeriesAudioPreference: vi.fn(async () => ({})),
   },
diff --git a/src/lib/components/player/VideoPlayer.svelte b/src/lib/components/player/VideoPlayer.svelte
index e42ba6f8..460aef8f 100644
--- a/src/lib/components/player/VideoPlayer.svelte
+++ b/src/lib/components/player/VideoPlayer.svelte
@@ -246,7 +246,7 @@
 
   // Streaming bandwidth ceiling. The ladder and the current value both come from
   // Rust — the frontend never encodes what a step means.
-  // TRACES: UR-074 | DR-160
+  // TRACES: UR-074 | DR-162
   let showQualityMenu = $state(false);
   let streamingQualities = $state<[StreamingQuality, string, string][]>([]);
   let selectedQuality = $state<StreamingQuality>("original");
@@ -653,7 +653,7 @@
   // flips the component into HTML5 mode and breaks native seeking, and nothing
   // about playback waits on this list.
   //
-  // TRACES: UR-074 | DR-160
+  // TRACES: UR-074 | DR-162
   onMount(() => {
     Promise.all([
       commands.playerGetStreamingQualities(),
@@ -1929,7 +1929,7 @@
    * only supplies the position to resume at and reverts the selection if the
    * switch fails.
    *
-   * TRACES: UR-074 | DR-160
+   * TRACES: UR-074 | DR-162
    */
   async function selectQuality(quality: StreamingQuality) {
     showQualityMenu = false;
@@ -2354,7 +2354,7 @@
           </div>
         {/if}
 
-        <!-- Streaming quality (bandwidth ceiling). TRACES: UR-074 | DR-160 -->
+        <!-- Streaming quality (bandwidth ceiling). TRACES: UR-074 | DR-162 -->
         {#if streamingQualities.length > 0}
           <div class="relative">
             <button
diff --git a/src/lib/components/player/VideoPlayer.touchScrub.test.ts b/src/lib/components/player/VideoPlayer.touchScrub.test.ts
index ab0aa622..97c02abc 100644
--- a/src/lib/components/player/VideoPlayer.touchScrub.test.ts
+++ b/src/lib/components/player/VideoPlayer.touchScrub.test.ts
@@ -84,6 +84,10 @@ vi.mock("$lib/api/bindings", () => ({
     playerCancelSleepTimer: vi.fn(async () => ({})),
     playerSetSubtitleTrack: vi.fn(async () => ({})),
     playerSwitchAudioTrack: vi.fn(async () => ({})),
+    // The player loads the streaming-quality picker on mount; without these the
+    // mock throws and every test in the file fails before it starts.
+    playerGetStreamingQualities: vi.fn(async () => []),
+    playerGetVideoSettings: vi.fn(async () => ({ streamingQuality: "original" })),
     storageGetSeriesAudioPreference: vi.fn(async () => null),
     storageSaveSeriesAudioPreference: vi.fn(async () => ({})),
   },
diff --git a/src/lib/player/index.ts b/src/lib/player/index.ts
index 5a1da010..dc6555d0 100644
--- a/src/lib/player/index.ts
+++ b/src/lib/player/index.ts
@@ -189,7 +189,7 @@ async function switchAudioTrack(
  * backend itself, and hands HTML5 a URL for the same `reloadSource` primitive
  * the audio-track switch uses. Requires an active video adapter.
  *
- * TRACES: UR-074 | DR-160
+ * TRACES: UR-074 | DR-162
  */
 async function setStreamQuality(
   quality: StreamingQuality,
diff --git a/src/routes/settings/+page.svelte b/src/routes/settings/+page.svelte
index dd6e6f52..8a0e25bc 100644
--- a/src/routes/settings/+page.svelte
+++ b/src/routes/settings/+page.svelte
@@ -68,7 +68,7 @@
 
   // Bandwidth ceilings offered by the streaming-quality picker, as
   // [variant, label, detail] — the numbers behind each step are Jellyfin
-  // encoding vocabulary, so Rust serves the list. TRACES: UR-074 | DR-160
+  // encoding vocabulary, so Rust serves the list. TRACES: UR-074 | DR-162
   let streamingQualities = $state<[StreamingQuality, string, string][]>([]);
 
   // Download/caching behaviour, incl. the WiFi-only gate (UR-053).
@@ -340,7 +340,7 @@
     persistVideo();
   }
 
-  /** TRACES: UR-074 | DR-160 */
+  /** TRACES: UR-074 | DR-162 */
   function handleStreamingQualityChange(quality: StreamingQuality) {
     videoSettings.streamingQuality = quality;
     persistVideo();
@@ -698,7 +698,7 @@
 
         <!-- Streaming quality: the bandwidth ceiling every video stream is
              opened against. The steps and their labels come from Rust.
-             TRACES: UR-074 | DR-160 -->
+             TRACES: UR-074 | DR-162 -->
         <div class="bg-[var(--color-surface)] rounded-lg p-6 mt-4">
           <h3 class="text-xl font-semibold text-white">Streaming Quality</h3>
           <p class="text-sm text-gray-400 mt-1 mb-4">