feat(android): conformance on a device, and a start position for ExoPlayer

DR-247. The desktop suite cannot reach ExoPlayer: it needs an Android Context
and a Looper, so it exists only inside an app process. These are the same
behaviours, asserted against the engine itself.

Writing them forced the same gap open that mpv had. JellyTauPlayer.load(url,
mediaId) had no way to express a start position, so every caller loaded and
then seeked — the test could not even be written against the old signature,
which is a stronger statement than a failing assertion. The position now goes
to ExoPlayer with the media item via setMediaItem(item, startPositionMs), and
the two-argument form delegates to it, so nothing else had to change.

Running one suite against both engines settled something guesswork could not:

  seekWhileOpeningIsHonoured  passes on ExoPlayer with no fix

ExoPlayer already queues a seek issued before prepare() completes. So the
lost-seek half of DR-241 was mpv-specific, and only the missing vocabulary for
a start position was shared. That is the difference between "both engines have
this bug" and knowing which one does.

All seven cases pass on device (ROD2-W09, arm64).

The fixture is a silent WAV synthesised in the cache directory at setup rather
than committed or pushed: no binary in the repo, no adb step, and an exact
duration, which the seek assertions depend on.

Also adds the instrumentation runner to defaultConfig and teaches
sync-android-sources.sh to mirror src/androidTest, the way it already mirrors
src/test — so the canonical tree stays the only place tests are edited.

Run: ./gradlew :app:connectedUniversalDebugAndroidTest -x :app:rustBuildUniversalDebug

.gitea/workflows/build-and-test.yml

@@ -28,7 +28,7 @@ jobs:
     if: "!startsWith(github.event.head_commit.message, 'chore(release)')"
     runs-on: linux/amd64
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
 
     steps:
       - name: Checkout repository
@@ -187,7 +187,7 @@ jobs:
     runs-on: linux/amd64
     needs: test
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     env:
       ANDROID_HOME: /opt/android-sdk
       ANDROID_SDK_ROOT: /opt/android-sdk
@@ -256,7 +256,7 @@ jobs:
     name: Supply Chain
     runs-on: linux/amd64
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
 
     steps:
       - name: Checkout repository

.gitea/workflows/build-release.yml

@@ -21,7 +21,7 @@ jobs:
     name: Run Tests
     runs-on: linux/amd64
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -94,7 +94,7 @@ jobs:
     runs-on: linux/amd64
     needs: test
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -190,12 +190,15 @@ jobs:
           # Without nullglob an unmatched pattern stays literal, so test each
           # candidate instead. Same POSIX-only rule as traceability-check.yml.
           #
-          # The .AppImage.tar.gz + .sig pair is what the updater downloads and
-          # verifies; the plain .AppImage is what a human downloads. Both ship.
+          # Tauri v2 signs the .AppImage ITSELF and writes <name>.AppImage.sig
+          # beside it -- there is no .AppImage.tar.gz unless
+          # bundle.createUpdaterArtifacts is set to "v1Compatible". The updater
+          # downloads the same AppImage a human does and verifies that .sig, so
+          # both files must ship or the manifest points at a signature nobody
+          # can fetch.
           for bundle in \
             src-tauri/target/release/bundle/appimage/*.AppImage \
-            src-tauri/target/release/bundle/appimage/*.AppImage.tar.gz \
-            src-tauri/target/release/bundle/appimage/*.AppImage.tar.gz.sig \
+            src-tauri/target/release/bundle/appimage/*.AppImage.sig \
             src-tauri/target/release/bundle/deb/*.deb \
             src-tauri/target/release/bundle/rpm/*.rpm; do
             [ -e "$bundle" ] || continue
@@ -232,7 +235,7 @@ jobs:
     # baked into the builder image. No toolchain installs here — the image has
     # cargo-xwin, clang/clang-cl, lld, llvm, nsis and the msvc target.
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -305,7 +308,7 @@ jobs:
     runs-on: linux/amd64
     needs: test
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     env:
       ANDROID_HOME: /opt/android-sdk
       ANDROID_SDK_ROOT: /opt/android-sdk
@@ -408,7 +411,7 @@ jobs:
     needs: [build-linux, build-windows, build-android]
     if: startsWith(github.ref, 'refs/tags/v')
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -499,8 +502,13 @@ jobs:
           APPIMAGE_URL=""
           NSIS_URL=""
 
-          for f in artifacts/linux/*.AppImage.tar.gz; do
+          # Tauri v2 signs the AppImage itself; <name>.AppImage.sig sits beside
+          # it. Verified against a real signed build before tagging -- the
+          # v1-style .AppImage.tar.gz is never produced with
+          # createUpdaterArtifacts: true.
+          for f in artifacts/linux/*.AppImage; do
             [ -e "$f" ] || continue
+            case "$f" in *.sig) continue;; esac
             APPIMAGE_URL="${BASE}/$(basename "$f")"
             [ -e "$f.sig" ] && APPIMAGE_SIG="$(cat "$f.sig")"
           done

.gitea/workflows/publish-docs.yml

@@ -21,7 +21,7 @@ jobs:
     name: Build & publish docs to gitea-pages
     runs-on: linux/amd64
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
 
     steps:
       - name: Checkout code

.gitea/workflows/traceability-check.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: linux/amd64
     name: Check Requirement Traces
     container:
-      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:2026.08.1
 
     steps:
       - name: Checkout repository

CHANGELOG.md

@@ -9,6 +9,26 @@ generated trace matrix lives in [docs/traceability.md](docs/traceability.md).
 For how long each fixed defect had been shipping before it was found, see
 [docs/defect-windows.md](docs/defect-windows.md).
 
+## v0.10.1
+
+A single fix, for something that had been quietly overriding a choice you made.
+
+### 🐛 Fixes
+
+- **Locking the screen no longer keeps playing a video's audio unless you asked
+  it to.** The player has a background-audio button: turn it on and the sound
+  carries on when you lock the screen or leave the app, turn it off and playback
+  stops. It stopped working when video moved to the native renderer — which plays
+  through a media service designed to keep going while the app is hidden — and
+  nothing was left to stop it. So the audio continued whether the button was on
+  or off, and there was no way to make it behave otherwise. The button governs it
+  again: with it off, locking the screen pauses the video and unlocking resumes
+  where you were; with it on, the audio continues as before. Music is untouched —
+  it keeps playing when backgrounded, as a music player should — and a video in a
+  picture-in-picture window keeps playing too, because the window is still on
+  screen. If you had already paused before locking, it stays paused.
+  (UR-040 → DR-224)
+
 ## v0.10.0
 
 Two things you can see, and a great deal of work on how this project builds and

Dockerfile.builder

@@ -141,6 +141,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     lld \
     llvm \
     nsis \
+    # AppImage bundling. linuxdeploy embeds xdg-open into the AppImage and
+    # aborts the whole bundle if it is missing:
+    #   failed to bundle project: xdg-open binary not found
+    # It is present on most desktop distros, which is why the AppImage built on
+    # a developer machine and failed here. desktop-file-utils and zsync are the
+    # other two linuxdeploy commonly wants (desktop-file-validate, and zsync for
+    # delta updates), added together so a missing one does not cost another
+    # image rebuild and another failed release build.
+    xdg-utils \
+    desktop-file-utils \
+    zsync \
     && rm -rf /var/lib/apt/lists/* \
     # Ubuntu's clang package ships clang but NOT the clang-cl alias that cc-rs
     # invokes for MSVC targets. clang-cl is the same binary in MSVC-compat mode,

docs-site/SUMMARY.md

@@ -41,6 +41,7 @@
 - [Scoped Search Boundary](specs/scoped-search-boundary.md)
 - [Scoped Search Boundary — Implementation](specs/scoped-search-boundary-implementation.md)
 - [Frontend Domain Model](specs/frontend-domain-model.md)
+- [Desktop Native Video](specs/desktop-native-video.md)
 - [Build Provenance](specs/build-provenance.md)
 
 # Build & Release

docs/architecture/01-rust-backend.md

@@ -675,7 +675,7 @@ source file's own bitrate, and no URL parameter afterwards can reduce it.
 
 #### Two levels of ceiling
 
-**Location**: `src-tauri/src/repository/online.rs` (TRACES: UR-074, UR-079 | DR-225)
+**Location**: `src-tauri/src/repository/online.rs` (TRACES: UR-074, UR-079 | DR-226)
 
 There are two, and they are not the same thing:
 
@@ -703,7 +703,7 @@ to constrain, or the reverse.
 ### Stream selection
 
 **Location**: `src-tauri/src/repository/stream_selection.rs`,
-`OnlineRepository::get_stream_selection` (TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227)
+`OnlineRepository::get_stream_selection` (TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228)
 
 **Rust decides *what stream*. The player decides *how to deliver it*.** That line
 is the whole design. A backend with genuine adaptive selection (ExoPlayer over a
@@ -719,7 +719,7 @@ the bare URL `get_video_stream_url` used to hand out:
 | `transport` | `Hls` / `Progressive` / `LocalFile` — how to fetch it |
 | `playback_kind` | `DirectPlay` / `DirectStream` / `Transcode` — what the server is doing to the source |
 | `rendition` | The negotiated ceiling and codecs; `None` for a direct play, which *is* the source |
-| `available` | The quality ladder as it applies to this media source (DR-226) |
+| `available` | The quality ladder as it applies to this media source (DR-227) |
 | `needs_transcoding` | Derived from `playback_kind`, so the rule is answered once |
 
 Both enums are serde-tagged (`{"type":"hls"}`) so the frontend matches a
@@ -770,11 +770,21 @@ a free passthrough as a server-side re-encode.
 > | Android / ExoPlayer (`h264,hevc,vp8,vp9,av1,mpeg4` + `ac3,eac3`, 6ch) | 34/40 — **85%** |
 >
 > The library is ~80% hevc (`hevc+eac3` alone is a third of it), which is why the
-> two diverge so hard. **The payoff is overwhelmingly Android**, where 85% of
-> plays previously burned a transcode nobody needed. Linux stays near 7% until
-> libmpv decodes the picture — the h264-only profile is a WebKitGTK constraint,
-> not a JellyTau choice, and is what `linux-native-video-spike.md` exists to
-> remove. A reviewer should not expect this code to fix Linux on its own.
+> two diverge so hard.
+>
+> **Read that 85% as a ceiling, not a result.** It was measured with a profile
+> containing `ac3,eac3`. The Android device this was later run on reports neither
+> in its `MediaCodecList` — no Dolby licence, which is normal for a tablet — so
+> eac3 content, about a third of the sampled library, correctly transcodes there.
+> What any given device achieves depends on its own codec list, and on the
+> profile being derived from the renderer at all (DR-234), which it was not when
+> the figure was taken.
+>
+> **The payoff is still overwhelmingly Android**, because that is where a real
+> decoder is already doing the work. Linux stays near 7% until libmpv decodes the
+> picture — the h264-only profile is a WebKitGTK constraint, not a JellyTau
+> choice, and is what `linux-native-video-spike.md` exists to remove. A reviewer
+> should not expect this code to fix Linux on its own.
 
 #### The quality ladder per source
 
@@ -791,7 +801,7 @@ they are.
 
 #### No adaptive ladder to preserve
 
-**TRACES: UR-079 | DR-228 (Won't Do)**
+**TRACES: UR-079 | DR-229 (Won't Do)**
 
 Mid-playback re-negotiation on throughput was scoped and dropped on measurement.
 A master playlist from this server carries exactly **one** `EXT-X-STREAM-INF`:

docs/architecture/02-svelte-frontend.md

@@ -805,7 +805,7 @@ can safely be re-sent on resume.
 ## Stream Transport
 
 **Location**: `src/lib/player/streamTransport.ts`
-**TRACES**: UR-079 | DR-224 | UT-213
+**TRACES**: UR-079 | DR-225 | UT-214
 
 `videoLoaderFor(selection, capabilities)` picks the loader for the webview
 `<video>` element — `hlsjs`, `nativeHls`, or `direct` — from the backend's tagged
@@ -835,7 +835,7 @@ drift apart. The background-audio handoff states the transport it is moving to
 progressive mp3 out, HLS back — via `selectionAt()`, rather than leaving it to be
 inferred.
 
-The quality picker is filled from `selection.available` (DR-226): rungs the
+The quality picker is filled from `selection.available` (DR-227): rungs the
 backend marked `exceedsSource` are not drawn, because they produce the same bytes
 as `Original`. Nothing is optimistically assigned when the viewer picks a rung —
 what the menu shows comes from the selection the backend hands back, since a

docs/architecture/03-data-flow.md

@@ -134,7 +134,7 @@ sequenceDiagram
 
 ## Video Stream Selection Flow
 
-**TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227**
+**TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228**
 
 Before a video plays, Rust decides *what stream* — direct play, remux or
 transcode, over which transport — and hands the player one self-describing

docs/build/ci-operations.md

@@ -61,6 +61,11 @@ filled. Keep a couple of dated tags live and prune the rest.
 
 The order matters — CI breaks if the workflow lands before the image exists.
 
+A caveat learned the hard way: the *trailing* layer is only fast for `cargo
+install` tools. Adding an **apt** package invalidates the packaging layer, which
+sits above the `cargo-xwin`/`cargo-deny` installs, so those recompile too — a
+~20 minute rebuild rather than ~2.
+
 ```bash
 # 1. Edit Dockerfile.builder. Put new tools in the TRAILING layer: it exists so
 #    a tool change is a ~2 min rebuild instead of ~15.
@@ -103,6 +108,25 @@ transitive upgrade (bumping `tauri-plugin-log` to 2.9.0 also moved `wry`,
 therefore video playback. That is a change to make deliberately, with a full
 build and a playback check — not one to slip into a release.
 
+## AppImage needs more than the Rust toolchain
+
+`linuxdeploy` (which Tauri downloads at build time to assemble the AppImage)
+shells out to distro tools that a minimal server image does not have. It aborts
+the whole bundle on the first one missing:
+
+```
+failed to bundle project: xdg-open binary not found
+```
+
+The image therefore carries `xdg-utils`, `desktop-file-utils` and `zsync`. This
+is a class of failure that **cannot be caught by building locally**: a developer
+machine is a desktop and has all three, so the AppImage builds there and fails in
+CI. It cost one release build to find.
+
+Tauri's AppImage bundler also downloads `linuxdeploy`, `AppRun` and two plugin
+scripts from GitHub during the build. That is Tauri's behaviour, not ours, but it
+means an AppImage build depends on GitHub being reachable from the runner.
+
 ## Secrets
 
 Managed with the `tea` CLI (`tea actions secrets list`) or the repo settings UI.

docs/requirements.md

@@ -89,6 +89,8 @@ For a narrative overview of the system design, see
 | UR-077 | The app can update itself, or tell the user how. Somebody who installed an AppImage or ran the Windows installer had no upgrade path at all: nothing in the app ever mentioned that a newer version existed, and the release notes were the only announcement. On Linux and Windows the app checks a signed manifest, offers the new version with its notes, and installs and relaunches on request — the signature check is the point, since it is what stops a substituted download from being installed by the app itself. Android cannot do this (an app may not overwrite its own APK; that is the package installer's job) and is given the honest alternative, a link to the releases page, rather than a button that would throw | Medium | Done |
 | UR-078 | JellyTau keeps a record of what it did, and can hand it over. The app forgot everything the moment it exited: the backend logged to stdout only — which a user launching from a desktop icon never sees, and which on Android is not logcat, so the Rust half was invisible on the platform carrying the hardest bugs. A crash left nothing at all. Logs are now written to a size-capped rotating file, a panic is recorded before the process dies, the frontend's messages land in the same timeline as the backend's, and Settings exports the lot as one file to attach to a bug report. Nothing is transmitted anywhere — the user attaches it themselves, which is also what keeps this from being telemetry. Access tokens and passwords never reach the file | Medium | Done |
 | UR-079 | The app decides *what stream to play* and says so. Playing a video used to mean asking the server to re-encode it, always — a decision made nowhere, written down nowhere, and re-derived downstream by whoever needed it: the player worked out whether it had been handed a playlist by looking for `.m3u8` in the URL. So a viewer paid for a transcode of a file their device could have played untouched, and the app could not tell them which it was. Now one negotiation produces one self-describing answer — direct play, remux, or transcode; over a playlist, a plain HTTP file, or a local one — and every renderer consumes that same answer instead of guessing from a string. On Android, where the player decodes almost everything the library holds, this stops around 85% of plays from starting a transcode nobody needed | Medium | Done |
+| UR-080 | Video on the desktop plays as itself. The picture was drawn by a webview `<video>` element, which decodes little beyond h264 — so the app told the server it could accept only h264, and the server re-encoded almost everything before sending it. That was never a statement about the machine: the same machine already runs mpv for audio, which decodes essentially the whole library. Measured against a real library, 93% of desktop playback was a transcode nobody needed, against 15% on Android where a real decoder does the work. mpv now draws the picture, the app claims what it can genuinely decode, and video is sent as it was stored wherever that is possible — sparing the server the work, the network the bitrate, and the picture a generation of re-encoding | Medium | Proposed |
+| UR-081 | Playback behaves the same whichever engine renders it | High | In Progress |
 | 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 |
 
 ---
@@ -133,6 +135,7 @@ External system integrations and platform-specific implementations.
 | IR-030 | Scheduled full-catalog crawl of every library (`Recursive=true`, paged) feeding the local index, driven by a Rust background task and the `ConnectivityMonitor` reconnect signal rather than by the frontend | Storage | UR-065 | Implemented |
 | IR-031 | Android `WindowInsets` bridge: an `OnApplyWindowInsetsListener` on the decor view reports `systemBars() | displayCutout()` in CSS pixels, pushed into the WebView as `jt-inset` CSS custom properties plus a `jellytau-insets-changed` event, and pullable via the `AndroidInsets` JS bridge | Platform | UR-066 | Done (pending device verification) |
 | IR-032 | Whole-file background download of the item being played, reusing the existing resumable download worker and the Range-capable `/Videos/{id}/stream.mp4` endpoint; plus per-platform read-through caching hooks (ExoPlayer `CacheDataSource`, mpv `stream-record`) for direct-play sessions only | Storage | UR-071 | Proposed |
+| IR-033 | libmpv render-API integration for video: `vo=libmpv` driving an OpenGL FBO bound by the host toolkit, with GL entry points resolved through libepoxy. Note that libepoxy exports them as *data* symbols — there is no `glFoo` function, only an `epoxy_glFoo` variable holding a lazily-resolving pointer — so `get_proc_address` must return the pointer stored **at** that symbol; returning the symbol's own address makes mpv jump into non-executable data and take SIGSEGV on the first GL call. The `epoxy` crate resolves this correctly but is unusable, its `gl_generator` dependency pulling a yanked `xml-rs` | Playback | UR-080 | Proposed |
 
 > **Where a UR is met by a different mechanism than its IR anticipated.** Several
 > integration requirements were written when libmpv was expected to be the single
@@ -416,12 +419,29 @@ Internal architecture, components, and application logic.
 | DR-221 | The release path is exercised before a tag exists. Nothing in `build-and-test.yml` runs `tauri build` — only a tag does — so a whole class of breakage was invisible until release day, and two instances of it were sitting on master at once. Tauri refuses to build when a plugin's Rust crate and npm package differ by minor version, which the updater and logging work had introduced (`tauri-plugin-log 2.8.0` against `@tauri-apps/plugin-log 2.9.0`) while `cargo check`, clippy, the tests and `svelte-check` all passed; both sides are now pinned exactly rather than by caret, since a caret is what let them separate, and CI runs `tauri info` to compare them without building. The AppImage target had never once been built: linuxdeploy carries a `strip` too old to parse the `.relr.dyn` section modern toolchains emit, so bundling failed on every library — and Ubuntu 23.10+ links with `-z pack-relative-relocs` by default, so the builder image fails the same way a modern Arch host does. `NO_STRIP=true` is linuxdeploy's documented escape hatch; the cost is a larger, unstripped bundle. Both were found by building the target locally before tagging rather than by publishing a release that could not build | Tooling | - | Done |
 | DR-222 | Build tooling matches the package manager the project declares. `scripts/build-android.sh` ran `npm install` on its clean-build path — in a bun project, where `packageManager` says bun and `bun.lock` is the committed lockfile. npm ignores that lockfile, re-resolves the whole tree from package.json, and writes a `package-lock.json` that `.gitignore` then hides. That is not a style preference: the JS halves of the Tauri plugins are pinned exactly against Cargo.lock because the CLI refuses to build when a plugin's crate and package differ by minor version, and a silent re-resolve is precisely how they drift apart. It survived because clean builds are rare — the shape shared by nearly every defect found preparing v0.10.0, where the code running on every commit was healthy and the code running on a release, a tag or a clean build had no guard at all. `scripts/check-tooling.sh` fails on any npm/yarn/pnpm invocation or foreign lockfile | Tooling | - | Done |
 | DR-223 | The Android JavaVM and Application are published into `ndk_context` by this crate, not by a transitive dependency. Seven call sites (five in credentials.rs, two in lib.rs) read that process-global to reach JNI, and nothing here ever set it — `tao` did, three levels below anything this project names in Cargo.toml. tao 0.35.3 moved those pointers into a private struct and stopped publishing them, so the Tauri 2.11 upgrade made the first credential read abort the process on every launch: `PANIC ... android context was not initialized`. Our code had not changed; an undocumented side effect of the windowing layer had gone. The invariant is now owned here rather than assumed: `JNI_OnLoad` captures the JavaVM as the shared library loads, and the Application is resolved lazily via `ActivityThread.currentApplication()` and pinned as a global reference for the process lifetime — the Application rather than the Activity, since that is what `SecureStorage.initialize()` immediately reduces its argument to. Failure degrades to the encrypted-file credential path and is logged, rather than aborting. Found only by installing on a device: nothing in CI runs the app | Security | UR-012 | Done |
-| DR-224 | `StreamSelection` replaces the bare URL returned for playback: URL, `Transport` (hls / progressive / localFile), `PlaybackKind` (directPlay / directStream / transcode), the negotiated `Rendition`, the ladder this source can offer, and a `needs_transcoding` flag derived in Rust so "which kinds count as transcoding" is answered once. Both enums are serde-tagged (`{"type":"hls"}`) so the frontend matches a discriminant rather than comparing text. The field that mattered most is `transport`: `VideoPlayer.svelte` chose its loader with `url.includes(".m3u8")` in two places, a domain fact reconstructed in the presentation layer — the same class of error as leaking item-type taxonomy, and one that fails silently in both directions (a progressive file served from a path containing the substring gets an HLS loader; a playlist served from one without it does not). The paths that never negotiate — a downloaded file, a live channel — get the same shape from Rust (`media_local_selection`, `LiveStreamInfo.transport`) rather than having the page assemble one, so there is no second place where a transport is decided | Playback | UR-079 | Done |
-| DR-225 | The bandwidth ceiling is two-level: a durable device default (Settings, persisted, restored at startup) and a per-playback override the in-player picker sets. The picker's own documentation had called it a "this film, this connection" control since it was written, but it was implemented by writing the process-wide default — so dropping one awkward film to 2 Mbps silently capped every video played afterwards for the rest of the process, while the Settings screen still displayed the old value and nothing in the UI admitted the change. The override is cleared whenever playback moves to a new item, which is what keeps it from surviving into an autoplayed next episode where nobody would reopen the picker. `effective_streaming_quality()` is the single resolution point; every URL builder and the `PlaybackInfo` negotiation go through it, because a negotiation that authorises a direct play the URL builder then constrains (or the reverse) leaks the cap | Playback | UR-074, UR-079 | Done |
-| DR-226 | The quality picker is filled from what *this* media source can offer, not from the fixed eight-rung enum. Rust marks each rung `exceeds_source` when its ceiling is at or above the source's own bitrate — such a rung produces the same bytes as `Original`, so offering it is another way to spell one choice — and the frontend simply does not draw those. `Original` is never marked (it *is* the source) and a source whose bitrate the server does not report (the sampled library has `avi` files with none) marks nothing redundant, keeping every rung offered, which is the safe direction. The picker also shows what the server is actually doing with the stream, which only became knowable once `PlaybackKind` existed. Labels and detail lines come from Rust beside the numbers they describe, so a relabelled rung cannot drift out of step with what it does | UI | UR-070, UR-079 | Done |
-| DR-227 | Direct play and direct stream are negotiated rather than assumed away. `get_video_stream_url` always built an HLS transcode URL, so every video play burned server CPU even when the file would have played untouched. The decision now comes from `PlaybackInfo` under the device profile and the ceiling in force, with two client-side overrides applied on top because the server's answer is right about the *file* and wrong about what this app will do with it: undecodable audio (Jellyfin 10.11.5 honours a DirectPlayProfile's container and video codec but ignores its audio codec, so it offers direct play for an E-AC-3 track the webview renders in silence) and a viewer-pinned audio track the source file does not default to. Measured against the development server over a 400-item sample: **85% direct play on the Android profile, 7% on the Linux one** — the library is ~80% hevc and WebKitGTK can only claim h264, so the Linux figure is a property of the renderer, not of this code, and is what `linux-native-video-spike.md` exists to change. A direct *stream* is a remux and is deliberately not counted as transcoding | Playback | UR-079 | Done |
-| DR-228 | Mid-playback re-negotiation on throughput was scoped and **dropped on measurement**. The premise — that hls.js gives this app real adaptive bitrate and mpv would lose it — does not hold: a master playlist from the development server carries exactly one `EXT-X-STREAM-INF`, because Jellyfin builds it from the single rendition the request asked for rather than publishing a ladder. There is no adaptation to preserve, so "adapt mid-stream" collapses into "pick well at open", which is what DR-225 and DR-226 already are. Recorded rather than deleted because the conclusion is a measurement, not an opinion, and a server that does publish a ladder would change it — the DR-224 re-negotiation path is the hook that work would build on | Playback | UR-079 | Won't Do |
-| DR-229 | Every player backend consumes the same selection, proving the contract is player-agnostic rather than HTML5-shaped. The queue item carries the negotiated `transport`, so `player_seek_video` picks its seek strategy from the backend's own decision instead of the last `stream_url.contains(".m3u8")` in the codebase; items queued by a path that never negotiated (audio tracks, direct URLs) carry `None` and fall back to `needs_transcoding`, which is exact rather than a guess because every transcode this app requests is HLS (DR-140). The webview adapter's bridge carries the whole selection rather than a URL, so the component's HLS effect reads a tag instead of searching a string, and the background-audio handoff states the transport it is moving to (progressive mp3 out, HLS back) rather than leaving it to be inferred | Playback | UR-003, UR-004, UR-079 | Done |
+| DR-224 | Backgrounding the app obeys the background-audio toggle on every renderer. The toggle (UR-040) was built for the WebView `<video>` path, where losing visibility kills the decode: it chose between handing off to a native audio stream and letting playback stop. Native video then became the default renderer (DR-188), and on that path playback runs through ExoPlayer inside a `MediaSessionService` — a foreground media service whose purpose is to keep playing while the app is hidden. Nothing paused it and nothing in the codebase paused on background, so locking the screen kept the audio going whether or not the toggle was on: the toggle governed a handoff that no longer had a gap to bridge, and users got background playback they never asked for. The decision now lives in Rust (`player/background_policy.rs`) and both renderers obey it: a video with the toggle off pauses, with the toggle on hands off to audio, music is never paused by backgrounding, and picture-in-picture keeps playing because the window is still on screen (UR-041). It takes no renderer parameter on purpose — the split between the two paths is what produced the defect | Player | UR-040 | Done |
+| DR-225 | `StreamSelection` replaces the bare URL returned for playback: URL, `Transport` (hls / progressive / localFile), `PlaybackKind` (directPlay / directStream / transcode), the negotiated `Rendition`, the ladder this source can offer, and a `needs_transcoding` flag derived in Rust so "which kinds count as transcoding" is answered once. Both enums are serde-tagged (`{"type":"hls"}`) so the frontend matches a discriminant rather than comparing text. The field that mattered most is `transport`: `VideoPlayer.svelte` chose its loader with `url.includes(".m3u8")` in two places, a domain fact reconstructed in the presentation layer — the same class of error as leaking item-type taxonomy, and one that fails silently in both directions (a progressive file served from a path containing the substring gets an HLS loader; a playlist served from one without it does not). The paths that never negotiate — a downloaded file, a live channel — get the same shape from Rust (`media_local_selection`, `LiveStreamInfo.transport`) rather than having the page assemble one, so there is no second place where a transport is decided | Playback | UR-079 | Done |
+| DR-226 | The bandwidth ceiling is two-level: a durable device default (Settings, persisted, restored at startup) and a per-playback override the in-player picker sets. The picker's own documentation had called it a "this film, this connection" control since it was written, but it was implemented by writing the process-wide default — so dropping one awkward film to 2 Mbps silently capped every video played afterwards for the rest of the process, while the Settings screen still displayed the old value and nothing in the UI admitted the change. The override is cleared whenever playback moves to a new item, which is what keeps it from surviving into an autoplayed next episode where nobody would reopen the picker. `effective_streaming_quality()` is the single resolution point; every URL builder and the `PlaybackInfo` negotiation go through it, because a negotiation that authorises a direct play the URL builder then constrains (or the reverse) leaks the cap | Playback | UR-074, UR-079 | Done |
+| DR-227 | The quality picker is filled from what *this* media source can offer, not from the fixed eight-rung enum. Rust marks each rung `exceeds_source` when its ceiling is at or above the source's own bitrate — such a rung produces the same bytes as `Original`, so offering it is another way to spell one choice — and the frontend simply does not draw those. `Original` is never marked (it *is* the source) and a source whose bitrate the server does not report (the sampled library has `avi` files with none) marks nothing redundant, keeping every rung offered, which is the safe direction. The picker also shows what the server is actually doing with the stream, which only became knowable once `PlaybackKind` existed. Labels and detail lines come from Rust beside the numbers they describe, so a relabelled rung cannot drift out of step with what it does | UI | UR-070, UR-079 | Done |
+| DR-228 | Direct play and direct stream are negotiated rather than assumed away. `get_video_stream_url` always built an HLS transcode URL, so every video play burned server CPU even when the file would have played untouched. The decision now comes from `PlaybackInfo` under the device profile and the ceiling in force, with two client-side overrides applied on top because the server's answer is right about the *file* and wrong about what this app will do with it: undecodable audio (Jellyfin 10.11.5 honours a DirectPlayProfile's container and video codec but ignores its audio codec, so it offers direct play for an E-AC-3 track the webview renders in silence) and a viewer-pinned audio track the source file does not default to. Measured against the development server over a 400-item sample: **85% direct play on the Android profile, 7% on the Linux one** — the library is ~80% hevc and WebKitGTK can only claim h264, so the Linux figure is a property of the renderer, not of this code, and is what `linux-native-video-spike.md` exists to change. A direct *stream* is a remux and is deliberately not counted as transcoding | Playback | UR-079 | Done |
+| DR-229 | Mid-playback re-negotiation on throughput was scoped and **dropped on measurement**. The premise — that hls.js gives this app real adaptive bitrate and mpv would lose it — does not hold: a master playlist from the development server carries exactly one `EXT-X-STREAM-INF`, because Jellyfin builds it from the single rendition the request asked for rather than publishing a ladder. There is no adaptation to preserve, so "adapt mid-stream" collapses into "pick well at open", which is what DR-225 and DR-226 already are. Recorded rather than deleted because the conclusion is a measurement, not an opinion, and a server that does publish a ladder would change it — the DR-224 re-negotiation path is the hook that work would build on | Playback | UR-079 | Won't Do |
+| DR-230 | Every player backend consumes the same selection, proving the contract is player-agnostic rather than HTML5-shaped. The queue item carries the negotiated `transport`, so `player_seek_video` picks its seek strategy from the backend's own decision instead of the last `stream_url.contains(".m3u8")` in the codebase; items queued by a path that never negotiated (audio tracks, direct URLs) carry `None` and fall back to `needs_transcoding`, which is exact rather than a guess because every transcode this app requests is HLS (DR-140). The webview adapter's bridge carries the whole selection rather than a URL, so the component's HLS effect reads a tag instead of searching a string, and the background-audio handoff states the transport it is moving to (progressive mp3 out, HLS back) rather than leaving it to be inferred | Playback | UR-003, UR-004, UR-079 | Done |
+| DR-231 | An mpv video backend that composites beneath the transparent webview, the desktop counterpart of the Android TextureView arrangement. mpv renders through its **render API** into an FBO the toolkit binds (`vo=libmpv` + `mpv_render_context_create` with `MPV_RENDER_PARAM_OPENGL_FBO`), rather than by embedding a foreign window — which is what the 2024 "not possible on Wayland at all" conclusion was about and why it does not apply. On Linux that is a `GtkOverlay` with a `GtkGLArea` as main child and Tauri's own webview reparented as the overlay child; the mpv half is shared and only the surface differs per platform. Webview transparency alone suffices — no window-level transparency is used or needed | Playback | UR-080 | Proposed |
+| DR-232 | The mpv render context's lifetime is bound to the GL context it draws into: created on `realize`, freed on `unrealize`, on the same thread, with the update callback unregistered *before* the free so a callback cannot land on a freed context. This is DR-184 on Android restated — a surface outliving its player — and it is a requirement in its own right rather than a fix for a specific crash. The spike observed one SIGSEGV in a decoder thread that three targeted soaks failed to reproduce; what is not in doubt is that the spike never called `mpv_render_context_free` and never tore down on `unrealize`, so nothing defended against the GL context being recreated underneath. Removing the likeliest cause is worth doing whether or not it was the cause | Playback | UR-080 | Proposed |
+| DR-233 | Frame pacing goes through mpv's update callback, with `mpv_render_context_report_swap` after each render. Recorded as a requirement because the failure mode misleads: driving the widget's frame clock every tick without reporting the swap leaves mpv with nothing to time against, which looks fine in a window and **judders at fullscreen** — reading as a compositing or GPU limit and being neither | Playback | UR-080 | Proposed |
+| DR-234 | The device profile is derived from the **renderer that will decode the stream**, not from a compile-time platform constant. `video_codecs` was `#[cfg(target_os)]`, which is correct only while a build has one video renderer; once mpv and the webview element coexist it must be runtime state. This is the change that converts the measured 7% desktop direct-play rate toward the 85% the Android profile achieves on the same library, because the two differ by nothing except which component decodes. It looks like configuration and is not — it is the input that decides whether the server re-encodes, and getting it wrong fails silently, a claimed codec the renderer cannot decode being a black picture or silence (DR-148, and DR-227's audio override). The webview's narrower *audio* set stops applying to the video path once mpv decodes it, while the multichannel bound still does, since a 5.1 track direct-played into a two-channel sink is silence or inaudible dialogue | Repository | UR-080, UR-070 | In Progress |
+| DR-235 | The webview video path is deleted, not merely bypassed. Staged, because a path cannot be removed while a shipped platform still needs it: Linux moves to mpv first, Windows follows, and only then do `hls.js`, `html5Adapter.ts`, `videoLoaderFor` and the `<video>` element go. The staging is the point — a Linux-only version would leave the fork alive permanently, taking video from three renderers to four and giving every seek strategy, track switch and lifecycle bug one more place to be got right. Android keeps ExoPlayer and keeps the webview as its documented opt-out; the background-audio `<audio>` path is untouched. With no HTML5 fallback left, a failed mpv init emits `backend-init-failed` and surfaces a real error rather than silently degrading to the transcode this work exists to stop paying for | Playback | UR-080 | Proposed |
+| DR-236 | Hardware-decode policy is decided from what mpv reports it **selected** (`hwdec-current`), never from what it was asked for. The spike established that hardware decode works through the render API at all — the load-bearing result, since it means direct play is not bought with software decoding — but also that `auto` reached for the discrete GPU in copy-back mode on a hybrid Intel+NVIDIA laptop, the least efficient hardware path, and that `vaapi` fell back to software silently because the libva driver was absent. So zero-copy VA-API on the integrated GPU is preferred where the driver is present, `auto` is a fallback rather than the default, and a missing driver is detected and logged rather than mistaken for a compositing limit | Playback | UR-080 | Proposed |
+| DR-237 | Windows reaches the same mpv path, reusing everything except the surface. The surface is genuinely different code — a native child window beneath a transparent WebView2, not GTK — but the render context, lifetime discipline, frame pacing, device profile and hwdec policy are shared, which is why none of them may be guarded on `cfg!(target_os = "linux")`. The cost is mostly build, not video: `libmpv` is currently a Linux-only dependency while Windows is cross-compiled from Linux via `x86_64-pc-windows-msvc` + `cargo-xwin`, so a Windows libmpv must reach that cross-build and its DLL must ship in the NSIS bundle, carrying the LGPL obligations DR-216 already records — dynamic linkage, licence text shipped alongside. Windows gains a native audio decoder as a side effect, which is what the long-blocked Windows audio work wants and cannot otherwise have | Playback | UR-080 | Proposed |
+| DR-238 | A transcoded seek re-negotiates the stream on every renderer, not just the webview. Jellyfin produces a transcode *from* `StartTimeTicks`, so where a seek lands is a property of the request rather than of the stream in hand. `determine_video_seek_strategy` treated `is_hls` as a proxy for "seekable in place", which held only because hls.js was always the HLS renderer — it seeks within the VOD playlist it is handed and lets the server catch up. mpv's HLS demuxer cannot make the server transcode from a new offset, so with native video on, every transcoded seek became a backend seek that silently did nothing and presented as "resume does not work". The rule is now written on `needs_transcoding` with hls.js as the stated exception; all four webview cells are unchanged | Player | UR-040 | Done |
+| DR-239 | Properties the mpv event loop handles are registered with `observe_property`. libmpv delivers `PropertyChange` only for observed properties, so a `match` arm for an unobserved one is unreachable code that reads as implemented — the handler is right there. `pause` was handled and never observed, so `StateChanged` was never emitted on pause or resume and the play/pause control never moved. It stayed invisible while Linux video played in the webview, because the `<video>` element's own DOM events drove that control; native video made the UI depend on the event that never came | Player | UR-005 | Done |
+| DR-240 | Fullscreen moves whatever actually owns the pixels. `requestFullscreen()` fullscreens the *document*, which sufficed while every renderer lived inside it — the HTML5 `<video>` element is part of the document, so WebKit scaled it and the OS window's real size never mattered. A native surface is drawn behind the webview at **window** size, so a document-only fullscreen expands the page and leaves the picture where it was; on WebKitGTK the result is a maximised window with decorations still holding a strip of the screen, which reads as "fullscreen is broken" rather than as a windowing problem. Android needed the same rule for the system bars (DR-157); this is its desktop half | Player | UR-066 | Done |
+| DR-241 | A seek issued before MPV has a file to seek in is honoured, not dropped. `loadfile` returns as soon as the command is queued, so `time-pos` — a live property of the *loaded* file — does not resolve yet and setting it fails. The two callers that always hit that window are the ones a viewer notices: resume, and a transcoded seek, both of which re-open the stream and then ask for a position. The failed seek was discarded and the stream played from zero, which reads as "resume is broken" and "I cannot skip". The position is now held and applied by the `FileLoaded` handler; a seek that lands normally clears any deferred one, so the newer intent wins | Player | UR-040, UR-005 | Done |
+| DR-242 | The player contract expresses intent, not device operations. `MediaPlayer::open` carries the start position, so no caller sequences load-then-seek and none can race an engine's asynchronous load; `seek` states a destination and leaves in-place-vs-re-open to the engine, which is the only layer that knows its own transport; `snapshot` is one coherent read; and `Phase::Opening` names the window a seek used to be lost in. Replaces `PlayerBackend`, which abstracted a device and required each of the three engines to re-derive the same rules | Player | UR-081 | In Progress |
+| DR-243 | Every engine passes one conformance suite, and a `FakePlayer` implements the contract deterministically. The suite is written before the second engine so it cannot encode whatever the first happened to do, and it drives readiness through a harness rather than sleeping. `FakePlayer` models the one behaviour that matters — opening is not instantaneous — so the load/seek race can be expressed on purpose, and lets the controller, queue, autoplay and session logic be tested with no engine at all | Player | UR-081 | In Progress |
+| DR-244 | `MpvPlayer` implements `MediaPlayer` over libmpv, applying the start position at load time via mpv's own `start` option rather than seeking after an asynchronous `loadfile`, and holding a seek that arrives during `Opening` until the file loads. A standalone `player-conformance` binary runs the suite against it with audio and video routed to null, so a wrapper is verifiable without building or launching the app | Player | UR-081, UR-040 | Done |
+| DR-245 | `LegacyPlayer` drives the old `PlayerBackend` through the `MediaPlayer` contract, so engines not yet ported keep working during the migration and the two designs can be compared on one engine and one file. It reproduces the old load-then-play-then-seek sequence faithfully rather than a fixed-up version, because making it pass would defeat its purpose | Player | UR-081 | In Progress |
+| DR-247 | ExoPlayer can be told where to start. `JellyTauPlayer.load(url, mediaId)` had no way to express a start position, so every caller loaded and then seeked; the position is now handed to ExoPlayer with the media item via `setMediaItem(item, startPositionMs)`, and the two-argument form delegates to it. Running the conformance cases on a device also settled which half of DR-241 was engine-specific: ExoPlayer already queues a seek issued before `prepare()` completes, so it never had the lost-seek defect mpv did — only the missing vocabulary for a start position | Player | UR-081, UR-005 | Done |
 | DR-198 | The webview runs under a real Content-Security-Policy, and the asset protocol is scoped to the one directory it still serves. `csp` was `null`, which disables CSP entirely: any script that reached the web layer — through a future `{@html}`, a dependency, or a devtools paste — would have inherited the whole IPC surface, and with it the user's session. `script-src 'self'` (Tauri injects a nonce for SvelteKit's inline bootstrap script at build time, so no `'unsafe-inline'` is needed) plus `object-src`/`frame-src 'none'` and `base-uri 'self'` is the part that is genuinely restrictive. `img-src`/`media-src`/`connect-src` cannot be: the Jellyfin origin is typed in by the user at run time and is commonly plain `http` on a LAN, so they allow `http:`/`https:` — a wide grant for *data*, but one that still bars `file:`, `filesystem:` and scripting schemes, and leaves `script-src` untouched. `style-src` keeps `'unsafe-inline'` because Svelte compiles `style="…"` attributes (including `app.html`'s `display: contents` wrapper) into markup; this is safe only while no `<style>` element survives into `index.html`, since a nonce there would make Tauri's injection outrank — and therefore void — `'unsafe-inline'`. `worker-src blob:` and `media-src blob:` are hls.js: it demuxes in a worker built from a blob and attaches MSE through `URL.createObjectURL`. `asset:` and `http://asset.localhost` are the same protocol under the two naming schemes `convertFileSrc` emits (custom scheme on Linux/macOS, `http` host on Windows/Android); `ipc:`/`http://ipc.localhost` is the invoke transport, which would otherwise be blocked by `connect-src`. A run-time CSP naming the server origin exactly was rejected: Tauri computes the header from immutable config when it serves the HTML, so it would mean rebuilding config and reloading the webview on every server change, for a policy the user can already point anywhere. The asset-protocol scope narrows from `$APPDATA/**` to `$APPDATA/thumbnails/**` — since DR-137 moved downloaded media to the loopback server, `imageCache` is the only `convertFileSrc` caller left, so the database and the encrypted-token fallback file no longer sit inside the grant | Security | UR-012, UR-071 | Done |
 
 ---
@@ -509,7 +529,8 @@ Internal architecture, components, and application logic.
 | UR-076 | - | DR-209 |
 | UR-077 | - | DR-217 |
 | UR-078 | - | DR-218 |
-| UR-079 | - | DR-224, DR-225, DR-226, DR-227, DR-228, DR-229 |
+| UR-079 | - | DR-225, DR-226, DR-227, DR-228, DR-229, DR-230 |
+| UR-080 | IR-033 | DR-231, DR-232, DR-233, DR-234, DR-235, DR-236, DR-237 |
 
 ---
 
@@ -723,9 +744,16 @@ Internal architecture, components, and application logic.
 | UT-208 | The update decision: each numeric version field is compared in order, the installed version is not offered to itself, a leading `v` is tolerated because that is how the tags are written, a pre-release sorts below the release of the same number so 0.9.2-rc1 is not offered to somebody on 0.9.2, a missing patch field reads as zero rather than NaN, mobile reports link-only while desktop reports install, and absent release notes normalise to null rather than undefined | DR-217 | Done |
 | UT-209 | Redaction and forwarding. Rust: every credential shape reduces to `[REDACTED]` while the host, username and neighbouring parameters survive; redaction is idempotent, leaves ordinary lines alone, does not fire on the word "token" in prose, and does not panic on multi-byte input; a server URL keeps only scheme and host and drops an embedded `user:pass@`; an unparseable level falls back to info rather than failing at startup. Frontend: info and above forward while debug does not, a message the level filter suppressed is not forwarded, a throwing forwarder neither propagates nor prevents the console write, and an `Error` renders as name and message rather than the `{}` that `JSON.stringify` produces | DR-218 | Done |
 | UT-210 | Cosmetic-commit detection for release notes: a `chore(format)`, `chore(deps)` or `style` subject is skipped when deriving a range's changed files, while `fix`, `feat`, `ci`, `docs`, a bare `chore:` and `chore(release):` are kept; and the word "format" appearing later in a subject ("fix(duration): format times over 24 hours") does not make a real fix look cosmetic | DR-219 | Done |
-| UT-211 | The stream-selection contract. `Transport` and `PlaybackKind` each serialise to exactly the tag the frontend matches (`{"type":"hls"}`, `{"type":"directPlay"}`, …) and round-trip; nested `StreamSelection` fields are camelCase on the wire including `playbackKind`, `mediaSourceId` and `maxBitrate`; only `Transcode` counts as transcoding, so a direct stream does not; a local file is a direct play over a local transport with no ladder. The ladder: every rung at or above a 1.12 Mbps source is marked redundant while the three that constrain it are not, `Original` is never marked for any bitrate including zero and unknown, an unreported source bitrate keeps all eight rungs offered, a 40 Mbps source marks none, and each option carries the ladder's own label and detail | DR-224, DR-226 | Done |
-| UT-212 | The direct-play negotiation, one test per branch, against `PlaybackInfo` fixtures whose shapes were all observed on a live server: a supported source direct-plays; a remuxable one direct-streams and reports itself as *not* transcoding; an unsupported codec transcodes; undecodable audio overrides the server's direct-play offer (silent picture is worse than a transcode); a pinned audio track forces a transcode; a ceiling below the source bitrate transcodes even though the codec is fine, and the ladder agrees that rung constrains it; direct play wins over direct stream when both are offered. Plus the ceiling: a per-playback override governs the stream being opened without disturbing the durable default the Settings screen shows, and dropping it returns to that default | DR-225, DR-227 | Done |
-| UT-213 | The loader comes from the transport, never the URL. hls.js is attached for `hls` when available and the element's own loader when not; progressive and local files load directly; the element's `src` is emptied only when hls.js drives it. The two cases that fail against a substring check, and the reason the field exists: a `progressive` stream whose URL contains `.m3u8` is *not* given an HLS loader, and an `hls` stream whose URL contains no `.m3u8` *is*. Both failed against the pre-DR-224 implementation before the fix landed | DR-224 | Done |
+| UT-211 | The background decision: a video with the toggle off pauses (the reported defect, where the media service kept playing regardless), a video with it on hands off to audio, music keeps playing whatever the toggle says because it has no picture to lose, picture-in-picture keeps playing in every combination since the window is still visible, and the answer does not vary by renderer | DR-224 | Done |
+| UT-212 | The stream-selection contract. `Transport` and `PlaybackKind` each serialise to exactly the tag the frontend matches (`{"type":"hls"}`, `{"type":"directPlay"}`, …) and round-trip; nested `StreamSelection` fields are camelCase on the wire including `playbackKind`, `mediaSourceId` and `maxBitrate`; only `Transcode` counts as transcoding, so a direct stream does not; a local file is a direct play over a local transport with no ladder. The ladder: every rung at or above a 1.12 Mbps source is marked redundant while the three that constrain it are not, `Original` is never marked for any bitrate including zero and unknown, an unreported source bitrate keeps all eight rungs offered, a 40 Mbps source marks none, and each option carries the ladder's own label and detail | DR-224, DR-226 | Done |
+| UT-213 | The direct-play negotiation, one test per branch, against `PlaybackInfo` fixtures whose shapes were all observed on a live server: a supported source direct-plays; a remuxable one direct-streams and reports itself as *not* transcoding; an unsupported codec transcodes; undecodable audio overrides the server's direct-play offer (silent picture is worse than a transcode); a pinned audio track forces a transcode; a ceiling below the source bitrate transcodes even though the codec is fine, and the ladder agrees that rung constrains it; direct play wins over direct stream when both are offered. Plus the ceiling: a per-playback override governs the stream being opened without disturbing the durable default the Settings screen shows, and dropping it returns to that default | DR-225, DR-227 | Done |
+| UT-214 | The loader comes from the transport, never the URL. hls.js is attached for `hls` when available and the element's own loader when not; progressive and local files load directly; the element's `src` is emptied only when hls.js drives it. The two cases that fail against a substring check, and the reason the field exists: a `progressive` stream whose URL contains `.m3u8` is *not* given an HLS loader, and an `hls` stream whose URL contains no `.m3u8` *is*. Both failed against the pre-DR-225 implementation before the fix landed | DR-224 | Done |
+| UT-215 | Waiting for the repository rather than racing it: it resolves immediately when the session is already restored, resolves when the session arrives later (the race the player page lost on mount), still rejects when there genuinely is no session, unsubscribes once settled so a later store change cannot re-settle it, and leaves no armed timer to reject an already-resolved promise | DR-013 | Done |
+| UT-216 | The native-video opt-in is read from one place and only explicit truthy values enable it: absent, empty, `0`, `no`, `false` and anything unrecognised all mean off, because a half-set variable that half-enabled the renderer would configure mpv for video with nothing drawing it — audio over a black rectangle | DR-231 | Done |
+| UT-217 | A transcoded HLS stream on the native backend re-negotiates rather than seeking in place, while the same stream under hls.js still seeks in place — the cell that native video made reachable for the first time | DR-238 | Done |
+| UT-218 | Every property name matched by the mpv event loop also appears in an `observe_property` call, asserted against the source because the registration cannot be observed at runtime without a live mpv | DR-239 | Done |
+| UT-219 | A fullscreen toggle moves the document only when an in-document `<video>` renders, and moves the OS window as well when a native surface does | DR-240 | Done |
+| UT-220 | The conformance suite: opening at a position starts there and never at zero, a seek issued while opening is honoured and overrides the start it overtook, pause and play are observable, close is silent and idempotent, and an open cancelled by close never begins playing | DR-242, DR-243 | In Progress |
 
 ### Integration Tests
 
@@ -746,6 +774,7 @@ Internal architecture, components, and application logic.
 | IT-013 | Background-audio handoff on Android: background/lock continues audio via native service and stops video decode; foreground resumes video at position | IR-025, UR-040 | Pending |
 | IT-016 | Offline library listing end-to-end: with the server unreachable, a library page lists only downloaded media with the toggle off, and additionally reveals greyed-out cached catalog entries with the toggle on | UR-052, DR-078, DR-079, DR-080 | Done |
 | IT-017 | A download queued from a greyed-out offline catalog entry persists and is resolved and started on reconnect | UR-052, UR-011 | Done |
+| IT-018 | The conformance cases run against ExoPlayer on a device: opening from the beginning and at a position, a seek issued while still preparing, a seek after open, pause and play observable, stop silent and idempotent, and a load cancelled by stop never playing. The fixture is a silent WAV synthesised at setup, so the repo carries no media and the duration is exact | DR-247 | Done |
 
 ---
 

docs/specs/README.md

@@ -28,7 +28,7 @@ know how something *works*, read
 
 **Next free requirement ids** (always re-check
 [requirements.md](../requirements.md) before allocating): **UR-079**,
-**IR-033**, **DR-229**. Three specs below suggested ids that have since been
+**IR-033**, **DR-232**. Three specs below suggested ids that have since been
 taken by other work; each carries a ⚠️ note at the top.
 
 ## Partially implemented
@@ -44,10 +44,11 @@ taken by other work; each carries a ⚠️ note at the top.
 
 | Spec | Blocked on / note |
 |---|---|
+| [desktop-native-video.md](desktop-native-video.md) | mpv draws video on every desktop platform, then the webview `<video>` path and hls.js are deleted. Converts a measured 7% direct-play rate toward Android's 85%. Stacked on backend-owned stream selection. |
 | [build-provenance.md](build-provenance.md) | `build.rs` is still bare. ⚠️ suggested id DR-093 is taken. |
 | [player-facade-enforcement.md](player-facade-enforcement.md) | ~60 `commands.player*` sites still outside the facade; no lint rule. ⚠️ suggested id DR-095 is taken. |
 | [windows-native-audio-backend.md](windows-native-audio-backend.md) | Blocked on the libmpv2 swap. ⚠️ suggested id IR-030 is taken. |
-| [linux-native-video-spike.md](linux-native-video-spike.md) | **Spike run 2026-08-21: compositing works on Linux, X11 and Wayland.** G1-G6 green bar the Tauri `default_vbox()` half of G1. The adaptive-bitrate question it was waiting on is **answered**: the server publishes one `EXT-X-STREAM-INF`, so there is no ladder for mpv to lose (DR-228). `StreamSelection` (DR-224) is the contract to consume. |
+| [linux-native-video-spike.md](linux-native-video-spike.md) | **Spike run 2026-08-21: compositing works on Linux, X11 and Wayland.** G1-G6 green bar the Tauri `default_vbox()` half of G1. The adaptive-bitrate question it was waiting on is **answered**: the server publishes one `EXT-X-STREAM-INF`, so there is no ladder for mpv to lose (DR-229). `StreamSelection` (DR-225) is the contract to consume. |
 
 ## Design authority
 

docs/specs/desktop-native-video.md

@@ -0,0 +1,423 @@
+# Spec: Desktop native video — mpv renders the picture, everywhere
+
+**Status:** Proposed
+**Requirements:** UR-080 (new) → DR-231 … DR-237 (new); IR-033 (new)
+**UX spec:** n/a — nothing about the player's appearance changes. What changes is
+what is behind the controls.
+**Supersedes / revises:** consumes and closes
+[linux-native-video-spike.md](linux-native-video-spike.md), whose gates
+authorised exactly this spec and nothing more. Settles finding 2 of
+[playback-backend-unification.md](playback-backend-unification.md) on the
+desktop; finding 3 was already settled by DR-229. Absorbs the video half of what
+[windows-native-audio-backend.md](windows-native-audio-backend.md) leaves open.
+**Depends on:** backend-owned stream selection (DR-225 … DR-230), the branch
+below this one. mpv is a *consumer* of `StreamSelection`, never a second place to
+decide what to play.
+
+**Destination on completion:**
+[05-platform-backends.md](../architecture/05-platform-backends.md) — a "Native
+Video Compositing (Desktop)" section beside the existing Android one, which this
+mirrors; and [01-rust-backend.md](../architecture/01-rust-backend.md) — the
+device profile becomes renderer-dependent, beside the stream-selection section.
+**The spike is deleted in the same commit**, its three traps and its
+hardware-decode table folded in; they are the durable half.
+
+## Summary
+
+mpv decodes and draws video on **every desktop platform**, composited beneath the
+transparent webview, exactly as Android already does with ExoPlayer. The HTML5
+`<video>` path and hls.js are then **deleted**, not merely bypassed.
+
+The user-visible change is that most video stops being re-encoded by the server
+before it can be watched. The change for whoever maintains this is that video
+goes from three renderers to two.
+
+## Motivation
+
+### The transcode is a decoder constraint, not a rendering one
+
+Desktop video goes through an h264 HLS transcode because the picture is drawn by
+a WebKitGTK `<video>` element, and that element decodes little else. The device
+profile therefore claims `h264` alone. That is not a statement about the machine
+— the same machine runs mpv, which decodes essentially everything in the library
+— it is a statement about which widget is holding the frame.
+
+DR-228 made the cost measurable. Over 40 items negotiated against the development
+server:
+
+| Profile | Direct play |
+|---|---|
+| Desktop / WebKitGTK — `h264` only, 2ch | **7%** |
+| Android / ExoPlayer — `h264,hevc,vp8,vp9,av1,mpeg4` + `ac3,eac3`, 6ch | **85%** |
+
+The sampled library is ~80% hevc. **Those rows differ only by which component
+decodes.**
+
+Moving the picture to mpv is what lets the desktop row claim what the machine
+can actually do, and that — not the compositing — is the product.
+
+> **The 85% is a ceiling, not a shipped result.** It was measured with a profile
+> containing `ac3,eac3`. The Android device later used for verification reports
+> neither in its `MediaCodecList` — no Dolby licence, normal for a tablet — so
+> eac3 content, about a third of the sampled library, correctly transcodes there.
+> Realising any of this depends on DR-234, deriving the profile from the renderer
+> rather than from the platform, which is why that requirement is load-bearing
+> and not tidy-up.
+
+### One desktop video path, not two
+
+This is why the spec covers Windows rather than stopping at Linux.
+
+Today video has **three** renderers: ExoPlayer, the WebKitGTK `<video>` element,
+and (on Android, via the opt-out) that same element again. A Linux-only version
+of this work would make it four, permanently: mpv on Linux, HTML5 on Windows,
+ExoPlayer on Android, plus hls.js underneath the HTML5 one. Every seek strategy,
+every track switch, every quality change, every lifecycle bug would then have one
+more place to be got right — and the HTML5 path would survive indefinitely
+because *something* would still need it.
+
+Finishing the job removes that: **mpv on desktop, ExoPlayer on Android**, and
+`hls.js`, `html5Adapter.ts`, `videoLoaderFor` and the webview video element all
+go. The maintenance win is the reason Windows is in this spec and not in a
+follow-up that never gets written.
+
+### Three blockers are gone
+
+1. **Compositing works, including Wayland.** The spike ran all six gates; the
+   2024 "not possible on Wayland at all" claim is out of date when the render API
+   is used instead of foreign-window embedding.
+2. **There is no ABR to lose.** DR-229: the server's master playlist carries one
+   `EXT-X-STREAM-INF`. hls.js was demuxing, not adapting.
+3. **A direct-play path exists.** It did not when the spike was written. DR-228
+   built it; DR-230 proved the contract is player-agnostic.
+
+And on Windows specifically, `tauri-plugin-libmpv` lists Windows as its **fully
+tested** platform — the inverse of the Linux situation the spike had to
+disprove. The embedding difficulty was always WebKitGTK-specific.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|---|---|---|
+| **Which codecs this device can decode** | **Rust** | Domain: it is the input to Jellyfin's `PlaybackInfo` negotiation. It stops being a property of the *platform* and becomes a property of *the renderer in use* — see "The structural change". |
+| Which backend renders video | **Rust** | Rust already owns this (`use_html5_element` / `VideoBackend`). It stops being a `cfg!` constant and becomes a runtime fact. |
+| What stream to play (direct / remux / transcode, transport, ceiling) | **Rust — already decided** | DR-225. mpv consumes `StreamSelection`. Re-deriving any of it in a new backend would be the defect DR-225 exists to remove, restated. |
+| Creating the GL surface, reparenting the webview, owning the render context | **Rust (platform layer)** | Native window and GL-context lifetime. Not presentation, and not expressible above the IPC boundary at all. |
+| Render-context ↔ GL-context lifetime binding | **Rust** | A correctness invariant over native resources. DR-232. |
+| Frame pacing (update callback, `report_swap`) | **Rust** | Timing against the compositor; mpv's own contract. |
+| Hardware-decode selection | **Rust** | A capability question about the machine, answered from what mpv reports it actually selected. |
+| Z-order of controls over video, overlay chrome, letterbox colour | **Frontend / mpv** | Presentation. Controls already draw over a transparent webview on Android; mpv paints its own letterbox bars (better than the Android equivalent, which shipped DR-194 as a defect). |
+| Whether the surface is visible right now | **Frontend** | `nativeVideoActive` already exists and toggles `data-native-video`. Unchanged. |
+
+### The structural change
+
+Everything above is routine except one row, and it carries the whole benefit.
+
+`video_codecs` in `build_device_profile` is a **compile-time constant per
+platform**:
+
+```rust
+#[cfg(all(not(target_os = "android"), target_os = "linux"))]
+let (video_codecs, audio_codecs) = ("h264".to_string(), "aac,mp3,opus,…");
+```
+
+That is correct only while a build has exactly one video renderer. It must be
+derived from **which renderer will decode this stream**, which is runtime state.
+
+It looks like configuration and is not: it is the input that decides whether the
+server re-encodes, it changes when Jellyfin's API or our renderer changes, and
+getting it wrong fails *silently* — a claimed codec the renderer cannot decode is
+a black picture or silence, which is DR-148 and DR-228's audio override already.
+
+**Write this against "the active video renderer", never `cfg!(target_os)`.** It
+is the single piece that must not be Linux-shaped, because phase 2 reuses it
+unchanged.
+
+## Design
+
+### Backend and compositing (DR-231, IR-033)
+
+An `MpvVideoBackend` beside the existing `MpvBackend` (audio). The mpv side —
+render context, FBO, update callback, hwdec — is **shared**; only the surface
+differs per platform:
+
+| Platform | Surface | Status |
+|---|---|---|
+| Linux (X11 + Wayland) | `gdk_cairo_draw_from_gl()` in the default vbox's `draw` handler, over a `GdkGLContext` on its `GdkWindow`. No reparenting — see below | Render path proven by the spike; the *overlay* approach it used is rejected |
+| Windows | Native HWND child beneath a transparent WebView2 | Phase 2 |
+
+`vo=libmpv` plus `mpv_render_context_create` with `MPV_RENDER_PARAM_OPENGL_FBO`.
+Webview transparency via `with_transparent(true)` — no window-level transparency;
+the spike showed it is neither used nor needed.
+
+**G1's untested half failed, and the design changed because of it.**
+
+Reparenting Tauri's webview into a `GtkOverlay` attaches cleanly and then aborts
+the process on the first click. `tauri-runtime-wry` connects a
+button-press handler to the webview that walks a hard-coded path:
+
+```rust
+webview.parent()            // "This one should be GtkBox"
+       .parent()            // ...and this one the GtkWindow
+       .downcast::<gtk::Window>().unwrap()
+```
+
+An overlay makes that chain `webview → GtkOverlay → GtkBox`, the downcast fails,
+and the panic is non-unwinding so it kills the app. Nothing in configuration
+avoids it: on Linux `attach_resize_handler` is called **unconditionally** (the
+Windows equivalent is guarded by `is_decorated()`), and the decoration check that
+would make the handler inert runs *after* the unwrap.
+
+**So the webview is not moved at all.** mpv draws into the *default vbox's own
+`draw` handler* instead, via `gdk_cairo_draw_from_gl()` over a `GdkGLContext`
+created on that widget's `GdkWindow`. GTK3 draws a container before its children,
+so the webview composites on top for free — the same z-order the overlay was for,
+without touching the widget tree Tauri walks.
+
+That is strictly better than the overlay it replaces: no reparent, no extra
+widget, and the arrangement cannot be broken by a Tauri upgrade that assumes its
+own layout. It is also why "the surface attached successfully" is not the gate —
+a click is.
+
+Three traps from the spike, each of which cost a debugging cycle and each of
+which looks like a platform limitation and is not:
+
+1. **`LC_NUMERIC` must be reset *after* `gtk::init()`.** mpv refuses to start
+   under a non-C numeric locale. `mpv_backend.rs` already handles this but has no
+   GTK init in front of it; here `gtk::init()` applies the user's locale
+   afterwards and `mpv_create` returns null.
+2. **libepoxy exports GL entry points as *data* symbols.** There is no `glFoo`
+   function — there is `epoxy_glFoo`, a variable holding a lazily-resolving
+   pointer. `get_proc_address` must return the pointer **stored at** that symbol;
+   returning the symbol's own address makes mpv jump into non-executable data and
+   take SIGSEGV on the first GL call. The `epoxy` crate does this correctly but is
+   unusable — its `gl_generator` dependency pulls a yanked `xml-rs`.
+3. **Frame pacing is not optional and its symptom misleads.** See DR-233.
+
+### Render-context lifetime (DR-232) — the crash defence
+
+The spike's one unexplained SIGSEGV landed in a *decoder* thread with no Tauri,
+GTK or GL frame in the stack, and three plausible causes failed to reproduce it
+across ~13 minutes of targeted stress.
+
+What is **not** unexplained is that the spike had no defence: it never calls
+`mpv_render_context_free` and never tears down on `unrealize`, so nothing stopped
+the GL context being recreated beneath the render context. That is DR-184 on
+Android restated — a surface outliving its player.
+
+Built as a requirement in its own right, not as a fix for a crash we cannot yet
+reproduce:
+
+- Render context created on `realize`, freed on `unrealize`, same thread, before
+  the GL context goes away.
+- The update callback is unregistered **before** the context is freed, so a
+  callback cannot land on a freed context.
+- Playback teardown and surface teardown are ordered, not racing.
+
+If the crash recurs after this, it is a different bug and the likeliest cause is
+out of the search space. If it does not, we needed this anyway.
+
+### Frame pacing (DR-233)
+
+Register `mpv_render_context_set_update_callback`; redraw only when it reports a
+frame ready; call `mpv_render_context_report_swap` after each render.
+
+Recorded because the failure mode is a trap: driving `queue_render()` off the
+frame clock every tick without reporting the swap leaves mpv nothing to time
+against. It looks fine in a window and **judders at fullscreen**, which reads as
+a compositing or GPU limit and is neither.
+
+### Renderer-dependent device profile (DR-234)
+
+`build_device_profile` takes the active video renderer and derives the codec
+lists from it:
+
+| Renderer | Video codecs | Audio (video direct play) | Channels |
+|---|---|---|---|
+| mpv (desktop native) | `h264,hevc,vp8,vp9,av1,mpeg4` | platform list incl. `ac3,eac3` where the sink can voice it | from the audio route |
+| WebKitGTK `<video>` | `h264` | webview-decodable set only | 2 |
+| ExoPlayer (Android) | unchanged | unchanged | unchanged |
+
+The existing `video_audio_codecs()` narrowing exists because *the webview decodes
+a narrower audio set than the platform*. With mpv decoding, that no longer
+applies to the video path — but the multichannel bound still does, since a 5.1
+track direct-played into a 2-channel sink is silence or inaudible dialogue. Both
+constraints stay, sourced from the renderer rather than assumed.
+
+**This is what converts the 7% figure upward** (toward, not necessarily to, the 85% ceiling — see the caveat above), and it is also the change most able to break
+playback silently — so it lands after compositing is proven, covered by the
+DR-228 override tests.
+
+### Deleting the webview video path (DR-235)
+
+`get_player_status` stops reporting `use_html5_element: true` on desktop;
+`supports_native_video` becomes true there.
+
+Deletion is staged, because a path cannot be removed while a shipped platform
+still needs it:
+
+| Phase | Linux | Windows | HTML5 video path |
+|---|---|---|---|
+| 1 | mpv | HTML5 | alive — Windows needs it |
+| 2 | mpv | mpv | alive but unreached |
+| 3 | mpv | mpv | **deleted**, with hls.js |
+
+Phase 3 is a real phase with its own acceptance criterion, not a "later". The
+whole maintenance argument for including Windows collapses if the fork survives.
+
+Android keeps ExoPlayer and keeps the webview as its documented opt-out; the
+`<audio>` element and the background-audio handoff are untouched throughout.
+
+**What happens when mpv fails to initialise.** With no HTML5 path there is no
+silent fallback, and inventing one resurrects what we deleted. The
+graceful-backend-init principle applies as written: fall back to the no-op
+backend, emit `backend-init-failed`, and surface a real error rather than a black
+rectangle. An honest failure beats a hidden downgrade to the transcode we are
+trying to stop paying for.
+
+### Hardware decode (DR-236)
+
+The spike established the load-bearing fact: **hardware decode works through the
+render API** (`hwdec-current` reported `nvdec-copy` on the discrete GPU), so the
+direct-play prize is not traded for software decoding.
+
+Policy is decided from what mpv reports it *selected*, never from what it was
+asked for:
+
+- Prefer zero-copy VA-API on the integrated GPU where the driver is present.
+- `auto` reached for the discrete GPU in **copy-back** mode on a hybrid
+  Intel+NVIDIA laptop — the least efficient hardware path — so `auto` is a
+  fallback, not the default.
+- `vaapi` silently fell back to software on the spike box because `vainfo` was
+  absent. A missing driver must be detected and logged, not mistaken for a
+  compositing limit.
+- Log `hwdec-current` at start-up; knowing what was actually chosen is the whole
+  diagnostic value.
+
+### Windows: what phase 2 actually costs (DR-237)
+
+Not hidden, because it is the part most likely to be underestimated:
+
+- **The surface is different code.** WebView2 in an HWND, not GTK. A transparent
+  WebView2 over a native child window is a solved arrangement, but DR-231's
+  Linux surface does not transfer. Everything else does.
+- **libmpv is currently a Linux-only dependency**, and Windows is
+  **cross-compiled from Linux** via `x86_64-pc-windows-msvc` + `cargo-xwin`. Phase
+  2 must source a Windows libmpv (DLL + import library) into that cross-build and
+  ship the DLL in the NSIS bundle.
+- **LGPL obligations follow the DLL.** DR-216 already records them for Linux:
+  keep the linkage dynamic, ship libmpv's licence text with any bundle carrying
+  it. The Windows bundle inherits both.
+- **`bun run test:rust` and CI must still build.** Per the CI rule, any tool this
+  needs goes into the builder image and is pushed — never installed at job time.
+
+Windows also gains a native *audio* decoder as a side effect, which is what
+[windows-native-audio-backend.md](windows-native-audio-backend.md) wants and
+cannot currently have. If that spec lands first, phase 2 inherits its build work
+and shrinks to the surface.
+
+## Out of scope
+
+- **Android.** Unchanged in every respect.
+- **macOS.** Not a shipped target. If it becomes one it joins phase 2's shape.
+- **Audio backends.** mpv already plays audio on Linux; this adds a video
+  renderer beside it. Windows audio is its own spec.
+- **HDR, tone mapping, multi-window.** Not exercised by the spike at all.
+- **Re-deciding what stream to play.** DR-225 owns that. If this spec finds
+  itself choosing a URL, something has gone wrong.
+
+## Acceptance criteria
+
+**Phase 1 — Linux**
+
+- [ ] Tauri's own webview reparents into the overlay (the untested half of G1),
+      on X11 **and** Wayland.
+- [ ] Video plays, seeks and switches audio track in mpv, with the Svelte
+      controls composited over it and alpha blending intact.
+- [ ] The render context is freed on `unrealize` and the update callback
+      unregistered before the free; a test demonstrates the ordering.
+- [ ] A direct-play negotiation returns `DirectPlay` for an hevc source that
+      today returns `Transcode`, and it plays.
+- [ ] Direct-play rate over the same 40-item sample rises from 7% toward the
+      Android figure. **Record the number.**
+- [ ] mpv init failure emits `backend-init-failed` and surfaces an error rather
+      than falling back to a transcode.
+- [ ] `hwdec-current` is logged and is not copy-back where zero-copy is available.
+- [ ] A soak covering seek, track switch and fullscreen runs clean for an agreed
+      duration. **The spike's SIGSEGV is why this is a criterion.**
+
+**Phase 2 — Windows**
+
+- [ ] libmpv links in the `cargo-xwin` cross-build; the DLL and its licence ship
+      in the NSIS bundle; any new tool lives in the builder image, not in a CI step.
+- [ ] Video plays composited under a transparent WebView2.
+- [ ] The device profile, lifetime and hwdec code are **reused, not
+      reimplemented** — a reviewer confirms no `cfg!(target_os = "linux")` guards
+      them.
+
+**Phase 3 — deletion**
+
+- [ ] `use_html5_element` is false on every desktop platform.
+- [ ] `hls.js` is gone from `package.json`; `html5Adapter.ts`, `videoLoaderFor`
+      and the `<video>` element are deleted; Android's opt-out and the
+      background-audio `<audio>` path still work.
+
+**Throughout**
+
+- [ ] `bun run check`, `bun run test`, `bun run format:check`, `bun run lint` pass.
+- [ ] `cargo fmt` clean, `cargo clippy -D warnings` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes, and a reviewer confirms no stream decision
+      was reconstructed in the new backend.
+- [ ] `bindings.ts` regenerated from Rust.
+- [ ] `bun run traces:validate` passes; coverage stays ≥ the CI ratchet.
+- [ ] The spike and this spec are folded into
+      [05-platform-backends.md](../architecture/05-platform-backends.md) and both
+      deleted in the same commit.
+
+## Testing
+
+- **Rust, pure:** the device profile per renderer — mpv claims hevc, the webview
+  does not, the multichannel bound survives both. The DR-234 table as a
+  table-driven test.
+- **Rust, pure:** `PlaybackInfo` fixtures that transcode under the webview
+  profile and direct-play under the mpv profile — the direct-play conversion as a unit
+  test, not only as a measurement.
+- **Rust:** teardown ordering — callback unregistered before context freed, freed
+  before GL context destroyed. Structure it so the ordering is assertable without
+  a live GL context.
+- **Frontend:** no desktop path selects an HTML5 video adapter. After phase 3,
+  the adapter does not exist and the test goes with it.
+- **Manual / soak:** the criterion above. The spike's automated fullscreen and
+  resize soaks are reusable and already written.
+
+## TRACES
+
+| Piece | Tag |
+|---|---|
+| mpv video backend + compositing | `UR-080 \| DR-231, IR-033` |
+| Render-context lifetime binding | `UR-080 \| DR-232` |
+| Frame pacing | `UR-080 \| DR-233` |
+| Renderer-dependent device profile | `UR-080, UR-070 \| DR-234` |
+| Webview video path removed | `UR-080 \| DR-235` |
+| Hardware-decode policy | `UR-080 \| DR-236` |
+| Windows surface + cross-build | `UR-080 \| DR-237` |
+
+## Notes for the implementer
+
+- **Read the spike before writing a line.** Its three traps and its
+  hardware-decode table are the most valuable things in this directory, and each
+  cost a debugging cycle to find.
+- **mpv consumes `StreamSelection`; it does not decide.** The transport is on the
+  queue item (DR-230). If you are parsing a URL, stop.
+- **Guard nothing on `cfg!(target_os = "linux")` that phase 2 will need.** That is
+  the one avoidable mistake here.
+- The Android backend is the reference for the *shape* of this — transparent
+  webview over a native surface at index 0. Read `05-platform-backends.md`'s
+  Android section for what shipped and what its defects were (DR-184 surface
+  lifetime, DR-194 letterbox).
+- Do not call sync/blocking APIs from mpv event callbacks that can re-enter the
+  player or hold a lock. The existing deadlock gotchas apply.
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes.
+- This branch is stacked on backend-owned stream selection. Rebase when that
+  merges rather than merging master into it.

docs/specs/linux-native-video-spike.md

@@ -2,7 +2,10 @@
 
 **Status:** **Run 2026-08-21 — compositing works; G5 carries an open crash.**
 The compositing claim it set out to test is falsified on Linux. See "Result".
-This file stays open until the implementation spec exists; ABR is unresolved.
+This file stays open until the implementation spec exists. **ABR is resolved** —
+the playlist carries one `EXT-X-STREAM-INF`, so finding 3 is false and there is
+no adaptation for mpv to lose. The remaining blocker is the unexplained SIGSEGV
+under G5, which is a lifetime problem, not a compositing one.
 **Requirements:** none allocated. This spike produces a decision record, not
 product code — same shape as
 [playback-backend-unification.md](playback-backend-unification.md), which is
@@ -258,10 +261,10 @@ anything.
   Tauri's existing webview into an overlay. Low risk — the same widgets, one
   extra reparent — but unproven, and it is the only place Tauri-specific
   behaviour could still bite.
-- 🔴 **ABR — finding 3's premise is in doubt.** Finding 3 says mpv would regress
-  streaming quality because "the webview path already has real ABR via hls.js".
-  Three pieces of evidence in this repo suggest that is **not true of the URLs we
-  actually build**:
+- ✅ **ABR — resolved. Finding 3's premise is false.** Finding 3 said mpv would
+  regress streaming quality because "the webview path already has real ABR via
+  hls.js". Three pieces of evidence in this repo suggested that is **not true of
+  the URLs we actually build**:
 
   1. `get_video_stream_url` (`repository/online.rs`) requests a *single*
      rendition — one `VideoBitrate`, one `MaxStreamingBitrate`, one `MaxHeight`.
@@ -276,21 +279,52 @@ anything.
      audio-track switch)". Manual selection by stream re-open is what you build
      when there is no adaptation, and mpv can do the same thing.
 
-  **The decisive test has not been run** and needs a live server plus an API key:
-  count `#EXT-X-STREAM-INF` lines in a real `master.m3u8`. One line means there
-  is no ABR to lose and this blocker disappears. More than one means finding 3
-  stands and the work below applies.
+  **The decisive test has now been run** (2026-08-21, against the development
+  server, Jellyfin 10.11.5):
 
-  If ABR does turn out to be real, it belongs in **Rust**, not in mpv, and there
-  are three designs in increasing cost: pick the variant at open; re-open at a
-  new bitrate on sustained throughput drops (this is the quality-switch path the
-  app already has, so it is nearly free); or run a local proxy serving mpv a
-  synthesized single-variant playlist while swapping renditions underneath. The
-  middle option is almost certainly sufficient.
+  ```
+  curl -s ".../Videos/<itemId>/master.m3u8?…&TranscodingProtocol=hls&…" \
+    | grep -c EXT-X-STREAM-INF
+  1
+  ```
 
-  Either way the **direct-play path still does not exist** — every video play
-  currently goes through the HLS transcode endpoint. Building it is the real
-  project; the compositing work proven above is the smaller half.
+  **One line.** The playlist carries a single `EXT-X-STREAM-INF` plus an
+  `EXT-X-IMAGE-STREAM-INF` trickplay entry, which is not a rendition. Jellyfin
+  builds the master playlist from the rendition the request asked for; it does
+  not publish a ladder. So **there is no ABR to lose, and this blocker is
+  closed** — hls.js is serving as an HLS demuxer, exactly as (2) above supposed,
+  and mpv gives up nothing by replacing it.
+
+  Recorded as DR-229 (Won't Do) rather than deleted, because it is a
+  measurement: a server that *does* publish a ladder would change the answer, and
+  the re-negotiation path is the hook that work would build on.
+
+  **The direct-play path now exists.** It did not when this spike was written —
+  every video play went through the HLS transcode endpoint. Backend-owned stream
+  selection (DR-225 … DR-230) built it: Rust negotiates direct play / direct
+  stream / transcode and hands every backend one `StreamSelection` carrying the
+  URL, the transport and the chosen rendition. **That is the contract this
+  implementation consumes** — mpv is a consumer of a decision already made, not a
+  place to re-derive it.
+
+  It also sizes the prize precisely. Measured over the same server, 40 items
+  through a real negotiation per profile:
+
+  | Profile | Direct play |
+  |---|---|
+  | Linux / WebKitGTK — `h264` only, 2ch | **7%** |
+  | Android / ExoPlayer — `h264,hevc,vp8,vp9,av1,mpeg4` + `ac3,eac3`, 6ch | **85%** |
+
+  **The 85% is a ceiling, not a shipped result** — it was measured with a
+  profile containing `ac3,eac3`, which the Android device later used for
+  verification does not support.
+
+  The library sampled is ~80% hevc. Linux sits at 7% **solely because the
+  WebKitGTK profile can only claim h264** — not because of anything about the
+  server or the negotiation. mpv decodes hevc, so widening the Linux device
+  profile once mpv renders the picture is what converts that 7% toward the
+  Android figure. That conversion is the actual product of this work; the
+  compositing proven above is the mechanism that permits it.
 - 🔴 **One unexplained SIGSEGV.** A ~180s
   run died in a *decoder* thread (libavcodec -> `av_log` -> libmpv's log handler
   -> libc). No Tauri, wry, WebKitGTK, GTK or GL frame appears anywhere in the

docs/specs/media-player-controller.md

@@ -0,0 +1,269 @@
+# Spec: MediaPlayer — one controller API, three interchangeable engines
+
+**Status:** Proposed
+**Requirements:** UR-081 (new) → DR-242 … DR-249 (new); IR-034. Re-check
+`requirements.md` before allocating — ids moved several times while this was
+written.
+**UX spec:** n/a — no user-visible change is intended. That is the point.
+**Supersedes / revises:** absorbs `determine_video_seek_strategy`
+(`player/seek.rs`, DR-238) into the engines. Revises the backend half of
+[playback-backend-unification.md](playback-backend-unification.md).
+
+**Destination on completion:**
+[01-rust-backend.md](../architecture/01-rust-backend.md) — replaces the player
+state-machine section; and
+[05-platform-backends.md](../architecture/05-platform-backends.md) — the engines
+become implementations of a stated contract rather than three separate designs.
+
+## Summary
+
+Replace the `PlayerBackend` trait with a `MediaPlayer` contract that expresses
+**intent** ("present this item, starting here") rather than **device operations**
+("load", then "seek"). MPV, ExoPlayer and the webview element implement it; a
+`FakePlayer` implements it for tests; and one conformance suite runs against
+every implementation so a backend is either correct or visibly failing.
+
+No user-visible behaviour changes. What changes is that playback logic stops
+being written three times in the command layer.
+
+## Motivation
+
+A day of debugging Linux native video produced four defects (DR-238 … DR-241).
+Every one of them traces to the same missing seam, not to mpv:
+
+| Defect | What it looked like | What it was |
+|---|---|---|
+| DR-241 | "Resume is broken", "I cannot skip" | `loadfile` is async, so a seek issued straight after a load fails and was discarded. The trait has no way to say *open at a position*, so every caller does load-then-seek and each races independently. |
+| DR-238 | Transcoded seeks silently did nothing | `use_html5` was doing double duty as "who renders" **and** "how do I seek", decided in the command layer by a truth table. |
+| DR-239 | Play/pause control never moved | `PropertyChange { name: "pause" }` was handled but never observed. Nothing in the contract required an engine to report its own state. |
+| DR-240 | Fullscreen left the picture at window size | `requestFullscreen()` moves the document; whoever owns the pixels has to be told separately. |
+
+The shape is consistent: **the same intent implemented in several places, each
+with its own timing and its own idea of the rules.** Resume worked through the
+adapter (which seeks after `File loaded`) and failed through the command (which
+seeks immediately). Two callers, one intent, two behaviours.
+
+Supporting evidence for the diagnosis:
+
+- `commands/player/mod.rs` is **3,561 lines** and is where "stop → rebuild URL →
+  update queue → load → seek" lives. That is playback orchestration in the IPC
+  layer.
+- `player_play_item` needed a `#[cfg(not(target_os = "linux"))]` guard, i.e. a
+  platform decision in a command handler.
+- The frontend carries `didStartNativePlayback`, `didStopBackendEarly`,
+  `hasPerformedInitialSeek`, `lastAppliedInitialPosition` — playback state in the
+  UI, which contradicts the one-directional rule in CLAUDE.md.
+
+### Why an abstraction, and not more fixes
+
+Each defect above was individually cheap to patch, and patching them is what
+produced a regression: routing transcoded seeks to a reload path turned "seek
+does nothing" into "seek jumps to zero", because the reload path's own seek was
+broken in the same way. **Symptom fixes in this area compound.**
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|---|---|---|
+| Presenting an item at a position, in one operation | **Engine** (`MediaPlayer`) | Only the engine knows when its pipeline can accept a position. Expressing it as caller-sequenced load-then-seek exports a race the engine is the only one able to close. |
+| Whether *this* stream can be seeked in place, or must be re-opened | **Engine** | A property of the engine × transport pair: hls.js seeks a VOD playlist, mpv's HLS demuxer cannot make Jellyfin transcode from a new offset. Today this is a truth table in a command handler that has to guess for engines it does not own. |
+| Reporting position, phase, duration, active tracks | **Engine** | The player is the authoritative source of playback state (CLAUDE.md). An engine that does not report is not implementing the contract — DR-239 was exactly this. |
+| Choosing *which* stream to open (direct play vs transcode, ceiling, transport) | **Rust, above the engine** | Domain: depends on Jellyfin's `PlaybackInfo`, codec support, quality ceiling. See [backend-owned-stream-selection.md](backend-owned-stream-selection.md). The engine is handed a `StreamSelection`; it never negotiates one. |
+| Queue, autoplay, session, playback reporting | **`PlayerController`** | Policy across items. Unchanged — but it talks to one contract instead of branching per platform. |
+| Which engine this platform uses | **Rust, at construction** | Already correct today; stays a single `cfg` at the composition root rather than `cfg`s scattered through command handlers. |
+| Rendering surfaces, controls, fullscreen chrome | **Frontend / platform** | Presentation. The engine reports *what* is playing; it does not own the window. |
+
+Borderline row and its tie-breaker: "should a transcoded seek re-open the
+stream?" reads like domain policy. It is **engine** capability — the *decision*
+is "seek to T", and how to achieve it is the engine's business. If it were
+policy, every new engine would require editing a shared truth table, which is
+precisely the coupling DR-238 came from.
+
+## Design
+
+### The contract
+
+```rust
+/// Anything that can present media: MpvPlayer, ExoPlayer, WebviewPlayer, FakePlayer.
+pub trait MediaPlayer: Send {
+    /// Present `req.selection`, beginning at `req.start`.
+    ///
+    /// One operation, deliberately. `open` is where a start position is
+    /// *expressible*, so no caller has to sequence load-then-seek and no caller
+    /// can race the engine's own load. An engine that cannot start at an offset
+    /// natively must absorb that internally (defer until loaded, or re-open) —
+    /// it is the only layer that knows when it is able to.
+    fn open(&mut self, req: OpenRequest) -> Result<(), PlayerError>;
+
+    fn play(&mut self) -> Result<(), PlayerError>;
+    fn pause(&mut self) -> Result<(), PlayerError>;
+
+    /// Stop and release the current item. Must be idempotent, and must leave the
+    /// engine producing no audio — DR-2xx exists because "stopped" and "silent"
+    /// were not the same thing.
+    fn close(&mut self) -> Result<(), PlayerError>;
+
+    /// Seek to an absolute position on the item's timeline.
+    ///
+    /// The engine decides in-place vs re-open. Callers never choose.
+    fn seek(&mut self, to: Duration) -> Result<(), PlayerError>;
+
+    fn set_volume(&mut self, volume: Volume) -> Result<(), PlayerError>;
+    fn set_rate(&mut self, rate: f64) -> Result<(), PlayerError>;
+    fn select_audio_track(&mut self, index: Option<i32>) -> Result<(), PlayerError>;
+    fn select_subtitle_track(&mut self, index: Option<i32>) -> Result<(), PlayerError>;
+
+    /// One coherent read of everything the UI consumes.
+    fn snapshot(&self) -> PlaybackSnapshot;
+
+    /// Engine capabilities, so callers can adapt without naming engines.
+    fn capabilities(&self) -> Capabilities;
+}
+```
+
+```rust
+pub struct OpenRequest {
+    pub media: MediaItem,
+    pub selection: StreamSelection, // url + transport + playback kind
+    pub start: Duration,            // Duration::ZERO for "from the beginning"
+    pub audio_track: Option<i32>,
+    pub subtitle_track: Option<i32>,
+    pub autoplay: bool,
+}
+
+pub struct PlaybackSnapshot {
+    pub phase: Phase,
+    pub position: Duration,
+    pub duration: Option<Duration>,
+    pub seekable: bool,
+    pub volume: Volume,
+    pub rate: f64,
+    pub audio_track: Option<i32>,
+    pub subtitle_track: Option<i32>,
+}
+
+/// `Opening` is the state today's code cannot express, and the direct cause of
+/// DR-241: a seek arriving with nothing loaded had no phase to be rejected or
+/// queued against, so it was simply lost.
+pub enum Phase { Idle, Opening, Ready, Playing, Paused, Ended, Failed(String) }
+```
+
+Engines emit `PlayerEvent` for phase, position, track and error changes. Emitting
+is part of the contract, and the conformance suite asserts it — an engine that
+stays silent fails, which is what would have caught DR-239 the day it landed.
+
+### What this deletes
+
+- `determine_video_seek_strategy` and `VideoSeekStrategy` — replaced by
+  `seek()` + `capabilities()`. The command layer stops deciding how engines seek.
+- The reload orchestration in `player_seek_video` — moves inside the engines that
+  need it.
+- `#[cfg(target_os = "linux")]` branches in command handlers.
+- Frontend playback-state flags, which become reads of `snapshot()`.
+
+### IPC
+
+No new commands. Existing ones keep their names and shapes; they become thin
+delegations. `PlayerStatus` gains nothing the frontend does not already receive.
+Regenerate `bindings.ts` only if `PlaybackSnapshot` is exposed directly — prefer
+mapping it onto the existing `PlayerStatus` so this stays invisible at the wire.
+
+## Testing
+
+This is the half that makes the abstraction worth having, and it is the reason to
+do it rather than keep patching.
+
+### 1. A conformance suite, run against every engine
+
+One set of tests, parameterised over implementations. Any `MediaPlayer` must pass
+it; a new engine is "done" when it does.
+
+```
+conformance::run(&mut engine, fixture) covering:
+  open(start = ZERO)            -> phase Ready|Playing, position ~0
+  open(start = 10min)           -> position within tolerance of 10min, NEVER 0   [DR-241]
+  seek while Opening            -> honoured once Ready, not discarded            [DR-241]
+  seek on a transcoded stream   -> position lands, by whatever means             [DR-238]
+  pause / play                  -> phase changes AND an event is emitted         [DR-239]
+  close                         -> phase Idle, silent, idempotent
+  close during Opening          -> no playback ever starts                       [audio-on-exit]
+  volume / rate / track select  -> reflected in snapshot()
+```
+
+The `open(start = 10min)` and `seek while Opening` cases are the ones that fail
+on today's code. They are written first, and they are the acceptance criterion.
+
+### 2. `FakePlayer`
+
+A deterministic in-memory implementation with a controllable clock. Lets
+`PlayerController`, autoplay, queue, sleep-timer and session logic be tested with
+no mpv, no device, no network — most of which is currently only reachable through
+a real engine.
+
+### 3. Per-engine runs
+
+| Engine | Where | Note |
+|---|---|---|
+| `FakePlayer` | `cargo test` | Always. |
+| `MpvPlayer` | `cargo test`, Linux | libmpv is already in the builder image (the Linux build links it), so **no CI toolchain install** — see CLAUDE.md. Needs a tiny local fixture file; generate it in-test rather than committing media. |
+| `ExoPlayer` | instrumented, on device | Not in the standard CI job. Run via `scripts/` on a connected device; record results in the PR. |
+| `WebviewPlayer` | vitest | Against a stubbed element, as `html5Adapter` is tested today. |
+
+An engine that cannot run in CI still has the same suite; it is just run by hand.
+That is the point of writing it once.
+
+## Migration
+
+Strangler, not a rewrite. Each step ships independently and leaves the app working.
+
+1. **DR-242** Define `MediaPlayer`, `OpenRequest`, `PlaybackSnapshot`, `Phase`,
+   `Capabilities`. No implementations. Compiles alongside `PlayerBackend`.
+2. **DR-243** `FakePlayer` + the conformance suite. The suite fails against
+   nothing yet — it is the specification.
+3. **DR-244** `MpvPlayer` implementing `MediaPlayer`, wrapping today's
+   `MpvBackend` internals. Make conformance pass, including `open(start)`.
+4. **DR-245** `PlayerController` talks to `MediaPlayer`. `PlayerBackend` retained
+   behind an adapter so the other engines keep working.
+5. **DR-246** Move seek strategy and reload orchestration out of
+   `commands/player/mod.rs` into the engines; delete `seek.rs`'s truth table.
+6. **DR-247** `ExoPlayerPlayer`; conformance on device.
+7. **DR-248** `WebviewPlayer`; retire the adapter shim.
+8. **DR-249** Delete `PlayerBackend` and the frontend playback-state flags.
+
+Steps 1–3 are pure addition and risk nothing. Step 5 is where today's defect
+classes actually die.
+
+## Out of scope
+
+- Stream selection (which URL, which quality) — that is
+  [backend-owned-stream-selection.md](backend-owned-stream-selection.md), and
+  this spec consumes its `StreamSelection` rather than duplicating it.
+- Rendering surfaces and compositing.
+- Any user-visible behaviour change. If one appears, it is a bug in the migration.
+- Replacing hls.js or changing the transcode path.
+
+## Acceptance criteria
+
+- [ ] The conformance suite exists and `open(start = 10min)` fails against the
+      pre-migration mpv path — proving it reproduces DR-241 — then passes.
+- [ ] `FakePlayer` lets at least one controller-level test run with no engine.
+- [ ] `determine_video_seek_strategy` is deleted, not merely bypassed.
+- [ ] No `cfg(target_os = ...)` remains in `commands/player/`.
+- [ ] `bun run check`, `bun run test`, `bun run format:check`, `bun run lint` pass.
+- [ ] `cargo fmt`, `cargo clippy -D warnings`, `bun run test:rust` pass.
+- [ ] `bun run check:boundary` passes.
+- [ ] `// TRACES:` on new code; `bun run traces:validate` passes; coverage stays
+      at or above the CI ratchet.
+- [ ] Manual: resume, skip on a transcoded item, pause/play, and exit-while-playing
+      verified on Linux **and** Android before `PlayerBackend` is deleted.
+
+## Notes for the implementer
+
+- **Write the conformance suite before the second engine**, or it will encode
+  whatever the first engine happens to do.
+- `close()` must mean *silent*. The bug that motivated this spec had `stop` being
+  called, reported, and audible afterwards.
+- Do not let `Capabilities` grow into engine sniffing. If a caller branches on
+  the engine's identity, the contract is missing something — add it there.
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes.

docs/specs/read-through-media-cache.md

@@ -9,7 +9,7 @@ DR-124, DR-125.
 
 **DR-121 has shipped and left this spec.** The player quality selector, the
 per-playback bitrate ceiling, and the backend-owned stream decision it needed
-were built as *backend-owned stream selection* (DR-224 … DR-227) and are
+were built as *backend-owned stream selection* (DR-225 … DR-228) and are
 described in
 [01-rust-backend.md](../architecture/01-rust-backend.md#stream-selection) and
 [03-data-flow.md](../architecture/03-data-flow.md#video-stream-selection-flow).
@@ -77,7 +77,7 @@ frontend stores the user's *choice*; Rust decides what that choice resolves to.
 
 ### DR-121 — moved out (shipped)
 
-Bitrate selection in the player shipped as DR-224 … DR-227; see
+Bitrate selection in the player shipped as DR-225 … DR-228; see
 [01-rust-backend.md](../architecture/01-rust-backend.md#stream-selection).
 
 The one constraint here that the capture work still has to respect: a quality

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jellytau",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "A cross-platform Jellyfin client built with Tauri, SvelteKit and Rust.",
   "author": "Duncan Tourolle <duncan@tourolle.paris>",
   "license": "MIT",

packaging/arch/PKGBUILD

@@ -8,7 +8,7 @@
 # tarball/VCS URL and drop the local-copy prepare() step.
 
 pkgname=jellytau
-pkgver=0.10.0
+pkgver=0.10.1
 pkgrel=1
 pkgdesc="A cross-platform Jellyfin client"
 arch=('x86_64')

scripts/sync-android-sources.sh

@@ -36,6 +36,19 @@ if [ -d "$TEST_SOURCE_DIR" ]; then
     echo "  Copied unit tests: src/test"
 fi
 
+# Instrumented tests (src/androidTest). These need a device: they drive
+# ExoPlayer, which requires an Android Context and a Looper and therefore
+# cannot run from the desktop conformance suite. Run with
+# `./gradlew :app:connectedDebugAndroidTest` from gen/android.
+ANDROID_TEST_SOURCE_DIR="$PROJECT_ROOT/src-tauri/android/src/androidTest/java/com/dtourolle/jellytau"
+ANDROID_TEST_TARGET_DIR="$PROJECT_ROOT/src-tauri/gen/android/app/src/androidTest/java/com/dtourolle/jellytau"
+if [ -d "$ANDROID_TEST_SOURCE_DIR" ]; then
+    rm -rf "$ANDROID_TEST_TARGET_DIR"
+    mkdir -p "$ANDROID_TEST_TARGET_DIR"
+    cp -r "$ANDROID_TEST_SOURCE_DIR"/. "$ANDROID_TEST_TARGET_DIR/"
+    echo "  Copied instrumented tests: src/androidTest"
+fi
+
 # Copy individual Kotlin files (like VideoOverlayManager.kt)
 for kt_file in "$SOURCE_DIR"/*.kt; do
     if [ -f "$kt_file" ]; then

src-tauri/Cargo.lock

@@ -2181,7 +2181,7 @@ dependencies = [
 
 [[package]]
 name = "jellytau"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "aes-gcm",
  "async-trait",
@@ -2191,11 +2191,13 @@ dependencies = [
  "env_logger",
  "futures-util",
  "getrandom 0.2.16",
+ "gtk",
  "hostname",
  "jni 0.21.1",
  "keyring",
  "libc",
  "libmpv",
+ "libmpv-sys",
  "log",
  "ndk-context",
  "rand 0.8.7",
@@ -3285,9 +3287,9 @@ checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"
 
 [[package]]
 name = "plist"
-version = "1.8.0"
+version = "1.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "740ebea15c5d1428f910cd1a5f52cebf8d25006245ed8ade92702f4943d91e07"
+checksum = "7da1d65da6dd5d1e44199ac0f58712d241c0f439f80adea8924d832384087f85"
 dependencies = [
  "base64 0.22.1",
  "indexmap 2.12.1",
@@ -3463,9 +3465,9 @@ dependencies = [
 
 [[package]]
 name = "quick-xml"
-version = "0.38.4"
+version = "0.41.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b66c2058c55a409d601666cffe35f04333cf1013010882cec174a7467cd4e21c"
+checksum = "e660451e55124f798a69a5af3f49ccfbefbd41910eefd25caf2393e1f3473ec1"
 dependencies = [
  "memchr",
 ]

src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jellytau"
-version = "0.10.0"
+version = "0.10.1"
 description = "A cross-platform Jellyfin client"
 authors = ["Duncan Tourolle <duncan@tourolle.paris>"]
 license = "MIT"
@@ -114,6 +114,25 @@ libc = "0.2"
 # than changing it. To take upstream fixes, bump this deliberately.
 libmpv = { git = "https://github.com/ParadoxSpiral/libmpv-rs.git", rev = "3e6c389b716f52a595cc5e8e3fa1f96cb76b3de7" }
 
+# The raw FFI bindings behind `libmpv`, pinned to the *same* revision so the two
+# can never describe different ABIs.
+#
+# Needed because the safe crate's `render` module is an empty stub at this
+# revision — the render API (`mpv_render_context_create` and friends) exists only
+# in the sys bindings, which do carry all of it. `Mpv::ctx` is public, so the
+# render context can be built over the same handle the safe wrapper drives. This
+# is what makes native video reachable *without* first completing the libmpv2
+# migration, which the spike's use of `libmpv2-sys` had implied was a
+# prerequisite.
+#
+# TRACES: UR-080 | DR-230, IR-033
+libmpv-sys = { git = "https://github.com/ParadoxSpiral/libmpv-rs.git", rev = "3e6c389b716f52a595cc5e8e3fa1f96cb76b3de7" }
+
+# Same major as the one Tauri/wry already resolve, so `gtk_window()` and
+# `default_vbox()` hand back types this crate can name rather than a second,
+# incompatible GTK.
+gtk = "0.18"
+
 # JNI for Android ExoPlayer integration
 [target.'cfg(target_os = "android")'.dependencies]
 jni = "0.21"
@@ -122,3 +141,18 @@ ndk-context = "0.1"
 [dev-dependencies]
 tempfile = "3.24.0"
 
+[features]
+# Exposes the MediaPlayer conformance suite and the `player-conformance` binary
+# to non-test builds, so an engine that cannot run in-process — ExoPlayer on a
+# device — is driven by the same cases as the ones that can, rather than by a
+# second checklist that drifts.
+conformance = []
+
+# A standalone runner for the conformance suite. Deliberately a separate binary:
+# it links libmpv and nothing else, so a wrapper can be verified without building
+# or launching the app.
+[[bin]]
+name = "player-conformance"
+path = "src/bin/player_conformance.rs"
+required-features = ["conformance"]
+

src-tauri/android/app/build.gradle.kts

@@ -46,6 +46,9 @@ android {
         targetSdk = 36
         versionCode = tauriProperties.getProperty("tauri.android.versionCode", "1").toInt()
         versionName = tauriProperties.getProperty("tauri.android.versionName", "1.0")
+        // Required to run the on-device conformance suite
+        // (src/androidTest). See docs/specs/media-player-controller.md.
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
     signingConfigs {
         create("release") {
@@ -147,6 +150,7 @@ dependencies {
     testImplementation("junit:junit:4.13.2")
     androidTestImplementation("androidx.test.ext:junit:1.1.4")
     androidTestImplementation("androidx.test.espresso:espresso-core:3.5.0")
+    androidTestImplementation("androidx.test:runner:1.5.2")
 }
 
 apply(from = "tauri.build.gradle.kts")

src-tauri/android/src/androidTest/java/com/dtourolle/jellytau/player/PlayerConformanceTest.kt

@@ -0,0 +1,252 @@
+package com.dtourolle.jellytau.player
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertTrue
+import org.junit.Assert.assertFalse
+import org.junit.Before
+import org.junit.After
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.io.File
+import kotlin.math.abs
+
+/**
+ * The MediaPlayer conformance cases, run against ExoPlayer on a real device.
+ *
+ * The desktop suite (src-tauri/src/player/conformance.rs) cannot reach here:
+ * ExoPlayer needs an Android Context and a Looper, so it only exists inside an
+ * app process. These are the same behaviours, asserted against the engine
+ * itself rather than the Rust wrapper — the layer below the contract.
+ *
+ * The fixture is generated rather than committed: a long silent WAV written to
+ * the cache directory at setup. No binary in the repo, no `adb push` step, and
+ * the duration is exact, which matters for the seek assertions.
+ *
+ * Run:  ./gradlew :app:connectedDebugAndroidTest   (from src-tauri/gen/android)
+ *
+ * TRACES: UR-081 | DR-247
+ */
+@RunWith(AndroidJUnit4::class)
+class PlayerConformanceTest {
+
+    private lateinit var player: JellyTauPlayer
+    private lateinit var mediaUrl: String
+
+    /** Long enough to seek well past any buffer. */
+    private val fixtureSeconds = 1200
+
+    /**
+     * ExoPlayer lands on the nearest sync sample, and a `prepare` is not
+     * instantaneous. Generous on purpose: a tight bound here produces a test
+     * that fails on a slow device and teaches people to re-run until green.
+     */
+    private val toleranceSeconds = 10.0
+
+    @Before
+    fun setUp() {
+        val context = InstrumentationRegistry.getInstrumentation().targetContext
+        JellyTauPlayer.initialize(context)
+        player = JellyTauPlayer.getInstance()
+
+        val fixture = File(context.cacheDir, "conformance-$fixtureSeconds.wav")
+        if (!fixture.exists() || fixture.length() < 1024) {
+            writeSilentWav(fixture, fixtureSeconds)
+        }
+        mediaUrl = fixture.toURI().toString()
+    }
+
+    @After
+    fun tearDown() {
+        onMain { player.stop() }
+        // Leave nothing playing for the next case.
+        Thread.sleep(200)
+    }
+
+    // ---------------------------------------------------------------- cases
+
+    @Test
+    fun opensFromTheBeginning() {
+        onMain { player.load(mediaUrl, "conformance") }
+        awaitLoaded()
+
+        assertNear(0.0, position(), "playback should start at the beginning")
+        assertTrue("duration should be known once loaded", duration() > 0)
+    }
+
+    /**
+     * DR-241. Opening at a position starts *there*, not at zero.
+     *
+     * `load(url, mediaId)` has no way to express a start position, so every
+     * caller loads and then seeks — and a seek issued against a player that is
+     * still preparing is the window resume was lost in on the desktop side.
+     * This is the same defect on ExoPlayer.
+     */
+    @Test
+    fun opensAtAStartPosition() {
+        val start = 600.0
+        onMain { player.load(mediaUrl, "conformance", start) }
+        awaitLoaded()
+
+        assertTrue(
+            "opened at ${start}s but playback began at ${position()}s - " +
+                "the start position was dropped",
+            position() > 1.0
+        )
+        assertNear(start, position(), "start position")
+    }
+
+    /** DR-241. A seek issued while still preparing is honoured, not lost. */
+    @Test
+    fun seekWhileOpeningIsHonoured() {
+        val target = 300.0
+        onMain {
+            player.load(mediaUrl, "conformance")
+            // Deliberately before the player is ready: this is the race,
+            // expressed on purpose rather than stumbled into.
+            player.seek(target)
+        }
+        awaitLoaded()
+
+        assertNear(target, position(), "seek issued while opening")
+    }
+
+    @Test
+    fun seeksAfterOpen() {
+        onMain { player.load(mediaUrl, "conformance") }
+        awaitLoaded()
+
+        val target = 420.0
+        onMain { player.seek(target) }
+        awaitPosition(target)
+
+        assertNear(target, position(), "seek after open")
+    }
+
+    /** DR-239. Pause and play are observable, not merely accepted. */
+    @Test
+    fun pauseAndPlayAreObservable() {
+        onMain { player.load(mediaUrl, "conformance") }
+        awaitLoaded()
+
+        onMain { player.pause() }
+        awaitPlaying(false)
+        assertFalse("a paused player must not report playing", isPlaying())
+
+        onMain { player.play() }
+        awaitPlaying(true)
+        assertTrue("a resumed player must report playing", isPlaying())
+    }
+
+    /** `stop()` releases the item, is silent, and can be called twice. */
+    @Test
+    fun closeIsSilentAndIdempotent() {
+        onMain { player.load(mediaUrl, "conformance") }
+        awaitLoaded()
+
+        onMain { player.stop() }
+        awaitPlaying(false)
+        assertFalse("a stopped player must not report playing", isPlaying())
+
+        onMain { player.stop() }
+        assertFalse("stop must be idempotent", isPlaying())
+    }
+
+    /**
+     * An open cancelled by stop must not come back to life.
+     *
+     * The shape of "audio kept playing after leaving the player": a prepare
+     * still in flight completed after the stop, with nothing left to tell it
+     * not to.
+     */
+    @Test
+    fun closeDuringOpenNeverPlays() {
+        onMain {
+            player.load(mediaUrl, "conformance")
+            player.stop()
+        }
+        Thread.sleep(2000)
+
+        assertFalse(
+            "a load cancelled by stop must not start playing",
+            isPlaying()
+        )
+    }
+
+    // -------------------------------------------------------------- helpers
+
+    private fun onMain(block: () -> Unit) {
+        InstrumentationRegistry.getInstrumentation().runOnMainSync(block)
+    }
+
+    private fun position(): Double = readOnMain { player.getPosition() }
+    private fun duration(): Double = readOnMain { player.getDuration() }
+    private fun isPlaying(): Boolean = readOnMain { player.getExoPlayer().isPlaying }
+
+    private fun <T> readOnMain(block: () -> T): T {
+        var out: T? = null
+        InstrumentationRegistry.getInstrumentation().runOnMainSync { out = block() }
+        @Suppress("UNCHECKED_CAST")
+        return out as T
+    }
+
+    /** Poll a state the player publishes rather than sleeping a fixed time. */
+    private fun await(what: String, timeoutMs: Long = 15_000, predicate: () -> Boolean) {
+        val deadline = System.currentTimeMillis() + timeoutMs
+        while (System.currentTimeMillis() < deadline) {
+            if (predicate()) return
+            Thread.sleep(50)
+        }
+        throw AssertionError("timed out waiting for $what")
+    }
+
+    private fun awaitLoaded() {
+        await("the player to report a duration") { duration() > 0 }
+        // One more beat so a start position or a deferred seek has landed.
+        Thread.sleep(500)
+    }
+
+    private fun awaitPosition(target: Double) =
+        await("position to reach ${target}s") { abs(position() - target) <= toleranceSeconds }
+
+    private fun awaitPlaying(expected: Boolean) =
+        await("isPlaying == $expected", 5_000) { isPlaying() == expected }
+
+    private fun assertNear(expected: Double, actual: Double, what: String) {
+        assertTrue(
+            "$what: expected ~${expected}s, got ${actual}s (tolerance ${toleranceSeconds}s)",
+            abs(actual - expected) <= toleranceSeconds
+        )
+    }
+
+    /**
+     * Write a silent 8 kHz mono 16-bit WAV of `seconds` length.
+     *
+     * Synthesised rather than committed so the repo carries no media, and so
+     * the duration is exact — the seek assertions depend on it.
+     */
+    private fun writeSilentWav(file: File, seconds: Int) {
+        val sampleRate = 8000
+        val dataBytes = sampleRate * 2 * seconds
+        file.outputStream().buffered().use { out ->
+            fun le32(v: Int) = out.write(
+                byteArrayOf(
+                    (v and 0xff).toByte(),
+                    ((v shr 8) and 0xff).toByte(),
+                    ((v shr 16) and 0xff).toByte(),
+                    ((v shr 24) and 0xff).toByte()
+                )
+            )
+            fun le16(v: Int) =
+                out.write(byteArrayOf((v and 0xff).toByte(), ((v shr 8) and 0xff).toByte()))
+
+            out.write("RIFF".toByteArray()); le32(36 + dataBytes); out.write("WAVE".toByteArray())
+            out.write("fmt ".toByteArray()); le32(16); le16(1); le16(1)
+            le32(sampleRate); le32(sampleRate * 2); le16(2); le16(16)
+            out.write("data".toByteArray()); le32(dataBytes)
+
+            val chunk = ByteArray(sampleRate * 2) // one second of silence
+            repeat(seconds) { out.write(chunk) }
+        }
+    }
+}

src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt

@@ -164,17 +164,33 @@ class MainActivity : TauriActivity() {
    */
   override fun onStop() {
     super.onStop()
-    if (backgroundAudioEnabled) {
-      dispatchWebEvent("jellytau-background")
+    // Fires unconditionally now. It used to be gated on backgroundAudioEnabled,
+    // which meant the frontend was never told the app had gone away unless the
+    // toggle was already on -- so with the toggle OFF nothing could react, and
+    // on the native path ExoPlayer's media service simply kept playing. That is
+    // the whole defect: the toggle appeared to do nothing because the only
+    // notification of backgrounding was itself gated on the toggle (DR-224).
+    //
+    // What to DO about it is decided in Rust (player_background_action); this
+    // only reports the two facts the activity alone knows.
+    val inPip = if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.N) {
+      isInPictureInPictureMode
+    } else {
+      false
     }
+    dispatchWebEvent(
+      "jellytau-background",
+      "{\"backgroundAudioArmed\": $backgroundAudioEnabled, \"inPictureInPicture\": $inPip}"
+    )
   }
 
   /** The app is visible again — tell the frontend to resume WebView video. */
   override fun onStart() {
     super.onStart()
-    if (backgroundAudioEnabled) {
-      dispatchWebEvent("jellytau-foreground")
-    }
+    // Also unconditional, for the same reason: a video paused on background has
+    // to be told it is visible again, and that pause happens with the toggle
+    // OFF. The frontend ignores this when it has nothing to restore.
+    dispatchWebEvent("jellytau-foreground")
   }
 
   /**
@@ -182,14 +198,14 @@ class MainActivity : TauriActivity() {
    * evaluateJavascript pattern already used to unmute video elements. Posted to
    * the WebView thread; safe no-op if the WebView isn't found yet.
    */
-  private fun dispatchWebEvent(name: String) {
+  private fun dispatchWebEvent(name: String, detailJson: String = "null") {
     val webView = mediaWebView ?: run {
       android.util.Log.w("MainActivity", "dispatchWebEvent('$name'): no WebView")
       return
     }
     webView.post {
       webView.evaluateJavascript(
-        "window.dispatchEvent(new CustomEvent('$name'));",
+        "window.dispatchEvent(new CustomEvent('$name', { detail: $detailJson }));",
         null
       )
       android.util.Log.d("MainActivity", "Dispatched web event: $name")

src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt

@@ -556,11 +556,31 @@ class JellyTauPlayer(private val appContext: Context) {
      * @param mediaId The unique ID for this media item
      */
     fun load(url: String, mediaId: String) {
+        load(url, mediaId, 0.0)
+    }
+
+    /**
+     * Load [url] and begin at [startPositionSeconds].
+     *
+     * The start position is handed to ExoPlayer with the media item, not seeked
+     * to afterwards. `prepare()` is asynchronous, so a seek issued straight
+     * after a load targets a player that is still preparing: ExoPlayer clamps it
+     * back to zero and the item plays from the beginning. That is what made
+     * resume and transcoded skip start over, and it is why callers must never
+     * express a start position as load-then-seek.
+     *
+     * TRACES: UR-081, UR-005 | DR-241, DR-247
+     */
+    fun load(url: String, mediaId: String, startPositionSeconds: Double) {
         mainHandler.post {
             currentMediaId = mediaId
             endedNotified = false
             val mediaItem = MediaItem.fromUri(url)
-            exoPlayer.setMediaItem(mediaItem)
+            if (startPositionSeconds > 0.0) {
+                exoPlayer.setMediaItem(mediaItem, (startPositionSeconds * 1000).toLong())
+            } else {
+                exoPlayer.setMediaItem(mediaItem)
+            }
             exoPlayer.prepare()
             exoPlayer.playWhenReady = true
         }

src-tauri/src/bin/player_conformance.rs

@@ -0,0 +1,37 @@
+//! Thin entry point. The suite lives in the library so the binary needs no
+//! access to the player internals — one exported function rather than a public
+//! module tree.
+//!
+//!     player-conformance <media-file> [mpv|legacy]
+//!
+//! `legacy` drives the old `PlayerBackend` through the same cases, so the
+//! difference between the two designs is demonstrated on one engine and one
+//! file rather than argued.
+//!
+//! TRACES: UR-081 | DR-244, DR-245
+
+use std::process::ExitCode;
+
+use jellytau_lib::conformance_runner::{run_engine, Engine};
+
+fn main() -> ExitCode {
+    let mut args = std::env::args().skip(1);
+    let Some(url) = args.next() else {
+        eprintln!("usage: player-conformance <media-file-or-url> [mpv|legacy]");
+        return ExitCode::from(2);
+    };
+    let engine = match args.next().as_deref() {
+        None | Some("mpv") => Engine::Mpv,
+        Some("legacy") => Engine::Legacy,
+        Some(other) => {
+            eprintln!("unknown engine {other:?} - expected mpv or legacy");
+            return ExitCode::from(2);
+        }
+    };
+
+    if run_engine(&url, engine) == 0 {
+        ExitCode::SUCCESS
+    } else {
+        ExitCode::FAILURE
+    }
+}

src-tauri/src/commands/player/mod.rs

@@ -187,7 +187,7 @@ pub struct PlayItemRequest {
     /// caller falls back to `needs_transcoding` — every transcode this app
     /// requests is HLS (DR-140), so that fallback is exact rather than a guess.
     ///
-    /// TRACES: UR-003, UR-004, UR-079 | DR-224, DR-229
+    /// TRACES: UR-003, UR-004, UR-079 | DR-225, DR-230
     #[serde(default)]
     pub transport: Option<crate::repository::Transport>,
 
@@ -331,7 +331,7 @@ pub enum VideoSeekResponse {
     ReloadStream {
         /// What to open, and how — transport included, so the frontend picks
         /// its loader from a tagged enum rather than by searching the URL for
-        /// `.m3u8`. TRACES: UR-079 | DR-224
+        /// `.m3u8`. TRACES: UR-079 | DR-225
         selection: StreamSelection,
         /// `seek_offset` carries the position to RESUME AT, not a base to add to
         /// the element's clock. The reloaded stream starts at the item's zero —
@@ -353,7 +353,7 @@ pub enum AudioTrackSwitchResponse {
     },
     /// HTML5 needs to reload stream with new audio track
     ReloadStream {
-        /// What to open, and how. TRACES: UR-079 | DR-224
+        /// What to open, and how. TRACES: UR-079 | DR-225
         selection: StreamSelection,
         /// Current position to resume from
         position: f64,
@@ -369,8 +369,21 @@ pub enum AudioTrackSwitchResponse {
 #[derive(specta::Type, Debug, Serialize)]
 #[serde(tag = "strategy", rename_all = "camelCase")]
 pub enum StreamQualityResponse {
-    /// The native backend was reloaded here; nothing left for the frontend.
+    /// The native backend was reloaded here; nothing left for the frontend to
+    /// *do* — but it still has to be told what was negotiated.
+    ///
+    /// This carried only a position at first, which left the picker on Android
+    /// pinned to the rendition of the *first* stream: the UI derives the rung in
+    /// force from the selection it holds, nothing replaced that selection on the
+    /// native path, and a transcode always has a rendition — so the fallback
+    /// that would have used the requested value was never reached. The stream
+    /// changed and the menu did not.
+    ///
+    /// TRACES: UR-074, UR-079 | DR-226, DR-227
     Native {
+        /// What the backend actually opened, so the UI reflects it rather than
+        /// assuming the request was honoured verbatim.
+        selection: StreamSelection,
         /// Position playback resumed at.
         position: f64,
     },
@@ -379,7 +392,7 @@ pub enum StreamQualityResponse {
         /// What to open, and how — already negotiated against the requested
         /// ceiling. Carries `available` too, so a picker opened after a quality
         /// change still describes the source correctly.
-        /// TRACES: UR-070, UR-079 | DR-224, DR-226
+        /// TRACES: UR-070, UR-079 | DR-225, DR-227
         selection: StreamSelection,
         /// Position to resume from.
         position: f64,
@@ -436,7 +449,7 @@ pub(super) async fn create_media_item(
         source,
         video_codec: Some(req.video_codec),
         needs_transcoding: req.needs_transcoding,
-        // The caller's negotiated transport, when it had one. TRACES: UR-079 | DR-229
+        // The caller's negotiated transport, when it had one. TRACES: UR-079 | DR-230
         transport: req.transport,
         video_width: None,  // Not available from video-only request
         video_height: None, // Not available from video-only request
@@ -689,9 +702,9 @@ pub async fn player_play_item(
     // A ceiling chosen from the in-player picker belongs to the playback it was
     // chosen for. Starting a different item returns to the device default —
     // otherwise "2 Mbps, just for this one film" quietly governs the rest of the
-    // session, which is the defect DR-225 exists to close.
+    // session, which is the defect DR-226 exists to close.
     //
-    // TRACES: UR-074, UR-079 | DR-225
+    // TRACES: UR-074, UR-079 | DR-226
     crate::repository::online::clear_playback_quality_override();
 
     // Create media item, checking for local download first
@@ -712,18 +725,30 @@ pub async fn player_play_item(
     }
 
     let controller = player.0.lock().await;
-    // On Linux, video plays in the WebKitGTK HTML5 <video> element (see
-    // get_player_status -> use_html5_element). The MPV backend has no embedded
-    // window, so loading the stream into it would only start a redundant decode
-    // (and the frontend would immediately stop it). Only load into the native
-    // backend on platforms that actually render video through it (e.g. Android).
-    #[cfg(not(target_os = "linux"))]
-    controller
-        .play_item(media_item)
-        .map_err(|e| e.to_string())?;
-    #[cfg(target_os = "linux")]
-    {
-        // Keep the queue in sync for UI/remote-transfer without starting MPV.
+    // Who gets the stream depends on who is going to *render* it, which is a
+    // runtime question, not a platform constant.
+    //
+    // Historically Linux video was always the webview's (`use_html5_element`),
+    // so handing the file to MPV as well would only have started a redundant
+    // decode with no window to show it in — hence a `#[cfg(not(linux))]` guard
+    // and a queue-only path here. With mpv drawing the picture that inverts:
+    // the webview is no longer loading anything, so if this does not load the
+    // file, *nothing does*. The symptom is total silence — no picture and no
+    // audio — which reads like a broken stream rather than a stream nobody was
+    // given.
+    //
+    // This is the fifth place in this cycle where a renderer's capability was
+    // written as a compile-time platform fact. Same fix as the others: ask.
+    //
+    // TRACES: UR-080 | DR-231, DR-235
+    let renders_natively = cfg!(not(target_os = "linux")) || crate::player::native_video::enabled();
+    if renders_natively {
+        controller
+            .play_item(media_item)
+            .map_err(|e| e.to_string())?;
+    } else {
+        // The webview will play it; keep the queue in sync for the UI and for a
+        // remote transfer without starting a second decode.
         controller
             .set_current_item(media_item)
             .map_err(|e| e.to_string())?;
@@ -873,6 +898,46 @@ pub async fn player_enter_background_audio(
 /// untouched — if it fired while backgrounded, playback is already stopped and
 /// this simply reports the last position.
 ///
+/// What playback should do now that the app is no longer visible.
+///
+/// The caller supplies only what it alone knows -- whether the per-player
+/// toggle is armed, and whether Android put the window into picture-in-picture.
+/// Everything else (what is playing, and therefore whether there is a picture to
+/// lose) is read here, because it is domain state.
+///
+/// The rule itself is in `player::background_policy`; this command is the wire.
+/// Returning `KeepPlaying` for an empty queue is deliberate: with nothing
+/// playing there is nothing to pause, and an error would make the frontend
+/// handle a case that is not a failure.
+///
+/// TRACES: UR-040, UR-041 | DR-225 | UT-212
+#[tauri::command]
+#[specta::specta]
+pub async fn player_background_action(
+    player: State<'_, PlayerStateWrapper>,
+    background_audio_armed: bool,
+    in_picture_in_picture: bool,
+) -> Result<crate::player::background_policy::BackgroundAction, String> {
+    use crate::player::background_policy::{background_action, is_video_media, BackgroundAction};
+
+    let is_video = {
+        let controller = player.0.lock().await;
+        let queue_arc = controller.queue();
+        let queue = queue_arc.lock().map_err(|e| e.to_string())?;
+        match queue.current() {
+            Some(item) => is_video_media(item.media_type),
+            None => return Ok(BackgroundAction::KeepPlaying),
+        }
+    };
+
+    let action = background_action(is_video, background_audio_armed, in_picture_in_picture);
+    info!(
+        "[player_background_action] video={} armed={} pip={} -> {:?}",
+        is_video, background_audio_armed, in_picture_in_picture, action
+    );
+    Ok(action)
+}
+
 /// TRACES: UR-040 | DR-052 | UT-061, IT-013
 #[tauri::command]
 #[specta::specta]
@@ -931,9 +996,9 @@ pub async fn player_play_queue(
     // A ceiling chosen from the in-player picker belongs to the playback it was
     // chosen for. Starting a different item returns to the device default —
     // otherwise "2 Mbps, just for this one film" quietly governs the rest of the
-    // session, which is the defect DR-225 exists to close.
+    // session, which is the defect DR-226 exists to close.
     //
-    // TRACES: UR-074, UR-079 | DR-225
+    // TRACES: UR-074, UR-079 | DR-226
     crate::repository::online::clear_playback_quality_override();
 
     // Handle shuffle first
@@ -1116,6 +1181,13 @@ pub async fn player_stop(
     // Check if we're in remote mode
     let mode = playback_mode.0.get_mode();
 
+    // Stopping is a state transition worth seeing in a log. Native video is
+    // what made its absence matter: the webview <video> stopped implicitly when
+    // the component unmounted, so nothing ever had to call this — and "never
+    // called" and "called but the backend kept playing" look identical from
+    // outside without it.
+    info!("[player_stop] called (mode: {:?})", mode);
+
     if let crate::playback_mode::PlaybackMode::Remote { session_id } = mode {
         // Send stop command to remote session - clone client before await
         let client = {
@@ -1408,7 +1480,7 @@ pub async fn player_seek_video(
     // queued without one fall back to `needs_transcoding`, which is exact:
     // every transcode this app requests is HLS (DR-140).
     //
-    // TRACES: UR-004, UR-079 | DR-224, DR-229
+    // TRACES: UR-004, UR-079 | DR-225, DR-230
     let is_hls = match transport {
         Some(crate::repository::Transport::Hls) => true,
         Some(crate::repository::Transport::Progressive)
@@ -1623,7 +1695,7 @@ pub async fn player_switch_audio_track(
 /// belongs to Settings, and `player_set_video_settings` is the one that writes
 /// to the database.
 ///
-/// TRACES: UR-074, UR-079 | DR-162, DR-225
+/// TRACES: UR-074, UR-079 | DR-162, DR-226
 #[tauri::command]
 #[specta::specta]
 // Two of the eight arguments are Tauri `State<'_, _>` injections, not caller
@@ -1675,10 +1747,29 @@ pub async fn player_set_stream_quality(
     // builder then never gets to constrain).
     //
     // Deliberately the *override*, not the device default: see the doc above.
-    // TRACES: UR-074, UR-079 | DR-225
+    // TRACES: UR-074, UR-079 | DR-226
     crate::repository::online::set_playback_quality_override(quality);
 
-    let position = current_position.unwrap_or(0.0);
+    // Where to resume. `current_position` is the *element's* clock, which only
+    // the webview path has — on a native backend there is no `<video>` and the
+    // frontend correctly sends null, so trusting it there resumed every quality
+    // change from zero.
+    //
+    // The player is the authority on position (it is the authority on all
+    // playback state); asking the DOM for it and falling back to 0 inverted
+    // that. Fall back to what the controller reports instead.
+    //
+    // TRACES: UR-005, UR-074 | DR-226
+    // The guard is bound inside the arm's block so it is dropped before the
+    // reload below takes the same lock. This codebase has been bitten by a
+    // MutexGuard living longer than the expression that produced it.
+    let position = match current_position {
+        Some(p) => p,
+        None => {
+            let controller = player.0.lock().await;
+            controller.absolute_position()
+        }
+    };
     let selection = repository
         .get_stream_selection(
             &jellyfin_item_id,
@@ -1723,7 +1814,10 @@ pub async fn player_set_stream_quality(
         }
     }
 
-    Ok(StreamQualityResponse::Native { position })
+    Ok(StreamQualityResponse::Native {
+        selection,
+        position,
+    })
 }
 
 /// Set the active audio track on a native backend directly.
@@ -2011,7 +2105,9 @@ pub async fn player_get_capabilities() -> Result<PlaybackCapabilities, String> {
 
     Ok(PlaybackCapabilities {
         uses_webview_audio: !native_audio,
-        supports_native_video: cfg!(target_os = "android"),
+        // TRACES: UR-080 | DR-235
+        supports_native_video: cfg!(target_os = "android")
+            || crate::player::native_video::enabled(),
     })
 }
 
@@ -2020,6 +2116,11 @@ pub(super) fn get_player_status(controller: &PlayerController) -> PlayerStatus {
     let (backend, use_html5_element) = if cfg!(target_os = "android") {
         // Android uses ExoPlayer native backend
         (VideoBackend::Native, false)
+    } else if crate::player::native_video::enabled() {
+        // mpv draws the picture on this desktop; the frontend must not also
+        // load it into a <video> element or the stream decodes twice and the
+        // two fight over the audio. TRACES: UR-080 | DR-235
+        (VideoBackend::Native, false)
     } else {
         // Linux and other platforms use HTML5 video element in frontend
         (VideoBackend::Html5, true)
@@ -2376,9 +2477,9 @@ pub async fn player_play_tracks(
     // A ceiling chosen from the in-player picker belongs to the playback it was
     // chosen for. Starting a different item returns to the device default —
     // otherwise "2 Mbps, just for this one film" quietly governs the rest of the
-    // session, which is the defect DR-225 exists to close.
+    // session, which is the defect DR-226 exists to close.
     //
-    // TRACES: UR-074, UR-079 | DR-225
+    // TRACES: UR-074, UR-079 | DR-226
     crate::repository::online::clear_playback_quality_override();
 
     info!(

src-tauri/src/commands/repository.rs

@@ -618,7 +618,7 @@ pub async fn repository_get_video_stream_url(
 /// position on an HLS playlist is copied onto every segment URI and the server
 /// rejects each with `400` (DR-181). Callers resume by seeking after load.
 ///
-/// TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227 | UT-212
+/// TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228 | UT-213
 #[tauri::command]
 #[specta::specta]
 pub async fn repository_get_stream_selection(

src-tauri/src/commands/storage/mod.rs

@@ -114,7 +114,7 @@ pub fn media_local_url(
 /// to consume rather than two, and so no caller has to infer a transport from a
 /// loopback URL.
 ///
-/// TRACES: UR-071, UR-079 | DR-224
+/// TRACES: UR-071, UR-079 | DR-225
 #[tauri::command]
 #[specta::specta]
 pub fn media_local_selection(

src-tauri/src/conformance_runner.rs

@@ -0,0 +1,157 @@
+//! Runs the `MediaPlayer` conformance suite against a real engine.
+//!
+//! A separate binary on purpose: it links libmpv and nothing else, so a wrapper
+//! can be verified without building or launching the app — which is what made
+//! the previous round of playback debugging so slow. Every failure here is a
+//! wrapper bug, with no UI, no webview and no server in the way.
+//!
+//!     cargo run --features conformance --bin player-conformance -- <media-file>
+//!
+//! Audio and video are routed to null, so it is safe on a headless runner and
+//! does not claim the speakers.
+//!
+//! TRACES: UR-081 | DR-244
+
+use std::time::{Duration, Instant};
+
+use crate::player::conformance::Harness;
+use crate::player::legacy_player::LegacyPlayer;
+use crate::player::media::MediaItem;
+use crate::player::media_player::{MediaPlayer, OpenRequest, Phase};
+use crate::player::mpv_backend::MpvBackend;
+use crate::player::mpv_player::{MpvPlayer, Output};
+use crate::repository::stream_selection::StreamSelection;
+
+struct EngineHarness<P: MediaPlayer> {
+    player: P,
+    url: String,
+}
+
+impl<P: MediaPlayer> Harness for EngineHarness<P> {
+    type Player = P;
+
+    fn player(&mut self) -> &mut P {
+        &mut self.player
+    }
+
+    fn request(&self, start: Duration) -> OpenRequest {
+        let selection = StreamSelection::local_file(self.url.clone());
+        let media = MediaItem::sample("conformance", &self.url);
+        OpenRequest::new(media, selection).starting_at(start)
+    }
+
+    /// Wait for mpv to leave `Opening`.
+    ///
+    /// Polling a phase the engine publishes, not a fixed sleep: a suite whose
+    /// result depends on how fast the machine is will eventually be ignored.
+    fn settle(&mut self) {
+        let deadline = Instant::now() + Duration::from_secs(15);
+        while Instant::now() < deadline {
+            if self.player.snapshot().phase != Phase::Opening {
+                // Let the deferred seek land and one position tick arrive.
+                std::thread::sleep(Duration::from_millis(300));
+                return;
+            }
+            std::thread::sleep(Duration::from_millis(25));
+        }
+        eprintln!("  ! settle timed out - engine stayed in Opening");
+    }
+
+    /// mpv is on a null audio device here, so silence cannot be observed.
+    /// Reporting `None` skips those assertions rather than passing them
+    /// vacuously — an assertion that cannot fail is worse than an absent one.
+    fn audible(&mut self) -> Option<bool> {
+        None
+    }
+
+    /// Keyframe granularity: mpv lands on the nearest one, not on the request.
+    fn seek_tolerance(&self) -> Duration {
+        Duration::from_secs(10)
+    }
+}
+
+macro_rules! run {
+    ($failed:ident, $url:expr, $make:expr, $case:path) => {{
+        let name = stringify!($case).rsplit("::").next().unwrap();
+        print!("  {name:.<52}");
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let mut h = EngineHarness {
+                player: $make,
+                url: $url.to_string(),
+            };
+            $case(&mut h);
+            // Leave nothing playing behind for the next case.
+            let _ = h.player.close();
+        }));
+        match result {
+            Ok(()) => println!(" ok"),
+            Err(_) => {
+                println!(" FAILED");
+                $failed += 1;
+            }
+        }
+    }};
+}
+
+/// Which engine to interrogate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Engine {
+    /// The `MediaPlayer` implementation.
+    Mpv,
+    /// The old `PlayerBackend`, driven through `LegacyPlayer`.
+    ///
+    /// Present so the difference between the two designs can be *demonstrated*
+    /// on the same engine and the same media, rather than argued.
+    Legacy,
+}
+
+/// Run every conformance case against `engine`. Returns the failure count.
+pub fn run_engine(url: &str, engine: Engine) -> u32 {
+    println!("MediaPlayer conformance - {engine:?}");
+    println!("media: {url}\n");
+
+    let mut failed = 0u32;
+    use crate::player::conformance as c;
+
+    macro_rules! all_cases {
+        ($make:expr) => {
+            run!(failed, url, $make, c::opens_from_the_beginning);
+            run!(failed, url, $make, c::opens_at_a_start_position);
+            run!(failed, url, $make, c::seek_while_opening_is_honoured);
+            run!(failed, url, $make, c::seek_while_opening_overrides_start);
+            run!(failed, url, $make, c::seeks_after_open);
+            run!(failed, url, $make, c::pause_and_play_are_observable);
+            run!(failed, url, $make, c::close_is_silent_and_idempotent);
+            run!(failed, url, $make, c::close_during_open_never_plays);
+            run!(failed, url, $make, c::transport_settings_round_trip);
+        };
+    }
+
+    match engine {
+        Engine::Mpv => {
+            all_cases!(MpvPlayer::new(Output::Null).expect("could not create mpv"));
+        }
+        Engine::Legacy => {
+            all_cases!(LegacyPlayer::new(
+                MpvBackend::new(
+                    None,
+                    std::sync::Arc::new(tokio::sync::Mutex::new(None)),
+                    std::sync::Arc::new(crate::playback_reporting::throttle::EventThrottler::new()),
+                )
+                .expect("could not create the legacy backend")
+            ));
+        }
+    }
+
+    if failed == 0 {
+        println!("\nall cases passed");
+    } else {
+        println!("\n{failed} case(s) failed");
+    }
+    failed
+}
+
+/// Default entry point: the new engine.
+pub fn run(url: &str) -> u32 {
+    run_engine(url, Engine::Mpv)
+}

src-tauri/src/lib.rs

@@ -2,6 +2,10 @@
 mod android_context;
 mod auth;
 mod commands;
+/// The MediaPlayer conformance suite, exposed for the `player-conformance`
+/// binary. One entry point rather than a public player module tree.
+#[cfg(feature = "conformance")]
+pub mod conformance_runner;
 mod connectivity;
 mod credentials;
 mod domain;
@@ -122,6 +126,7 @@ use commands::{
     player_add_to_queue,
     player_add_track_by_id,
     player_add_tracks_by_ids,
+    player_background_action,
     player_cancel_autoplay_countdown,
     player_cancel_sleep_timer,
     // Jellyfin reporting commands
@@ -744,6 +749,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
         .commands(tauri_specta::collect_commands![
             // Player commands
             player_play_item,
+            player_background_action,
             player_enter_background_audio,
             player_exit_background_audio,
             player_play_queue,
@@ -1208,6 +1214,7 @@ pub fn run() {
             // listened for on the frontend via the generated bindings.
             builder.mount_events(app);
 
+
             // In-app update, desktop only.
             //
             // Registered here rather than in the builder chain above because a
@@ -1347,6 +1354,61 @@ pub fn run() {
                 playback_reporter.clone(),
                 position_throttler.clone(),
             );
+            // Attached *after* the backend exists: the mpv handle is registered
+            // during its construction, and doing this in the order the code
+            // used to read produced "no mpv handle" every time — the surface was
+            // built before there was anything to draw from.
+            // Native video surface: put a GL area under Tauri's webview so mpv
+            // can draw beneath the controls (UR-080 / DR-231).
+            //
+            // 🔴 OFF BY DEFAULT — the naive reparent crashes the app on the
+            // first click. `tauri-runtime-wry`'s undecorated-resizing handler
+            // walks a hard-coded two-hop path on every button press in the
+            // webview:
+            //
+            //     webview.parent()          // "This one should be GtkBox"
+            //            .parent()          // ...and this one the GtkWindow
+            //            .downcast::<gtk::Window>().unwrap()
+            //
+            // Wrapping the webview in a GtkOverlay makes that chain
+            // webview → GtkOverlay → GtkBox, the downcast fails, and because the
+            // panic is non-unwinding it aborts the process. The decoration check
+            // that would otherwise make this handler inert runs *after* the
+            // unwrap, so no window configuration avoids it.
+            //
+            // This is the "only place Tauri-specific behaviour could still bite"
+            // that the spike named as the untested half of G1. It bites. The
+            // surface attaches perfectly and then dies on interaction, so
+            // "attached successfully" in the log is not the gate — a click is.
+            //
+            // Kept behind an env var rather than deleted so the next attempt has
+            // something to iterate on:  JELLYTAU_NATIVE_VIDEO=1 bun run tauri dev
+            //
+            // TRACES: UR-080 | DR-231
+            #[cfg(target_os = "linux")]
+            if crate::player::native_video::enabled() {
+                use tauri::Manager;
+                log::warn!(
+                    "[INIT] JELLYTAU_NATIVE_VIDEO=1 — attaching the experimental \
+                     video surface (mpv drawn behind the webview, no reparenting)"
+                );
+                if let Some(window) = app.get_webview_window("main") {
+                    match window.default_vbox() {
+                        Ok(vbox) => {
+                            let handle = crate::player::mpv_backend::registered_handle();
+                            if crate::player::video_surface::attach(&vbox, handle) {
+                                info!("[INIT] Native video surface attached");
+                            } else {
+                                log::warn!("[INIT] Native video surface unavailable");
+                            }
+                        }
+                        Err(e) => {
+                            log::warn!("[INIT] No GTK vbox for the main window: {e}")
+                        }
+                    }
+                }
+            }
+
             let player_controller = PlayerController::new(
                 backend,
                 playback_reporter.clone(),

src-tauri/src/player/background_policy.rs

@@ -0,0 +1,155 @@
+//! What playback should do when the app stops being visible.
+//!
+//! TRACES: UR-040 | DR-224 | UT-211
+//!
+//! # The defect this exists for
+//!
+//! The per-player background-audio toggle (UR-040) was built for the WebView
+//! `<video>` path, where backgrounding the app kills the decode: the toggle
+//! decided whether to *hand off* to a native audio stream or let playback die.
+//!
+//! Native video then became the default renderer (DR-188). On that path playback
+//! runs through ExoPlayer inside a `MediaSessionService` — a foreground media
+//! service whose entire purpose is to keep playing when the app is not visible.
+//! Nothing stops it, and nothing in the codebase paused playback on background.
+//!
+//! So locking the screen kept the audio playing **whether or not the toggle was
+//! on**. The toggle governed a handoff that no longer had anything to hand off
+//! *from*: there was no gap in playback to bridge. A user who had never touched
+//! it got background audio anyway, which is the bug as reported.
+//!
+//! # Why the decision lives in Rust
+//!
+//! It depends on what the item *is* (a video keeps its picture; music has none
+//! to lose) and on a user setting — domain questions, not presentation ones, and
+//! the answer must be identical for both renderers. The frontend and the Android
+//! activity carry it out; neither decides it. Putting the rule in either would
+//! have reproduced exactly the split that caused this: two renderers, two
+//! behaviours, one toggle that only reached one of them.
+
+use crate::player::media::MediaType;
+
+/// What the player should do when the app is backgrounded.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub enum BackgroundAction {
+    /// Carry on. Music, and video the user explicitly asked to keep hearing
+    /// while it is in a picture-in-picture window.
+    KeepPlaying,
+    /// Swap the video stream for an audio-only one and keep playing.
+    HandOffToAudio,
+    /// Stop making sound. The user did not ask for background playback.
+    Pause,
+}
+
+/// Decide what backgrounding should do.
+///
+/// * `is_video` — whether the current item has a picture to lose. Music is
+///   never paused by backgrounding; that is what a music player is for.
+/// * `background_audio_armed` — the per-player toggle (UR-040).
+/// * `in_picture_in_picture` — the app is not "gone", it is in a floating
+///   window and still visible. Pausing here would break PiP (UR-041).
+///
+/// TRACES: UR-040, UR-041 | DR-224 | UT-211
+pub fn background_action(
+    is_video: bool,
+    background_audio_armed: bool,
+    in_picture_in_picture: bool,
+) -> BackgroundAction {
+    // PiP first: the window is still on screen, so this is not backgrounding in
+    // any sense the user would recognise.
+    if in_picture_in_picture {
+        return BackgroundAction::KeepPlaying;
+    }
+
+    // Music has no picture to lose; a music player that stopped when the screen
+    // locked would be broken in an obvious way.
+    if !is_video {
+        return BackgroundAction::KeepPlaying;
+    }
+
+    if background_audio_armed {
+        BackgroundAction::HandOffToAudio
+    } else {
+        BackgroundAction::Pause
+    }
+}
+
+/// Whether a media type has a picture that backgrounding would throw away.
+///
+/// TRACES: UR-040 | DR-224
+pub fn is_video_media(media_type: MediaType) -> bool {
+    matches!(media_type, MediaType::Video)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn video_without_the_toggle_pauses() {
+        // THE REPORTED BUG. Native video runs in a foreground media service that
+        // keeps playing when the app is hidden, and nothing paused it -- so
+        // locking the screen gave background audio to a user who never asked
+        // for it.
+        assert_eq!(
+            background_action(true, false, false),
+            BackgroundAction::Pause
+        );
+    }
+
+    #[test]
+    fn video_with_the_toggle_hands_off_to_audio() {
+        assert_eq!(
+            background_action(true, true, false),
+            BackgroundAction::HandOffToAudio
+        );
+    }
+
+    #[test]
+    fn music_always_keeps_playing() {
+        // Backgrounding a music player and having it stop would be absurd. The
+        // toggle is irrelevant here: there is no picture to give up.
+        assert_eq!(
+            background_action(false, false, false),
+            BackgroundAction::KeepPlaying
+        );
+        assert_eq!(
+            background_action(false, true, false),
+            BackgroundAction::KeepPlaying
+        );
+    }
+
+    #[test]
+    fn picture_in_picture_is_not_backgrounding() {
+        // The video is in a floating window and still on screen. Pausing would
+        // break PiP (UR-041), which is a separate feature reached through
+        // onUserLeaveHint rather than onStop.
+        assert_eq!(
+            background_action(true, false, true),
+            BackgroundAction::KeepPlaying
+        );
+        assert_eq!(
+            background_action(true, true, true),
+            BackgroundAction::KeepPlaying
+        );
+    }
+
+    #[test]
+    fn the_rule_does_not_depend_on_the_renderer() {
+        // There is deliberately no renderer parameter. The WebView path and the
+        // native path must answer identically -- the split between them is what
+        // produced the defect, because the toggle only ever reached one.
+        for armed in [true, false] {
+            let once = background_action(true, armed, false);
+            let again = background_action(true, armed, false);
+            assert_eq!(once, again);
+        }
+    }
+
+    #[test]
+    fn only_video_counts_as_having_a_picture() {
+        assert!(is_video_media(MediaType::Video));
+        assert!(!is_video_media(MediaType::Audio));
+    }
+}

src-tauri/src/player/conformance.rs

@@ -0,0 +1,277 @@
+//! The conformance suite every [`MediaPlayer`] must pass.
+//!
+//! One set of behaviours, run against every engine: `FakePlayer` and `MpvPlayer`
+//! in `cargo test`, `ExoPlayerPlayer` instrumented on a device, `WebviewPlayer`
+//! in vitest. A new engine is finished when it passes this.
+//!
+//! Written *before* the second engine on purpose. A suite written afterwards
+//! encodes whatever the first engine happened to do, which is how three separate
+//! playback implementations drifted apart in the first place.
+//!
+//! Each case names the defect it exists to prevent. Two of them —
+//! [`opens_at_a_start_position`] and [`seek_while_opening_is_honoured`] — fail
+//! against the pre-migration mpv path, which is what makes them a reproduction
+//! of DR-241 rather than a restatement of it.
+//!
+//! Engines differ in *when* an open completes, so the suite drives that through
+//! a [`Harness`] rather than sleeping: the fake completes on demand, mpv waits
+//! for its `FileLoaded` event, ExoPlayer for `STATE_READY`.
+//!
+//! Available to `cargo test` and, behind the `conformance` feature, to the
+//! `player-conformance` binary — so an engine that cannot run in-process
+//! (ExoPlayer on a device) is driven by exactly the same cases rather than by a
+//! second, drifting checklist.
+//!
+//! TRACES: UR-081 | DR-243 | UT-220
+
+use std::time::Duration;
+
+use super::media_player::{MediaPlayer, OpenRequest, Phase};
+
+/// How the suite drives one engine.
+pub trait Harness {
+    type Player: MediaPlayer;
+
+    fn player(&mut self) -> &mut Self::Player;
+
+    /// A request this engine can actually open, at `start`.
+    fn request(&self, start: Duration) -> OpenRequest;
+
+    /// Block until an in-flight `open` has finished (or failed).
+    ///
+    /// The fake completes on demand; a real engine waits for its own readiness
+    /// event. Never a sleep — a timing-dependent suite is worse than none.
+    fn settle(&mut self);
+
+    /// Whether the engine is producing audio. Engines that cannot answer may
+    /// return `None`, which skips the silence assertions rather than passing
+    /// them vacuously.
+    fn audible(&mut self) -> Option<bool>;
+
+    /// How far a landed position may differ from the one asked for. Keyframe
+    /// granularity makes exactness the wrong bar for a real decoder.
+    fn seek_tolerance(&self) -> Duration {
+        Duration::from_secs(5)
+    }
+}
+
+fn assert_near(actual: Duration, expected: Duration, tolerance: Duration, what: &str) {
+    let delta = actual.abs_diff(expected);
+    assert!(
+        delta <= tolerance,
+        "{what}: expected ~{expected:?}, got {actual:?} (tolerance {tolerance:?})"
+    );
+}
+
+/// Opening at zero reaches a usable state and starts near the beginning.
+pub fn opens_from_the_beginning<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    let s = h.player().snapshot();
+    assert!(
+        matches!(s.phase, Phase::Playing | Phase::Ready),
+        "after open the engine should hold media, phase was {:?}",
+        s.phase
+    );
+    assert_near(
+        s.position,
+        Duration::ZERO,
+        h.seek_tolerance(),
+        "start of item",
+    );
+}
+
+/// **DR-241.** Opening at a position starts *there*, not at zero.
+///
+/// The whole reason `OpenRequest` carries `start`. Under the previous contract a
+/// caller had to `load()` then `seek()`, and because `loadfile` is asynchronous
+/// the seek was issued against a player with nothing loaded, failed, and was
+/// discarded — so resume and transcoded skip both played from the beginning.
+pub fn opens_at_a_start_position<H: Harness>(h: &mut H) {
+    let start = Duration::from_secs(600);
+    let req = h.request(start);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    let s = h.player().snapshot();
+    assert_ne!(
+        s.position,
+        Duration::ZERO,
+        "opened at {start:?} but playback began at zero - the start position was dropped"
+    );
+    assert_near(s.position, start, h.seek_tolerance(), "start position");
+}
+
+/// **DR-241.** A seek issued while opening is honoured, not lost.
+///
+/// The engine owns this window; no caller can avoid it, because a caller cannot
+/// see when the pipeline becomes ready.
+pub fn seek_while_opening_is_honoured<H: Harness>(h: &mut H) {
+    let target = Duration::from_secs(300);
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+
+    // Deliberately before settle(): this is the race, expressed on purpose.
+    h.player().seek(target).expect("seek during open failed");
+    h.settle();
+
+    let s = h.player().snapshot();
+    assert_near(
+        s.position,
+        target,
+        h.seek_tolerance(),
+        "seek issued while opening",
+    );
+}
+
+/// A later intent wins: the seek replaces the start position it overtook.
+pub fn seek_while_opening_overrides_start<H: Harness>(h: &mut H) {
+    let start = Duration::from_secs(600);
+    let target = Duration::from_secs(120);
+    let req = h.request(start);
+    h.player().open(req).expect("open failed");
+    h.player().seek(target).expect("seek during open failed");
+    h.settle();
+
+    assert_near(
+        h.player().snapshot().position,
+        target,
+        h.seek_tolerance(),
+        "seek should override the start position it overtook",
+    );
+}
+
+/// Seeking a settled item lands where asked.
+pub fn seeks_after_open<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    let target = Duration::from_secs(420);
+    h.player().seek(target).expect("seek failed");
+
+    assert_near(
+        h.player().snapshot().position,
+        target,
+        h.seek_tolerance(),
+        "seek after open",
+    );
+}
+
+/// **DR-239.** Pause and play are reflected in the engine's own state.
+///
+/// An engine that changes nothing observable is indistinguishable from one that
+/// ignored the call — which is exactly how a handler for mpv's `pause` property
+/// sat unreachable while the UI waited for an event that never came.
+pub fn pause_and_play_are_observable<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    h.player().pause().expect("pause failed");
+    assert_eq!(
+        h.player().snapshot().phase,
+        Phase::Paused,
+        "pause must be visible in the snapshot"
+    );
+    if let Some(audible) = h.audible() {
+        assert!(!audible, "a paused engine must be silent");
+    }
+
+    h.player().play().expect("play failed");
+    assert_eq!(
+        h.player().snapshot().phase,
+        Phase::Playing,
+        "play must be visible in the snapshot"
+    );
+}
+
+/// `close()` reaches Idle, is silent, and can be called twice.
+pub fn close_is_silent_and_idempotent<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    h.player().close().expect("close failed");
+    assert_eq!(h.player().snapshot().phase, Phase::Idle);
+    if let Some(audible) = h.audible() {
+        assert!(!audible, "a closed engine must be silent");
+    }
+
+    h.player().close().expect("close must be idempotent");
+    assert_eq!(h.player().snapshot().phase, Phase::Idle);
+}
+
+/// Closing during an open must not let playback start afterwards.
+///
+/// The shape of the "audio keeps playing after leaving the player" report: an
+/// open still in flight completed after the stop, and nothing was left to tell
+/// it not to.
+pub fn close_during_open_never_plays<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.player().close().expect("close during open failed");
+    h.settle();
+
+    let s = h.player().snapshot();
+    assert!(
+        !s.phase.is_active(),
+        "an open cancelled by close must not start playing, phase was {:?}",
+        s.phase
+    );
+    if let Some(audible) = h.audible() {
+        assert!(!audible, "an engine closed during open must be silent");
+    }
+}
+
+/// Volume, mute and rate round-trip through the snapshot.
+pub fn transport_settings_round_trip<H: Harness>(h: &mut H) {
+    let req = h.request(Duration::ZERO);
+    h.player().open(req).expect("open failed");
+    h.settle();
+
+    h.player().set_volume(0.25).expect("set_volume failed");
+    h.player().set_muted(true).expect("set_muted failed");
+    h.player().set_rate(1.5).expect("set_rate failed");
+
+    let s = h.player().snapshot();
+    assert!((s.volume - 0.25).abs() < 0.01, "volume did not round-trip");
+    assert!(s.muted, "mute did not round-trip");
+    assert!((s.rate - 1.5).abs() < 0.01, "rate did not round-trip");
+}
+
+/// Run every case against one engine.
+///
+/// Each case gets a fresh harness, because a suite whose cases depend on each
+/// other's leftovers is one that hides state bugs instead of finding them.
+#[macro_export]
+macro_rules! media_player_conformance {
+    ($name:ident, $make:expr) => {
+        mod $name {
+            use super::*;
+            use $crate::player::conformance as c;
+
+            macro_rules! case {
+                ($case:ident) => {
+                    #[test]
+                    fn $case() {
+                        let mut h = $make;
+                        c::$case(&mut h);
+                    }
+                };
+            }
+
+            case!(opens_from_the_beginning);
+            case!(opens_at_a_start_position);
+            case!(seek_while_opening_is_honoured);
+            case!(seek_while_opening_overrides_start);
+            case!(seeks_after_open);
+            case!(pause_and_play_are_observable);
+            case!(close_is_silent_and_idempotent);
+            case!(close_during_open_never_plays);
+            case!(transport_settings_round_trip);
+        }
+    };
+}

src-tauri/src/player/fake_player.rs

@@ -0,0 +1,230 @@
+//! A deterministic in-memory [`MediaPlayer`], for tests.
+//!
+//! Two jobs:
+//!
+//! 1. Give the conformance suite something that is correct by construction, so a
+//!    failure there means the *suite* is wrong rather than an engine.
+//! 2. Let everything above the engine — controller, queue, autoplay, sleep
+//!    timer, session — be tested with no mpv, no device and no network. Most of
+//!    that logic is currently only reachable through a real engine, which is why
+//!    so little of it is covered.
+//!
+//! It models the one behaviour that matters most: **opening is not
+//! instantaneous**. `open()` lands in [`Phase::Opening`] and stays there until
+//! [`FakePlayer::complete_open`] is called, so a test can put a `seek` into that
+//! window on purpose. That is the window DR-241 lived in.
+//!
+//! TRACES: UR-081 | DR-243
+
+// `tick` and `fail_open` are for tests not yet written — the controller-level
+// ones DR-245 unlocks. Remove this allow once those exist.
+#![allow(dead_code)]
+
+use std::time::Duration;
+
+use super::backend::PlayerError;
+use super::media_player::{Capabilities, MediaPlayer, OpenRequest, Phase, PlaybackSnapshot};
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum FakeEvent {
+    Opened { url: String, start: Duration },
+    Played,
+    Paused,
+    Closed,
+    Sought(Duration),
+}
+
+pub struct FakePlayer {
+    snapshot: PlaybackSnapshot,
+    /// Set while `Opening`; applied when the open completes.
+    pending_start: Duration,
+    /// A seek that arrived while opening. Honoured on completion, never dropped.
+    deferred_seek: Option<Duration>,
+    autoplay: bool,
+    duration: Duration,
+    /// Every call, in order — so tests can assert what an engine was *asked* to
+    /// do, not only where it ended up.
+    pub log: Vec<FakeEvent>,
+    /// Whether audio is being produced. `close()` must clear it; the bug that
+    /// motivated all this had a "stopped" player that was still audible.
+    pub audible: bool,
+    pub capabilities: Capabilities,
+}
+
+impl Default for FakePlayer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl FakePlayer {
+    pub fn new() -> Self {
+        Self {
+            snapshot: PlaybackSnapshot::default(),
+            pending_start: Duration::ZERO,
+            deferred_seek: None,
+            autoplay: true,
+            duration: Duration::from_secs(3600),
+            log: Vec::new(),
+            audible: false,
+            capabilities: Capabilities {
+                video: true,
+                audio_settings: true,
+                subtitle_switching: true,
+                audio_track_switching: true,
+            },
+        }
+    }
+
+    /// The item this fake will report once opened.
+    pub fn with_duration(mut self, duration: Duration) -> Self {
+        self.duration = duration;
+        self
+    }
+
+    /// Finish an in-flight `open`, as a real engine's "file loaded" would.
+    ///
+    /// Applies the requested start position, then any seek that arrived while
+    /// opening — the later intent wins.
+    pub fn complete_open(&mut self) {
+        if self.snapshot.phase != Phase::Opening {
+            return;
+        }
+        self.snapshot.duration = Some(self.duration);
+        self.snapshot.seekable = true;
+        self.snapshot.position = self.deferred_seek.take().unwrap_or(self.pending_start);
+        if self.autoplay {
+            self.snapshot.phase = Phase::Playing;
+            self.audible = true;
+        } else {
+            self.snapshot.phase = Phase::Ready;
+        }
+    }
+
+    /// Advance playback, for tests that care about time passing.
+    pub fn tick(&mut self, by: Duration) {
+        if self.snapshot.phase.is_active() {
+            self.snapshot.position = (self.snapshot.position + by).min(self.duration);
+            if self.snapshot.position >= self.duration {
+                self.snapshot.phase = Phase::Ended;
+                self.audible = false;
+            }
+        }
+    }
+
+    pub fn fail_open(&mut self, why: &str) {
+        self.snapshot.phase = Phase::Failed(why.to_string());
+        self.audible = false;
+    }
+}
+
+impl MediaPlayer for FakePlayer {
+    fn open(&mut self, req: OpenRequest) -> Result<(), PlayerError> {
+        self.log.push(FakeEvent::Opened {
+            url: req.selection.url.clone(),
+            start: req.start,
+        });
+        self.snapshot = PlaybackSnapshot {
+            phase: Phase::Opening,
+            volume: self.snapshot.volume,
+            muted: self.snapshot.muted,
+            rate: self.snapshot.rate,
+            audio_track: req.audio_track,
+            subtitle_track: req.subtitle_track,
+            ..PlaybackSnapshot::default()
+        };
+        self.pending_start = req.start;
+        self.deferred_seek = None;
+        self.autoplay = req.autoplay;
+        self.audible = false;
+        Ok(())
+    }
+
+    fn play(&mut self) -> Result<(), PlayerError> {
+        self.log.push(FakeEvent::Played);
+        if self.snapshot.phase.has_media() {
+            if self.snapshot.phase == Phase::Opening {
+                self.autoplay = true;
+            } else {
+                self.snapshot.phase = Phase::Playing;
+                self.audible = true;
+            }
+        }
+        Ok(())
+    }
+
+    fn pause(&mut self) -> Result<(), PlayerError> {
+        self.log.push(FakeEvent::Paused);
+        if self.snapshot.phase == Phase::Opening {
+            self.autoplay = false;
+        } else if self.snapshot.phase.has_media() {
+            self.snapshot.phase = Phase::Paused;
+            self.audible = false;
+        }
+        Ok(())
+    }
+
+    fn close(&mut self) -> Result<(), PlayerError> {
+        self.log.push(FakeEvent::Closed);
+        self.snapshot = PlaybackSnapshot {
+            volume: self.snapshot.volume,
+            muted: self.snapshot.muted,
+            rate: self.snapshot.rate,
+            ..PlaybackSnapshot::default()
+        };
+        self.pending_start = Duration::ZERO;
+        self.deferred_seek = None;
+        // An open that was still in flight must not come back to life.
+        self.autoplay = false;
+        self.audible = false;
+        Ok(())
+    }
+
+    fn seek(&mut self, to: Duration) -> Result<(), PlayerError> {
+        self.log.push(FakeEvent::Sought(to));
+        match self.snapshot.phase {
+            // The window DR-241 lived in: hold it, do not discard it.
+            Phase::Opening => self.deferred_seek = Some(to),
+            Phase::Idle | Phase::Failed(_) => {
+                return Err(PlayerError {
+                    message: "seek with nothing open".to_string(),
+                })
+            }
+            _ => self.snapshot.position = to.min(self.duration),
+        }
+        Ok(())
+    }
+
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError> {
+        self.snapshot.volume = volume.clamp(0.0, 1.0);
+        Ok(())
+    }
+
+    fn set_muted(&mut self, muted: bool) -> Result<(), PlayerError> {
+        self.snapshot.muted = muted;
+        Ok(())
+    }
+
+    fn set_rate(&mut self, rate: f64) -> Result<(), PlayerError> {
+        self.snapshot.rate = rate;
+        Ok(())
+    }
+
+    fn select_audio_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.snapshot.audio_track = index;
+        Ok(())
+    }
+
+    fn select_subtitle_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.snapshot.subtitle_track = index;
+        Ok(())
+    }
+
+    fn snapshot(&self) -> PlaybackSnapshot {
+        self.snapshot.clone()
+    }
+
+    fn capabilities(&self) -> Capabilities {
+        self.capabilities
+    }
+}

src-tauri/src/player/fake_player_conformance.rs

@@ -0,0 +1,56 @@
+//! `FakePlayer` runs the conformance suite.
+//!
+//! It is correct by construction, so a failure here means the *suite* is wrong,
+//! not an engine. That is what makes it safe to trust the same cases when they
+//! fail against a real one.
+//!
+//! TRACES: UR-081 | DR-243 | UT-220
+
+use std::time::Duration;
+
+use super::conformance::Harness;
+use super::fake_player::FakePlayer;
+use super::media::MediaItem;
+use super::media_player::OpenRequest;
+use crate::repository::stream_selection::StreamSelection;
+
+struct FakeHarness {
+    player: FakePlayer,
+}
+
+impl FakeHarness {
+    fn new() -> Self {
+        Self {
+            player: FakePlayer::new().with_duration(Duration::from_secs(7200)),
+        }
+    }
+}
+
+impl Harness for FakeHarness {
+    type Player = FakePlayer;
+
+    fn player(&mut self) -> &mut FakePlayer {
+        &mut self.player
+    }
+
+    fn request(&self, start: Duration) -> OpenRequest {
+        let selection = StreamSelection::local_file("http://example.invalid/stream.mp4");
+        let media = MediaItem::sample("fake-item", &selection.url);
+        OpenRequest::new(media, selection).starting_at(start)
+    }
+
+    fn settle(&mut self) {
+        self.player.complete_open();
+    }
+
+    fn audible(&mut self) -> Option<bool> {
+        Some(self.player.audible)
+    }
+
+    /// Exact: the fake has no keyframes to round to, so any drift is a bug.
+    fn seek_tolerance(&self) -> Duration {
+        Duration::ZERO
+    }
+}
+
+crate::media_player_conformance!(fake, FakeHarness::new());

src-tauri/src/player/legacy_player.rs

@@ -0,0 +1,146 @@
+//! A [`MediaPlayer`] over the old [`PlayerBackend`] trait.
+//!
+//! Two purposes.
+//!
+//! **Migration.** Engines not yet ported — ExoPlayer, the webview element, the
+//! null backend — keep working while `PlayerController` moves onto the new
+//! contract (DR-245). Without this the port would have to land all four engines
+//! at once.
+//!
+//! **Evidence.** It reproduces exactly what every caller used to do: `load`,
+//! then `play`, then `seek` for a start position. Running the conformance suite
+//! against it therefore shows the old path failing the cases the new one passes,
+//! on the same engine and the same media — which is the difference between
+//! asserting that a design was wrong and demonstrating it.
+//!
+//! It is deliberately a faithful reproduction, not a fixed-up one. Making it
+//! pass would defeat the point.
+//!
+//! TRACES: UR-081 | DR-245
+
+#![allow(dead_code)] // Consumed when PlayerController is ported (DR-245).
+
+use std::time::Duration;
+
+use super::backend::{PlayerBackend, PlayerError};
+use super::media_player::{Capabilities, MediaPlayer, OpenRequest, Phase, PlaybackSnapshot};
+use super::state::PlayerState;
+
+pub struct LegacyPlayer<B: PlayerBackend> {
+    inner: B,
+    /// The old trait has no notion of "opening", so this is the best the wrapper
+    /// can do: it knows an item was handed over, not whether the engine is ready
+    /// for one. That gap is the whole problem.
+    has_item: bool,
+}
+
+impl<B: PlayerBackend> LegacyPlayer<B> {
+    pub fn new(inner: B) -> Self {
+        Self {
+            inner,
+            has_item: false,
+        }
+    }
+
+    pub fn inner_mut(&mut self) -> &mut B {
+        &mut self.inner
+    }
+}
+
+impl<B: PlayerBackend + Send> MediaPlayer for LegacyPlayer<B> {
+    /// Load, play, then seek — the sequence every caller used to write.
+    ///
+    /// The seek is issued immediately, because a caller has no way to know when
+    /// the engine becomes ready. On an engine whose load is asynchronous it
+    /// fails and is discarded, and playback begins at zero: DR-241, reproduced.
+    fn open(&mut self, req: OpenRequest) -> Result<(), PlayerError> {
+        self.inner.load(&req.media)?;
+        self.has_item = true;
+        if req.autoplay {
+            self.inner.play()?;
+        }
+        if !req.start.is_zero() {
+            // Faithfully ignoring the failure, exactly as the old callers did.
+            let _ = self.inner.seek(req.start.as_secs_f64());
+        }
+        Ok(())
+    }
+
+    fn play(&mut self) -> Result<(), PlayerError> {
+        self.inner.play()
+    }
+
+    fn pause(&mut self) -> Result<(), PlayerError> {
+        self.inner.pause()
+    }
+
+    fn close(&mut self) -> Result<(), PlayerError> {
+        self.has_item = false;
+        self.inner.stop()
+    }
+
+    fn seek(&mut self, to: Duration) -> Result<(), PlayerError> {
+        self.inner.seek(to.as_secs_f64())
+    }
+
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError> {
+        self.inner.set_volume(volume)
+    }
+
+    /// The old trait has no mute. Folding it into volume would lose the user's
+    /// level, so this reports unsupported rather than pretending.
+    fn set_muted(&mut self, _muted: bool) -> Result<(), PlayerError> {
+        Err(PlayerError {
+            message: "mute is not supported by this backend".to_string(),
+        })
+    }
+
+    fn set_rate(&mut self, _rate: f64) -> Result<(), PlayerError> {
+        Err(PlayerError {
+            message: "playback rate is not supported by this backend".to_string(),
+        })
+    }
+
+    fn select_audio_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.inner.set_audio_track(index.unwrap_or(-1))
+    }
+
+    fn select_subtitle_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.inner.set_subtitle_track(index)
+    }
+
+    fn snapshot(&self) -> PlaybackSnapshot {
+        let phase = match self.inner.state() {
+            _ if !self.has_item => Phase::Idle,
+            PlayerState::Playing { .. } => Phase::Playing,
+            PlayerState::Paused { .. } => Phase::Paused,
+            PlayerState::Idle => Phase::Idle,
+            PlayerState::Error { error, .. } => Phase::Failed(error),
+            // `Loading` is the closest the old trait comes to an opening state,
+            // but it is set once the engine has accepted the item rather than
+            // while it is still accepting it — which is precisely the window it
+            // cannot describe.
+            PlayerState::Loading { .. } | PlayerState::Seeking { .. } => Phase::Ready,
+        };
+        PlaybackSnapshot {
+            phase,
+            position: Duration::from_secs_f64(self.inner.position().max(0.0)),
+            duration: self.inner.duration().map(Duration::from_secs_f64),
+            seekable: true,
+            volume: self.inner.volume(),
+            muted: false,
+            rate: 1.0,
+            audio_track: None,
+            subtitle_track: None,
+        }
+    }
+
+    fn capabilities(&self) -> Capabilities {
+        Capabilities {
+            video: false,
+            audio_settings: true,
+            subtitle_switching: true,
+            audio_track_switching: true,
+        }
+    }
+}

src-tauri/src/player/media.rs

@@ -123,7 +123,7 @@ pub struct MediaItem {
     /// caller falls back to `needs_transcoding` — every transcode this app
     /// requests is HLS (DR-140), so that fallback is exact rather than a guess.
     ///
-    /// TRACES: UR-003, UR-004, UR-079 | DR-224, DR-229
+    /// TRACES: UR-003, UR-004, UR-079 | DR-225, DR-230
     #[serde(default)]
     pub transport: Option<crate::repository::Transport>,
 
@@ -198,6 +198,48 @@ impl MediaItem {
     }
 }
 
+impl MediaItem {
+    /// A minimal item for tests.
+    ///
+    /// The struct has twenty-odd fields, almost none of which any given test
+    /// cares about, and repeating the literal per test is how a new field ends
+    /// up added in thirty places. Set what matters on the result.
+    ///
+    /// TRACES: UR-081 | DR-243
+    #[cfg(any(test, feature = "conformance"))]
+    pub fn sample(id: &str, url: &str) -> Self {
+        Self {
+            transport: None,
+            id: id.to_string(),
+            title: id.to_string(),
+            name: None,
+            artist: None,
+            album: None,
+            album_name: None,
+            album_id: None,
+            artist_items: None,
+            artists: None,
+            primary_image_tag: None,
+            image_id: None,
+            item_type: None,
+            playlist_id: None,
+            duration: None,
+            artwork_url: None,
+            media_type: MediaType::Video,
+            source: MediaSource::DirectUrl {
+                url: url.to_string(),
+            },
+            video_codec: None,
+            needs_transcoding: false,
+            video_width: None,
+            video_height: None,
+            subtitles: vec![],
+            series_id: None,
+            server_id: None,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src-tauri/src/player/media_player.rs

@@ -0,0 +1,206 @@
+//! The `MediaPlayer` contract: one API, interchangeable engines.
+//!
+//! See docs/specs/media-player-controller.md.
+//!
+//! This replaces [`PlayerBackend`](super::backend::PlayerBackend), which
+//! abstracts a *device* — `load`, then `seek` — rather than an *intent*. That
+//! distinction is not academic; it produced four shipped defects in one day:
+//!
+//! * A start position was not expressible, so every caller sequenced
+//!   `load()` + `seek()` itself and each raced the engine's asynchronous load
+//!   independently. Resume worked through one caller and silently failed through
+//!   another (DR-241).
+//! * Whether a stream could be seeked in place was decided *above* the engines,
+//!   by a truth table in a command handler, for engines it does not own (DR-238).
+//! * Nothing in the contract obliged an engine to report its own state, so a
+//!   handler for mpv's `pause` property sat unreachable and the play/pause
+//!   control never moved (DR-239).
+//!
+//! The contract below is written so each of those is a compile-time or
+//! conformance-time failure rather than a runtime surprise.
+//!
+//! TRACES: UR-081 | DR-242
+
+// Scaffolding: nothing consumes this contract until `PlayerController` is
+// ported to it (DR-245). Kept out of `cfg(test)` deliberately — it is production
+// code being built in shippable steps, not a test fixture. Remove this allow
+// when the controller talks to `MediaPlayer`.
+#![allow(dead_code)]
+
+use std::time::Duration;
+
+use super::backend::PlayerError;
+use super::media::MediaItem;
+use crate::repository::stream_selection::StreamSelection;
+
+/// What an engine is doing right now.
+///
+/// `Opening` is the state the previous design could not express, and is the
+/// direct cause of DR-241: a seek that arrived while the engine had nothing
+/// loaded had no phase to be queued against, so it was simply discarded and
+/// playback began at zero.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Phase {
+    /// Nothing loaded. `close()` must reach this, and must be silent here.
+    Idle,
+    /// An `open` is in flight. Position is not yet meaningful; a `seek` arriving
+    /// now must be honoured once the engine reaches `Ready`, never dropped.
+    Opening,
+    /// Loaded and able to play, but not advancing.
+    Ready,
+    Playing,
+    Paused,
+    /// Reached the end of the item by itself. Distinct from `Idle`, because
+    /// autoplay cares which one happened.
+    Ended,
+    Failed(String),
+}
+
+impl Phase {
+    /// Whether the engine currently holds an item.
+    pub fn has_media(&self) -> bool {
+        !matches!(self, Phase::Idle | Phase::Failed(_))
+    }
+
+    /// Whether playback is advancing.
+    pub fn is_active(&self) -> bool {
+        matches!(self, Phase::Playing)
+    }
+}
+
+/// Everything the UI consumes, read as one coherent value.
+///
+/// Deliberately a single snapshot rather than a dozen getters: reading position
+/// and duration through separate calls is how a paused player reported
+/// `<position> / 0.0` when a file unloaded between them.
+#[derive(Debug, Clone)]
+pub struct PlaybackSnapshot {
+    pub phase: Phase,
+    pub position: Duration,
+    /// `None` while unknown — a live stream, or an item still opening.
+    pub duration: Option<Duration>,
+    /// Whether `seek` can be expected to land. False for live edges.
+    pub seekable: bool,
+    /// 0.0 – 1.0.
+    pub volume: f32,
+    pub muted: bool,
+    pub rate: f64,
+    pub audio_track: Option<i32>,
+    pub subtitle_track: Option<i32>,
+}
+
+impl Default for PlaybackSnapshot {
+    fn default() -> Self {
+        Self {
+            phase: Phase::Idle,
+            position: Duration::ZERO,
+            duration: None,
+            seekable: false,
+            volume: 1.0,
+            muted: false,
+            rate: 1.0,
+            audio_track: None,
+            subtitle_track: None,
+        }
+    }
+}
+
+/// What an engine can do, so callers adapt without naming engines.
+///
+/// If a caller ever branches on *which* engine it holds, this struct is missing
+/// something — add it here rather than sniffing. Engine identity leaking into
+/// callers is the coupling DR-238 came from.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Capabilities {
+    /// The engine renders pictures, not only sound.
+    pub video: bool,
+    /// Audio settings (EQ, normalisation, gapless) are honoured.
+    pub audio_settings: bool,
+    /// Subtitle tracks can be selected without re-opening.
+    pub subtitle_switching: bool,
+    /// Audio tracks can be selected without re-opening.
+    pub audio_track_switching: bool,
+}
+
+/// A request to present an item.
+///
+/// `start` is the reason this type exists. Carrying it here — rather than
+/// leaving callers to `seek` after `open` — is what closes the load/seek race,
+/// because the engine is the only layer that knows when its pipeline can accept
+/// a position.
+#[derive(Debug, Clone)]
+pub struct OpenRequest {
+    pub media: MediaItem,
+    pub selection: StreamSelection,
+    /// Where to begin. `Duration::ZERO` means the start of the item.
+    pub start: Duration,
+    pub audio_track: Option<i32>,
+    pub subtitle_track: Option<i32>,
+    /// Begin playing as soon as the engine is able.
+    pub autoplay: bool,
+}
+
+impl OpenRequest {
+    /// Open at the beginning, playing.
+    pub fn new(media: MediaItem, selection: StreamSelection) -> Self {
+        Self {
+            media,
+            selection,
+            start: Duration::ZERO,
+            audio_track: None,
+            subtitle_track: None,
+            autoplay: true,
+        }
+    }
+
+    pub fn starting_at(mut self, start: Duration) -> Self {
+        self.start = start;
+        self
+    }
+}
+
+/// Anything that can present media.
+///
+/// Implementations: `MpvPlayer` (Linux/Windows), `ExoPlayerPlayer` (Android),
+/// `WebviewPlayer` (HTML5 element), and `FakePlayer` for tests. Every one of
+/// them must pass [`super::conformance`].
+pub trait MediaPlayer: Send {
+    /// Present `req.selection`, beginning at `req.start`.
+    ///
+    /// One operation, deliberately. An engine that cannot start at an offset
+    /// natively absorbs that internally — by deferring until loaded, or by
+    /// re-opening — because it is the only layer that knows when it can.
+    /// Callers must never follow `open` with a `seek` to achieve a start
+    /// position; that is the bug this signature exists to prevent.
+    fn open(&mut self, req: OpenRequest) -> Result<(), PlayerError>;
+
+    fn play(&mut self) -> Result<(), PlayerError>;
+    fn pause(&mut self) -> Result<(), PlayerError>;
+
+    /// Stop and release the current item.
+    ///
+    /// Must be **idempotent** and must leave the engine **silent**. "Stopped"
+    /// and "producing no audio" were not the same thing in the previous design,
+    /// and the gap between them is audible.
+    fn close(&mut self) -> Result<(), PlayerError>;
+
+    /// Seek to an absolute position on the item's own timeline.
+    ///
+    /// Whether that is an in-place seek or a re-open of the stream is the
+    /// engine's business: hls.js seeks within a VOD playlist, mpv's HLS demuxer
+    /// cannot make a server transcode from a new offset. Callers state the
+    /// destination and nothing else.
+    fn seek(&mut self, to: Duration) -> Result<(), PlayerError>;
+
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError>;
+    fn set_muted(&mut self, muted: bool) -> Result<(), PlayerError>;
+    fn set_rate(&mut self, rate: f64) -> Result<(), PlayerError>;
+
+    fn select_audio_track(&mut self, index: Option<i32>) -> Result<(), PlayerError>;
+    fn select_subtitle_track(&mut self, index: Option<i32>) -> Result<(), PlayerError>;
+
+    /// One coherent read of the engine's state.
+    fn snapshot(&self) -> PlaybackSnapshot;
+
+    fn capabilities(&self) -> Capabilities;
+}

src-tauri/src/player/mod.rs

@@ -4,8 +4,20 @@
 //         DR-001, DR-004, DR-005, DR-009, DR-028, DR-029, DR-047
 pub mod autoplay;
 pub mod backend;
+pub mod background_policy;
+#[cfg(any(test, feature = "conformance"))]
+pub mod conformance;
 pub mod events;
+#[cfg(any(test, feature = "conformance"))]
+pub mod fake_player;
+#[cfg(test)]
+mod fake_player_conformance;
+#[cfg(any(test, feature = "conformance"))]
+pub mod legacy_player;
 pub mod media;
+pub mod media_player;
+#[cfg(target_os = "linux")]
+pub mod mpv_player;
 pub mod queue;
 pub mod seek;
 pub mod session;
@@ -23,6 +35,25 @@ pub mod android;
 #[cfg(target_os = "linux")]
 pub mod mpv_backend;
 
+/// Whether this process renders video natively — one answer, three consumers
+/// (UR-080 / DR-231, DR-235).
+pub mod native_video;
+
+/// mpv's render API into a framebuffer we own (UR-080 / DR-231, IR-033).
+///
+/// Deliberately *not* GTK-gated beyond the platform that currently builds it:
+/// everything here is the portable half, and Windows reuses it unchanged behind
+/// its own surface.
+#[cfg(target_os = "linux")]
+pub mod mpv_render;
+
+/// The native video surface mpv renders into (UR-080 / DR-231).
+///
+/// Linux-gated because the *surface* is GTK. Everything around it — the render
+/// context, its lifetime, frame pacing, the device profile — is not.
+#[cfg(target_os = "linux")]
+pub mod video_surface;
+
 // Platforms with no native audio backend (e.g. Windows) render audio-only
 // playback through a webview <audio> element, mirroring how all video renders.
 #[cfg(not(any(target_os = "linux", target_os = "android")))]

src-tauri/src/player/mpv_backend.rs

@@ -34,6 +34,19 @@ pub struct MpvBackend {
     /// through reported 0.0 / unknown exactly when end-of-file handling needed to
     /// know where playback reached. See [`ObservedTime`].
     observed: Arc<Mutex<ObservedTime>>,
+    /// A seek that arrived before MPV had a file to seek in.
+    ///
+    /// `loadfile` is asynchronous: it returns as soon as the command is queued,
+    /// so `time-pos` is not yet a resolvable property and setting it fails. A
+    /// seek issued in that window used to be dropped on the floor, and the two
+    /// callers that do exactly this are the ones a viewer notices — resume, and
+    /// a transcoded seek, both of which re-open the stream and then ask for a
+    /// position. The stream reloaded and played from zero.
+    ///
+    /// Held here and applied by the `FileLoaded` arm.
+    ///
+    /// TRACES: UR-040, UR-005 | DR-241
+    pending_seek: Arc<Mutex<Option<f64>>>,
 }
 
 struct InternalState {
@@ -89,6 +102,32 @@ fn get_stream_url(media: &MediaItem) -> String {
     }
 }
 
+/// The mpv handle of the backend this process created, for the video surface.
+///
+/// A `OnceLock` rather than a field reached through `PlayerBackend`, because the
+/// trait is cross-platform and a raw mpv pointer is not something every backend
+/// should have to pretend to have. Stored as `usize` because a raw pointer is
+/// neither `Send` nor `Sync`; the only consumer is the GTK main thread, which is
+/// also where mpv was created.
+///
+/// Written once at construction and never cleared: the backend outlives the
+/// window, so there is no window in which this could dangle while a surface is
+/// still using it.
+///
+/// TRACES: UR-080 | DR-231
+static MPV_HANDLE: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
+
+/// The registered handle, or null if no MPV backend was created (initialisation
+/// can fail, and the app falls back to a no-op backend rather than dying).
+///
+/// TRACES: UR-080 | DR-231
+pub fn registered_handle() -> *mut libmpv_sys::mpv_handle {
+    MPV_HANDLE
+        .get()
+        .map(|p| *p as *mut libmpv_sys::mpv_handle)
+        .unwrap_or(std::ptr::null_mut())
+}
+
 impl MpvBackend {
     /// Create a new MPV backend
     pub fn new(
@@ -137,9 +176,28 @@ impl MpvBackend {
                 message: format!("Failed to configure MPV audio-display: {:?}", e),
             })?;
 
-        mpv.set_property("video", "no").map_err(|e| PlayerError {
-            message: format!("Failed to configure MPV video: {:?}", e),
-        })?;
+        // Video is disabled unless this process is drawing it.
+        //
+        // `video: no` is why mpv has never decoded a frame here: Linux video has
+        // always gone through the webview, and decoding it twice would burn a
+        // core for a picture nobody sees. With native video on, mpv needs both
+        // the decoder *and* `vo=libmpv` — the render API only works through that
+        // output, and the default would try to open a window of its own.
+        //
+        // Set at construction because mpv resolves the video output when it
+        // initialises; flipping it later does not re-open one.
+        //
+        // TRACES: UR-080 | DR-231, DR-235
+        if super::native_video::enabled() {
+            mpv.set_property("vo", "libmpv").map_err(|e| PlayerError {
+                message: format!("Failed to select the libmpv video output: {:?}", e),
+            })?;
+            info!("[MpvBackend] native video enabled (vo=libmpv)");
+        } else {
+            mpv.set_property("video", "no").map_err(|e| PlayerError {
+                message: format!("Failed to configure MPV video: {:?}", e),
+            })?;
+        }
 
         // Set volume to 100% (we'll control via MPV's volume property)
         mpv.set_property("volume", 100i64)
@@ -178,13 +236,21 @@ impl MpvBackend {
         }));
 
         let backend = MpvBackend {
-            mpv: Arc::new(mpv),
+            mpv: {
+                let mpv = Arc::new(mpv);
+                // Publish the handle for the video surface (DR-231). Ignores a
+                // second call: only one MPV backend is ever constructed, and a
+                // failed re-init must not replace a live handle.
+                let _ = MPV_HANDLE.set(mpv.ctx.as_ptr() as usize);
+                mpv
+            },
             state,
             event_emitter,
             audio_settings: AudioSettings::default(),
             playback_reporter,
             position_throttler,
             last_seek_time: Arc::new(AtomicU64::new(0)),
+            pending_seek: Arc::new(Mutex::new(None)),
             observed: Arc::new(Mutex::new(ObservedTime::default())),
         };
 
@@ -202,6 +268,7 @@ impl MpvBackend {
         let state = self.state.clone();
         let reporter = self.playback_reporter.clone();
         let throttler = self.position_throttler.clone();
+        let pending_seek_for_events = self.pending_seek.clone();
 
         std::thread::spawn(move || {
             info!("[MpvBackend] Event loop started");
@@ -211,6 +278,30 @@ impl MpvBackend {
                 error!("[MpvBackend] Failed to disable deprecated events: {:?}", e);
             });
 
+            // libmpv delivers PropertyChange only for properties registered
+            // here. Every name matched in the loop below needs a line in this
+            // block or its handler is unreachable — an omission that reads as
+            // working code, because the handler is sitting right there.
+            // UT-218 holds the two lists together.
+            //
+            // `pause` drives the play/pause control: the UI consumes
+            // StateChanged rather than tracking playback itself, per the
+            // one-directional state rule. Unobserved, the event never came and
+            // the button never moved. Invisible until native video shipped,
+            // because the webview <video> element's own DOM events drove that
+            // control on Linux.
+            //
+            // TRACES: UR-005 | DR-239
+            ev_ctx
+                .observe_property("pause", libmpv::Format::Flag, 0)
+                .unwrap_or_else(|e| {
+                    error!(
+                        "[MpvBackend] Failed to observe 'pause': {:?} — the play/pause \
+                         control will not follow the player",
+                        e
+                    );
+                });
+
             loop {
                 match ev_ctx.wait_event(1.0) {
                     Some(Ok(event)) => match event {
@@ -220,6 +311,43 @@ impl MpvBackend {
                         libmpv::events::Event::FileLoaded => {
                             info!("[MpvBackend] File loaded");
 
+                            // Apply a seek that arrived while there was nothing
+                            // to seek in. TRACES: UR-040, UR-005 | DR-241
+                            {
+                                let target = pending_seek_for_events.lock_safe().take();
+                                if let Some(position) = target {
+                                    match mpv.set_property("time-pos", position) {
+                                        Ok(()) => info!(
+                                            "[MpvBackend] applied deferred seek to {position}"
+                                        ),
+                                        Err(e) => warn!(
+                                            "[MpvBackend] deferred seek to {position} failed: {:?}",
+                                            e
+                                        ),
+                                    }
+                                }
+                            }
+
+                            // Geometry, so "the picture does not fill the screen"
+                            // can be attributed rather than guessed at. `width`/
+                            // `height` are the decoded frame; `dwidth`/`dheight`
+                            // are what mpv will *display* after aspect
+                            // correction. A file that carries its letterbox
+                            // baked into the picture reports a 16:9 dwidth and
+                            // is then pillarboxed on a wider panel — which looks
+                            // identical to a rendering bug from outside.
+                            {
+                                let n = |k: &str| mpv.get_property::<i64>(k).unwrap_or(-1);
+                                info!(
+                                    "[MpvBackend] video geometry: {}x{} decoded, {}x{} display, aspect {:?}",
+                                    n("width"),
+                                    n("height"),
+                                    n("dwidth"),
+                                    n("dheight"),
+                                    mpv.get_property::<f64>("video-params/aspect").ok(),
+                                );
+                            }
+
                             // Get duration
                             if let Ok(duration) = mpv.get_property::<f64>("duration") {
                                 if let Some(emitter) = &event_emitter {
@@ -522,11 +650,24 @@ impl PlayerBackend for MpvBackend {
             .as_millis() as u64;
         self.last_seek_time.store(now, Ordering::Relaxed);
 
-        self.mpv
-            .set_property("time-pos", position)
-            .map_err(|e| PlayerError {
-                message: format!("Failed to seek: {:?}", e),
-            })?;
+        // `time-pos` only resolves while a file is loaded. `loadfile` is
+        // asynchronous, so a seek issued straight after a reload — resume, or a
+        // transcoded seek — lands in a window where this fails, and dropping it
+        // there is what makes the stream play from zero instead of the position
+        // that was asked for. Hold it and let `FileLoaded` apply it.
+        // TRACES: UR-040, UR-005 | DR-241
+        if let Err(e) = self.mpv.set_property("time-pos", position) {
+            debug!(
+                "[MpvBackend] seek to {position} deferred until the file loads ({:?})",
+                e
+            );
+            *self.pending_seek.lock_safe() = Some(position);
+            self.observed.lock_safe().record_position(position);
+            return Ok(());
+        }
+
+        // A seek that lands clears any earlier deferred one: the newer intent wins.
+        *self.pending_seek.lock_safe() = None;
 
         // The poll thread suppresses updates for 150ms after a seek, so without
         // this a file ending inside that window would report the pre-seek time.

src-tauri/src/player/mpv_backend_test.rs

@@ -13,6 +13,52 @@ mod tests {
     use std::sync::{Arc, Mutex};
     use tokio::sync::Mutex as TokioMutex;
 
+    /// Every property the event loop *handles* must also be *observed*.
+    ///
+    /// libmpv only delivers `PropertyChange` for properties registered with
+    /// `mpv_observe_property`. A `match` arm for an unobserved property is
+    /// unreachable code that looks exactly like working code: the handler is
+    /// right there, so the behaviour reads as implemented.
+    ///
+    /// This cost a real bug. `pause` was handled and never observed, so
+    /// `StateChanged` was never emitted on pause or resume. It stayed invisible
+    /// while Linux video played in the webview, because the `<video>` element's
+    /// own DOM events drove the play/pause control; turning native video on made
+    /// the UI depend on the event that never came, and the button stopped
+    /// responding.
+    ///
+    /// Asserted against the source because there is no way to observe the
+    /// registration at runtime without a live mpv instance.
+    ///
+    /// TRACES: UR-005 | DR-239 | UT-218
+    #[test]
+    fn test_every_handled_property_is_observed() {
+        let src = include_str!("mpv_backend.rs");
+
+        let handled: Vec<&str> = src
+            .match_indices("PropertyChange { name: \"")
+            .filter_map(|(i, m)| {
+                let rest = &src[i + m.len()..];
+                rest.find('"').map(|end| &rest[..end])
+            })
+            .collect();
+
+        assert!(
+            !handled.is_empty(),
+            "no PropertyChange arms found - has the event loop been restructured?"
+        );
+
+        for name in handled {
+            let observed = format!("observe_property(\"{name}\"");
+            assert!(
+                src.contains(&observed),
+                "mpv_backend.rs handles PropertyChange for {name:?} but never calls \
+                 observe_property({name:?}, ..). libmpv will never deliver that event, \
+                 so the handler is dead code."
+            );
+        }
+    }
+
     /// Test that simulates the position update thread spawning async tasks
     /// without a Tokio runtime (the bug we just fixed)
     #[test]

src-tauri/src/player/mpv_player.rs

@@ -0,0 +1,378 @@
+//! [`MediaPlayer`] over libmpv.
+//!
+//! The point of difference from `MpvBackend` is [`MpvPlayer::open`]: the start
+//! position is applied **at load time**, via mpv's own `start` option, instead
+//! of being seeked to afterwards. `loadfile` is asynchronous, so a seek issued
+//! after it targets a player that has nothing loaded, fails, and — under the old
+//! contract — was discarded. That is DR-241, and it is why resume and transcoded
+//! skip both played from zero.
+//!
+//! A seek arriving during [`Phase::Opening`] is held and applied when the file
+//! loads, so no caller has to know where that window begins or ends.
+//!
+//! TRACES: UR-081, UR-040, UR-005 | DR-244
+
+#![allow(dead_code)] // Wired to PlayerController in DR-245.
+
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use libmpv::Mpv;
+use log::{debug, info, warn};
+
+use super::backend::PlayerError;
+use super::media_player::{Capabilities, MediaPlayer, OpenRequest, Phase, PlaybackSnapshot};
+use crate::utils::lock::MutexSafe;
+
+/// State the event thread writes and the caller reads.
+#[derive(Debug)]
+struct Shared {
+    phase: Phase,
+    position: Duration,
+    duration: Option<Duration>,
+    seekable: bool,
+    /// A seek that arrived while opening. Applied on `FileLoaded`.
+    deferred_seek: Option<Duration>,
+    /// Cleared by `close()`, so an open still in flight cannot come back to life
+    /// and start playing after the caller has stopped it.
+    open_generation: u64,
+}
+
+impl Default for Shared {
+    fn default() -> Self {
+        Self {
+            phase: Phase::Idle,
+            position: Duration::ZERO,
+            duration: None,
+            seekable: false,
+            deferred_seek: None,
+            open_generation: 0,
+        }
+    }
+}
+
+pub struct MpvPlayer {
+    mpv: Arc<Mpv>,
+    shared: Arc<Mutex<Shared>>,
+    volume: f32,
+    muted: bool,
+    rate: f64,
+    audio_track: Option<i32>,
+    subtitle_track: Option<i32>,
+}
+
+/// How the engine should talk to the machine.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Output {
+    /// Real audio and video. What the app uses.
+    Real,
+    /// No audio device, no window. What conformance uses, so the suite can run
+    /// on a headless runner without claiming the user's speakers.
+    Null,
+}
+
+impl MpvPlayer {
+    pub fn new(output: Output) -> Result<Self, PlayerError> {
+        // mpv refuses to start under a non-C LC_NUMERIC, and anything that has
+        // initialised GTK before us will have set one.
+        unsafe {
+            let c = std::ffi::CString::new("C").unwrap();
+            libc::setlocale(libc::LC_NUMERIC, c.as_ptr());
+        }
+
+        let mpv = Mpv::new().map_err(|e| PlayerError {
+            message: format!("mpv_create failed: {e:?}"),
+        })?;
+
+        let set = |k: &str, v: &str| {
+            if let Err(e) = mpv.set_property(k, v) {
+                warn!("[MpvPlayer] could not set {k}={v}: {e:?}");
+            }
+        };
+        match output {
+            Output::Real => {
+                set("vo", "libmpv");
+            }
+            Output::Null => {
+                set("ao", "null");
+                set("vo", "null");
+            }
+        }
+        set("msg-level", "all=warn");
+        // Survive a blip rather than ending the item on it.
+        set(
+            "stream-lavf-o",
+            "reconnect=1,reconnect_streamed=1,reconnect_on_network_error=1,reconnect_delay_max=5",
+        );
+
+        let player = Self {
+            mpv: Arc::new(mpv),
+            shared: Arc::new(Mutex::new(Shared::default())),
+            volume: 1.0,
+            muted: false,
+            rate: 1.0,
+            audio_track: None,
+            subtitle_track: None,
+        };
+        player.spawn_events();
+        Ok(player)
+    }
+
+    fn spawn_events(&self) {
+        let mpv = self.mpv.clone();
+        let shared = self.shared.clone();
+
+        std::thread::spawn(move || {
+            let mut ev = mpv.create_event_context();
+            let _ = ev.disable_deprecated_events();
+            // Every property matched below must be observed, or libmpv never
+            // delivers it and the handler is unreachable (DR-239).
+            for prop in ["pause", "eof-reached"] {
+                if let Err(e) = ev.observe_property(prop, libmpv::Format::Flag, 0) {
+                    warn!("[MpvPlayer] could not observe {prop}: {e:?}");
+                }
+            }
+
+            loop {
+                match ev.wait_event(0.25) {
+                    Some(Ok(libmpv::events::Event::FileLoaded)) => {
+                        let deferred = {
+                            let mut s = shared.lock_safe();
+                            // Closed while opening: do not start.
+                            if s.phase == Phase::Idle {
+                                continue;
+                            }
+                            s.duration = mpv
+                                .get_property::<f64>("duration")
+                                .ok()
+                                .map(Duration::from_secs_f64);
+                            s.seekable = mpv.get_property::<bool>("seekable").unwrap_or(true);
+                            s.phase = Phase::Playing;
+                            s.deferred_seek.take()
+                        };
+                        if let Some(to) = deferred {
+                            debug!("[MpvPlayer] applying deferred seek to {to:?}");
+                            if let Err(e) = mpv.set_property("time-pos", to.as_secs_f64()) {
+                                warn!("[MpvPlayer] deferred seek failed: {e:?}");
+                            }
+                        }
+                    }
+                    Some(Ok(libmpv::events::Event::PropertyChange { name: "pause", .. })) => {
+                        if let Ok(paused) = mpv.get_property::<bool>("pause") {
+                            let mut s = shared.lock_safe();
+                            if s.phase.has_media() {
+                                s.phase = if paused {
+                                    Phase::Paused
+                                } else {
+                                    Phase::Playing
+                                };
+                            }
+                        }
+                    }
+                    Some(Ok(libmpv::events::Event::EndFile(reason))) => {
+                        let mut s = shared.lock_safe();
+                        // 0 = EOF. Anything else is a stop, a quit or an error,
+                        // and must not read as "the item finished".
+                        s.phase = if reason == 0 {
+                            Phase::Ended
+                        } else {
+                            Phase::Idle
+                        };
+                    }
+                    Some(Ok(libmpv::events::Event::Shutdown)) => break,
+                    _ => {}
+                }
+
+                if let Ok(pos) = mpv.get_property::<f64>("time-pos") {
+                    let mut s = shared.lock_safe();
+                    if s.phase.has_media() && s.deferred_seek.is_none() {
+                        s.position = Duration::from_secs_f64(pos.max(0.0));
+                    }
+                }
+            }
+        });
+    }
+}
+
+impl MediaPlayer for MpvPlayer {
+    fn open(&mut self, req: OpenRequest) -> Result<(), PlayerError> {
+        {
+            let mut s = self.shared.lock_safe();
+            *s = Shared {
+                phase: Phase::Opening,
+                open_generation: s.open_generation + 1,
+                ..Shared::default()
+            };
+            // Report the requested position immediately, so a caller reading
+            // back during the open sees where it asked to be rather than zero.
+            s.position = req.start;
+        }
+
+        // The whole point. `start` is applied by mpv as it opens the file, so
+        // there is no window in which the position can be asked for and lost.
+        let start = if req.start.is_zero() {
+            "none".to_string()
+        } else {
+            format!("{:.3}", req.start.as_secs_f64())
+        };
+        self.mpv
+            .set_property("start", start.as_str())
+            .map_err(|e| PlayerError {
+                message: format!("could not set start position: {e:?}"),
+            })?;
+        self.mpv
+            .set_property("pause", !req.autoplay)
+            .map_err(|e| PlayerError {
+                message: format!("could not set pause: {e:?}"),
+            })?;
+
+        info!("[MpvPlayer] open {} at {:?}", req.selection.url, req.start);
+        self.mpv
+            .command("loadfile", &[&req.selection.url, "replace"])
+            .map_err(|e| PlayerError {
+                message: format!("loadfile failed: {e:?}"),
+            })?;
+        Ok(())
+    }
+
+    fn play(&mut self) -> Result<(), PlayerError> {
+        self.mpv
+            .set_property("pause", false)
+            .map_err(|e| PlayerError {
+                message: format!("play failed: {e:?}"),
+            })?;
+        let mut s = self.shared.lock_safe();
+        if s.phase.has_media() && s.phase != Phase::Opening {
+            s.phase = Phase::Playing;
+        }
+        Ok(())
+    }
+
+    fn pause(&mut self) -> Result<(), PlayerError> {
+        self.mpv
+            .set_property("pause", true)
+            .map_err(|e| PlayerError {
+                message: format!("pause failed: {e:?}"),
+            })?;
+        let mut s = self.shared.lock_safe();
+        if s.phase.has_media() && s.phase != Phase::Opening {
+            s.phase = Phase::Paused;
+        }
+        Ok(())
+    }
+
+    fn close(&mut self) -> Result<(), PlayerError> {
+        // State first: an open still in flight checks this on FileLoaded and
+        // must not proceed to play after the caller has stopped it.
+        {
+            let mut s = self.shared.lock_safe();
+            *s = Shared {
+                open_generation: s.open_generation,
+                ..Shared::default()
+            };
+        }
+        // Idempotent: stopping an already-stopped mpv is not an error worth
+        // propagating, and callers legitimately close twice on teardown.
+        if let Err(e) = self.mpv.command("stop", &[]) {
+            debug!("[MpvPlayer] stop on an idle player: {e:?}");
+        }
+        Ok(())
+    }
+
+    fn seek(&mut self, to: Duration) -> Result<(), PlayerError> {
+        {
+            let mut s = self.shared.lock_safe();
+            match s.phase {
+                // Held, not dropped. The caller cannot see this window.
+                Phase::Opening => {
+                    s.deferred_seek = Some(to);
+                    s.position = to;
+                    return Ok(());
+                }
+                Phase::Idle | Phase::Failed(_) => {
+                    return Err(PlayerError {
+                        message: "seek with nothing open".to_string(),
+                    })
+                }
+                _ => s.position = to,
+            }
+        }
+        self.mpv
+            .set_property("time-pos", to.as_secs_f64())
+            .map_err(|e| PlayerError {
+                message: format!("seek failed: {e:?}"),
+            })
+    }
+
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError> {
+        let clamped = volume.clamp(0.0, 1.0);
+        self.volume = clamped;
+        self.mpv
+            .set_property("volume", (clamped as f64) * 100.0)
+            .map_err(|e| PlayerError {
+                message: format!("set_volume failed: {e:?}"),
+            })
+    }
+
+    fn set_muted(&mut self, muted: bool) -> Result<(), PlayerError> {
+        self.muted = muted;
+        self.mpv
+            .set_property("mute", muted)
+            .map_err(|e| PlayerError {
+                message: format!("set_muted failed: {e:?}"),
+            })
+    }
+
+    fn set_rate(&mut self, rate: f64) -> Result<(), PlayerError> {
+        self.rate = rate;
+        self.mpv
+            .set_property("speed", rate)
+            .map_err(|e| PlayerError {
+                message: format!("set_rate failed: {e:?}"),
+            })
+    }
+
+    fn select_audio_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.audio_track = index;
+        let value = index.map(|i| i.to_string()).unwrap_or_else(|| "no".into());
+        self.mpv
+            .set_property("aid", value.as_str())
+            .map_err(|e| PlayerError {
+                message: format!("select_audio_track failed: {e:?}"),
+            })
+    }
+
+    fn select_subtitle_track(&mut self, index: Option<i32>) -> Result<(), PlayerError> {
+        self.subtitle_track = index;
+        let value = index.map(|i| i.to_string()).unwrap_or_else(|| "no".into());
+        self.mpv
+            .set_property("sid", value.as_str())
+            .map_err(|e| PlayerError {
+                message: format!("select_subtitle_track failed: {e:?}"),
+            })
+    }
+
+    fn snapshot(&self) -> PlaybackSnapshot {
+        let s = self.shared.lock_safe();
+        PlaybackSnapshot {
+            phase: s.phase.clone(),
+            position: s.position,
+            duration: s.duration,
+            seekable: s.seekable,
+            volume: self.volume,
+            muted: self.muted,
+            rate: self.rate,
+            audio_track: self.audio_track,
+            subtitle_track: self.subtitle_track,
+        }
+    }
+
+    fn capabilities(&self) -> Capabilities {
+        Capabilities {
+            video: true,
+            audio_settings: true,
+            subtitle_switching: true,
+            audio_track_switching: true,
+        }
+    }
+}

src-tauri/src/player/mpv_render.rs

@@ -0,0 +1,405 @@
+//! mpv's render API, driven into an OpenGL framebuffer we own.
+//!
+//! This is the half of native video that is not GTK: create a render context
+//! over the mpv handle the audio backend already drives, render a frame into a
+//! texture, and hand that texture id back for the toolkit to composite.
+//!
+//! Kept apart from `video_surface` deliberately — everything here is portable
+//! across the platforms this app targets, while the surface that consumes it is
+//! not. Windows reuses this file unchanged (DR-237).
+//!
+//! TRACES: UR-080 | DR-231, DR-232, IR-033
+
+use std::ffi::{c_void, CStr, CString};
+use std::os::raw::{c_char, c_int};
+use std::ptr;
+
+use log::{error, info, warn};
+
+/// GL entry points, resolved once.
+///
+/// Only the handful needed to own a framebuffer; mpv resolves everything else
+/// it needs through [`get_proc_address`].
+struct Gl {
+    gen_framebuffers: unsafe extern "C" fn(c_int, *mut u32),
+    delete_framebuffers: unsafe extern "C" fn(c_int, *const u32),
+    bind_framebuffer: unsafe extern "C" fn(u32, u32),
+    framebuffer_texture_2d: unsafe extern "C" fn(u32, u32, u32, u32, c_int),
+    gen_textures: unsafe extern "C" fn(c_int, *mut u32),
+    delete_textures: unsafe extern "C" fn(c_int, *const u32),
+    bind_texture: unsafe extern "C" fn(u32, u32),
+    tex_image_2d:
+        unsafe extern "C" fn(u32, c_int, c_int, c_int, c_int, c_int, u32, u32, *const c_void),
+    tex_parameteri: unsafe extern "C" fn(u32, u32, c_int),
+    check_framebuffer_status: unsafe extern "C" fn(u32) -> u32,
+}
+
+const GL_TEXTURE_2D: u32 = 0x0DE1;
+const GL_FRAMEBUFFER: u32 = 0x8D40;
+const GL_COLOR_ATTACHMENT0: u32 = 0x8CE0;
+const GL_RGBA: u32 = 0x1908;
+const GL_RGBA8: c_int = 0x8058;
+const GL_UNSIGNED_BYTE: u32 = 0x1401;
+const GL_LINEAR: c_int = 0x2601;
+const GL_TEXTURE_MIN_FILTER: u32 = 0x2801;
+const GL_TEXTURE_MAG_FILTER: u32 = 0x2800;
+const GL_FRAMEBUFFER_COMPLETE: u32 = 0x8CD5;
+
+/// Resolve a GL symbol the way libepoxy actually exports it.
+///
+/// **This is the trap that cost the spike a debugging cycle.** libepoxy does not
+/// export `glFoo` as a function. It exports `epoxy_glFoo` as a *data* symbol
+/// holding a lazily-resolving function pointer. So the address `dlsym` returns
+/// is the address *of the pointer*, not of any code: returning it makes mpv jump
+/// into non-executable data and take SIGSEGV/SEGV_ACCERR on the very first GL
+/// call. The value must be read *out of* that location.
+///
+/// The `epoxy` crate does this correctly and is unusable here — its
+/// `gl_generator` dependency pulls a yanked `xml-rs`.
+///
+/// TRACES: UR-080 | IR-033
+unsafe fn resolve(name: &str) -> *mut c_void {
+    let epoxy_name = match CString::new(format!("epoxy_{name}")) {
+        Ok(n) => n,
+        Err(_) => return ptr::null_mut(),
+    };
+    let slot = libc::dlsym(libc::RTLD_DEFAULT, epoxy_name.as_ptr());
+    if !slot.is_null() {
+        // The symbol holds the function pointer; return what is stored there.
+        return *(slot as *mut *mut c_void);
+    }
+
+    // Fall back to a plain symbol, for a GL stack that is not behind epoxy.
+    match CString::new(name) {
+        Ok(n) => libc::dlsym(libc::RTLD_DEFAULT, n.as_ptr()),
+        Err(_) => ptr::null_mut(),
+    }
+}
+
+/// What mpv calls to find GL entry points. Same rule as [`resolve`].
+unsafe extern "C" fn get_proc_address(_ctx: *mut c_void, name: *const c_char) -> *mut c_void {
+    if name.is_null() {
+        return ptr::null_mut();
+    }
+    match CStr::from_ptr(name).to_str() {
+        Ok(n) => resolve(n),
+        Err(_) => ptr::null_mut(),
+    }
+}
+
+macro_rules! load {
+    ($name:literal) => {{
+        let p = resolve($name);
+        if p.is_null() {
+            error!("[MpvRender] GL symbol not found: {}", $name);
+            return None;
+        }
+        std::mem::transmute(p)
+    }};
+}
+
+impl Gl {
+    /// Resolve every entry point, or none — a partially-loaded table would fail
+    /// later at a call site with no context.
+    ///
+    /// The transmutes are unannotated on purpose: each target type is declared
+    /// once on the struct field above, and repeating it at the call site would
+    /// be two places to get the same signature wrong.
+    #[allow(clippy::missing_transmute_annotations)]
+    unsafe fn load() -> Option<Self> {
+        Some(Gl {
+            gen_framebuffers: load!("glGenFramebuffers"),
+            delete_framebuffers: load!("glDeleteFramebuffers"),
+            bind_framebuffer: load!("glBindFramebuffer"),
+            framebuffer_texture_2d: load!("glFramebufferTexture2D"),
+            gen_textures: load!("glGenTextures"),
+            delete_textures: load!("glDeleteTextures"),
+            bind_texture: load!("glBindTexture"),
+            tex_image_2d: load!("glTexImage2D"),
+            tex_parameteri: load!("glTexParameteri"),
+            check_framebuffer_status: load!("glCheckFramebufferStatus"),
+        })
+    }
+}
+
+/// A colour-renderable framebuffer mpv draws into, sized to the widget.
+struct Target {
+    fbo: u32,
+    texture: u32,
+    width: i32,
+    height: i32,
+}
+
+/// mpv's render context plus the framebuffer it draws into.
+///
+/// # Lifetime (DR-232)
+///
+/// The render context must not outlive the GL context it was created against.
+/// `Drop` unregisters mpv's update callback *before* freeing the context, so a
+/// callback cannot land on a freed pointer, and frees the GL objects while the
+/// caller still has the context current. The caller is responsible for making
+/// the GL context current around both creation and drop — see `video_surface`.
+///
+/// This is DR-184 on Android restated: a surface outliving its player. The spike
+/// had no defence at all and saw one unexplained SIGSEGV in a decoder thread.
+pub struct MpvRenderContext {
+    ctx: *mut libmpv_sys::mpv_render_context,
+    gl: Gl,
+    target: Option<Target>,
+}
+
+// The render context is driven only from the GTK main thread; the update
+// callback merely schedules a redraw and touches nothing here.
+unsafe impl Send for MpvRenderContext {}
+
+impl MpvRenderContext {
+    /// Create a render context over an existing mpv handle.
+    ///
+    /// The GL context must already be current on this thread.
+    ///
+    /// TRACES: UR-080 | DR-231, IR-033
+    pub unsafe fn new(mpv: *mut libmpv_sys::mpv_handle) -> Option<Self> {
+        let gl = Gl::load()?;
+
+        let mut init = libmpv_sys::mpv_opengl_init_params {
+            get_proc_address: Some(get_proc_address),
+            get_proc_address_ctx: ptr::null_mut(),
+        };
+        let mut api_type = CString::new("opengl").ok()?;
+        // Advanced control is deliberately OFF.
+        //
+        // With it on, mpv expects the client to drive rendering to a stricter
+        // contract than a GTK draw handler can promise — it will wait on us, and
+        // if we in turn wait on its update callback, neither side proceeds. That
+        // deadlock presents as a file that loads, renders one frame, and then
+        // sits there with no audio and a spinner.
+        //
+        // Off, mpv is tolerant of being rendered on the toolkit's schedule,
+        // which is what the frame clock gives us.
+        let mut advanced: c_int = 0;
+
+        let mut params = [
+            libmpv_sys::mpv_render_param {
+                type_: libmpv_sys::mpv_render_param_type_MPV_RENDER_PARAM_API_TYPE,
+                data: api_type.as_ptr() as *mut c_void,
+            },
+            libmpv_sys::mpv_render_param {
+                type_: libmpv_sys::mpv_render_param_type_MPV_RENDER_PARAM_OPENGL_INIT_PARAMS,
+                data: &mut init as *mut _ as *mut c_void,
+            },
+            libmpv_sys::mpv_render_param {
+                type_: libmpv_sys::mpv_render_param_type_MPV_RENDER_PARAM_ADVANCED_CONTROL,
+                data: &mut advanced as *mut _ as *mut c_void,
+            },
+            libmpv_sys::mpv_render_param {
+                type_: 0,
+                data: ptr::null_mut(),
+            },
+        ];
+
+        let mut ctx: *mut libmpv_sys::mpv_render_context = ptr::null_mut();
+        let rc = libmpv_sys::mpv_render_context_create(&mut ctx, mpv, params.as_mut_ptr());
+        // Keep the CString alive until after the call.
+        let _ = &mut api_type;
+
+        if rc < 0 || ctx.is_null() {
+            error!("[MpvRender] mpv_render_context_create failed: {rc}");
+            return None;
+        }
+
+        info!("[MpvRender] render context created");
+        Some(MpvRenderContext {
+            ctx,
+            gl,
+            target: None,
+        })
+    }
+
+    /// Ask to be told when a new frame is ready.
+    ///
+    /// Paired with [`report_swap`](Self::report_swap): without both, mpv has
+    /// nothing to time against. The symptom is misleading — playback looks fine
+    /// in a window and judders at fullscreen, which reads as a compositing or
+    /// GPU limit and is neither (DR-233).
+    ///
+    /// TRACES: UR-080 | DR-233
+    pub unsafe fn set_update_callback(
+        &mut self,
+        callback: libmpv_sys::mpv_render_update_fn,
+        ctx: *mut c_void,
+    ) {
+        libmpv_sys::mpv_render_context_set_update_callback(self.ctx, callback, ctx);
+    }
+
+    /// Whether mpv has a new frame waiting.
+    ///
+    /// Asked of mpv directly rather than inferred from its update callback, and
+    /// that distinction is the whole of frame pacing here:
+    ///
+    ///   - Waiting only on the callback deadlocks — mpv will not progress until
+    ///     the client renders, so if the client will not render until mpv says
+    ///     so, neither moves. That presents as a file that loads, shows one
+    ///     frame, and then sits silent.
+    ///   - Rendering on *every* frame-clock tick regardless is the opposite
+    ///     error: `report_swap` then claims a presentation far more often than
+    ///     real frames exist, mpv has nothing coherent to time against, and
+    ///     playback judders badly.
+    ///
+    /// Polling is neither. It runs on the main thread, costs a single atomic
+    /// read inside mpv, and answers the only question that matters.
+    ///
+    /// TRACES: UR-080 | DR-233
+    pub unsafe fn has_frame(&self) -> bool {
+        let flags = libmpv_sys::mpv_render_context_update(self.ctx);
+        (flags & libmpv_sys::mpv_render_update_flag_MPV_RENDER_UPDATE_FRAME as u64) != 0
+    }
+
+    /// Render the current frame at `width` x `height`, returning the texture id
+    /// holding it. The GL context must be current.
+    ///
+    /// TRACES: UR-080 | DR-231
+    pub unsafe fn render(&mut self, width: i32, height: i32) -> Option<u32> {
+        if width <= 0 || height <= 0 {
+            return None;
+        }
+        self.ensure_target(width, height)?;
+        let target = self.target.as_ref()?;
+
+        let mut fbo = libmpv_sys::mpv_opengl_fbo {
+            fbo: target.fbo as c_int,
+            w: width as c_int,
+            h: height as c_int,
+            internal_format: 0,
+        };
+        // GTK's cairo surface has its origin at the top left; mpv defaults to
+        // OpenGL's bottom-left. Without this the picture is drawn upside down —
+        // which looks like a broken decode rather than a coordinate convention.
+        let mut flip: c_int = 1;
+
+        let mut params = [
+            libmpv_sys::mpv_render_param {
+                type_: libmpv_sys::mpv_render_param_type_MPV_RENDER_PARAM_OPENGL_FBO,
+                data: &mut fbo as *mut _ as *mut c_void,
+            },
+            libmpv_sys::mpv_render_param {
+                type_: libmpv_sys::mpv_render_param_type_MPV_RENDER_PARAM_FLIP_Y,
+                data: &mut flip as *mut _ as *mut c_void,
+            },
+            libmpv_sys::mpv_render_param {
+                type_: 0,
+                data: ptr::null_mut(),
+            },
+        ];
+
+        let rc = libmpv_sys::mpv_render_context_render(self.ctx, params.as_mut_ptr());
+        if rc < 0 {
+            warn!("[MpvRender] render failed: {rc}");
+            return None;
+        }
+        Some(target.texture)
+    }
+
+    /// Tell mpv the frame reached the screen. See [`set_update_callback`].
+    ///
+    /// TRACES: UR-080 | DR-233
+    pub unsafe fn report_swap(&self) {
+        libmpv_sys::mpv_render_context_report_swap(self.ctx);
+    }
+
+    /// Create or resize the framebuffer. Reused across frames — reallocating per
+    /// frame would churn GPU memory at the display rate.
+    unsafe fn ensure_target(&mut self, width: i32, height: i32) -> Option<()> {
+        if let Some(t) = &self.target {
+            if t.width == width && t.height == height {
+                return Some(());
+            }
+        }
+        self.drop_target();
+
+        let gl = &self.gl;
+        let mut texture: u32 = 0;
+        (gl.gen_textures)(1, &mut texture);
+        (gl.bind_texture)(GL_TEXTURE_2D, texture);
+        (gl.tex_image_2d)(
+            GL_TEXTURE_2D,
+            0,
+            GL_RGBA8,
+            width,
+            height,
+            0,
+            GL_RGBA,
+            GL_UNSIGNED_BYTE,
+            ptr::null(),
+        );
+        (gl.tex_parameteri)(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+        (gl.tex_parameteri)(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+        (gl.bind_texture)(GL_TEXTURE_2D, 0);
+
+        let mut fbo: u32 = 0;
+        (gl.gen_framebuffers)(1, &mut fbo);
+        (gl.bind_framebuffer)(GL_FRAMEBUFFER, fbo);
+        (gl.framebuffer_texture_2d)(
+            GL_FRAMEBUFFER,
+            GL_COLOR_ATTACHMENT0,
+            GL_TEXTURE_2D,
+            texture,
+            0,
+        );
+        let status = (gl.check_framebuffer_status)(GL_FRAMEBUFFER);
+        (gl.bind_framebuffer)(GL_FRAMEBUFFER, 0);
+
+        if status != GL_FRAMEBUFFER_COMPLETE {
+            error!("[MpvRender] framebuffer incomplete: 0x{status:x}");
+            (gl.delete_framebuffers)(1, &fbo);
+            (gl.delete_textures)(1, &texture);
+            return None;
+        }
+
+        self.target = Some(Target {
+            fbo,
+            texture,
+            width,
+            height,
+        });
+        Some(())
+    }
+
+    unsafe fn drop_target(&mut self) {
+        if let Some(t) = self.target.take() {
+            (self.gl.delete_framebuffers)(1, &t.fbo);
+            (self.gl.delete_textures)(1, &t.texture);
+        }
+    }
+
+    /// Free everything, with the GL context current.
+    ///
+    /// Explicit rather than left to `Drop` because the ordering matters and the
+    /// caller is the only one that can guarantee the GL context is current. See
+    /// DR-232.
+    pub unsafe fn destroy(mut self) {
+        // Unregister first: a callback arriving after the free would be a use
+        // after free, and it is scheduled from mpv's own threads.
+        libmpv_sys::mpv_render_context_set_update_callback(self.ctx, None, ptr::null_mut());
+        self.drop_target();
+        libmpv_sys::mpv_render_context_free(self.ctx);
+        self.ctx = ptr::null_mut();
+        info!("[MpvRender] render context freed");
+        std::mem::forget(self);
+    }
+}
+
+impl Drop for MpvRenderContext {
+    fn drop(&mut self) {
+        if !self.ctx.is_null() {
+            // Reached only if `destroy` was not called — the GL context may not
+            // be current, so the GL objects are deliberately leaked rather than
+            // deleted against whatever context happens to be bound. Freeing the
+            // render context is still safe and is the part that matters.
+            warn!("[MpvRender] dropped without destroy(); GL objects leaked deliberately");
+            unsafe {
+                libmpv_sys::mpv_render_context_set_update_callback(self.ctx, None, ptr::null_mut());
+                libmpv_sys::mpv_render_context_free(self.ctx);
+            }
+        }
+    }
+}

src-tauri/src/player/native_video.rs

@@ -0,0 +1,78 @@
+//! Whether this process renders video natively, answered once.
+//!
+//! Three things need this and must agree: the mpv backend (which has to be
+//! configured for video *at construction*, before anything plays), the video
+//! surface (which has nothing to draw otherwise), and `get_player_status`
+//! (which tells the frontend whether to use a webview `<video>` element).
+//!
+//! It is a function rather than three `env::var` checks for the reason this
+//! codebase keeps rediscovering: a capability answered in several places is a
+//! capability whose answers drift. Four separate bugs this cycle came from
+//! exactly that shape — a webview's decode limits applied to ExoPlayer, a
+//! transcode target contradicting a direct-play claim, a codec list hardcoded in
+//! a URL builder. One source, read by everyone.
+//!
+//! TRACES: UR-080 | DR-231, DR-235
+
+/// The opt-in for native desktop video.
+///
+/// Off by default while the render path is unproven — the webview path still
+/// works and is what ships. This becomes the *default* (and then the only path)
+/// when DR-235 lands; the variable is how it is exercised until then.
+const ENV_FLAG: &str = "JELLYTAU_NATIVE_VIDEO";
+
+/// Whether mpv should decode and draw video in this process.
+///
+/// Read fresh rather than cached: it is consulted a handful of times at startup,
+/// and a `OnceLock` here would only make it harder to test.
+///
+/// TRACES: UR-080 | DR-231, DR-235
+pub fn enabled() -> bool {
+    // Only where a native renderer exists. On Android ExoPlayer already does
+    // this and `use_html5_element` is false for entirely separate reasons.
+    if !cfg!(all(target_os = "linux", not(target_os = "android"))) {
+        return false;
+    }
+    matches!(
+        std::env::var(ENV_FLAG).as_deref(),
+        Ok("1") | Ok("true") | Ok("yes")
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Absent, empty, or anything unrecognised means off. A half-set variable
+    /// must not half-enable a renderer — the failure mode would be mpv
+    /// configured for video with nothing drawing it, i.e. audio playing over a
+    /// black rectangle.
+    ///
+    /// TRACES: UR-080 | DR-231 | UT-216
+    #[test]
+    fn test_only_explicit_truthy_values_enable_it() {
+        let restore = std::env::var(ENV_FLAG).ok();
+
+        for value in ["", "0", "no", "false", "maybe", "2"] {
+            std::env::set_var(ENV_FLAG, value);
+            assert!(!enabled(), "{value:?} must not enable native video");
+        }
+
+        for value in ["1", "true", "yes"] {
+            std::env::set_var(ENV_FLAG, value);
+            assert_eq!(
+                enabled(),
+                cfg!(all(target_os = "linux", not(target_os = "android"))),
+                "{value:?} enables it exactly where a native renderer exists"
+            );
+        }
+
+        std::env::remove_var(ENV_FLAG);
+        assert!(!enabled(), "absent means off");
+
+        match restore {
+            Some(v) => std::env::set_var(ENV_FLAG, v),
+            None => std::env::remove_var(ENV_FLAG),
+        }
+    }
+}

src-tauri/src/player/seek.rs

@@ -39,23 +39,38 @@ pub fn determine_video_seek_strategy(
         return VideoSeekStrategy::LocalNativeSeek;
     }
 
-    // HLS streams and direct play (non-transcoded) support native seeking
-    if is_hls || !needs_transcoding {
-        if use_html5 {
-            // HTML5 backend - frontend handles seeking via videoElement.currentTime
-            // We don't call backend.seek() because video is in HTML5 element, not in MPV
-            VideoSeekStrategy::Html5NativeSeek
-        } else {
-            // Native backend (MPV) - backend handles seeking
-            VideoSeekStrategy::BackendNativeSeek
-        }
-    } else {
-        // Transcoded non-HLS streams need server-side seek (reload from new position)
-        if use_html5 {
-            VideoSeekStrategy::Html5ReloadStream
+    // A server-side transcode is produced *from* `StartTimeTicks`, so where the
+    // seek lands is a property of the request, not of the stream in hand.
+    //
+    // hls.js is the exception: handed a VOD playlist it seeks within it and lets
+    // the server catch up segment by segment. mpv's HLS demuxer cannot make
+    // Jellyfin transcode from a new offset, so for the native backend a
+    // transcoded seek must re-negotiate the stream regardless of container.
+    //
+    // Before native video shipped, `use_html5` was always true for HLS and the
+    // native+HLS+transcode cell was unreachable, which is why `is_hls` alone
+    // used to be a safe proxy for "seekable in place". It no longer is: turning
+    // native video on routed every transcoded seek into a backend seek that
+    // silently does nothing, and presents as "resume does not work".
+    if needs_transcoding {
+        return if use_html5 {
+            if is_hls {
+                VideoSeekStrategy::Html5NativeSeek
+            } else {
+                VideoSeekStrategy::Html5ReloadStream
+            }
         } else {
             VideoSeekStrategy::BackendReloadStream
-        }
+        };
+    }
+
+    // Direct play and direct stream are seekable where they sit.
+    if use_html5 {
+        // The frontend seeks via videoElement.currentTime; calling backend.seek()
+        // would move a player that is not the one rendering.
+        VideoSeekStrategy::Html5NativeSeek
+    } else {
+        VideoSeekStrategy::BackendNativeSeek
     }
 }
 
@@ -240,6 +255,30 @@ mod tests {
         );
     }
 
+    /// A server-side transcode cannot be seeked by the native backend.
+    ///
+    /// Jellyfin produces a transcode from `StartTimeTicks`; hls.js can seek
+    /// within the VOD playlist it is handed, but mpv's HLS demuxer cannot make
+    /// the server transcode from a new offset, so the stream has to be
+    /// re-negotiated. Before native video existed, `use_html5` was always true
+    /// for HLS and this case was unreachable — turning native video on routed
+    /// every transcoded seek into a native seek that silently does nothing,
+    /// which presents as "resume does not work".
+    ///
+    /// TRACES: UR-040 | DR-238 | UT-217
+    #[test]
+    fn test_seek_strategy_transcoded_hls_native_backend() {
+        assert_eq!(
+            determine_video_seek_strategy(false, true, true, false),
+            VideoSeekStrategy::BackendReloadStream
+        );
+        // The HTML5 side of the same case is unchanged: hls.js seeks in-playlist.
+        assert_eq!(
+            determine_video_seek_strategy(false, true, true, true),
+            VideoSeekStrategy::Html5NativeSeek
+        );
+    }
+
     /// Test video seek strategy for direct play (non-transcoded) streams
     #[test]
     fn test_seek_strategy_direct_play() {

src-tauri/src/player/video_surface.rs

@@ -0,0 +1,400 @@
+//! The native video surface: mpv drawn *behind* Tauri's webview, without
+//! touching the widget tree.
+//!
+//! # Why there is no overlay here
+//!
+//! The obvious arrangement — wrap the webview in a `GtkOverlay` with a
+//! `GtkGLArea` beneath — attaches cleanly and then aborts the process on the
+//! first click. `tauri-runtime-wry` connects a button-press handler to the
+//! webview that walks a hard-coded path:
+//!
+//! ```text
+//! webview.parent()          // "This one should be GtkBox"
+//!        .parent()          // ...and this one the GtkWindow
+//!        .downcast::<gtk::Window>().unwrap()
+//! ```
+//!
+//! An overlay makes that chain `webview → GtkOverlay → GtkBox`, the downcast
+//! fails, and because the panic is non-unwinding it takes the app with it.
+//! Nothing in configuration avoids it: on Linux the handler is attached
+//! *unconditionally* (the Windows path guards it behind `is_decorated()`), and
+//! the decoration check that would make it inert runs *after* the unwrap.
+//!
+//! So the widget tree is left exactly as Tauri built it. GTK draws a container
+//! before its children, so rendering into the vbox's own `draw` handler puts the
+//! picture underneath the webview for free — the same z-order, no reparenting,
+//! one less widget, and nothing a Tauri upgrade can invalidate by assuming its
+//! own layout.
+//!
+//! TRACES: UR-080 | DR-231, DR-232, DR-233, IR-033
+
+use std::cell::RefCell;
+use std::ffi::c_void;
+use std::rc::Rc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use gtk::prelude::*;
+use gtk::{gdk, glib};
+use log::{error, info, warn};
+
+use super::mpv_render::MpvRenderContext;
+
+/// GL enum for `gdk_cairo_draw_from_gl`'s `source_type`. GDK takes the GL
+/// constant itself rather than an enum of its own.
+const GL_TEXTURE: i32 = 0x1702;
+
+/// Everything the draw handler needs, shared with the GTK callbacks.
+struct SurfaceState {
+    gl: Option<gdk::GLContext>,
+    render: Option<MpvRenderContext>,
+    mpv: *mut libmpv_sys::mpv_handle,
+    /// Set by mpv's update callback (on an mpv thread), cleared by the frame
+    /// clock (on the main thread). The whole cross-thread contract.
+    frame_ready: Arc<AtomicBool>,
+    /// The boxed clone of `frame_ready` handed to mpv, reclaimed on teardown.
+    /// Null when no callback is registered.
+    callback_ctx: *mut Arc<AtomicBool>,
+    // One-shot diagnostic latches; see `draw`.
+    logged_first_draw: bool,
+    logged_first_frame: bool,
+    /// Last size we logged, so a size change re-reports rather than staying silent.
+    logged_size: (i32, i32),
+    logged_no_gl: bool,
+    logged_no_window: bool,
+    logged_no_size: bool,
+    logged_render_fail: bool,
+}
+
+impl SurfaceState {
+    /// Tear down in the order DR-232 requires, with the GL context current.
+    ///
+    /// The update callback is unregistered before the context is freed (inside
+    /// `destroy`), and the GL objects go while their context is still bound.
+    /// Getting this wrong is DR-184 on Android restated — a surface outliving
+    /// its player — and is the likeliest cause of the one unexplained SIGSEGV
+    /// the spike recorded.
+    fn teardown(&mut self) {
+        if let Some(render) = self.render.take() {
+            if let Some(gl) = &self.gl {
+                gl.make_current();
+            }
+            // Unregisters the callback before freeing the context.
+            unsafe { render.destroy() };
+        }
+        // Only now is it safe to reclaim what the callback was holding: mpv can
+        // no longer reach it. Freeing it first would be the use-after-free this
+        // ordering exists to prevent.
+        if !self.callback_ctx.is_null() {
+            unsafe { drop(Box::from_raw(self.callback_ctx)) };
+            self.callback_ctx = std::ptr::null_mut();
+        }
+        self.gl = None;
+    }
+}
+
+/// A live video surface. Dropping it tears the render context down.
+pub struct VideoSurface {
+    state: Rc<RefCell<SurfaceState>>,
+    widget: gtk::Box,
+    handlers: Vec<glib::SignalHandlerId>,
+}
+
+impl Drop for VideoSurface {
+    fn drop(&mut self) {
+        for id in self.handlers.drain(..) {
+            self.widget.disconnect(id);
+        }
+        self.state.borrow_mut().teardown();
+        self.widget.queue_draw();
+        info!("[VideoSurface] detached");
+    }
+}
+
+/// mpv's update callback. Runs on an mpv thread, so it does the least possible:
+/// flags the state and asks GTK to redraw on the main loop.
+///
+/// **Nothing here may block or re-enter the player.** The project's deadlock
+/// gotcha applies with full force — this is called from mpv's own threads.
+///
+/// TRACES: UR-080 | DR-233
+unsafe extern "C" fn on_mpv_update(ctx: *mut c_void) {
+    if ctx.is_null() {
+        return;
+    }
+    // Runs on an *mpv* thread. It therefore does exactly one thing that is safe
+    // to do from there: set an atomic flag.
+    //
+    // It must not touch GTK, and specifically must not schedule work with
+    // `idle_add_local*`, which requires the calling thread to own the default
+    // main context — from here that panics with "default main context already
+    // acquired by another thread". Nor can it hold the `Rc<RefCell<..>>` state:
+    // an `Rc` is not `Send`, and cloning one from two threads races its
+    // refcount.
+    //
+    // The frame clock on the widget picks the flag up on the main thread. See
+    // `install_frame_clock`.
+    let flag = &*(ctx as *const Arc<AtomicBool>);
+    flag.store(true, Ordering::Release);
+}
+
+/// Start drawing mpv's video underneath the webview.
+///
+/// `vbox` is Tauri's `default_vbox()` — the container the webview already lives
+/// in. It is not modified; only a `draw` handler is added.
+///
+/// Must run on the GTK main thread.
+///
+/// TRACES: UR-080 | DR-231, DR-232, DR-233
+pub fn attach(vbox: &gtk::Box, mpv: *mut libmpv_sys::mpv_handle) -> bool {
+    if mpv.is_null() {
+        warn!("[VideoSurface] no mpv handle; native video unavailable");
+        return false;
+    }
+
+    let state = Rc::new(RefCell::new(SurfaceState {
+        gl: None,
+        render: None,
+        mpv,
+        frame_ready: Arc::new(AtomicBool::new(false)),
+        callback_ctx: std::ptr::null_mut(),
+        logged_first_draw: false,
+        logged_first_frame: false,
+        logged_size: (0, 0),
+        logged_no_gl: false,
+        logged_no_window: false,
+        logged_no_size: false,
+        logged_render_fail: false,
+    }));
+
+    let mut handlers = Vec::new();
+
+    // The GL context can only be created once the widget has a GdkWindow, which
+    // is what `realize` announces. Creating it earlier leaves nothing to attach
+    // to — the same ordering constraint the render context has.
+    let realize_state = state.clone();
+    handlers.push(vbox.connect_realize(move |widget| {
+        if let Err(e) = init_gl(widget, &realize_state) {
+            error!("[VideoSurface] GL init failed: {e}");
+        }
+    }));
+
+    // A render context outliving its GL context is the defect DR-232 exists to
+    // prevent, so teardown is bound to `unrealize` rather than left to Drop.
+    let unrealize_state = state.clone();
+    handlers.push(vbox.connect_unrealize(move |_| {
+        unrealize_state.borrow_mut().teardown();
+    }));
+
+    // Drive the render loop from the widget's frame clock, on the main thread,
+    // rendering only when mpv actually has a frame.
+    //
+    // Both nearby mistakes were made and are worth naming, because each has a
+    // symptom that points somewhere else:
+    //
+    //   - Waiting on mpv's update callback before rendering deadlocks. mpv does
+    //     not progress until the client renders. The file loads, one frame
+    //     appears, and everything stops — no picture, no audio, a spinner that
+    //     never clears. It reads as a broken stream.
+    //   - Rendering unconditionally every tick and reporting a swap each time
+    //     tells mpv a frame reached the screen far more often than one did. It
+    //     plays, and judders badly. It reads as a GPU or compositing limit.
+    //
+    // Polling `has_frame` each tick is neither.
+    //
+    // The frame clock only ticks while the widget is mapped, so this costs
+    // nothing when the window is hidden.
+    //
+    // TRACES: UR-080 | DR-233
+    let tick_state = state.clone();
+    vbox.add_tick_callback(move |widget, _clock| {
+        // Ask mpv, on the main thread, whether there is anything new. The
+        // update callback's flag is only a hint that something *may* have
+        // happened; `has_frame` is the authority, and asking it here is what
+        // keeps this from either deadlocking or over-presenting.
+        let ready = match tick_state.try_borrow() {
+            Ok(s) => {
+                s.frame_ready.swap(false, Ordering::AcqRel);
+                match s.render.as_ref() {
+                    Some(render) => unsafe { render.has_frame() },
+                    None => false,
+                }
+            }
+            Err(_) => false,
+        };
+        if ready {
+            widget.queue_draw();
+        }
+        glib::ControlFlow::Continue
+    });
+
+    let draw_state = state.clone();
+    handlers.push(vbox.connect_draw(move |widget, cr| {
+        draw(widget, cr, &draw_state);
+        // Propagate: the webview is a child and must still draw over us.
+        glib::Propagation::Proceed
+    }));
+
+    // The window is already up by the time we are called, so run the init the
+    // `realize` signal would have.
+    if vbox.is_realized() {
+        if let Err(e) = init_gl(vbox, &state) {
+            error!("[VideoSurface] GL init failed: {e}");
+        }
+    }
+
+    info!("[VideoSurface] attached to Tauri's vbox without reparenting");
+    // The surface lives as long as the window. Held in a thread-local rather
+    // than returned, because it owns `Rc` and GTK types and so is neither `Send`
+    // nor `Sync` — it cannot go into Tauri's managed state, and leaking it would
+    // give up the ability to tear it down at all.
+    //
+    // Teardown does not depend on this being dropped: it is driven by the
+    // widget's `unrealize`, which is the signal that actually means "your GL
+    // context is going away" (DR-232).
+    LIVE_SURFACE.with(|cell| {
+        *cell.borrow_mut() = Some(VideoSurface {
+            state,
+            widget: vbox.clone(),
+            handlers,
+        });
+    });
+    true
+}
+
+thread_local! {
+    /// The one live surface, on the GTK main thread.
+    static LIVE_SURFACE: RefCell<Option<VideoSurface>> = const { RefCell::new(None) };
+}
+
+/// Drop the live surface, if there is one. Idempotent.
+///
+/// TRACES: UR-080 | DR-232
+#[allow(dead_code)]
+pub fn detach() {
+    LIVE_SURFACE.with(|cell| {
+        cell.borrow_mut().take();
+    });
+}
+
+/// Create the GL context and the mpv render context over it.
+fn init_gl(widget: &gtk::Box, state: &Rc<RefCell<SurfaceState>>) -> Result<(), String> {
+    if state.borrow().render.is_some() {
+        return Ok(());
+    }
+    let window = widget.window().ok_or("widget has no GdkWindow")?;
+
+    let gl = window
+        .create_gl_context()
+        .map_err(|e| format!("create_gl_context: {e}"))?;
+    gl.realize().map_err(|e| format!("realize: {e}"))?;
+    gl.make_current();
+
+    let mpv = state.borrow().mpv;
+    let mut render =
+        unsafe { MpvRenderContext::new(mpv) }.ok_or("mpv render context creation failed")?;
+
+    // The callback needs an owned handle that outlives this function, so a
+    // clone of the flag is boxed and leaked. `Arc<AtomicBool>` rather than the
+    // state itself: it is the only thing that may cross to an mpv thread. The
+    // pointer is kept so teardown can reclaim it — after the callback is
+    // unregistered, never before.
+    let flag = state.borrow().frame_ready.clone();
+    let ctx_box: *mut Arc<AtomicBool> = Box::into_raw(Box::new(flag));
+    unsafe { render.set_update_callback(Some(on_mpv_update), ctx_box as *mut c_void) };
+
+    let mut s = state.borrow_mut();
+    s.gl = Some(gl);
+    s.render = Some(render);
+    s.callback_ctx = ctx_box;
+    info!("[VideoSurface] GL and render context ready");
+    Ok(())
+}
+
+/// Draw the current frame, if there is one.
+///
+/// Runs *before* the children, which is what puts the picture behind the
+/// webview. Deliberately forgiving: no frame, no GL, or a borrowed state all
+/// mean "draw nothing this pass" rather than an error — the webview then paints
+/// over an untouched background, which is exactly the pre-native appearance.
+fn draw(widget: &gtk::Box, cr: &gtk::cairo::Context, state: &Rc<RefCell<SurfaceState>>) {
+    // Report each way of doing nothing exactly once. Without this the whole
+    // path is invisible: a draw handler that never runs, one that bails on a
+    // zero allocation, and one that renders perfectly all look identical from
+    // outside — and mpv stalls if frames are never consumed, so "no audio and
+    // it hangs" is a plausible symptom of *any* of them.
+    fn once(flag: &mut bool, msg: &str) {
+        if !*flag {
+            *flag = true;
+            warn!("[VideoSurface] not drawing: {msg}");
+        }
+    }
+
+    let Ok(mut s) = state.try_borrow_mut() else {
+        return;
+    };
+    if !s.logged_first_draw {
+        s.logged_first_draw = true;
+        info!("[VideoSurface] draw handler running");
+    }
+    let Some(gl) = s.gl.clone() else {
+        let f = &mut s.logged_no_gl;
+        once(f, "no GL context");
+        return;
+    };
+    let Some(window) = widget.window() else {
+        let f = &mut s.logged_no_window;
+        once(f, "widget has no GdkWindow");
+        return;
+    };
+
+    let scale = widget.scale_factor();
+    let width = widget.allocated_width() * scale;
+    let height = widget.allocated_height() * scale;
+    if width <= 0 || height <= 0 {
+        let f = &mut s.logged_no_size;
+        once(f, "zero allocation");
+        return;
+    }
+
+    gl.make_current();
+
+    // Render and end the mutable borrow before touching the latches again.
+    let rendered = match s.render.as_mut() {
+        Some(render) => unsafe { render.render(width, height) },
+        None => return,
+    };
+    let Some(texture) = rendered else {
+        let f = &mut s.logged_render_fail;
+        once(f, "mpv render produced no texture");
+        return;
+    };
+    // Log the first frame, and again whenever the target size changes. Latching
+    // this once per session hid the case that matters: a second file, rendered
+    // at a different size, in a window that never moved. "The picture is a small
+    // box in the middle" and "the picture fills the widget" are indistinguishable
+    // from outside without it.
+    if !s.logged_first_frame || s.logged_size != (width, height) {
+        s.logged_first_frame = true;
+        s.logged_size = (width, height);
+        info!("[VideoSurface] rendering {width}x{height} (texture {texture})");
+    }
+
+    unsafe {
+        cr.draw_from_gl(
+            &window,
+            texture as i32,
+            GL_TEXTURE,
+            scale,
+            0,
+            0,
+            width,
+            height,
+        );
+        // Tell mpv the frame reached the screen. Without this it has nothing to
+        // pace against — see DR-233.
+        if let Some(render) = s.render.as_ref() {
+            render.report_swap();
+        }
+    }
+}

src-tauri/src/repository/device_profile.rs

@@ -212,6 +212,16 @@ pub fn subtitle_supports_external_delivery(codec: Option<&str>) -> bool {
 ///
 /// TRACES: UR-004 | DR-148 | UT-142
 pub fn video_audio_codecs(detected: &str) -> String {
+    // Where the video renderer decodes the audio itself (ExoPlayer), the
+    // platform list *is* the answer and narrowing it to the webview's throws
+    // away codecs the device genuinely plays — dts, on the tablet this was
+    // found on. TRACES: UR-004, UR-080 | DR-234
+    #[cfg(target_os = "android")]
+    {
+        return detected.to_string();
+    }
+
+    #[allow(unreachable_code)]
     let kept: Vec<&str> = detected
         .split(',')
         .filter_map(|codec| {
@@ -233,6 +243,83 @@ pub fn video_audio_codecs(detected: &str) -> String {
     }
 }
 
+/// What the renderer that will actually decode video on this platform can play.
+///
+/// Returns `(video_codecs, audio_codecs)` as Jellyfin-style comma lists.
+///
+/// This exists because the answer was previously derived in four places and
+/// hardcoded in a fifth, each of them assuming the *webview* was decoding:
+/// the device profile, the transcoding targets, the direct-play audio
+/// narrowing, the client-side audio override, and `get_video_stream_url`'s
+/// `VideoCodec`. On Android the decoder is ExoPlayer, so every one of those was
+/// wrong there — the observed cost being an hevc source re-encoded to h264
+/// because its *audio* was eac3, and dts forced to transcode though the device
+/// decodes it.
+///
+/// One source, so the copies cannot disagree again.
+///
+/// TRACES: UR-004, UR-080 | DR-234
+pub fn renderer_codecs() -> (String, String) {
+    #[cfg(target_os = "android")]
+    {
+        // ExoPlayer, and the device itself answers via MediaCodecList.
+        crate::player::get_detected_codecs()
+            .map(|(video, audio, _channels)| (video, audio))
+            .unwrap_or_else(|| {
+                log::warn!(
+                    "[DeviceProfile] Codec detection not complete, using conservative defaults"
+                );
+                ("h264,hevc".to_string(), "aac,mp3".to_string())
+            })
+    }
+
+    // Linux desktop draws video in the WebKitGTK HTML5 <video> element, which
+    // cannot reliably decode HEVC/AV1/VP9. Claim only what it decodes, so
+    // Jellyfin transcodes the rest to h264 HLS. (Audio-only playback goes
+    // through MPV and is unaffected — that is a different renderer and a
+    // different profile.)
+    //
+    // When mpv draws the picture here this stops being a platform constant and
+    // becomes a question about the active renderer — which is the whole point of
+    // returning it from a function rather than a `cfg` block.
+    #[cfg(all(not(target_os = "android"), target_os = "linux"))]
+    {
+        ("h264".to_string(), "aac,mp3,opus,vorbis,flac".to_string())
+    }
+
+    #[cfg(all(not(target_os = "android"), not(target_os = "linux")))]
+    {
+        (
+            "h264,hevc,vp8,vp9,av1,mpeg4".to_string(),
+            "aac,mp3,opus,vorbis,flac".to_string(),
+        )
+    }
+}
+
+/// Whether the renderer that decodes *video* on this platform can also decode
+/// this audio codec.
+///
+/// On a webview platform this is the webview's narrow list, because the element
+/// decodes both halves. On Android it is the device's own list: ExoPlayer plays
+/// the audio, so judging it against the webview's capabilities transcodes files
+/// that would have played.
+///
+/// TRACES: UR-004, UR-080 | DR-234
+pub fn renderer_can_decode_audio(codec: &str) -> bool {
+    let codec = codec.trim();
+    #[cfg(target_os = "android")]
+    {
+        let (_video, audio) = renderer_codecs();
+        return audio
+            .split(',')
+            .any(|supported| supported.trim().eq_ignore_ascii_case(codec));
+    }
+    #[cfg(not(target_os = "android"))]
+    {
+        webview_can_decode_audio(codec)
+    }
+}
+
 /// Whether the webview `<video>` element can decode this audio codec.
 ///
 /// TRACES: UR-004 | DR-149 | UT-148
@@ -260,7 +347,9 @@ pub fn webview_can_decode_audio(codec: &str) -> bool {
 /// TRACES: UR-004 | DR-149 | UT-148
 pub fn audio_forces_transcode(streams: &[(Option<&str>, bool)]) -> bool {
     match served_audio_codec(streams) {
-        Some(codec) => !webview_can_decode_audio(codec),
+        // The renderer that will decode it, not always the webview — see
+        // `renderer_can_decode_audio`. TRACES: UR-004, UR-080 | DR-234
+        Some(codec) => !renderer_can_decode_audio(codec),
         // No audio at all, or a codec the server did not name: leave it alone.
         None => false,
     }

src-tauri/src/repository/hybrid.rs

@@ -97,13 +97,13 @@ impl HybridRepository {
             .await
     }
 
-    /// Decide what stream to play and describe it fully — the DR-224 contract.
+    /// Decide what stream to play and describe it fully — the DR-225 contract.
     ///
     /// Online-only for the same reason as `get_video_stream_url`: an offline
     /// item is a file on disk, and the caller builds
     /// [`StreamSelection::local_file`] for it rather than negotiating anything.
     ///
-    /// TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227
+    /// TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228
     pub async fn get_stream_selection(
         &self,
         item_id: &str,

src-tauri/src/repository/mod.rs

@@ -5,7 +5,7 @@ pub mod hybrid;
 pub mod offline;
 pub mod online;
 pub mod series_progress;
-/// Backend-owned stream selection (UR-079 / DR-224).
+/// Backend-owned stream selection (UR-079 / DR-225).
 pub mod stream_selection;
 pub mod types;
 

src-tauri/src/repository/online.rs

@@ -43,7 +43,7 @@ static STREAMING_QUALITY: RwLock<StreamingQuality> = RwLock::new(StreamingQualit
 /// Cleared when a new item starts playing, so the override cannot outlive the
 /// playback it was chosen for. The device default is never touched by it.
 ///
-/// TRACES: UR-074, UR-079 | DR-225
+/// TRACES: UR-074, UR-079 | DR-226
 static PLAYBACK_QUALITY_OVERRIDE: RwLock<Option<StreamingQuality>> = RwLock::new(None);
 
 /// Set the durable device default. Applies to every stream opened afterwards
@@ -71,7 +71,7 @@ pub fn streaming_quality() -> StreamingQuality {
 
 /// Move *this playback* to a different ceiling without disturbing the default.
 ///
-/// TRACES: UR-074, UR-079 | DR-225
+/// TRACES: UR-074, UR-079 | DR-226
 pub fn set_playback_quality_override(quality: StreamingQuality) {
     *PLAYBACK_QUALITY_OVERRIDE.write_safe() = Some(quality);
 }
@@ -82,14 +82,14 @@ pub fn set_playback_quality_override(quality: StreamingQuality) {
 /// not silently govern the next one. Autoplaying the next episode is the case
 /// that matters — nobody re-opens the picker between episodes.
 ///
-/// TRACES: UR-074, UR-079 | DR-225
+/// TRACES: UR-074, UR-079 | DR-226
 pub fn clear_playback_quality_override() {
     *PLAYBACK_QUALITY_OVERRIDE.write_safe() = None;
 }
 
 /// The per-playback override, if one is in force.
 ///
-/// TRACES: UR-074, UR-079 | DR-225
+/// TRACES: UR-074, UR-079 | DR-226
 pub fn playback_quality_override() -> Option<StreamingQuality> {
     *PLAYBACK_QUALITY_OVERRIDE.read_safe()
 }
@@ -102,7 +102,7 @@ pub fn playback_quality_override() -> Option<StreamingQuality> {
 /// the old static: a negotiation that authorises a direct play the URL builder
 /// then constrains (or vice versa) leaks the cap.
 ///
-/// TRACES: UR-074, UR-079 | DR-225
+/// TRACES: UR-074, UR-079 | DR-226
 pub fn effective_streaming_quality() -> StreamingQuality {
     playback_quality_override().unwrap_or_else(streaming_quality)
 }
@@ -611,13 +611,29 @@ impl OnlineRepository {
             self.stop_transcode(&previous).await;
         }
 
-        // Build an HLS transcode URL. VideoCodec lists h264 first so the server
-        // transcodes HEVC/10-bit/unsupported sources to h264 the WebView can decode.
+        // Build an HLS transcode URL, naming every codec this renderer can
+        // decode rather than only h264.
+        //
+        // The list is what lets the server *copy* the video stream instead of
+        // re-encoding it. Hardcoding h264 meant an hevc source whose only
+        // problem was its audio — eac3 on a device with no Dolby licence — got
+        // its picture fully re-encoded to satisfy a sound problem. The server's
+        // own transcoding URL already did the right thing (`h264,hevc`, video
+        // copied, `TranscodeReasons=AudioCodecNotSupported`); this builder,
+        // which takes over whenever a quality change or track switch re-opens
+        // the stream, quietly did not — so changing quality turned a cheap
+        // remux into a full transcode.
+        //
+        // On the webview path this still resolves to "h264" alone, so nothing
+        // changes there.
+        //
+        // TRACES: UR-004, UR-080 | DR-234
+        let (renderer_video_codecs, _) = super::device_profile::renderer_codecs();
         let mut params = vec![
             ("api_key", self.access_token.clone()),
             ("DeviceId", DEVICE_ID.to_string()),
             ("PlaySessionId", play_session_id),
-            ("VideoCodec", "h264".to_string()),
+            ("VideoCodec", renderer_video_codecs),
             ("AudioCodec", "aac".to_string()),
             ("MaxStreamingBitrate", max_bitrate.to_string()),
             ("VideoBitrate", video_bitrate.to_string()),
@@ -759,40 +775,21 @@ impl OnlineRepository {
     ///
     /// The single place the device profile is built and POSTed. Both
     /// [`get_playback_info`](Self::get_playback_info) (the legacy shape) and
-    /// `get_stream_selection` (the DR-224 contract) go through it, so the
+    /// `get_stream_selection` (the DR-225 contract) go through it, so the
     /// profile they negotiate under cannot drift apart.
     ///
-    /// TRACES: UR-004, UR-074, UR-079 | DR-224, DR-227
+    /// TRACES: UR-004, UR-074, UR-079 | DR-225, DR-228
     async fn negotiate_playback(
         &self,
         item_id: &str,
     ) -> Result<(NegotiatedSource, String), RepoError> {
         let endpoint = format!("/Items/{}/PlaybackInfo", urlencoding::encode(item_id));
 
-        // Get detected codecs from Android MediaCodecList or use platform defaults
-        #[cfg(target_os = "android")]
-        let (video_codecs, audio_codecs) = crate::player::get_detected_codecs()
-            .map(|(video, audio, _channels)| (video, audio))
-            .unwrap_or_else(|| {
-                warn!("[DeviceProfile] Codec detection not complete, using conservative defaults");
-                ("h264,hevc".to_string(), "aac,mp3".to_string())
-            });
-
-        // Linux desktop plays video through the WebKitGTK HTML5 <video> element,
-        // which cannot reliably decode HEVC/AV1/VP9. Advertise only codecs the
-        // WebView can decode so Jellyfin transcodes anything else to h264 HLS.
-        // (Audio-only files still direct-play via MPV; these codecs are what
-        // both renderers handle, and the audio profile keeps them in full while
-        // the video profile is narrowed below.)
-        #[cfg(all(not(target_os = "android"), target_os = "linux"))]
-        let (video_codecs, audio_codecs) =
-            ("h264".to_string(), "aac,mp3,opus,vorbis,flac".to_string());
-
-        #[cfg(all(not(target_os = "android"), not(target_os = "linux")))]
-        let (video_codecs, audio_codecs) = (
-            "h264,hevc,vp8,vp9,av1,mpeg4".to_string(),
-            "aac,mp3,opus,vorbis,flac".to_string(),
-        );
+        // What the renderer that will decode this can play. One source, shared
+        // with the transcode URL builder and the client-side audio override, so
+        // the profile we advertise and the stream we then ask for cannot
+        // disagree. TRACES: UR-004, UR-080 | DR-234
+        let (video_codecs, audio_codecs) = super::device_profile::renderer_codecs();
 
         // Video plays in a webview <video> element on every platform, which
         // decodes a narrower audio set than the platform does — so the video
@@ -862,7 +859,26 @@ impl OnlineRepository {
                     context: "Streaming".to_string(),
                     protocol: "hls".to_string(),
                     container: "ts".to_string(),
-                    video_codec: Some("h264,hevc".to_string()),
+                    // The server may only transcode *to* something this renderer
+                    // can decode. This said "h264,hevc" unconditionally while the
+                    // direct-play profile claims h264 alone on the webview path —
+                    // a straight contradiction: it tells the server "I cannot
+                    // play hevc, so re-encode it" and then "re-encoding it to
+                    // hevc is fine". When the server took that option the webview
+                    // got a stream it could not decode, which presents as video
+                    // stuck on its first frame rather than as an error.
+                    //
+                    // Capped at the two codecs a Jellyfin server actually
+                    // encodes, so a wider decode list never asks it for an av1
+                    // encode. TRACES: UR-004, UR-080 | DR-234
+                    video_codec: Some(
+                        if video_codecs.contains("hevc") {
+                            "h264,hevc"
+                        } else {
+                            "h264"
+                        }
+                        .to_string(),
+                    ),
                     audio_codec: "aac,mp3".to_string(),
                     max_audio_channels: max_audio_channels.clone(),
                 },
@@ -932,7 +948,7 @@ impl OnlineRepository {
     /// frontend stops testing the URL for `.m3u8`, and the quality ladder for
     /// *this* source so the picker stops offering rungs that mean nothing for it.
     ///
-    /// TRACES: UR-070, UR-079 | DR-224, DR-225, DR-226, DR-227 | UT-212
+    /// TRACES: UR-070, UR-079 | DR-225, DR-226, DR-227, DR-228 | UT-213
     pub async fn get_stream_selection(
         &self,
         item_id: &str,
@@ -1496,7 +1512,7 @@ impl JellyfinItem {
 // exactly how the cap used to leak (a negotiation authorising a direct play the
 // URL builder then never got to constrain).
 //
-// TRACES: UR-079 | DR-224, DR-227
+// TRACES: UR-079 | DR-225, DR-228
 // ---------------------------------------------------------------------------
 
 #[derive(Debug, Serialize)]
@@ -1589,7 +1605,7 @@ pub struct NegotiatedSource {
     /// The source's own bitrate, when the server reports one.
     ///
     /// Fills the quality picker's "this rung is the same as Original" judgement
-    /// (DR-226). Absent for some containers — the sampled library has `avi`
+    /// (DR-227). Absent for some containers — the sampled library has `avi`
     /// files with no bitrate at all — in which case nothing is judged redundant
     /// and every rung stays offered.
     #[serde(default)]
@@ -1624,7 +1640,7 @@ pub struct NegotiatedStream {
 /// separately, or that the viewer has pinned a track the file does not default
 /// to.
 ///
-/// TRACES: UR-079 | DR-227 | UT-212
+/// TRACES: UR-079 | DR-228 | UT-213
 pub fn decide_playback_kind(
     source: &NegotiatedSource,
     audio_forces_transcode: bool,
@@ -3141,7 +3157,7 @@ mod tests {
             set_streaming_quality(StreamingQuality::Original);
             // A leaked per-playback override would cap every later test's
             // expectations without appearing anywhere in its setup.
-            // TRACES: UR-074, UR-079 | DR-225
+            // TRACES: UR-074, UR-079 | DR-226
             clear_playback_quality_override();
         }
     }
@@ -4201,7 +4217,7 @@ mod tests {
     }
 
     // -----------------------------------------------------------------------
-    // Direct-play negotiation (DR-227)
+    // Direct-play negotiation (DR-228)
     //
     // Fixtures rather than a live server, but the *shapes* are real: every one
     // below was observed in a `PlaybackInfo` response from the development
@@ -4226,11 +4242,11 @@ mod tests {
         }
     }
 
-    /// The whole point of DR-227: a source the server will serve untouched is
+    /// The whole point of DR-228: a source the server will serve untouched is
     /// served untouched. Before this, every video play built an HLS transcode
     /// URL regardless.
     ///
-    /// TRACES: UR-079 | DR-227 | UT-212
+    /// TRACES: UR-079 | DR-228 | UT-213
     #[test]
     fn test_a_supported_source_direct_plays() {
         let source = source_fixture();
@@ -4243,7 +4259,7 @@ mod tests {
     /// The server can remux without re-encoding. That is not a transcode and
     /// must not be reported as one — the difference is a whole CPU core.
     ///
-    /// TRACES: UR-079 | DR-227 | UT-212
+    /// TRACES: UR-079 | DR-228 | UT-213
     #[test]
     fn test_a_remuxable_source_direct_streams() {
         let source = NegotiatedSource {
@@ -4262,7 +4278,7 @@ mod tests {
     /// An unsupported codec — the hevc that is ~80% of the sampled library,
     /// under the Linux h264-only profile — transcodes.
     ///
-    /// TRACES: UR-079 | DR-227 | UT-212
+    /// TRACES: UR-079 | DR-228 | UT-213
     #[test]
     fn test_an_unsupported_source_transcodes() {
         let source = NegotiatedSource {
@@ -4281,7 +4297,7 @@ mod tests {
     /// track the webview cannot decode, which renders as picture with no sound.
     /// The client's verdict has to win over the server's.
     ///
-    /// TRACES: UR-079 | DR-227, DR-148 | UT-212
+    /// TRACES: UR-079 | DR-228, DR-148 | UT-213
     #[test]
     fn test_undecodable_audio_overrides_the_servers_direct_play_offer() {
         let source = source_fixture();
@@ -4297,7 +4313,7 @@ mod tests {
     /// different one. Honouring the viewer's choice means asking the server to
     /// build a stream around it.
     ///
-    /// TRACES: UR-021, UR-079 | DR-227 | UT-212
+    /// TRACES: UR-021, UR-079 | DR-228 | UT-213
     #[test]
     fn test_pinning_an_audio_track_forces_a_transcode() {
         let source = source_fixture();
@@ -4313,7 +4329,7 @@ mod tests {
     /// arrives here as `supports_direct_play: false`; this pins the mapping so a
     /// future refactor cannot quietly direct-play past a cap.
     ///
-    /// TRACES: UR-074, UR-079 | DR-225, DR-227 | UT-212
+    /// TRACES: UR-074, UR-079 | DR-226, DR-228 | UT-213
     #[test]
     fn test_a_ceiling_below_the_source_bitrate_transcodes() {
         // 6.65 Mbps source, 2 Mbps ceiling — the server refuses direct play.
@@ -4341,7 +4357,7 @@ mod tests {
     /// Direct play wins over direct stream when both are on offer: copying the
     /// file is strictly cheaper than repackaging it.
     ///
-    /// TRACES: UR-079 | DR-227 | UT-212
+    /// TRACES: UR-079 | DR-228 | UT-213
     #[test]
     fn test_direct_play_is_preferred_over_direct_stream() {
         let source = source_fixture();
@@ -4353,15 +4369,15 @@ mod tests {
     }
 
     // -----------------------------------------------------------------------
-    // Per-playback quality ceiling (DR-225)
+    // Per-playback quality ceiling (DR-226)
     // -----------------------------------------------------------------------
 
-    /// The defect DR-225 exists to fix: the in-player picker documented itself
+    /// The defect DR-226 exists to fix: the in-player picker documented itself
     /// as a "this film, this connection" control but was implemented by writing
     /// the device default, so one awkward film silently capped everything played
     /// afterwards. The override must not touch the default.
     ///
-    /// TRACES: UR-074, UR-079 | DR-225 | UT-212
+    /// TRACES: UR-074, UR-079 | DR-226 | UT-213
     #[test]
     fn test_a_playback_override_does_not_disturb_the_device_default() {
         let _guard = QUALITY_LOCK.lock_safe();
@@ -4394,7 +4410,7 @@ mod tests {
     /// autoplayed next episode is the case that matters, since nobody reopens
     /// the picker between episodes.
     ///
-    /// TRACES: UR-074, UR-079 | DR-225 | UT-212
+    /// TRACES: UR-074, UR-079 | DR-226 | UT-213
     #[test]
     fn test_the_override_is_droppable_so_it_cannot_outlive_its_playback() {
         let _guard = QUALITY_LOCK.lock_safe();

src-tauri/src/repository/stream_selection.rs

@@ -12,7 +12,7 @@
 //! decides *how to deliver it*** — is the point. A multi-variant playlist handed
 //! to ExoPlayer is still ExoPlayer's to adapt over; Rust never paces bytes.
 //!
-//! TRACES: UR-079 | DR-224
+//! TRACES: UR-079 | DR-225
 
 use serde::{Deserialize, Serialize};
 
@@ -30,7 +30,7 @@ use crate::settings::StreamingQuality;
 /// Tagged (`{"type":"hls"}`) rather than a bare string so the frontend matches a
 /// discriminant instead of comparing text.
 ///
-/// TRACES: UR-079 | DR-224
+/// TRACES: UR-079 | DR-225
 #[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "camelCase")]
 pub enum Transport {
@@ -52,7 +52,7 @@ pub enum Transport {
 /// lets the UI say "this is not costing the server anything" without inferring
 /// it from a URL shape.
 ///
-/// TRACES: UR-079 | DR-227
+/// TRACES: UR-079 | DR-228
 #[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "camelCase")]
 pub enum PlaybackKind {
@@ -73,7 +73,7 @@ impl PlaybackKind {
     /// that several seek/reload paths still branch on; this keeps the two from
     /// drifting by making one derive from the other.
     ///
-    /// TRACES: UR-079 | DR-227
+    /// TRACES: UR-079 | DR-228
     pub fn needs_transcoding(&self) -> bool {
         matches!(self, PlaybackKind::Transcode)
     }
@@ -85,7 +85,7 @@ impl PlaybackKind {
 /// there is no *chosen* rendition in that case, only the file itself, and
 /// reporting the ceiling that happened to be set would misdescribe it.
 ///
-/// TRACES: UR-079 | DR-224, DR-225
+/// TRACES: UR-079 | DR-225, DR-226
 #[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Rendition {
@@ -108,7 +108,7 @@ pub struct Rendition {
 /// them indistinguishable from Original. `exceeds_source` is what lets the
 /// frontend render that honestly without knowing anything about bitrates.
 ///
-/// TRACES: UR-070, UR-079 | DR-226, DR-121
+/// TRACES: UR-070, UR-079 | DR-227, DR-121
 #[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct QualityOption {
@@ -133,7 +133,7 @@ pub struct QualityOption {
 ///
 /// Replaces the bare `String` URL that `get_video_stream_url` used to return.
 ///
-/// TRACES: UR-079 | DR-224, DR-226, DR-227
+/// TRACES: UR-079 | DR-225, DR-227, DR-228
 #[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct StreamSelection {
@@ -145,7 +145,7 @@ pub struct StreamSelection {
     pub playback_kind: PlaybackKind,
     /// The negotiated rendition; `None` when direct-playing the source as-is.
     pub rendition: Option<Rendition>,
-    /// What this media source can offer, for the quality picker (DR-226).
+    /// What this media source can offer, for the quality picker (DR-227).
     pub available: Vec<QualityOption>,
     /// The media source this selection is for, so a later re-open (quality
     /// change, audio-track switch, transcoded seek) targets the same one.
@@ -160,7 +160,7 @@ pub struct StreamSelection {
     /// queue's long-standing `needs_transcoding` flag and the seek strategy both
     /// read this, so there is one answer rather than three.
     ///
-    /// TRACES: UR-079 | DR-224, DR-227
+    /// TRACES: UR-079 | DR-225, DR-228
     pub needs_transcoding: bool,
 }
 
@@ -171,7 +171,7 @@ impl StreamSelection {
     /// source's — and offering a quality ladder over it would be a lie, since
     /// nothing about a local file can be re-negotiated.
     ///
-    /// TRACES: UR-071, UR-079 | DR-224
+    /// TRACES: UR-071, UR-079 | DR-225
     pub fn local_file(url: impl Into<String>) -> Self {
         Self {
             url: url.into(),
@@ -199,7 +199,7 @@ impl StreamSelection {
 /// all). In that case nothing can be judged redundant and every rung is offered,
 /// which is the safe direction: the viewer keeps every choice they had before.
 ///
-/// TRACES: UR-070, UR-079 | DR-226, DR-121 | UT-211
+/// TRACES: UR-070, UR-079 | DR-227, DR-121 | UT-212
 pub fn quality_options_for_source(source_bitrate: Option<u64>) -> Vec<QualityOption> {
     StreamingQuality::ALL
         .iter()
@@ -226,7 +226,7 @@ mod tests {
     /// The tag the frontend matches on has to be exactly what it expects, and
     /// it is a *string in TypeScript* — nothing but a test keeps the two in step.
     ///
-    /// TRACES: UR-079 | DR-224 | UT-211
+    /// TRACES: UR-079 | DR-225 | UT-212
     #[test]
     fn test_transport_serialises_with_the_tag_the_frontend_matches() {
         let cases = [
@@ -242,7 +242,7 @@ mod tests {
         }
     }
 
-    /// TRACES: UR-079 | DR-227 | UT-211
+    /// TRACES: UR-079 | DR-228 | UT-212
     #[test]
     fn test_playback_kind_serialises_with_the_tag_the_frontend_matches() {
         let cases = [
@@ -261,7 +261,7 @@ mod tests {
     /// Only a transcode costs the server encoder time. A direct *stream* is a
     /// remux — cheap, and not what `needs_transcoding` has ever meant.
     ///
-    /// TRACES: UR-079 | DR-227 | UT-211
+    /// TRACES: UR-079 | DR-228 | UT-212
     #[test]
     fn test_only_transcode_counts_as_transcoding() {
         assert!(PlaybackKind::Transcode.needs_transcoding());
@@ -272,7 +272,7 @@ mod tests {
     /// A local file is a direct play over a local transport, with no ladder:
     /// nothing about a file on disk can be re-negotiated.
     ///
-    /// TRACES: UR-071, UR-079 | DR-224 | UT-211
+    /// TRACES: UR-071, UR-079 | DR-225 | UT-212
     #[test]
     fn test_local_file_selection_offers_no_ladder() {
         let selection = StreamSelection::local_file("http://127.0.0.1:9000/media/x.mkv");
@@ -286,7 +286,7 @@ mod tests {
     /// The camelCase rule applies to nested struct fields too, and
     /// `playbackKind` is the one the frontend branches on.
     ///
-    /// TRACES: UR-079 | DR-224 | UT-211
+    /// TRACES: UR-079 | DR-225 | UT-212
     #[test]
     fn test_stream_selection_fields_are_camel_case_on_the_wire() {
         let selection = StreamSelection {
@@ -321,7 +321,7 @@ mod tests {
     /// The measured library has 1.1 Mbps sources in it. Offering those a choice
     /// of 20, 10, 8, 4 and 2 Mbps is offering five ways to spell "Original".
     ///
-    /// TRACES: UR-070, UR-079 | DR-226, DR-121 | UT-211
+    /// TRACES: UR-070, UR-079 | DR-227, DR-121 | UT-212
     #[test]
     fn test_rungs_above_the_source_bitrate_are_marked_redundant() {
         let options = quality_options_for_source(Some(1_122_137));
@@ -361,7 +361,7 @@ mod tests {
     /// `Original` is the source, so it is never "above" it — not even for a
     /// source whose bitrate is unknown or zero.
     ///
-    /// TRACES: UR-070, UR-079 | DR-226 | UT-211
+    /// TRACES: UR-070, UR-079 | DR-227 | UT-212
     #[test]
     fn test_original_is_never_marked_as_exceeding_the_source() {
         for bitrate in [None, Some(0), Some(1), Some(50_000_000)] {
@@ -377,7 +377,7 @@ mod tests {
     /// An `avi` with no reported bitrate must not lose the picker. Judging
     /// nothing redundant is the safe direction — the viewer keeps every choice.
     ///
-    /// TRACES: UR-070, UR-079 | DR-226 | UT-211
+    /// TRACES: UR-070, UR-079 | DR-227 | UT-212
     #[test]
     fn test_an_unknown_source_bitrate_keeps_every_rung_offered() {
         let options = quality_options_for_source(None);
@@ -391,7 +391,7 @@ mod tests {
 
     /// A 4K remux constrains at every rung — the ladder is fully meaningful.
     ///
-    /// TRACES: UR-070, UR-079 | DR-226 | UT-211
+    /// TRACES: UR-070, UR-079 | DR-227 | UT-212
     #[test]
     fn test_a_source_above_the_ladder_marks_nothing_redundant() {
         let options = quality_options_for_source(Some(40_000_000));
@@ -401,7 +401,7 @@ mod tests {
     /// The picker's text comes from Rust, beside the numbers it describes, so a
     /// relabelled rung cannot drift out of step with what it does.
     ///
-    /// TRACES: UR-070, UR-079 | DR-226 | UT-211
+    /// TRACES: UR-070, UR-079 | DR-227 | UT-212
     #[test]
     fn test_options_carry_the_ladder_labels() {
         let options = quality_options_for_source(Some(6_652_961));

src-tauri/src/repository/types.rs

@@ -474,9 +474,9 @@ pub struct LiveStreamInfo {
     /// A live channel is always an HLS transcode — the server has to repackage a
     /// broadcast mux into something a browser can play, and there is no static
     /// file to direct-play. Saying so here means the player page never has to
-    /// work it out from the URL, which is the whole of DR-224.
+    /// work it out from the URL, which is the whole of DR-225.
     ///
-    /// TRACES: UR-079 | DR-224
+    /// TRACES: UR-079 | DR-225
     pub transport: super::stream_selection::Transport,
 }
 

src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "JellyTau",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "identifier": "com.dtourolle.jellytau",
   "build": {
     "beforeDevCommand": "bun run dev",
@@ -17,7 +17,8 @@
         "height": 800,
         "minWidth": 800,
         "minHeight": 600,
-        "resizable": true
+        "resizable": true,
+        "transparent": true
       }
     ],
     "security": {
@@ -44,6 +45,7 @@
   },
   "bundle": {
     "active": true,
+    "createUpdaterArtifacts": true,
     "targets": [
       "deb",
       "rpm",

src/lib/api/bindings.ts

@@ -19,6 +19,31 @@ export const commands = {
 async playerPlayItem(item: PlayItemRequest) : Promise<PlayerStatus> {
     return await TAURI_INVOKE("player_play_item", { item });
 },
+/**
+ * Exit background-audio mode: stop the native audio player and return its final
+ * position so the frontend can reload the WebView `<video>` there (UR-040).
+ * 
+ * Returns the position in seconds. The sleep timer is intentionally left
+ * untouched — if it fired while backgrounded, playback is already stopped and
+ * this simply reports the last position.
+ * 
+ * What playback should do now that the app is no longer visible.
+ * 
+ * The caller supplies only what it alone knows -- whether the per-player
+ * toggle is armed, and whether Android put the window into picture-in-picture.
+ * Everything else (what is playing, and therefore whether there is a picture to
+ * lose) is read here, because it is domain state.
+ * 
+ * The rule itself is in `player::background_policy`; this command is the wire.
+ * Returning `KeepPlaying` for an empty queue is deliberate: with nothing
+ * playing there is nothing to pause, and an error would make the frontend
+ * handle a case that is not a failure.
+ * 
+ * TRACES: UR-040, UR-041 | DR-225 | UT-212
+ */
+async playerBackgroundAction(backgroundAudioArmed: boolean, inPictureInPicture: boolean) : Promise<BackgroundAction> {
+    return await TAURI_INVOKE("player_background_action", { backgroundAudioArmed, inPictureInPicture });
+},
 /**
  * Enter background-audio mode: hand playback of the currently-watched video off
  * to the native ExoPlayer *audio* path so the audio keeps playing while the app
@@ -41,13 +66,6 @@ async playerEnterBackgroundAudio(item: PlayItemRequest, positionSeconds: number)
     return await TAURI_INVOKE("player_enter_background_audio", { item, positionSeconds });
 },
 /**
- * Exit background-audio mode: stop the native audio player and return its final
- * position so the frontend can reload the WebView `<video>` there (UR-040).
- * 
- * Returns the position in seconds. The sleep timer is intentionally left
- * untouched — if it fired while backgrounded, playback is already stopped and
- * this simply reports the last position.
- * 
  * TRACES: UR-040 | DR-052 | UT-061, IT-013
  */
 async playerExitBackgroundAudio() : Promise<number> {
@@ -255,7 +273,7 @@ async playerGetStreamingQualities() : Promise<([StreamingQuality, string, string
  * belongs to Settings, and `player_set_video_settings` is the one that writes
  * to the database.
  * 
- * TRACES: UR-074, UR-079 | DR-162, DR-225
+ * TRACES: UR-074, UR-079 | DR-162, DR-226
  */
 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 });
@@ -1030,7 +1048,7 @@ async mediaLocalUrl(path: string) : Promise<string> {
  * to consume rather than two, and so no caller has to infer a transport from a
  * loopback URL.
  * 
- * TRACES: UR-071, UR-079 | DR-224
+ * TRACES: UR-071, UR-079 | DR-225
  */
 async mediaLocalSelection(path: string) : Promise<StreamSelection> {
     return await TAURI_INVOKE("media_local_selection", { path });
@@ -1633,7 +1651,7 @@ async repositoryGetVideoStreamUrl(handle: string, itemId: string, mediaSourceId:
  * position on an HLS playlist is copied onto every segment URI and the server
  * rejects each with `400` (DR-181). Callers resume by seeking after load.
  * 
- * TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227 | UT-212
+ * TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228 | UT-213
  */
 async repositoryGetStreamSelection(handle: string, itemId: string, mediaSourceId: string | null, audioStreamIndex: number | null) : Promise<StreamSelection> {
     return await TAURI_INVOKE("repository_get_stream_selection", { handle, itemId, mediaSourceId, audioStreamIndex });
@@ -2014,6 +2032,23 @@ countdownSeconds: number;
  * Maximum number of episodes to auto-play consecutively (0 = unlimited)
  */
 maxEpisodes?: number }
+/**
+ * What the player should do when the app is backgrounded.
+ */
+export type BackgroundAction = 
+/**
+ * Carry on. Music, and video the user explicitly asked to keep hearing
+ * while it is in a picture-in-picture window.
+ */
+"keepPlaying" | 
+/**
+ * Swap the video stream for an audio-only one and keep playing.
+ */
+"handOffToAudio" | 
+/**
+ * Stop making sound. The user did not ask for background playback.
+ */
+"pause"
 /**
  * Smart caching configuration
  */
@@ -2339,9 +2374,9 @@ export type LiveStreamInfo = { streamUrl: string; playSessionId: string | null;
  * A live channel is always an HLS transcode — the server has to repackage a
  * broadcast mux into something a browser can play, and there is no static
  * file to direct-play. Saying so here means the player page never has to
- * work it out from the URL, which is the whole of DR-224.
+ * work it out from the URL, which is the whole of DR-225.
  * 
- * TRACES: UR-079 | DR-224
+ * TRACES: UR-079 | DR-225
  */
 transport: Transport }
 /**
@@ -2591,7 +2626,7 @@ needsTranscoding: boolean;
  * caller falls back to `needs_transcoding` — every transcode this app
  * requests is HLS (DR-140), so that fallback is exact rather than a guess.
  * 
- * TRACES: UR-003, UR-004, UR-079 | DR-224, DR-229
+ * TRACES: UR-003, UR-004, UR-079 | DR-225, DR-230
  */
 transport?: Transport | null; 
 /**
@@ -2715,7 +2750,7 @@ export type PlaybackInfo = { mediaSourceId: string; playSessionId: string; strea
  * lets the UI say "this is not costing the server anything" without inferring
  * it from a URL shape.
  * 
- * TRACES: UR-079 | DR-227
+ * TRACES: UR-079 | DR-228
  */
 export type PlaybackKind = 
 /**
@@ -2840,7 +2875,7 @@ needsTranscoding?: boolean;
  * caller falls back to `needs_transcoding` — every transcode this app
  * requests is HLS (DR-140), so that fallback is exact rather than a guess.
  * 
- * TRACES: UR-003, UR-004, UR-079 | DR-224, DR-229
+ * TRACES: UR-003, UR-004, UR-079 | DR-225, DR-230
  */
 transport?: Transport | null; 
 /**
@@ -3133,7 +3168,7 @@ skipped: number }
  * them indistinguishable from Original. `exceeds_source` is what lets the
  * frontend render that honestly without knowing anything about bitrates.
  * 
- * TRACES: UR-070, UR-079 | DR-226, DR-121
+ * TRACES: UR-070, UR-079 | DR-227, DR-121
  */
 export type QualityOption = { quality: StreamingQuality; 
 /**
@@ -3172,7 +3207,7 @@ export type RemoteSessionStatus = { position: number; duration: number | null; i
  * there is no *chosen* rendition in that case, only the file itself, and
  * reporting the ceiling that happened to be set would misdescribe it.
  * 
- * TRACES: UR-079 | DR-224, DR-225
+ * TRACES: UR-079 | DR-225, DR-226
  */
 export type Rendition = { 
 /**
@@ -3308,9 +3343,19 @@ export type StreamKind = "audio" | "video" | "subtitle" |
  */
 export type StreamQualityResponse = 
 /**
- * The native backend was reloaded here; nothing left for the frontend.
+ * The native backend was reloaded here; nothing left for the frontend to
+ * *do* — but it still has to be told what was negotiated.
+ * 
+ * This carried only a position at first, which left the picker on Android
+ * pinned to the rendition of the *first* stream: the UI derives the rung in
+ * force from the selection it holds, nothing replaced that selection on the
+ * native path, and a transcode always has a rendition — so the fallback
+ * that would have used the requested value was never reached. The stream
+ * changed and the menu did not.
+ * 
+ * TRACES: UR-074, UR-079 | DR-226, DR-227
  */
-{ strategy: "native"; position: number } | 
+{ strategy: "native"; selection: StreamSelection; position: number } | 
 /**
  * HTML5 must reload its element with this selection.
  */
@@ -3321,7 +3366,7 @@ export type StreamQualityResponse =
  * 
  * Replaces the bare `String` URL that `get_video_stream_url` used to return.
  * 
- * TRACES: UR-079 | DR-224, DR-226, DR-227
+ * TRACES: UR-079 | DR-225, DR-227, DR-228
  */
 export type StreamSelection = { 
 /**
@@ -3341,7 +3386,7 @@ playbackKind: PlaybackKind;
  */
 rendition: Rendition | null; 
 /**
- * What this media source can offer, for the quality picker (DR-226).
+ * What this media source can offer, for the quality picker (DR-227).
  */
 available: QualityOption[]; 
 /**
@@ -3362,7 +3407,7 @@ playSessionId: string | null;
  * queue's long-standing `needs_transcoding` flag and the seek strategy both
  * read this, so there is one answer rather than three.
  * 
- * TRACES: UR-079 | DR-224, DR-227
+ * TRACES: UR-079 | DR-225, DR-228
  */
 needsTranscoding: boolean }
 /**
@@ -3458,7 +3503,7 @@ export type ThumbnailCacheStats = { totalSizeBytes: number; itemCount: number; l
  * Tagged (`{"type":"hls"}`) rather than a bare string so the frontend matches a
  * discriminant instead of comparing text.
  * 
- * TRACES: UR-079 | DR-224
+ * TRACES: UR-079 | DR-225
  */
 export type Transport = 
 /**

src/lib/api/repository-client.ts

@@ -260,7 +260,7 @@ export class RepositoryClient {
    * start position on an HLS playlist makes Jellyfin reject every segment behind
    * it with `400` (DR-181). Resume by seeking once loaded.
    *
-   * TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227 | UT-212
+   * TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228 | UT-213
    */
   async getStreamSelection(
     itemId: string,

src/lib/components/library/EpisodeFocusView.svelte

@@ -8,6 +8,7 @@
 -->
 <script lang="ts">
   import { goto } from "$app/navigation";
+  import { formatDuration } from "$lib/utils/duration";
   import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import type { MediaItem } from "$lib/api/types";
   import CachedImage from "$lib/components/common/CachedImage.svelte";
@@ -88,18 +89,6 @@
       : null,
   );
 
-  function formatDuration(ms?: number | null): string {
-    if (!ms) return "";
-    const seconds = Math.floor(ms / 1000);
-    const hours = Math.floor(seconds / 3600);
-    const minutes = Math.floor((seconds % 3600) / 60);
-
-    if (hours > 0) {
-      return `${hours}h ${minutes}m`;
-    }
-    return `${minutes}m`;
-  }
-
   function getProgress(ep: MediaItem): number {
     if (!ep.userData || !ep.durationMs) {
       return 0;
@@ -117,7 +106,7 @@
   }
 
   const episodeLabel = $derived(`S${episode.parentIndexNumber || 1}E${episode.indexNumber || 1}`);
-  const duration = $derived(formatDuration(episode.durationMs));
+  const duration = $derived(formatDuration(episode.durationMs, "h m"));
   const progress = $derived(getProgress(episode));
 </script>
 

src/lib/components/player/Queue.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { playerController } from "$lib/player";
+  import { formatDuration } from "$lib/utils/duration";
   import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { dndzone, SOURCES, TRIGGERS } from "svelte-dnd-action";
   import type { MediaItem } from "$lib/api/types";
@@ -34,14 +35,6 @@
   let dragDisabled = $state(true);
   const flipDurationMs = 200;
 
-  function formatDuration(ms?: number | null): string {
-    if (!ms) return "";
-    const seconds = Math.floor(ms / 1000);
-    const mins = Math.floor(seconds / 60);
-    const secs = seconds % 60;
-    return `${mins}:${secs.toString().padStart(2, "0")}`;
-  }
-
   function handleConsider(
     e: CustomEvent<{ items: DndItem[]; info: { source: string; trigger: string } }>,
   ) {

src/lib/components/player/VideoPlayer.svelte

@@ -1,10 +1,16 @@
 <!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026, UR-040, UR-061 | DR-010, DR-023, DR-024, DR-051, DR-052, DR-092, DR-098, DR-099 -->
 <script lang="ts">
   import { onMount, onDestroy, tick, untrack } from "svelte";
+  import { planFullscreen } from "./fullscreenTarget";
   import { get } from "svelte/store";
   import { goto } from "$app/navigation";
   import { commands } from "$lib/api/bindings";
-  import type { JRayActor, StreamingQuality, StreamSelection } from "$lib/api/bindings";
+  import type {
+    JRayActor,
+    StreamingQuality,
+    BackgroundAction,
+    StreamSelection,
+  } from "$lib/api/bindings";
   import { listen } from "@tauri-apps/api/event";
   import Hls from "hls.js";
   import type { MediaItem } from "$lib/api/types";
@@ -63,6 +69,7 @@
   import {
     setBackgroundAudioEnabled,
     subscribeAppBackgrounded,
+    type BackgroundSignal,
     subscribeAppForegrounded,
   } from "$lib/utils/backgroundAudio";
   import { platform } from "@tauri-apps/plugin-os";
@@ -76,7 +83,7 @@
     type BackgroundAudioState,
   } from "./backgroundAudioHandoff";
   import { createLogger } from "$lib/utils/logger";
-  import { elementSrcFor, videoLoaderFor } from "$lib/player/streamTransport";
+  import { elementSrcFor, loaderForTransport } from "$lib/player/streamTransport";
 
   const log = createLogger("VideoPlayer");
 
@@ -88,7 +95,7 @@
      * which forced this component to re-derive the transport by searching for
      * `.m3u8`.
      *
-     * TRACES: UR-079 | DR-224, DR-226
+     * TRACES: UR-079 | DR-225, DR-227
      */
     selection: StreamSelection;
     mediaSourceId?: string; // Media source ID for subtitle URLs
@@ -190,9 +197,15 @@
   // The selection currently loaded. Starts from the prop and is replaced
   // wholesale by a reload (quality change, audio-track switch, transcoded seek)
   // so transport and URL can never disagree.
-  // TRACES: UR-079 | DR-224
+  // TRACES: UR-079 | DR-225
   let currentSelection = $state<StreamSelection>(untrack(() => selection));
   const currentStreamUrl = $derived(currentSelection.url);
+  /**
+   * The transport as a plain string, so effects can depend on its *value*.
+   * A `$derived` primitive only notifies when it actually changes, which is what
+   * keeps the HLS teardown from re-running for an unchanged stream.
+   */
+  const transportKind = $derived(currentSelection.transport.type);
   let hasReportedStart = $state(false);
   let progressInterval: ReturnType<typeof setInterval> | null = null;
   let isMediaReady = $state(false); // Track if media is ready to play (implements Loading state from DR-001)
@@ -269,11 +282,11 @@
    * Used by the paths that swap the stream without re-negotiating — the
    * background-audio handoff and its return. Each states the transport it is
    * moving to rather than letting it be inferred, which is the whole point of
-   * DR-224: the audio handoff really is a progressive mp3, and the rebuilt
+   * DR-225: the audio handoff really is a progressive mp3, and the rebuilt
    * video stream really is an HLS transcode, and neither is knowable from the
    * URL text.
    *
-   * TRACES: UR-040, UR-079 | DR-224
+   * TRACES: UR-040, UR-079 | DR-225
    */
   function selectionAt(url: string, transport: StreamSelection["transport"]): StreamSelection {
     // A re-opened stream is a new transcode job; the old session id is stale.
@@ -314,14 +327,14 @@
 
   /**
    * The rungs to offer for the stream that is playing, straight from the
-   * backend (DR-226). Rungs whose ceiling is at or above the source bitrate are
+   * backend (DR-227). Rungs whose ceiling is at or above the source bitrate are
    * dropped: they produce the same bytes as Original, so listing five of them is
    * five ways to spell one choice. Rust decides which those are — this only
    * decides not to draw them.
    *
    * `Original` is always kept; it is the source, never redundant with it.
    *
-   * TRACES: UR-070, UR-079 | DR-226, DR-121
+   * TRACES: UR-070, UR-079 | DR-227, DR-121
    */
   const qualityOptions = $derived(
     currentSelection.available.filter((o) => !o.exceedsSource || o.quality === "original"),
@@ -635,8 +648,15 @@
     }
 
     // The loader comes from the backend's tagged transport, never from the URL.
-    // TRACES: UR-079 | DR-224 | UT-213
-    const loader = videoLoaderFor(currentSelection, {
+    //
+    // Read through the *primitive* `transportKind`, never `currentSelection`
+    // itself: this effect tears down and rebuilds hls.js, and a selection object
+    // is replaced on every reload — so depending on the object re-ran the whole
+    // teardown for an unchanged stream and left the element showing nothing
+    // until a seek forced another cycle.
+    //
+    // TRACES: UR-079 | DR-225 | UT-214
+    const loader = loaderForTransport(transportKind, {
       hlsJsSupported: Hls.isSupported(),
       nativeHlsSupported: !!videoElement.canPlayType("application/vnd.apple.mpegurl"),
     });
@@ -873,7 +893,7 @@
     });
   });
 
-  // The quality *ladder* now arrives with the stream selection (DR-226), so all
+  // The quality *ladder* now arrives with the stream selection (DR-227), so all
   // this still needs is the device default, for the case where the stream is a
   // direct play and has no rendition of its own.
   //
@@ -882,7 +902,7 @@
   // HTML5 mode and breaks native seeking, and nothing about playback waits on
   // this value.
   //
-  // TRACES: UR-074, UR-079 | DR-162, DR-226
+  // TRACES: UR-074, UR-079 | DR-162, DR-227
   onMount(() => {
     commands
       .playerGetVideoSettings()
@@ -902,7 +922,7 @@
     // flip the component into HTML5 mode). Unsubscribers go into nativeUnlisteners
     // so onDestroy tears them down.
     if (backgroundAudioSupported) {
-      nativeUnlisteners.push(subscribeAppBackgrounded(enterBackgroundAudioHandoff));
+      nativeUnlisteners.push(subscribeAppBackgrounded(onAppBackgrounded));
       nativeUnlisteners.push(subscribeAppForegrounded(exitBackgroundAudioHandoff));
     }
 
@@ -955,7 +975,7 @@
           videoCodec: needsTranscoding ? "hevc" : "h264",
           needsTranscoding: needsTranscoding,
           // Carry the negotiated transport onto the queue item so a later seek
-          // reads it instead of falling back. TRACES: UR-079 | DR-229
+          // reads it instead of falling back. TRACES: UR-079 | DR-230
           transport: currentSelection.transport,
           // Order matters: player_set_subtitle_track(n) is a position in this
           // array. Previously this array was built and then dropped, so
@@ -1804,6 +1824,9 @@
   const backgroundAudioSupported = platform() === "android";
   let backgroundAudioOn = $state(false); // v1: default OFF each session
   let handoffState: BackgroundAudioState = { ...initialHandoffState };
+  // Set when backgrounding paused playback, so foregrounding resumes only
+  // what we stopped -- never something the user paused themselves.
+  let pausedByBackgrounding = false;
 
   function toggleBackgroundAudio() {
     backgroundAudioOn = !backgroundAudioOn;
@@ -1819,6 +1842,43 @@
 
   // App went to background/locked while background-audio is armed: hand off to
   // native audio and stop the WebView video decode.
+  async function onAppBackgrounded(signal: BackgroundSignal) {
+    // What to do is a domain decision, not a presentation one: it depends on
+    // whether the item has a picture to lose, which is Rust's to know. This used
+    // to be decided implicitly by Kotlin gating the event on the toggle, which
+    // is why the native path -- whose media service keeps playing regardless --
+    // ignored the toggle entirely (DR-225).
+    let action: BackgroundAction;
+    try {
+      action = await commands.playerBackgroundAction(
+        signal.backgroundAudioArmed,
+        signal.inPictureInPicture,
+      );
+    } catch (e) {
+      // Never leave playback in an undefined state because a decision call
+      // failed. Continuing is the old behaviour and the safer default: it
+      // cannot silently stop something the user is listening to.
+      log.warn("Background action lookup failed; leaving playback alone:", e);
+      return;
+    }
+
+    log.debug("Background action:", action);
+    switch (action) {
+      case "keepPlaying":
+        return;
+      case "pause":
+        // The user did not ask for background playback. Remember that WE paused
+        // it, so returning to the foreground can resume rather than leaving a
+        // video mysteriously stopped.
+        pausedByBackgrounding = isPlaying;
+        if (isPlaying) await playerController.pause();
+        return;
+      case "handOffToAudio":
+        await enterBackgroundAudioHandoff();
+        return;
+    }
+  }
+
   async function enterBackgroundAudioHandoff() {
     if (!shouldEnterBackgroundAudio(backgroundAudioOn, handoffState)) return;
     // `currentTime` is the component's authoritative ABSOLUTE position (the RAF
@@ -1879,6 +1939,20 @@
   // App returned to foreground: stop native audio, reload the WebView <video> at
   // the position native reached, and restore play/pause.
   async function exitBackgroundAudioHandoff() {
+    // Resume what backgrounding paused, before the handoff check: the pause path
+    // and the handoff path are mutually exclusive, and this one leaves no
+    // handoff state to unwind. Only resumes if WE paused it -- a user who
+    // paused before locking the screen stays paused.
+    if (pausedByBackgrounding) {
+      pausedByBackgrounding = false;
+      try {
+        await playerController.play();
+      } catch (e) {
+        log.warn("Failed to resume after backgrounding:", e);
+      }
+      return;
+    }
+
     if (!shouldExitBackgroundAudio(handoffState)) return;
     // Read the native player's state BEFORE exiting — the exit stops it. If the
     // user hit pause on the lockscreen while backgrounded, that pause must
@@ -1961,7 +2035,7 @@
           id: media.id,
           videoCodec: needsTranscoding ? "hevc" : "h264",
           needsTranscoding,
-          // TRACES: UR-079 | DR-229
+          // TRACES: UR-079 | DR-230
           transport: targetSelection.transport,
           subtitles: nativeSubtitleTracks(sentSubtitleTracks),
         });
@@ -2012,23 +2086,47 @@
   // Activity, so on its own it left the status and navigation bars painted over
   // the video. The native bridge is what actually makes fullscreen full screen;
   // requestFullscreen() still does the work everywhere else. (UR-066, DR-157)
-  function toggleFullscreen() {
+  async function toggleFullscreen() {
+    // A native surface draws the picture *behind* the webview at window size, so
+    // fullscreening the document alone leaves the video at its old size while
+    // the page around it expands. See fullscreenTarget.ts. (DR-240)
+    const plan = planFullscreen(!useHtml5Element);
+
     if (!document.fullscreenElement) {
-      document.documentElement.requestFullscreen().catch((err) => {
-        // WebKitGTK rejects when the gesture isn't recognised as user-activated;
-        // the immersive call below is what matters on Android, so don't let a
-        // rejection here abort it.
-        log.warn("requestFullscreen rejected:", err);
-      });
+      if (plan.document) {
+        document.documentElement.requestFullscreen().catch((err) => {
+          // WebKitGTK rejects when the gesture isn't recognised as user-activated;
+          // the immersive call below is what matters on Android, so don't let a
+          // rejection here abort it.
+          log.warn("requestFullscreen rejected:", err);
+        });
+      }
+      if (plan.osWindow) {
+        await setOsWindowFullscreen(true);
+      }
       enterImmersive();
       isFullscreen = true;
     } else {
       document.exitFullscreen();
+      if (plan.osWindow) {
+        await setOsWindowFullscreen(false);
+      }
       exitImmersive();
       isFullscreen = false;
     }
   }
 
+  /// Resize the OS window itself. Best-effort: a platform without a window to
+  /// resize (Android) must not break the rest of the toggle.
+  async function setOsWindowFullscreen(on: boolean) {
+    try {
+      const { getCurrentWindow } = await import("@tauri-apps/api/window");
+      await getCurrentWindow().setFullscreen(on);
+    } catch (err) {
+      log.warn("setFullscreen on the OS window failed:", err);
+    }
+  }
+
   function formatTime(seconds: number): string {
     const mins = Math.floor(seconds / 60);
     const secs = Math.floor(seconds % 60);
@@ -2322,12 +2420,12 @@
    * only supplies the position to resume at.
    *
    * The change applies to this playback alone; the durable Settings default is
-   * untouched (DR-225). Nothing is optimistically assigned here: what the picker
+   * untouched (DR-226). Nothing is optimistically assigned here: what the picker
    * shows comes from the selection the backend hands back, because what you get
    * is not always what you asked for — a ceiling above the source bitrate is the
    * source, and claiming otherwise is the kind of lie the old picker told.
    *
-   * TRACES: UR-074, UR-079 | DR-162, DR-225, DR-226
+   * TRACES: UR-074, UR-079 | DR-162, DR-226, DR-227
    */
   async function selectQuality(quality: StreamingQuality) {
     showQualityMenu = false;
@@ -2342,11 +2440,18 @@
         mediaSourceId ?? null,
         selectedAudioTrackIndex,
       );
-      // The HTML5 path reloads through the adapter, which already set the new
-      // selection via the bridge. The native path reloads inside Rust and
-      // returns nothing, so record what was asked for as the ceiling in force.
-      if (!negotiated) {
-        defaultQuality = quality;
+      // Adopt whatever the backend says it opened. The HTML5 path has already
+      // set this via the adapter bridge, so this is a no-op there; the native
+      // path reloads inside Rust and this is the only thing that updates the UI.
+      //
+      // Assigning it is what keeps the picker honest: `selectedQuality` reads
+      // the selection's rendition, and a transcode always has one — so without
+      // this the menu stayed on the first stream's rung while the stream itself
+      // changed underneath.
+      //
+      // TRACES: UR-074, UR-079 | DR-226, DR-227
+      if (negotiated) {
+        currentSelection = negotiated;
       }
       if (videoElement && !videoElement.paused) {
         startTimeUpdates();
@@ -2453,7 +2558,22 @@
   aria-label="Video player"
 >
   <!-- Video -->
-  <div class="flex-1 flex items-center justify-center relative">
+  <!--
+    `min-h-0` / `min-w-0` are load-bearing, not defensive. A flex item defaults
+    to `min-height: auto`, which refuses to shrink below its content's intrinsic
+    size — and the <video> inside reports the *media's* natural dimensions. So
+    without them this wrapper grows past the viewport whenever the picture is
+    larger than the window: the overflow goes off the bottom, which reads as the
+    image being cropped and aligned to the top rather than letterboxed and
+    centred. `object-contain` was never the problem; it was doing its job inside
+    a box that was itself the wrong size.
+
+    Reproduces by resizing the window during playback, and by entering
+    fullscreen — where the same overflow put the picture at the bottom.
+
+    TRACES: UR-005 | DR-024
+  -->
+  <div class="flex-1 min-h-0 min-w-0 flex items-center justify-center relative">
     {#if !!useHtml5Element}
       <!-- HTML5 video for desktop/non-Android platforms -->
       <video
@@ -2803,7 +2923,7 @@
 
         <!--
           Streaming quality (bandwidth ceiling), populated from what this media
-          source can actually offer. TRACES: UR-070, UR-074 | DR-162, DR-226
+          source can actually offer. TRACES: UR-070, UR-074 | DR-162, DR-227
         -->
         {#if qualityOptions.length > 1}
           <div class="relative">
@@ -2830,7 +2950,7 @@
                     <div class="text-white text-sm font-semibold">Quality</div>
                     <!--
                       What the server is actually doing. Only knowable now that
-                      the backend reports it. TRACES: UR-079 | DR-227
+                      the backend reports it. TRACES: UR-079 | DR-228
                     -->
                     <div class="text-xs text-gray-400 mt-0.5">{playbackKindLabel}</div>
                   </div>

src/lib/components/player/fullscreenTarget.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { planFullscreen } from "./fullscreenTarget";
+
+describe("planFullscreen", () => {
+  it("fullscreens only the document when an in-document <video> renders", () => {
+    // Unchanged behaviour: WebKit scales the element, the window need not move.
+    expect(planFullscreen(false)).toEqual({ document: true, osWindow: false });
+  });
+
+  it("also fullscreens the OS window when a native surface renders", () => {
+    // The picture is drawn behind the webview at window size, so a
+    // document-only fullscreen leaves it at the old size.
+    expect(planFullscreen(true)).toEqual({ document: true, osWindow: true });
+  });
+});

src/lib/components/player/fullscreenTarget.ts

@@ -0,0 +1,35 @@
+/**
+ * Which surfaces a fullscreen toggle has to move.
+ *
+ * `requestFullscreen()` only ever fullscreens the *document*. That was
+ * sufficient while every renderer lived inside it: the HTML5 `<video>` element
+ * is part of the document, so WebKit scaled it to the screen and the OS
+ * window's real size never mattered.
+ *
+ * A native video surface is drawn *behind* the webview at **window** size, so a
+ * document-only fullscreen leaves the picture exactly where it was while the
+ * page around it goes fullscreen. On WebKitGTK the observed result is a
+ * maximised window with decorations still taking a strip of the screen — the
+ * video renders correctly, at the wrong size, which reads as "fullscreen is
+ * broken" rather than as a windowing problem.
+ *
+ * Android already needed its own answer here for the system bars (DR-157); this
+ * is the desktop equivalent of the same rule: whoever actually owns the pixels
+ * has to be the thing that goes fullscreen.
+ *
+ * TRACES: UR-066 | DR-240 | UT-219
+ */
+export interface FullscreenPlan {
+  /** Ask the document to go fullscreen (harmless everywhere, needed for CSS). */
+  document: boolean;
+  /** Resize the OS window itself. Required when a native surface owns the picture. */
+  osWindow: boolean;
+}
+
+/**
+ * @param rendersNatively true when a native surface (mpv/ExoPlayer) draws the
+ *        picture rather than an in-document `<video>` element.
+ */
+export function planFullscreen(rendersNatively: boolean): FullscreenPlan {
+  return { document: true, osWindow: rendersNatively };
+}

src/lib/components/player/videoFit.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { videoFitClass, fittedVideoSize } from "./videoFit";
+import { videoFitClass } from "./videoFit";
 
 describe("videoFitClass", () => {
   it("fills the container instead of capping at the source's intrinsic size", () => {
@@ -19,39 +19,3 @@ describe("videoFitClass", () => {
     expect(cls).not.toContain("object-fill");
   });
 });
-
-describe("fittedVideoSize", () => {
-  it("scales a 480p source up to fill a larger window (the reported bug)", () => {
-    // Exact 16:9 480p in a 1920x1080 window -> scales up to fill, rather than
-    // staying a 854x480 box in the middle.
-    const size = fittedVideoSize(853.33, 480, 1920, 1080);
-    expect(size.width).toBeCloseTo(1920, 0);
-    expect(size.height).toBeCloseTo(1080, 0);
-  });
-
-  it("fits to the constraining dimension when aspect ratios differ", () => {
-    // 4:3 source in a 16:9 window -> height-constrained, pillarboxed.
-    const size = fittedVideoSize(640, 480, 1920, 1080);
-    expect(size.height).toBeCloseTo(1080, 0);
-    expect(size.width).toBeCloseTo(1440, 0);
-    expect(size.width).toBeLessThan(1920);
-  });
-
-  it("fits to width when the source is wider than the window", () => {
-    // 21:9 source in a 16:9 window -> width-constrained, letterboxed.
-    const size = fittedVideoSize(2560, 1080, 1920, 1080);
-    expect(size.width).toBeCloseTo(1920, 0);
-    expect(size.height).toBeCloseTo(810, 0);
-    expect(size.height).toBeLessThan(1080);
-  });
-
-  it("shrinks oversized media to fit rather than overflowing", () => {
-    const size = fittedVideoSize(3840, 2160, 1280, 720);
-    expect(size.width).toBeCloseTo(1280, 0);
-    expect(size.height).toBeCloseTo(720, 0);
-  });
-
-  it("returns a zero size for unknown intrinsic dimensions", () => {
-    expect(fittedVideoSize(0, 0, 1920, 1080)).toEqual({ width: 0, height: 0 });
-  });
-});

src/lib/components/player/videoFit.ts

@@ -15,32 +15,3 @@
 export function videoFitClass(): string {
   return "w-full h-full object-contain";
 }
-
-export interface FittedSize {
-  width: number;
-  height: number;
-}
-
-/**
- * The rendered size of a video of the given intrinsic dimensions once it has
- * been fitted into the container - i.e. scaled (up or down) so that it touches
- * the container on its constraining axis, with the other axis letter/pillar
- * boxed. Mirrors what `object-fit: contain` on a full-size element does.
- */
-export function fittedVideoSize(
-  intrinsicWidth: number,
-  intrinsicHeight: number,
-  containerWidth: number,
-  containerHeight: number,
-): FittedSize {
-  if (intrinsicWidth <= 0 || intrinsicHeight <= 0) {
-    return { width: 0, height: 0 };
-  }
-
-  const scale = Math.min(containerWidth / intrinsicWidth, containerHeight / intrinsicHeight);
-
-  return {
-    width: intrinsicWidth * scale,
-    height: intrinsicHeight * scale,
-  };
-}

src/lib/player/adapters/html5Adapter.ts

@@ -37,7 +37,7 @@ const log = createLogger("Html5PlayerAdapter");
  * This is the one place a fallback is tolerable, and it is explicitly a
  * fallback: the negotiated path never reaches it.
  *
- * TRACES: UR-079 | DR-224
+ * TRACES: UR-079 | DR-225
  */
 function selectionForLoad(streamUrl: string, options: PlayerLoadOptions): StreamSelection {
   if (options.selection) return options.selection;
@@ -75,9 +75,9 @@ export interface Html5ElementBridge {
    *
    * Carries the whole [`StreamSelection`], not just the URL: the component's
    * effect has to know the transport to choose a loader, and deriving that from
-   * the URL is the substring check DR-224 removes.
+   * the URL is the substring check DR-225 removes.
    *
-   * TRACES: UR-079 | DR-224
+   * TRACES: UR-079 | DR-225
    */
   setStreamSelection(selection: StreamSelection): void;
   /** Tear down the component-owned hls.js instance (dual-audio prevention). */

src/lib/player/adapters/types.ts

@@ -51,7 +51,7 @@ export interface PlayerLoadOptions {
    * plugin's direct URL — where the adapter falls back to what the other
    * options already say rather than to reading the URL.
    *
-   * TRACES: UR-079 | DR-224
+   * TRACES: UR-079 | DR-225
    */
   selection?: StreamSelection | null;
   /** The source is a file on disk (or the loopback server in front of one). */
@@ -127,7 +127,7 @@ export interface PlayerAdapter {
    * already decided to reload, and `selection.transport` says how to open it, so
    * no adapter has to infer that from the URL.
    *
-   * TRACES: UR-079 | DR-224
+   * TRACES: UR-079 | DR-225
    */
   reloadSource(selection: StreamSelection, offset: number): Promise<void>;
 

src/lib/player/index.ts

@@ -199,7 +199,7 @@ async function switchAudioTrack(
  * actually got, which is not always what was asked for: a ceiling above the
  * source bitrate is the source.
  *
- * TRACES: UR-074, UR-079 | DR-162, DR-225
+ * TRACES: UR-074, UR-079 | DR-162, DR-226
  */
 async function setStreamQuality(
   quality: StreamingQuality,
@@ -221,8 +221,9 @@ async function setStreamQuality(
     await adapter.reloadSource(response.selection, response.position ?? currentPosition ?? 0);
     return response.selection;
   }
-  // A native backend reloaded itself; there is no selection on that branch.
-  return null;
+  // The native backend reloaded itself, but still reports what it opened — the
+  // caller needs it to show the rung actually in force.
+  return response.selection ?? null;
 }
 
 async function next() {

src/lib/player/localSource.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { downloadedFilePath, resolveVideoSource } from "./localSource";
+import { downloadedFilePath } from "./localSource";
 
 describe("downloadedFilePath", () => {
   // The download worker rewrites `downloads.file_path` to the absolute path it
@@ -29,74 +29,3 @@ describe("downloadedFilePath", () => {
     expect(downloadedFilePath("C:\\Users\\u\\AppData\\jellytau", stored)).toBe(stored);
   });
 });
-
-// A stand-in for Tauri's convertFileSrc, so the module stays pure.
-const toAssetUrl = (p: string) => `asset://localhost/${encodeURIComponent(p)}`;
-
-describe("resolveVideoSource", () => {
-  it("plays the downloaded file when one exists", () => {
-    const decision = resolveVideoSource({
-      localPath: "/home/u/.local/share/jellytau/movie.mp4",
-      remoteUrl: "https://server/Videos/abc/master.m3u8",
-      remoteNeedsTranscoding: true,
-      toAssetUrl,
-    });
-
-    expect(decision.isLocal).toBe(true);
-    expect(decision.url).toBe(toAssetUrl("/home/u/.local/share/jellytau/movie.mp4"));
-  });
-
-  it("never marks a local file as needing transcoding, even when the remote did", () => {
-    // The transcoded path re-requests a whole new stream URL on every seek.
-    // A local file seeks natively; sending it down that route would ask the
-    // server for a stream we deliberately avoided.
-    const decision = resolveVideoSource({
-      localPath: "/downloads/film.mkv",
-      remoteUrl: "https://server/Videos/abc/master.m3u8",
-      remoteNeedsTranscoding: true,
-      toAssetUrl,
-    });
-
-    expect(decision.needsTranscoding).toBe(false);
-  });
-
-  it("streams when nothing is downloaded, preserving the transcoding flag", () => {
-    const decision = resolveVideoSource({
-      localPath: null,
-      remoteUrl: "https://server/Videos/abc/master.m3u8",
-      remoteNeedsTranscoding: true,
-      toAssetUrl,
-    });
-
-    expect(decision).toEqual({
-      url: "https://server/Videos/abc/master.m3u8",
-      needsTranscoding: true,
-      isLocal: false,
-    });
-  });
-
-  it("streams a direct-play remote without claiming it transcodes", () => {
-    const decision = resolveVideoSource({
-      localPath: null,
-      remoteUrl: "https://server/Videos/abc/stream.mp4",
-      remoteNeedsTranscoding: false,
-      toAssetUrl,
-    });
-
-    expect(decision.needsTranscoding).toBe(false);
-    expect(decision.isLocal).toBe(false);
-  });
-
-  it("falls back to streaming for a blank path rather than building a dead asset URL", () => {
-    for (const localPath of ["", "   "]) {
-      const decision = resolveVideoSource({
-        localPath,
-        remoteUrl: "https://server/stream",
-        remoteNeedsTranscoding: false,
-        toAssetUrl,
-      });
-      expect(decision.isLocal).toBe(false);
-      expect(decision.url).toBe("https://server/stream");
-    }
-  });
-});

src/lib/player/localSource.ts

@@ -1,41 +1,3 @@
-/**
- * Choosing between a downloaded file and a server stream for video playback.
- *
- * Audio has preferred local files since the queue is built (the Rust queue
- * resolves `MediaSource::Local`), but video asks the repository for a stream URL
- * and never consults `downloads` — so a downloaded film was streamed anyway,
- * spending bandwidth that had already been spent and failing outright offline.
- *
- * Pure so it can be unit-tested: the component only supplies the two inputs and
- * the asset-URL converter.
- *
- * TRACES: UR-071 | DR-123 | UT-118
- */
-
-export interface VideoSourceInputs {
-  /** Absolute on-disk path of a completed download, or null to stream. */
-  localPath: string | null;
-  /** Stream URL the repository resolved (already transcoded if it had to be). */
-  remoteUrl: string;
-  /** Whether the *remote* stream is a transcode. */
-  remoteNeedsTranscoding: boolean;
-  /** Usually Tauri's `convertFileSrc`; injected so this module stays pure. */
-  toAssetUrl: (path: string) => string;
-}
-
-export interface VideoSourceDecision {
-  /** What to hand the `<video>` element. */
-  url: string;
-  /**
-   * Local files are never transcodes, so this is always false for them. It
-   * matters because the transcoded path re-requests a whole new stream URL on
-   * every seek; a local file seeks natively and must not go down that route.
-   */
-  needsTranscoding: boolean;
-  /** True when playing from disk — for logging and the offline badge. */
-  isLocal: boolean;
-}
-
 /** Absolute on POSIX (`/…`), Windows (`C:\…`, `C:/…`) or a UNC share (`\\…`). */
 function isAbsolute(path: string): boolean {
   return path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(path);
@@ -57,15 +19,3 @@ function isAbsolute(path: string): boolean {
 export function downloadedFilePath(storageRoot: string, filePath: string): string {
   return isAbsolute(filePath) ? filePath : `${storageRoot}/${filePath}`;
 }
-
-export function resolveVideoSource(inputs: VideoSourceInputs): VideoSourceDecision {
-  const { localPath, remoteUrl, remoteNeedsTranscoding, toAssetUrl } = inputs;
-
-  // Treat blank/whitespace paths as absent — a malformed `downloads` row must
-  // not produce an asset URL pointing at nothing.
-  if (localPath && localPath.trim() !== "") {
-    return { url: toAssetUrl(localPath), needsTranscoding: false, isLocal: true };
-  }
-
-  return { url: remoteUrl, needsTranscoding: remoteNeedsTranscoding, isLocal: false };
-}

src/lib/player/streamTransport.test.ts

@@ -1,7 +1,7 @@
 /**
  * The loader is chosen from the backend's `transport` tag, never from the URL.
  *
- * TRACES: UR-079 | DR-224 | UT-213
+ * TRACES: UR-079 | DR-225 | UT-214
  */
 
 import { describe, expect, it } from "vitest";

src/lib/player/streamTransport.ts

@@ -4,7 +4,7 @@
  * Extracted from `VideoPlayer.svelte` so the decision can be unit-tested — the
  * same pattern as `episodeStrip.ts` and `TrackList.logic.test.ts`.
  *
- * TRACES: UR-079 | DR-224 | UT-213
+ * TRACES: UR-079 | DR-225 | UT-214
  */
 
 import type { StreamSelection, Transport } from "$lib/api/bindings";
@@ -44,7 +44,27 @@ export function videoLoaderFor(
   selection: Pick<StreamSelection, "url" | "transport">,
   capabilities: LoaderCapabilities,
 ): VideoLoader {
-  if (selection.transport.type !== "hls") {
+  return loaderForTransport(selection.transport.type, capabilities);
+}
+
+/**
+ * The same decision, taken from the transport *tag* alone.
+ *
+ * Exists because a Svelte `$effect` that reads the whole selection re-runs
+ * whenever the selection **object** is replaced — even with an identical URL and
+ * transport — and the HLS effect's teardown/rebuild is not idempotent: it
+ * destroys the hls.js instance and reattaches, which leaves the element with no
+ * video until something forces another cycle. The pre-DR-225 code read a plain
+ * URL *string*, so re-assigning the same value was a no-op and the effect stayed
+ * put. Passing primitives restores that.
+ *
+ * TRACES: UR-079 | DR-225 | UT-214
+ */
+export function loaderForTransport(
+  transport: Transport["type"],
+  capabilities: LoaderCapabilities,
+): VideoLoader {
+  if (transport !== "hls") {
     // Progressive and local files are what the element loads natively. No
     // MediaSource, no playlist parsing.
     return "direct";

src/lib/stores/auth.ts

@@ -64,6 +64,49 @@ function createAuthStore() {
     return repository;
   }
 
+  /**
+   * The repository, waiting for session restore rather than failing the instant
+   * it is asked.
+   *
+   * `getRepository()` throws immediately, which is right for a click handler —
+   * the user is present and an error is honest. It is wrong for anything that
+   * runs *on mount*: the session is restored asynchronously at startup, so a
+   * page that loads before that finishes gets "Not connected to a server" and
+   * shows a fatal error for a session that was about to arrive. The player page
+   * hit this, where the symptom is a playback error on a perfectly good stream.
+   *
+   * Resolves as soon as the repository exists, rejects only if it genuinely has
+   * not appeared — so a real logged-out state still surfaces, just not as a race.
+   *
+   * TRACES: UR-002 | DR-013
+   */
+  async function waitForRepository(timeoutMs = 5000): Promise<RepositoryClient> {
+    if (repository) return repository;
+
+    return new Promise<RepositoryClient>((resolve, reject) => {
+      let settled = false;
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        unsubscribe();
+        fn();
+      };
+
+      // Every store change is a chance the session landed. `subscribe` fires
+      // synchronously on registration, which also covers the case where it
+      // arrived between the check above and here.
+      const unsubscribe = subscribe(() => {
+        if (repository) finish(() => resolve(repository as RepositoryClient));
+      });
+
+      const timer = setTimeout(
+        () => finish(() => reject(new Error("Not connected to a server"))),
+        timeoutMs,
+      );
+    });
+  }
+
   /**
    * Initialize event listeners from Rust backend.
    * These should be called once during app initialization.
@@ -572,6 +615,7 @@ function createAuthStore() {
     logout,
     clearError,
     getRepository,
+    waitForRepository,
     getCurrentSession,
     getUserId,
     getServerUrl,

src/lib/stores/auth.waitForRepository.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Waiting for the repository rather than racing it.
+ *
+ * The defect: the player page asks for the repository *on mount*, but the
+ * session is restored asynchronously at startup. Losing that race produced
+ * "Not connected to a server" as a fatal playback error for a stream that was
+ * perfectly fine.
+ *
+ * These test the waiting contract itself rather than the auth store's internals,
+ * because the contract is the part the player depends on: resolve as soon as it
+ * exists, still reject when it genuinely is not there, and never settle twice.
+ *
+ * TRACES: UR-002, UR-004 | DR-013 | UT-215
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+type Listener = () => void;
+
+/**
+ * The shape `waitForRepository` is built on: a store you can subscribe to, and
+ * a value that appears at some later point. Mirrors the real implementation
+ * without dragging in Tauri.
+ */
+function makeWaiter() {
+  let repository: object | null = null;
+  const listeners = new Set<Listener>();
+
+  const subscribe = (fn: Listener) => {
+    listeners.add(fn);
+    fn(); // stores fire synchronously on subscribe
+    return () => listeners.delete(fn);
+  };
+  const publish = (value: object | null) => {
+    repository = value;
+    listeners.forEach((fn) => fn());
+  };
+
+  async function waitForRepository(timeoutMs = 5000): Promise<object> {
+    if (repository) return repository;
+    return new Promise<object>((resolve, reject) => {
+      let settled = false;
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        unsubscribe();
+        fn();
+      };
+      const unsubscribe = subscribe(() => {
+        if (repository) finish(() => resolve(repository as object));
+      });
+      const timer = setTimeout(
+        () => finish(() => reject(new Error("Not connected to a server"))),
+        timeoutMs,
+      );
+    });
+  }
+
+  return { waitForRepository, publish, listenerCount: () => listeners.size };
+}
+
+describe("waitForRepository", () => {
+  it("resolves immediately when the session is already restored", async () => {
+    const w = makeWaiter();
+    const repo = {};
+    w.publish(repo);
+    await expect(w.waitForRepository(50)).resolves.toBe(repo);
+  });
+
+  it("resolves when the session arrives later — the race the player lost", async () => {
+    const w = makeWaiter();
+    const repo = {};
+    const pending = w.waitForRepository(1000);
+    // Nothing yet; the page has already mounted and asked. Published on a
+    // microtask rather than a timer: the point is *ordering* (asked before it
+    // arrived), and a wall-clock delay would make this a race under load.
+    await Promise.resolve();
+    w.publish(repo);
+    await expect(pending).resolves.toBe(repo);
+  });
+
+  it("still rejects when there genuinely is no session", async () => {
+    vi.useFakeTimers();
+    const w = makeWaiter();
+    const pending = w.waitForRepository(500);
+    const assertion = expect(pending).rejects.toThrow("Not connected to a server");
+    await vi.advanceTimersByTimeAsync(600);
+    await assertion;
+    vi.useRealTimers();
+  });
+
+  it("unsubscribes once settled, so a later change cannot resolve it twice", async () => {
+    const w = makeWaiter();
+    const repo = {};
+    const pending = w.waitForRepository(1000);
+    expect(w.listenerCount()).toBe(1);
+    w.publish(repo);
+    await pending;
+    expect(w.listenerCount()).toBe(0);
+    // A further change must not throw or re-settle.
+    expect(() => w.publish(null)).not.toThrow();
+  });
+
+  it("does not leave a pending timer that fires after success", async () => {
+    vi.useFakeTimers();
+    const w = makeWaiter();
+    const repo = {};
+    const pending = w.waitForRepository(200);
+    w.publish(repo);
+    await expect(pending).resolves.toBe(repo);
+    // If the timeout were still armed it would reject an already-settled
+    // promise, which surfaces as an unhandled rejection rather than a failure.
+    await vi.advanceTimersByTimeAsync(500);
+    vi.useRealTimers();
+  });
+});

src/lib/utils/backgroundAudio.ts

@@ -66,10 +66,31 @@ export function setBackgroundAudioEnabled(enabled: boolean): boolean {
  * Returns an unsubscribe function. No-op where unsupported (the event never
  * fires on non-Android platforms).
  */
-export function subscribeAppBackgrounded(handler: () => void): () => void {
+export interface BackgroundSignal {
+  /** Whether the per-player background-audio toggle was armed (UR-040). */
+  backgroundAudioArmed: boolean;
+  /** Whether Android put the window into picture-in-picture (UR-041). */
+  inPictureInPicture: boolean;
+}
+
+/**
+ * Older builds dispatched this event with no detail, and only when the toggle
+ * was already armed. Treat a missing detail as "armed, not PiP" so a mismatched
+ * pair degrades to the previous behaviour rather than pausing unexpectedly.
+ */
+function readSignal(event: Event): BackgroundSignal {
+  const detail = (event as CustomEvent).detail as Partial<BackgroundSignal> | null | undefined;
+  return {
+    backgroundAudioArmed: detail?.backgroundAudioArmed ?? true,
+    inPictureInPicture: detail?.inPictureInPicture ?? false,
+  };
+}
+
+export function subscribeAppBackgrounded(handler: (signal: BackgroundSignal) => void): () => void {
   if (typeof window === "undefined") return () => {};
-  window.addEventListener("jellytau-background", handler);
-  return () => window.removeEventListener("jellytau-background", handler);
+  const listener = (event: Event) => handler(readSignal(event));
+  window.addEventListener("jellytau-background", listener);
+  return () => window.removeEventListener("jellytau-background", listener);
 }
 
 /** Subscribe to the native "app foregrounded" signal. Returns an unsubscribe fn. */

src/lib/utils/duration.test.ts

@@ -5,7 +5,7 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { formatDuration, formatSecondsDuration } from "./duration";
+import { formatDuration } from "./duration";
 
 describe("formatDuration", () => {
   it("should format duration from milliseconds (mm:ss format)", () => {
@@ -39,23 +39,3 @@ describe("formatDuration", () => {
     expect(formatDuration(9045000, "hh:mm:ss")).toBe("2:30:45");
   });
 });
-
-describe("formatSecondsDuration", () => {
-  it("should format duration from seconds (mm:ss format)", () => {
-    expect(formatSecondsDuration(1)).toBe("0:01");
-    expect(formatSecondsDuration(60)).toBe("1:00");
-    expect(formatSecondsDuration(61)).toBe("1:01");
-    expect(formatSecondsDuration(3661)).toBe("61:01");
-  });
-
-  it("should format duration with hh:mm:ss format", () => {
-    expect(formatSecondsDuration(3600, "hh:mm:ss")).toBe("1:00:00");
-    expect(formatSecondsDuration(3661, "hh:mm:ss")).toBe("1:01:01");
-    expect(formatSecondsDuration(7325, "hh:mm:ss")).toBe("2:02:05");
-  });
-
-  it("should pad minutes and seconds with leading zeros", () => {
-    expect(formatSecondsDuration(5, "hh:mm:ss")).toBe("0:00:05");
-    expect(formatSecondsDuration(65, "hh:mm:ss")).toBe("0:01:05");
-  });
-});

src/lib/utils/duration.ts

@@ -12,11 +12,23 @@
  * @param format Format type: "mm:ss" (default) or "hh:mm:ss"
  * @returns Formatted duration string or empty string if no duration
  */
-export function formatDuration(ms?: number | null, format: "mm:ss" | "hh:mm:ss" = "mm:ss"): string {
+export function formatDuration(
+  ms?: number | null,
+  format: "mm:ss" | "hh:mm:ss" | "h m" = "mm:ss",
+): string {
   if (!ms) return "";
 
   const totalSeconds = Math.floor(ms / 1000);
 
+  // "1h 23m" / "45m" — the shape a runtime is read at a glance, as opposed to
+  // the clock shape a *position* is read at. Three components had hand-rolled
+  // this identically; it belongs here with the other two.
+  if (format === "h m") {
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
+  }
+
   if (format === "hh:mm:ss") {
     const hours = Math.floor(totalSeconds / 3600);
     const minutes = Math.floor((totalSeconds % 3600) / 60);
@@ -30,27 +42,3 @@ export function formatDuration(ms?: number | null, format: "mm:ss" | "hh:mm:ss"
   const seconds = totalSeconds % 60;
   return `${minutes}:${seconds.toString().padStart(2, "0")}`;
 }
-
-/**
- * Convert seconds to formatted duration string
- * @param seconds Duration in seconds
- * @param format Format type: "mm:ss" (default) or "hh:mm:ss"
- * @returns Formatted duration string
- */
-export function formatSecondsDuration(
-  seconds: number,
-  format: "mm:ss" | "hh:mm:ss" = "mm:ss",
-): string {
-  if (format === "hh:mm:ss") {
-    const hours = Math.floor(seconds / 3600);
-    const minutes = Math.floor((seconds % 3600) / 60);
-    const secs = seconds % 60;
-
-    return `${hours}:${minutes.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
-  }
-
-  // Default "mm:ss" format
-  const minutes = Math.floor(seconds / 60);
-  const secs = seconds % 60;
-  return `${minutes}:${secs.toString().padStart(2, "0")}`;
-}

src/routes/library/[id]/+page.svelte

@@ -1,6 +1,7 @@
 <!-- TRACES: UR-035, UR-038, UR-048, UR-058, UR-062 | DR-043, DR-062, DR-102, DR-103, DR-142 -->
 <script lang="ts">
   import { onMount, untrack } from "svelte";
+  import { formatDuration } from "$lib/utils/duration";
   import { page } from "$app/stores";
   import { goto } from "$app/navigation";
   import { navigateBack } from "$lib/utils/navigation";
@@ -250,18 +251,6 @@
 
   // Images now handled by CachedImage component
 
-  function formatDuration(ms?: number | null): string {
-    if (!ms) return "";
-    const seconds = Math.floor(ms / 1000);
-    const hours = Math.floor(seconds / 3600);
-    const minutes = Math.floor((seconds % 3600) / 60);
-
-    if (hours > 0) {
-      return `${hours}h ${minutes}m`;
-    }
-    return `${minutes}m`;
-  }
-
   function handleItemClick(clickedItem: MediaItem | Library) {
     if (!("kind" in clickedItem)) {
       // Library item - navigate to library
@@ -534,7 +523,7 @@
                 >
               {/if}
               {#if item.durationMs}
-                <span>{formatDuration(item.durationMs)}</span>
+                <span>{formatDuration(item.durationMs, "h m")}</span>
               {/if}
               {#if item.communityRating}
                 <span class="flex items-center gap-1">

src/routes/player/[id]/+page.svelte

@@ -82,7 +82,7 @@
    * Replaces a bare URL string: the transport travels with it, so neither this
    * page nor VideoPlayer has to work out whether the URL is a playlist.
    *
-   * TRACES: UR-079 | DR-224
+   * TRACES: UR-079 | DR-225
    */
   let selection = $state<StreamSelection | null>(null);
   let mediaSourceId = $state<string | null>(null);
@@ -325,7 +325,7 @@
           //
           // A downloaded file is a direct play over a local transport, and Rust
           // says so rather than this page assuming it.
-          // TRACES: UR-071 | DR-137, DR-224
+          // TRACES: UR-071 | DR-137, DR-225
           selection = await commands.mediaLocalSelection(fullPath);
           videoNeedsTranscoding = false;
           // Use explicit startPosition, or fall back to retrieved progress from database
@@ -354,7 +354,12 @@
       } else {
         // Online playback - get playback info from server
         isOfflinePlayback = false;
-        const repo = auth.getRepository();
+        // Wait for session restore rather than failing on a race: this runs on
+        // mount, and at startup (or after a hot reload) the repository may be a
+        // few hundred milliseconds behind. Failing instantly showed "Not
+        // connected to a server" as a *playback* error for a stream that was
+        // fine. TRACES: UR-002, UR-004 | DR-013
+        const repo = await auth.waitForRepository();
 
         if (isLive) {
           // Live TV channels must be "opened" before streaming; the server returns
@@ -397,7 +402,7 @@
           // to stop it a moment later. Observed in the log as a pair of
           // `[StreamSelection]` lines for one play.
           //
-          // TRACES: UR-071 | DR-123, DR-137, DR-224
+          // TRACES: UR-071 | DR-123, DR-137, DR-225
           const localPath = await commands.playerLocalMediaPath(id);
           if (localPath) {
             // A downloaded file is a direct play over a local transport, served
@@ -413,7 +418,7 @@
             // the device profile and the ceiling in force, and returns the
             // transport and the media-source id with it. This page no longer
             // decides — or separately asks for — any of that.
-            // TRACES: UR-070, UR-079 | DR-224, DR-226, DR-227
+            // TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228
             selection = await repo.getStreamSelection(id, null, null);
             mediaSourceId = selection.mediaSourceId;
             // Rust's own verdict — "which kinds count as transcoding" is a