From 7387f35c7ee1ee8ca2844092396c36c053b3f19a Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 16 Aug 2026 00:00:10 +0200
Subject: [PATCH] docs(player): correct the stale "native video defaults to
 off" comments

DR-161 made `experimentalNativeVideo` default to on, but three comments still
described the pre-flip world and one of them was load-bearing:

- `nativeVideo.ts` labelled the store "Default off" directly above a `load()`
  that returns true when nothing is stored.
- The two PiP comments explained themselves as "what makes PiP work in the
  shipping configuration", which stopped being true when Android started
  shrinking the real ExoPlayer surface. They still describe the Linux path and
  the flag-off case, so they say that instead.
- `video_audio_codecs` justified its narrow codec list with "video does not play
  through ExoPlayer", which is no longer so on Android. The narrow list is still
  right, for a different reason now recorded: the flag is a user setting and a
  download outlives it, so only the intersection holds on both sides of the
  switch. DR-171 carries the same caveat.

No behaviour change.
---
 docs/requirements.md                         |  2 +-
 src-tauri/src/repository/device_profile.rs   | 16 ++++++++++++----
 src/lib/components/player/VideoPlayer.svelte | 10 ++++++----
 src/lib/stores/nativeVideo.ts                |  6 +++++-
 src/lib/utils/pictureInPicture.ts            | 10 +++++++---
 5 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/docs/requirements.md b/docs/requirements.md
index 8d95e7c5..8dbdb114 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -327,7 +327,7 @@ Internal architecture, components, and application logic.
 | DR-168 | Pause and resume actually stop and restart the bytes. `pause_download` wrote `status = 'paused'` and did nothing else, and no cancellation existed anywhere in the download stack — no token, no flag, no abort — so the streaming task ran on, kept writing, and overwrote the row with `completed`/`failed` when it finished: the row flicked to "paused" and undid itself. `resume_download` had the mirror defect, flipping the row to `pending` without calling `pump_download_queue`; the pump runs when something calls it rather than polling, so a resumed download sat untouched until an unrelated event happened to pump the queue. A per-download stop flag (`download::stop`) is the missing half — a module-level registry because the two sides never meet, the command holding Tauri state and the worker running detached in `async_runtime::spawn`. The worker reads it between chunks and on retry (so a pause is not swallowed by a 45-second backoff), flushes, and returns `Stopped`, which is deliberately **not** retryable and **not** recorded as a failure: the `.part` file is left intact because that is exactly what the resume's Range request continues from. Registering returns a *fresh* flag, or a resumed download would inherit the pause that stopped it and halt instantly. Cancel and `clear_stale_downloads` signal it too, so neither deletes a file still being written | Downloads | UR-055 | Done |
 | DR-169 | Partial files are actually reaped. The worker named its sidecar with `Path::with_extension("part")`, which *replaces* the extension — `movie.mp4` became `movie.part` — while every cleanup path deleted `"{file_path}.part"`, i.e. `movie.mp4.part`. The two never matched, so the partial file of every cancelled or failed download stayed on disk indefinitely, invisible to the disk-usage totals because no `downloads` row pointed at it. `partial_path` appends instead, is the single definition both the writer and the cleaners use, and incidentally removes a collision the old form had, where `movie.mp4` and `movie.mkv` mapped to one `movie.part` | Downloads | UR-055 | Done |
 | DR-170 | Downloads at a chosen bitrate are no longer corrupted by their own retries. Only the `original` preset asks for `Static=true`; every other rung requests a **transcode**, which Jellyfin serves chunked, with no `Content-Length`, and cannot byte-seek — so it ignores `Range` and answers `200` with the whole stream from the beginning rather than `206` with the requested tail. The worker sent the Range header whenever a `.part` existed and appended the body unconditionally, so each retry and each resume concatenated a fresh copy of the entire transcode onto the bytes already on disk: the file grew past its real size and would not play, which is why "downloads for different bitrates" stayed broken after the `videoBitRate` casing fix (DR-adc460f3) corrected the *request*. `resume_offset` makes the response decide — append only on a `206`, otherwise truncate and take the stream from the top — and the total size is computed from that offset rather than from a partial length the server never agreed to | Downloads | UR-071 | Done |
-| DR-171 | A downloaded video keeps audio the device can actually decode. `original` quality asked for `Static=true`, which hands back the source file byte-for-byte — E-AC-3/AC-3/DTS/TrueHD track included — and video is rendered on both platforms by the webview `<video>` element, which decodes none of them. Streaming already knew this: DR-149 judges the track the server would serve against `WEBVIEW_AUDIO_CODECS` and forces a transcode over Jellyfin's own direct-play offer, because 10.11.5 honours a `DirectPlayProfile`'s container and video codec but ignores its audio codec. The download path never consulted that policy, so the *same film* had sound when streamed and played as picture in silence once downloaded — and offline a download is the only source a video has, so there was no working path left to fall back to. The rule is now one rule: `served_audio_codec` picks the track the server will serve (the default, or the first when none is marked) and both callers judge it, the streaming verdict staying a bool and the download path needing the codec itself so it can say what to re-encode. Only the audio is re-encoded — `allowVideoStreamCopy=true` keeps an h264 source's picture byte-for-byte and no bitrate or resolution cap is added, so `original` still means original quality; a source the webview could not have rendered anyway (HEVC) becomes h264 as a side effect, which is the only form of it that would have played. The decision is per item rather than blanket because the transcode costs the byte-range resumability `Static=true` gives the download worker (see DR-170 for what a chunked, length-less response does to a resume), so a file whose audio already plays keeps the direct copy. An unknown codec — item not fetchable, or the server named none — changes nothing: the policy only ever *adds* a transcode, so it cannot make a working download worse. `resolve_video_download_url` is the single entrance for all three resolution sites (the frontend's per-item command, the bulk series/season enqueue, and the offline-queued resume), since the pure builder cannot look a codec up and a caller that forgets to is exactly how the silent downloads shipped. **Files already downloaded stay silent** — the bytes on disk are the wrong bytes and only a re-download replaces them | Downloads | UR-071, UR-004 | Done |
+| DR-171 | A downloaded video keeps audio the device can actually decode. `original` quality asked for `Static=true`, which hands back the source file byte-for-byte — E-AC-3/AC-3/DTS/TrueHD track included — and video is rendered on both platforms by the webview `<video>` element, which decodes none of them. Streaming already knew this: DR-149 judges the track the server would serve against `WEBVIEW_AUDIO_CODECS` and forces a transcode over Jellyfin's own direct-play offer, because 10.11.5 honours a `DirectPlayProfile`'s container and video codec but ignores its audio codec. The download path never consulted that policy, so the *same film* had sound when streamed and played as picture in silence once downloaded — and offline a download is the only source a video has, so there was no working path left to fall back to. The rule is now one rule: `served_audio_codec` picks the track the server will serve (the default, or the first when none is marked) and both callers judge it, the streaming verdict staying a bool and the download path needing the codec itself so it can say what to re-encode. Only the audio is re-encoded — `allowVideoStreamCopy=true` keeps an h264 source's picture byte-for-byte and no bitrate or resolution cap is added, so `original` still means original quality; a source the webview could not have rendered anyway (HEVC) becomes h264 as a side effect, which is the only form of it that would have played. The decision is per item rather than blanket because the transcode costs the byte-range resumability `Static=true` gives the download worker (see DR-170 for what a chunked, length-less response does to a resume), so a file whose audio already plays keeps the direct copy. An unknown codec — item not fetchable, or the server named none — changes nothing: the policy only ever *adds* a transcode, so it cannot make a working download worse. The codec set judged against is the **webview's**, not the platform's, even though DR-161 made ExoPlayer the Android default: `experimentalNativeVideo` is a user setting, a downloaded file outlives whatever it was set to when the file arrived, and the narrow list is the only one that holds on both sides of it — at the cost of a Dolby-licensed device re-encoding a track its ExoPlayer could have played. `resolve_video_download_url` is the single entrance for all three resolution sites (the frontend's per-item command, the bulk series/season enqueue, and the offline-queued resume), since the pure builder cannot look a codec up and a caller that forgets to is exactly how the silent downloads shipped. **Files already downloaded stay silent** — the bytes on disk are the wrong bytes and only a re-download replaces them | Downloads | UR-071, UR-004 | Done |
 | 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) |
diff --git a/src-tauri/src/repository/device_profile.rs b/src-tauri/src/repository/device_profile.rs
index 7d95213e..3e296204 100644
--- a/src-tauri/src/repository/device_profile.rs
+++ b/src-tauri/src/repository/device_profile.rs
@@ -65,10 +65,18 @@ const FALLBACK_AUDIO_CODEC: &str = "aac";
 /// play the **video** can decode.
 ///
 /// The platform list comes from `MediaCodecList`, which describes ExoPlayer —
-/// but video does not play through ExoPlayer. Both Android and Linux render it
-/// in a webview `<video>` element, and Chromium/WebKit decode a much smaller set
-/// than the platform does. Advertising the raw list makes Jellyfin direct-play a
-/// track the webview cannot decode, and the user gets picture with no sound.
+/// but the webview `<video>` element may be what renders the video, and
+/// Chromium/WebKit decode a much smaller set than the platform does. Advertising
+/// the raw list makes Jellyfin direct-play a track the webview cannot decode, and
+/// the user gets picture with no sound.
+///
+/// Which renderer gets it is not fixed: Linux is always the element, and Android
+/// follows `experimentalNativeVideo`, which took ExoPlayer as its default in
+/// DR-161 but is a user setting either way. So the *narrow* list is the only one
+/// that holds on both sides of that switch. The cost is a Dolby-licensed Android
+/// device transcoding an E-AC-3 track its ExoPlayer could have direct-played;
+/// the alternative is silence for everyone the switch lands the other way, which
+/// is the bug this exists to prevent.
 ///
 /// The gap is widest on devices whose vendor licenses Dolby: a phone with
 /// `c2.dolby.eac3.decoder` reports `eac3`, so it — and only it — gets a silent
diff --git a/src/lib/components/player/VideoPlayer.svelte b/src/lib/components/player/VideoPlayer.svelte
index 460aef8f..662dd3ec 100644
--- a/src/lib/components/player/VideoPlayer.svelte
+++ b/src/lib/components/player/VideoPlayer.svelte
@@ -120,10 +120,12 @@
    * Keep native's picture-in-picture state in step with the `<video>` element.
    *
    * PiP is driven by the Activity, and it only ever knew about the native
-   * ExoPlayer surface — a path behind `experimentalNativeVideo`, which defaults
-   * to off. So in the shipping configuration nothing satisfied its "is a video
-   * playing?" check and the PiP button did nothing at all. Reporting the element
-   * gives it a surface it can shrink into. (UR-041, DR-160)
+   * ExoPlayer surface — a path behind `experimentalNativeVideo`, which at the
+   * time defaulted to off. So in the then-shipping configuration nothing
+   * satisfied its "is a video playing?" check and the PiP button did nothing at
+   * all. Reporting the element gives it a surface it can shrink into, and still
+   * has to: the flag defaults to on now (DR-161) but a user who turns it off is
+   * back on the element. (UR-041, DR-160, DR-161)
    */
   function reportPipVideoState() {
     if (!useHtml5Element || !videoElement) {
diff --git a/src/lib/stores/nativeVideo.ts b/src/lib/stores/nativeVideo.ts
index 7a54c91b..3940107a 100644
--- a/src/lib/stores/nativeVideo.ts
+++ b/src/lib/stores/nativeVideo.ts
@@ -73,7 +73,11 @@ function createExperimentalNativeVideoStore() {
   };
 }
 
-/** User opt-in for the native Android video path. Default off. */
+/**
+ * User opt-out for the native Android video path. **Defaults to on** since
+ * DR-161 — see `load()`. The name still says "experimental" because the flag
+ * remains a suppressor of Rust's backend choice, not a promoter of it.
+ */
 export const experimentalNativeVideo = createExperimentalNativeVideoStore();
 
 function createNativeVideoActiveStore() {
diff --git a/src/lib/utils/pictureInPicture.ts b/src/lib/utils/pictureInPicture.ts
index 7d4e2246..12eeb613 100644
--- a/src/lib/utils/pictureInPicture.ts
+++ b/src/lib/utils/pictureInPicture.ts
@@ -89,14 +89,18 @@ export function setAutoEnterEnabled(enabled: boolean): void {
 /**
  * Tell native that a WebView `<video>` is (or is no longer) the playback surface.
  *
- * This is what makes PiP work at all in the shipping configuration. The native
- * side only ever knew about the ExoPlayer surface, and that path is behind
- * `experimentalNativeVideo`, which defaults to off — so `canEnterPip` was always
+ * This is what makes PiP work on the HTML5 path. The native side only ever knew
+ * about the ExoPlayer surface, and that path is behind `experimentalNativeVideo`,
+ * which defaulted to off when this was written — so `canEnterPip` was always
  * false and pressing the button did nothing. Reporting the element's state gives
  * native a surface it can legitimately shrink into, plus the intrinsic size it
  * needs for the PiP window's aspect ratio and the play state for its play/pause
  * action.
  *
+ * The flag defaults to **on** now (DR-161), so Android normally shrinks the real
+ * ExoPlayer surface instead; this remains the path for Linux and for anyone who
+ * turned the flag off.
+ *
  * Pass `active: false` when the element goes away, or PiP would be offered over a
  * video that is no longer there.
  *