From edff6eedc945c367f44505809e5ed80caa7cb4ca Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sat, 22 Aug 2026 10:09:46 +0200
Subject: [PATCH] fix(player): let the background-audio toggle govern
 backgrounding again

Locking the screen kept a video's audio playing whether or not the
background-audio button was on. Reported as "audio only mode is always
active even if not selected".

The button (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 entire purpose is to keep playing while the app is hidden. Nothing
stopped it, and nothing in the codebase paused on background.

So the button governed a handoff that no longer had a gap to bridge.
There was no interruption to paper over, and a user who never touched it
got background playback anyway.

The gating made it self-concealing: MainActivity.onStop only dispatched
'jellytau-background' when backgroundAudioEnabled was already true. The
one notification that the app had gone away was itself conditional on the
setting, so with the button OFF nothing could react even in principle.
onStop and onStart now fire unconditionally and carry the two facts only
the activity knows -- whether the toggle is armed, and whether Android
put the window into picture-in-picture.

What to do about it is decided in Rust (player/background_policy.rs),
because it depends on whether the item has a picture to lose:

  video + toggle off  -> Pause
  video + toggle on   -> HandOffToAudio
  music, either       -> KeepPlaying   (no picture to give up)
  picture-in-picture  -> KeepPlaying   (the window is still on screen)

It takes no renderer parameter on purpose. Two renderers with two
behaviours and one toggle reaching only one of them is what produced the
defect; a rule that cannot see the renderer cannot reproduce it.

Two failure modes are deliberate. A decision call that fails leaves
playback alone rather than risking silence mid-listen. An event with no
detail -- older Kotlin against newer JS -- reads as "armed, not PiP",
degrading to the previous behaviour instead of pausing unexpectedly.

Foregrounding resumes only what backgrounding paused: a video the user
paused themselves before locking stays paused.

Written test-first per CLAUDE.md. The stub encoded today's behaviour
(nothing ever pauses) and failed exactly as reported --
`left: KeepPlaying, right: Pause` -- before the rule was implemented.

Verified on a device, R8-minified, both directions:

  [player_background_action] video=true armed=false pip=false -> Pause
  [player_background_action] video=true armed=true  pip=false -> HandOffToAudio

UR-040 / DR-224 / UT-211.
---
 CHANGELOG.md                                  |  20 +++
 docs/requirements.md                          |   2 +
 docs/specs/README.md                          |   2 +-
 package.json                                  |   2 +-
 packaging/arch/PKGBUILD                       |   2 +-
 src-tauri/Cargo.lock                          |   2 +-
 src-tauri/Cargo.toml                          |   2 +-
 .../com/dtourolle/jellytau/MainActivity.kt    |  30 +++-
 src-tauri/src/commands/player/mod.rs          |  40 +++++
 src-tauri/src/lib.rs                          |   2 +
 src-tauri/src/player/background_policy.rs     | 155 ++++++++++++++++++
 src-tauri/src/player/mod.rs                   |   1 +
 src-tauri/tauri.conf.json                     |   2 +-
 src/lib/api/bindings.ts                       |  49 +++++-
 src/lib/components/player/VideoPlayer.svelte  |  59 ++++++-
 src/lib/utils/backgroundAudio.ts              |  27 ++-
 16 files changed, 372 insertions(+), 25 deletions(-)
 create mode 100644 src-tauri/src/player/background_policy.rs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 749a45ba..757e83bf 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/docs/requirements.md b/docs/requirements.md
index 093eac08..6c316fab 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -415,6 +415,7 @@ 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 | 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-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 |
 
 ---
@@ -715,6 +716,7 @@ 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 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 |
 
 ### Integration Tests
 
diff --git a/docs/specs/README.md b/docs/specs/README.md
index de490b95..8d1e8230 100644
--- a/docs/specs/README.md
+++ b/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-224**. Three specs below suggested ids that have since been
+**IR-033**, **DR-225**. Three specs below suggested ids that have since been
 taken by other work; each carries a ⚠️ note at the top.
 
 ## Partially implemented
diff --git a/package.json b/package.json
index 987be0bc..076b6226 100644
--- a/package.json
+++ b/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",
diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD
index 7444eb8b..a3414313 100644
--- a/packaging/arch/PKGBUILD
+++ b/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')
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index a6ffd327..b96e3fde 100644
--- a/src-tauri/Cargo.lock
+++ b/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",
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index e7b17df6..553eeca7 100644
--- a/src-tauri/Cargo.toml
+++ b/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"
diff --git a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt b/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
index 48dd08f5..01630e8f 100644
--- a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
+++ b/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")
diff --git a/src-tauri/src/commands/player/mod.rs b/src-tauri/src/commands/player/mod.rs
index 98fb636f..e02a6508 100644
--- a/src-tauri/src/commands/player/mod.rs
+++ b/src-tauri/src/commands/player/mod.rs
@@ -840,6 +840,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-224 | UT-211
+#[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]
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index a4ae4ca5..d838a1f7 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -121,6 +121,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
@@ -742,6 +743,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,
diff --git a/src-tauri/src/player/background_policy.rs b/src-tauri/src/player/background_policy.rs
new file mode 100644
index 00000000..716384b9
--- /dev/null
+++ b/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));
+    }
+}
diff --git a/src-tauri/src/player/mod.rs b/src-tauri/src/player/mod.rs
index 6746491b..ea5201b7 100644
--- a/src-tauri/src/player/mod.rs
+++ b/src-tauri/src/player/mod.rs
@@ -4,6 +4,7 @@
 //         DR-001, DR-004, DR-005, DR-009, DR-028, DR-029, DR-047
 pub mod autoplay;
 pub mod backend;
+pub mod background_policy;
 pub mod events;
 pub mod media;
 pub mod queue;
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index 73982d7e..df006be0 100644
--- a/src-tauri/tauri.conf.json
+++ b/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",
diff --git a/src/lib/api/bindings.ts b/src/lib/api/bindings.ts
index c65dcfbc..22e6d436 100644
--- a/src/lib/api/bindings.ts
+++ b/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-224 | UT-211
+ */
+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> {
@@ -1976,6 +1994,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
  */
diff --git a/src/lib/components/player/VideoPlayer.svelte b/src/lib/components/player/VideoPlayer.svelte
index 24644b29..c190b772 100644
--- a/src/lib/components/player/VideoPlayer.svelte
+++ b/src/lib/components/player/VideoPlayer.svelte
@@ -4,7 +4,7 @@
   import { get } from "svelte/store";
   import { goto } from "$app/navigation";
   import { commands } from "$lib/api/bindings";
-  import type { JRayActor, StreamingQuality } from "$lib/api/bindings";
+  import type { JRayActor, StreamingQuality, BackgroundAction } 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 +63,7 @@
   import {
     setBackgroundAudioEnabled,
     subscribeAppBackgrounded,
+    type BackgroundSignal,
     subscribeAppForegrounded,
   } from "$lib/utils/backgroundAudio";
   import { platform } from "@tauri-apps/plugin-os";
@@ -825,7 +826,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));
     }
 
@@ -1722,6 +1723,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;
@@ -1737,6 +1741,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-224).
+    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
@@ -1797,6 +1838,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
diff --git a/src/lib/utils/backgroundAudio.ts b/src/lib/utils/backgroundAudio.ts
index 68da300a..53f87b42 100644
--- a/src/lib/utils/backgroundAudio.ts
+++ b/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. */