fix(downloads): honor the selected bitrate (videoBitRate, capital R)

Downloading at a specific quality silently returned the full-size
original. The download URL builder spelled the transcode params
`videoBitrate`/`audioBitrate`, but Jellyfin binds `videoBitRate`/
`audioBitRate` — with a capital R.

Query-key binding is case-insensitive, so this is not a casing
preference: the lowercase-r form is a different token that fails to
bind. The server discards it without error and then stream-copies the
source, so picking "480p" produced an original-quality file with no
failure surfaced anywhere. `maxHeight`/`videoCodec` were unaffected
(case-insensitive binding covers them), which is why the height cap
applied while the bitrate cap vanished.

Also set `allowVideoStreamCopy=false` on the transcode presets to force
a real re-encode. Video stream-copy is gated by `allowVideoStreamCopy`,
not `enableAutoStreamCopy` — the latter governs audio only.

`original` is unchanged: it stays a deliberate direct static copy, now
pinned by a test.

The pre-existing unit tests asserted the broken lowercase-r spellings,
so they passed against broken code; corrected. Verified red -> green by
extracting the pre-fix and post-fix builder bodies into an isolated
harness: 15 assertion failures before, 0 after.

TRACES: UR-071 | DR-123

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/build-release.yml

@@ -96,6 +96,12 @@ jobs:
       - name: Install dependencies
         run: bun install
 
+      # The Linux job previously had no version step at all, so a tagged release
+      # built Linux packages from whatever version happened to be committed.
+      - name: Set app version from tag
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
+
       - name: Build for Linux
         run: bun run tauri build
         env:
@@ -156,15 +162,13 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-bun-
 
+      # The tag is the single source of truth for a release version; the script
+      # stamps every file that carries it (package.json, tauri.conf.json,
+      # Cargo.toml, Cargo.lock). This step used to sed only tauri.conf.json, so
+      # the other three shipped whatever was committed.
       - name: Set app version from tag
-        run: |
-          # On a tag build the tag is the single source of truth for the version.
-          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
-            VERSION="${GITHUB_REF#refs/tags/v}"
-            echo "Setting version to $VERSION"
-            sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" src-tauri/tauri.conf.json
-          fi
-          grep '"version"' src-tauri/tauri.conf.json
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
 
       - name: Build Windows (NSIS installer + exe)
         run: OUTPUT_DIR="$PWD/dist/windows" WIN_BUNDLES=nsis ./scripts/build-windows-cross.sh
@@ -217,48 +221,22 @@ jobs:
       - name: Install dependencies
         run: bun install
 
+      # Stamp before `android init`: it derives its generated project (including
+      # the initial versionCode) from tauri.conf.json.
       - name: Set app version from tag
-        run: |
-          # On a tag build, the tag is the single source of truth for the
-          # version name. On non-tag runs keep whatever is in tauri.conf.json.
-          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
-            VERSION="${GITHUB_REF#refs/tags/v}"
-            echo "Setting version to $VERSION"
-            sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" src-tauri/tauri.conf.json
-          fi
-          grep '"version"' src-tauri/tauri.conf.json
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
 
       - name: Initialize Android project
         run: bun run tauri android init
 
+      # Re-run after init: tauri.properties only exists now, and its
+      # autogenerated versionCode (0.0.15 -> 15) is both tiny and NOT monotonic
+      # against the 1000 floor already shipped in the field. The script rewrites
+      # it as 1000 + major*10000 + minor*100 + patch. Runs unconditionally so
+      # untagged builds get a sane code too, derived from git describe.
       - name: Pin a monotonic Android versionCode
-        run: |
-          # `tauri android init` autogenerates src-tauri/gen/android/app/tauri.properties
-          # with a versionCode derived from the semver (e.g. 0.0.15 -> 15). That
-          # number is (a) tiny and (b) NOT monotonic across our history: earlier
-          # local/dev builds shipped versionCode 1000 (from a 0.1.0 config), so a
-          # plain 15 would be a *downgrade* and Android would refuse the update.
-          #
-          # Derive an explicit code that is both monotonic in semver order and
-          # always above the 1000 floor already in the field:
-          #   code = 1000 + major*10000 + minor*100 + patch
-          # e.g. 0.0.14 -> 1014, 0.0.15 -> 1015, 0.1.0 -> 1100, 1.0.0 -> 11000.
-          # POSIX sh only (the runner uses dash): no here-strings, no \s in sed.
-          PROPS="src-tauri/gen/android/app/tauri.properties"
-          VERSION=$(grep '"version"' src-tauri/tauri.conf.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
-          MAJ=$(echo "$VERSION" | cut -d. -f1)
-          MIN=$(echo "$VERSION" | cut -d. -f2)
-          PAT=$(echo "$VERSION" | cut -d. -f3)
-          # Guard against a malformed/missing component so we never emit code 0.
-          : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
-          CODE=$(( 1000 + MAJ*10000 + MIN*100 + PAT ))
-          echo "version=$VERSION -> versionCode=$CODE"
-          if grep -q '^tauri.android.versionCode=' "$PROPS"; then
-            sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
-          else
-            echo "tauri.android.versionCode=$CODE" >> "$PROPS"
-          fi
-          cat "$PROPS"
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
 
       - name: Sync custom Android sources & gradle config
         run: ./scripts/sync-android-sources.sh

CHANGELOG.md

@@ -6,6 +6,88 @@ Entries are grouped by the capability they change, not by commit. Requirement
 IDs in parentheses point at [docs/requirements.md](docs/requirements.md); the
 generated trace matrix lives in [docs/traceability.md](docs/traceability.md).
 
+## v0.5.0
+
+### ✨ Features
+
+- **Android video can render on the device's own video surface.** Settings →
+  Video Playback → **Native Video** (experimental, off by default) hands
+  decoding to ExoPlayer, which draws into a surface composited *behind* a
+  transparent WebView, with the player controls layered on top of it.
+
+  The backend had reported "this platform has a native video surface" on Android
+  all along, but the frontend threw that answer away in two separate places, so
+  the path had never actually run. Both are lifted. The setting can only ever
+  *suppress* the backend's choice, never override it upward: turning it off
+  forces the web player even where native is available, and turning it on does
+  nothing on platforms whose backend never offered it — Linux cannot composite
+  behind its webview, so it stays on the web player either way.
+
+  Verified playing on a physical device. Still unverified: the mini-player
+  transition, audio-track switching on the native path, and whether hardware
+  decoding measurably improves battery or CPU — so the toggle stays off by
+  default. (UR-003, UR-004 → DR-150)
+
+### 🐛 Fixes
+
+- **The video surface now reaches the screen at all.** The player built its
+  video surface, handed it to ExoPlayer, and then never added it to the view
+  hierarchy, because the Activity reference it needed was never supplied — so
+  native video would have decoded to a surface nobody could see, whatever else
+  was fixed. This also silently disabled picture-in-picture for video, which
+  gated on that same never-attached surface. (UR-003, UR-041 → DR-151)
+
+- **Platform playback support is no longer guessed from the browser user
+  agent.** The frontend re-derived "does this platform decode audio natively" by
+  string-matching `navigator.userAgent` — a second copy of a decision the
+  backend already makes, free to drift out of step with the backends it was
+  describing. The backend now reports its own capabilities and the frontend
+  consumes them. (UR-003, UR-005 → DR-152)
+
+### 🔧 Internal
+
+- **The git tag is now the single source of truth for a release version.** The
+  version lived in four files that had to be edited in lockstep, and the release
+  workflow rewrote exactly one of them — so a tagged build produced an installer
+  named for the tag wrapped around package metadata naming the *previous*
+  release, and the Linux job, which had no version step at all, shipped whatever
+  happened to be committed. `scripts/set-version.sh` now writes all four from
+  one argument and every release job calls it with the tag. The Android
+  `versionCode` is derived in the same place, guarded by tests for the property
+  that actually matters: it must increase monotonically and stay above the value
+  already installed in the field, or Android silently refuses the update.
+  (DR-153)
+
+## v0.4.8
+
+### 🐛 Fixes
+
+- **Video with an undecodable soundtrack now transcodes instead of playing
+  silent.** Advertising a webview-shaped profile (v0.4.7) turned out not to be
+  enough: Jellyfin 10.11.5 enforces a direct-play profile's container and video
+  codec but ignores its audio codec, offering an E-AC-3 track for direct play
+  against a profile listing only AAC — and no `CodecProfile` or channel limit
+  changes that. The client now checks the track it would actually be served
+  against what its renderer can decode and forces the h264/AAC HLS transcode
+  when it cannot, rather than trusting the negotiation.
+  (UR-004 → DR-149)
+
+## v0.4.7
+
+### 🐛 Fixes
+
+- **Video plays with sound on devices that ship a Dolby decoder.** The audio
+  codec list sent to Jellyfin came from `MediaCodecList`, which describes
+  ExoPlayer — but video does not play through ExoPlayer: it renders in the
+  webview `<video>` element, which decodes far less. A phone whose vendor
+  licenses Dolby therefore advertised `ac3`/`eac3`, got a direct play, and
+  showed full picture with no audio, while a leaner device claimed neither
+  codec, received an AAC transcode, and played the same file correctly. The
+  video direct-play profile is now narrowed to what the webview can decode;
+  audio-only playback is genuinely the native player's and keeps the full list,
+  so music is not transcoded needlessly.
+  (UR-004 → DR-148)
+
 ## v0.4.1
 
 ### 🐛 Fixes

docs/requirements.md

@@ -310,6 +310,12 @@ Internal architecture, components, and application logic.
 | DR-141 | The device profile states how many channels the audio route can actually voice. `MediaCodecList` answers "can this device *decode* 5.1", which is not the question that decides whether the user hears anything — a phone decodes an AC-3 5.1 track happily and still has two channels to play it out of. With no `MaxAudioChannels` in the profile, Jellyfin was free to direct-play the multichannel track, and the result is device dependent: a failed `AudioSink` configuration (silence) or dialogue folded into surround channels that go nowhere. media3's `AudioCapabilities.maxChannelCount` for the current route is reported over JNI alongside the codec lists, and bounds both the direct-play profile and the transcoding profiles, so the server downmixes rather than shipping channels the sink cannot take. Codecs are never removed from the profile — a device with genuine surround output keeps direct-playing it. A missing or zero reading means "route not yet established", not "no audio", and falls back to stereo, the one capability every sink has | Playback | UR-004 | Done |
 | DR-145 | Video playback starts only once the app actually holds audio focus. Video manages focus by hand (`handleAudioFocus=false`, because ExoPlayer's automatic handling is reserved for the audio path), and the request's three outcomes were all treated as success: `AUDIOFOCUS_REQUEST_DELAYED` — which `setAcceptsDelayedFocusGain(true)` explicitly invites, and which means the system is *withholding our audio* until it calls back — and an outright `REQUEST_FAILED` were logged and then followed by `playWhenReady = true`. The picture rolled with no sound, indistinguishable to the user from a broken stream. Playback is now held when focus is not granted and started from the `AUDIOFOCUS_GAIN` callback; an explicit `play()` re-requests focus rather than resuming into a stream the system is still muting, guarded by a held-focus flag so repeated plays do not leak focus requests. A `LOSS` clears the pending flag, so an unrelated later `GAIN` cannot start playback the user never asked for | Playback | UR-004 | Done |
 | DR-146 | The no-audio-track fallback picks a track the renderer can actually play. When ExoPlayer selected no audio track, the recovery forced group 0 / track 0 unconditionally — but the most likely reason nothing was selected is that this very track cannot be decoded on this device, so the override reinstated the silence it was meant to fix. It now scans the groups for the first `isTrackSupported` track and overrides to that, and clears `setTrackTypeDisabled(TRACK_TYPE_AUDIO)` because audio may equally have been off at the type level, which an override alone does not undo. When no group holds a supported track the condition is logged as an error — the server was expected to transcode — rather than leaving a silent video with no explanation in the log | Playback | UR-004 | Done |
+| DR-148 | The video direct-play profile advertises only what the **webview** can decode. The audio codec list comes from `MediaCodecList`, which describes ExoPlayer — but video does not play through ExoPlayer on either platform: Android force-renders every video in the webview `<video>` element (the interim override in `VideoPlayer.svelte`, because the native SurfaceView sits behind an opaque webview) and Linux always has. Chromium and WebKit decode a far narrower set than the platform does, and the gap is widest on devices whose vendor licenses Dolby: a phone shipping `/vendor/etc/media_codecs_dolby_audio.xml` reports `ac3,eac3`, so Jellyfin direct-played an E-AC-3 track with `static=true` and the webview built a video decoder and no audio decoder at all — full picture, no sound. The defect is triggered by *capability*, not the lack of it, which is why it reproduced on one Motorola while a Fairphone and an Honor tablet played the same file on the same build: a device without the Dolby decoder never claims the codec, so the server transcodes to AAC and it plays. `video_audio_codecs` narrows the platform list to the webview-decodable set (`aac,mp3,opus,vorbis,flac`) for the video direct-play profile *only* — the audio-only profile keeps the full list, since that playback really is the native player's and narrowing it would transcode music that plays perfectly well. A list with nothing decodable still claims `aac` rather than going out empty, because a profile that claims nothing invites the server to give up instead of transcoding. The video codec list is deliberately untouched: HEVC direct-plays through the webview correctly, so the constraint is specific to audio | Playback | UR-004 | Done |
+| DR-149 | The client decides whether its own renderer can decode the audio, rather than trusting the server's negotiation. Advertising a webview-shaped profile (DR-148) turned out to be necessary but not sufficient: Jellyfin 10.11.5 enforces a `DirectPlayProfile`'s `Container` and `VideoCodec` — excluding either returns `SupportsDirectPlay: false` with `TranscodeReasons=ContainerNotSupported` / `VideoCodecNotSupported` — but **ignores its `AudioCodec`**, offering an E-AC-3 track for direct play against a profile listing only `aac,flac,mp3,opus,vorbis`. Neither a `VideoAudio` `CodecProfile` forbidding the codec nor a `MaxAudioChannels: 2` against a 6-channel track changes the answer, so no profile the client can send fixes it and the picture plays silent. The negotiated source's audio is therefore checked locally against what the webview decodes, and an undecodable track forces the existing h264/aac HLS transcode URL regardless of the server saying direct play is fine — `direct_play` and `needs_transcoding` are corrected to match, so the frontend and the reporting path agree with the URL actually used. The track judged is the one the server would serve: the default, or the first when nothing is marked default, since a supported track further down the list is not the one that plays. A source with no audio streams, or a stream whose codec the server did not name, is left alone — forcing a transcode on a guess spends server CPU on files that already play | Playback | UR-004 | Done |
+| DR-150 | Android video renders on the native ExoPlayer surface behind a transparent WebView, behind the `experimentalNativeVideo` opt-in. Rust already reported `use_html5_element: false` on Android, but two frontend overrides discarded it — `createAdapter()` hardcoded `"html5"`, and `VideoPlayer.svelte` forced `useHtml5Element = true` and stopped the native backend `player_play_item` had just started. The flag is a **suppressor, never a promoter**: off forces HTML5 even where Rust says native, so an in-progress spike cannot ship as the default, but it can never select native where Rust reported HTML5 (Linux cannot composite behind WebKitGTK, so promoting there is a black screen). Compositing requires clearing two independent opaque layers, and clearing only one leaves audio over a black picture — the WebView widget background and window drawable from Kotlin (`AndroidVideoSurface.setTransparent`), and the page's `html`/`body` and app-shell background from CSS (`data-native-video`). Transparency is declared in `tauri.android.conf.json` rather than the base config, because a transparent window on Linux has nothing behind it, and is toggled per playback session rather than set once, because a permanently transparent window shows the launcher through the rest of the app | Playback | UR-003, UR-004 | Done (behind `experimentalNativeVideo`, default off) |
+| DR-151 | The player's video SurfaceView actually reaches the view hierarchy. `JellyTauPlayer.setActivity()` had zero callers, so `currentActivity` was always null and `autoAttachSurface()` returned at "Cannot attach surface - no Activity reference". The surface was created and handed to ExoPlayer but never added to the content view, so native video decoded to a surface that was never on screen — independent of any webview transparency. `MainActivity.onCreate` now supplies the reference, which also revives PiP on the video path: `canEnterPip()` gates on `isVideoSurfaceAttached()`, which had been permanently false | Playback | UR-003, UR-041 | Done |
+| DR-152 | Platform playback facilities are reported by Rust, not sniffed from the user agent. `webviewAudio.ts` re-derived "does this platform have a native audio backend" by matching `navigator.userAgent` against `android`/`linux` — a second copy of the `cfg!` gate the backends are compiled under, free to drift from it. `player_get_capabilities` now returns `usesWebviewAudio` and `supportsNativeVideo` from the same cfg gates, and the frontend consumes them; the settings toggle for native video is hidden entirely where the platform cannot support it | Player | UR-003, UR-005 | Done |
+| DR-153 | The git tag is the single source of truth for a release version. The version lived in four files (`package.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`) that had to be hand-edited in lockstep, and CI's release job rewrote exactly one of them — so a tagged build produced an installer named for the tag wrapped around package metadata naming the previous release, while the Linux job had no version step at all and shipped whatever was committed. `scripts/set-version.sh` writes all four from one argument and is the only thing that does; every release job calls it with the tag. The Android `versionCode` is derived in the same place as `1000 + major*10000 + minor*100 + patch`, which is monotonic in semver order and clears the 1000 floor already installed in the field — a lower code than the installed one makes Android refuse the update. A prerelease suffix is stripped before that arithmetic, which would otherwise abort the script, and a non-tag ref (CI passes `${GITHUB_REF#refs/tags/}` unconditionally) falls back to `git describe` rather than failing a branch build | Build | - | Done |
 | DR-143 | Flipping the offline downloaded-only gate actually re-queries the listing. The gate (DR-078) is a process-wide flag in Rust consulted only *while a query runs*, but no library surface re-queried when its inputs changed: `useServerReachabilityReload` fires only on the offline → **online** transition, and `GenericMediaListPage`, `GenericGenreBrowser` and the favourites page never even called its `checkServerReachability`. So going offline left the full server catalog on screen under a now-closed gate, and toggling "Show all server media" only greyed cards — `MediaCard.isServerOnly` is a pure frontend derivation that updates instantly — without adding or removing a single row. The filter therefore read as "shows everything until I filter, then greys some of it" while the backend gate was correct and simply never exercised. `catalogFilterVersion` is the refetch signal: `pushCatalogVisibility` now awaits `set_show_server_catalog` and bumps the version only **after** the backend accepts the new flag, since a reload racing the push would re-query under the old gate and undo itself. A failed push clears `lastIncludeCatalog` instead of latching it, so the next identical transition is retried rather than skipped as a no-op and left permanently disagreeing with the backend. `useOfflineFilterReload` subscribes pages to that signal, skipping the value they already loaded under; it is wired into both generic list components and the movies/music/tv/favourites landing pages and the `/library/[id]` detail page | UI | UR-052 | Done |
 | DR-135 | A download's media type comes from the item, not a default. `download_item` — the path a media card uses to queue an item while offline — never records `media_type`, and the reconnect resolver read that NULL as `'audio'`, so a **movie** queued from a card had its URL resolved by `get_audio_stream_url`. The file that landed on disk was an audio-only transcode, which is why a "downloaded" film could never play offline no matter how the path or protocol was fixed. The resolver now falls back to the item's own `item_type` (`VIDEO_ITEM_TYPES` in Rust, so the frontend never learns which types are video) and only defaults to audio when the item is not cached locally. An explicit `media_type` on the row still wins | Downloads | UR-071, UR-052 | Done |
 | DR-136 | Rows already downloaded under the audio default are repaired, not just prevented. They are identifiable after the fact — no `media_type`, but a video item — so on reconnect they are reset to `pending` with their audio URL cleared and re-resolved by DR-135's corrected logic, overwriting the audio file in place. Without this the fix is invisible to anyone who had already queued a film: the row still reads "downloaded" and still fails to play. Rows carrying an explicit `media_type` and genuine audio downloads are left untouched | Downloads | UR-071 | Done |
@@ -540,6 +546,15 @@ Internal architecture, components, and application logic.
 | UT-139 | A failed visibility push is retried on the next identical transition rather than latched | DR-143 | Done |
 | UT-140 | `useOfflineFilterReload` skips the value a page already loaded under and reloads on each later change | DR-143 | Done |
 | UT-141 | The advertised channel cap: an unknown or zero reading falls back to stereo, a real route keeps its channels, an absurd driver reading is capped at 7.1, and mono is taken at its word | DR-141 | Done |
+| UT-148 | Forcing a transcode from the client: an undecodable default track forces one, a decodable track does not, the default track decides rather than the first, the first decides when nothing is marked default, and neither an audio-less source nor an unnamed codec is second-guessed | DR-149 | Done |
+| UT-149 | `createAdapter` returns the native adapter only when Rust reports native AND `experimentalNativeVideo` is on; the flag off forces HTML5 even when Rust says native, and the flag on never promotes a platform Rust reported as HTML5 | DR-150 | Done |
+| UT-150 | `set-version.sh` stamps all four manifests without touching dependency versions, and the Android versionCode is monotonic across an upgrade sequence, clears the 1000 floor, and survives a prerelease suffix | DR-153 | Done |
+| UT-142 | The audio codecs offered for video direct play: a Dolby device's real `MediaCodecList` output drops `ac3`/`eac3`, AMR and raw PCM are dropped too, a fully-supported list is passed through untouched, a list with nothing decodable still claims `aac`, and stray spacing or casing does not decide whether the user gets sound | DR-148 | Done |
+| UT-143 | Subtitle URLs resolve to plain strings before they reach the markup (never a Promise), unresolvable tracks are dropped, a stale selection collapses to "Off", and a server-default track is never auto-selected | UR-020, DR-023 | Done |
+| UT-144 | VideoPlayer actually renders `<track kind="subtitles">` children carrying `data-stream-index`, with no `default` attribute and no async `getSubtitleUrl()` bound to `src` | UR-020, DR-023 | Done |
+| UT-145 | The frontend's subtitle payload survives the IPC hop: a camelCase `PlayItemRequest` carrying `subtitles` deserializes, `create_media_item` lands them on `MediaItem.subtitles` in the order sent, and a request without the field still defaults to empty | UR-020, IR-016 | Done |
+| UT-146 | The subtitle JSON serialized across the JNI boundary uses the keys `JellyTauPlayer.load()` reads — `url`, `language`, `label` and `mime_type`, never `mimeType` | UR-020, IR-016, JA-008 | Done |
+| UT-147 | The native subtitle payload and the track-selection index come from the same resolved list: the wire shape keeps `mime_type` and stream order, `playerPlayItem` actually sends it, and the index is a position in the sent list (so a track whose URL failed to resolve cannot shift the others) rather than the menu's row number | UR-020, IR-016 | Done |
 
 ### Integration Tests
 

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

@@ -1,7 +1,19 @@
 # Spec: Android native video — transparent-webview spike
 
-**Status:** Proposed (spike — timeboxed, may conclude "not viable")
-**Requirements:** IR-004, UR-003, UR-004 → DR-001, DR-023, DR-024
+**Status:** Spike succeeded — native video confirmed working on a physical
+device (2026-08-11) with `experimentalNativeVideo` on. Shipped behind that flag,
+default off. Branch `feat/android-native-video`.
+
+**The spike's central question is answered: yes.** A `SurfaceView` *can* be
+composited behind a transparent Tauri WebView on Android. Nothing upstream
+blocked it and nothing upstream demonstrated it — this is, as far as the issue
+trackers show, the first working instance. The remaining flag is about test
+coverage and the unverified cases below, not about viability.
+**Requirements:** IR-004, UR-003, UR-004, UR-041 → DR-001, DR-004, DR-150, DR-151, DR-152
+**Note:** the original draft cited DR-023/DR-024 here. Those are the *subtitle*
+and *audio-track selection UI* requirements — unrelated to this work. The IDs
+actually implemented are DR-150 (native rendering behind the flag), DR-151 (the
+severed SurfaceView attach chain) and DR-152 (capabilities reported by Rust).
 **UX spec:** n/a — no intended visual change; the video surface must land exactly where the `<video>` element is today
 **Supersedes / revises:** acts on finding 2 of [playback-backend-unification.md](playback-backend-unification.md)
 
@@ -109,6 +121,46 @@ in here rather than leaving a second, subtler copy of the bug behind. If
 `get_player_status` does not currently expose enough to cover the audio case, add
 the field — that is backend work, and correct.
 
+### Implementation findings (2026-08-11)
+
+Two blockers existed that this spec did not anticipate. Both were in code the
+spec assumed was merely *unreachable*; it was also *broken*.
+
+**1. The Kotlin attach chain was severed.** `JellyTauPlayer.setActivity()` had
+**zero callers** anywhere in the tree. `currentActivity` was therefore always
+null, so `autoAttachSurface()` logged "Cannot attach surface - no Activity
+reference" and returned. The `SurfaceView` was created and wired to ExoPlayer but
+never added to the view hierarchy — video would have decoded to a surface that
+was never on screen, *regardless* of webview transparency. Fixed by calling
+`JellyTauPlayer.setActivity(this)` from `MainActivity.onCreate`.
+
+Note the knock-on: `PictureInPictureManager.canEnterPip()` gates on
+`VideoOverlayManager.isVideoSurfaceAttached()`, which was permanently false. PiP
+on the video path was dead for the same reason.
+
+**2. `createAdapter()` was not the real gate.** It is never called by production
+code — `VideoPlayer.svelte` constructs `Html5PlayerAdapter` directly. The actual
+override was `VideoPlayer.svelte`'s INTERIM block, which read Rust's
+`useHtml5Element`, forced it to `true`, and called `playerStop()` to kill the
+native backend `player_play_item` had just started. Both sites are now fixed;
+`VideoPlayer.svelte` routes through `createAdapter()` so there is one gate.
+
+**Transparency needs two independent layers cleared,** not one. The spec's
+Phase 1 named only `html, body`. Clearing just the page leaves the WebView
+widget's own background opaque, which is a black screen with audio — the exact
+symptom the INTERIM comment described as "native surface not visible". Both are
+now toggled together by `$lib/utils/videoSurface.ts`:
+
+| Layer | Cleared by | Reachable from |
+|-------|-----------|----------------|
+| WebView widget background + window drawable | `AndroidVideoSurface.setTransparent()` (MainActivity) | Kotlin only |
+| `html`/`body` + app-shell `--color-background` | `data-native-video` attribute → app.css | CSS only |
+
+Transparency is scoped to `tauri.android.conf.json` rather than the base config:
+a transparent window on Linux is a regression, since nothing renders behind it.
+It is also toggled per-session rather than set once — a permanently transparent
+window shows the launcher through the rest of the app.
+
 ### Phase 3 — surface positioning
 
 The hard part, and where this most likely fails. The webview's `<video>` element
@@ -124,6 +176,32 @@ the video is effectively fullscreen on Android, which it is in the player route.
 rotation or the mini-player transition without visible artefacts, the spike fails
 and we keep HTML5. Do not ship a janky native path for a codec win.
 
+**Update: no rect plumbing was needed.** The premise — that the surface must be
+positioned to match a laid-out `<video>` box — does not hold on the player route,
+where video is fullscreen. `VideoOverlayManager` adds the SurfaceView at index 0
+of `android.R.id.content` with `MATCH_PARENT`, and `fitSurfaceToScreen()`
+(`JellyTauPlayer.kt`) already letterboxes/pillarboxes to the real video aspect
+ratio and re-centres via a `Gravity.CENTER` `FrameLayout.LayoutParams`. Rotation
+is handled by an `OnLayoutChangeListener` that re-fits on any bounds change. The
+frontend's native branch is a bare `flex-1` box, so there is no rect to report
+and nothing to keep in sync.
+
+Fullscreen playback is confirmed working on device. But this reasoning rests
+entirely on the fullscreen assumption, so **the mini-player transition is the
+known gap** — it is the one case where the surface is *not* fullscreen, and
+therefore the one case where the "no rect plumbing needed" conclusion could
+still turn out to be wrong. If artefacts appear there, the fix is the rect
+reporting this section originally proposed, scoped to that transition alone.
+
+### A trap for the next implementer
+
+There is a **stale duplicate player** at
+`src-tauri/android/app/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt`
+(only commit: `cfddc1e` "First working POC"). No `sourceSets` entry points at it,
+so it is not compiled — but edits made there silently do nothing. The canonical
+tree is `src-tauri/android/src`, synced into `gen/` by
+`scripts/sync-android-sources.sh`.
+
 ### What we gain if it works
 
 - **Hardware decode via MediaCodec** — `CodecDetector.kt` already reports
@@ -145,12 +223,13 @@ and we keep HTML5. Do not ship a janky native path for a codec win.
 The spike is **complete** when one of these is true:
 
 **Success path**
-- [ ] Transparent WebView confirmed working on a physical device.
-- [ ] `experimentalNativeVideo` off → behaviour byte-identical to today.
-- [ ] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust.
-- [ ] `experimentalNativeVideo` on → video plays via ExoPlayer/MediaCodec, correctly positioned, with working seek, audio-track switch, and subtitle selection through the existing `PlayerAdapter` contract.
-- [ ] No artefacts on rotation, background/foreground, or mini-player transition.
-- [ ] `adb shell dumpsys media.metrics` (or logcat) confirms a hardware decoder is in use.
+- [x] Transparent WebView confirmed working on a physical device (reported by the maintainer; the config that enables it is now committed in `tauri.android.conf.json`).
+- [x] `experimentalNativeVideo` off → behaviour byte-identical to today. Guarded by `adapterSelection.test.ts`, which asserts the flag-off case forces HTML5 even when Rust reports native.
+- [x] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust (`player_get_capabilities` → `usesWebviewAudio`).
+- [x] `experimentalNativeVideo` on → video plays via ExoPlayer, correctly positioned, on a physical device (2026-08-11). The surface reaches the hierarchy and is visible through the transparent WebView — the whole point of the spike.
+- [ ] Seek, audio-track switch and subtitle selection exercised through `NativePlayerAdapter`. Playback is confirmed; these individual controls are not yet each verified on the native path.
+- [ ] No artefacts on rotation, background/foreground, or **mini-player transition** — the last is the one case the fullscreen assumption does not cover, so it is the likeliest place to find a problem.
+- [ ] `adb shell dumpsys media.metrics` (or logcat) confirms a hardware decoder is in use. Plausible but unmeasured — do not claim the MediaCodec win until this is read.
 - [ ] Measured battery/thermal or CPU improvement over the HTML5 path on the same clip.
 
 **Failure path**
@@ -159,8 +238,15 @@ The spike is **complete** when one of these is true:
 - [ ] `nativeAdapter.ts:11-14` no longer cites tauri#10152.
 
 Either way:
-- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
-- [ ] `cargo fmt` / `cargo clippy` clean; `bun run test:rust` passes.
+- [x] `bun run check` (0 errors), `bun run test` (892 passed), `bun run check:boundary` pass.
+- [x] `cargo fmt` / `cargo clippy` clean (no new warnings); `cargo test` passes (603 lib + 7 doc).
+
+> Note: this environment has no host WebKitGTK dev packages, no Android SDK and
+> no `bun`, so all of the above were run inside the CI builder image
+> (`gitea.tourolle.paris/dtourolle/jellytau-builder:latest`). On Fedora the bind
+> mount needs `:z` for SELinux, and `scripts/build-android.sh` hardcodes
+> `ANDROID_HOME="$HOME/Android/Sdk"`, so the image's SDK at `/opt/android-sdk`
+> must be symlinked there rather than passed by env var.
 
 ## Testing
 
@@ -179,7 +265,7 @@ native adapter), write the failing test first.
 
 ## TRACES
 
-- `createAdapter` → `// TRACES: UR-003, UR-004 | DR-023, DR-024`
+- `createAdapter` → `// TRACES: UR-003, UR-004 | DR-004, DR-150 | UT-149`
 - Adapter-selection tests → `UT-xxx`
 - No new requirement IDs; this spike either satisfies existing IR-004 expectations or documents why it cannot.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jellytau",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "",
   "type": "module",
   "packageManager": "bun@1.3.5",

scripts/extract-traces.test.ts

@@ -175,8 +175,8 @@ describe("live requirements.md", () => {
 
     expect(defined.UR).toBe(71);
     expect(defined.IR).toBe(32);
-    expect(defined.DR).toBe(142);
+    expect(defined.DR).toBe(148);
     expect(defined.JA).toBe(35);
-    expect(defined.total).toBe(280);
+    expect(defined.total).toBe(286);
   });
 });

scripts/set-version.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# Stamp the release version into every file that carries it.
+#
+# The git tag is the single source of truth for a release version. The versions
+# committed in package.json / tauri.conf.json / Cargo.toml are a placeholder for
+# dev builds; a tagged build overwrites all of them from the tag so they cannot
+# disagree with each other or with the tag.
+#
+# Usage:
+#   ./scripts/set-version.sh 0.5.0        # explicit
+#   JELLYTAU_VERSION=0.5.0 ./scripts/set-version.sh
+#   ./scripts/set-version.sh              # derive from git describe (dev builds)
+#
+# Accepts the version with or without a leading "v".
+#
+# Why a script and not four sed lines in CI: the version lived in four files and
+# CI only ever rewrote one of them (tauri.conf.json), so a tagged release shipped
+# a matching installer name and mismatched package metadata. Keeping the write in
+# one place is what makes "the tag is authoritative" actually true.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+VERSION="${1:-${JELLYTAU_VERSION:-}}"
+
+# CI passes "${GITHUB_REF#refs/tags/}" unconditionally, which on an untagged
+# build is still a full ref ("refs/heads/master"). Treat anything that is not a
+# bare version as "no version given" and fall through to git describe, so a
+# branch build gets a sane dev version instead of failing the job.
+case "$VERSION" in
+  refs/*) VERSION="" ;;
+esac
+
+if [ -z "$VERSION" ]; then
+  # No explicit version: derive from the most recent tag. Dev builds land on
+  # something like 0.5.0 (exact tag) or 0.5.0-3-gabc1234 (ahead of the tag).
+  VERSION="$(git describe --tags --always --match 'v*' 2>/dev/null || echo "0.0.0")"
+fi
+
+# Tags are written v0.5.0; the files carry a bare semver.
+VERSION="${VERSION#v}"
+
+# Validate before writing anything — a malformed version silently propagated
+# into four files is far worse than a failed script.
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'; then
+  echo "❌ Not a valid semver: '$VERSION'" >&2
+  echo "   Expected MAJOR.MINOR.PATCH with an optional -prerelease/+build suffix." >&2
+  exit 1
+fi
+
+echo "📌 Setting version to $VERSION"
+
+# --- The three committed manifests -----------------------------------------
+# Anchored to the first "version" key so a dependency's version is never hit.
+
+# package.json — the top-level "version", which sits in the first few lines.
+perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' package.json
+
+# tauri.conf.json — likewise; this is the one the bundler reads for installer
+# names, and the one CI used to patch alone.
+perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' src-tauri/tauri.conf.json
+
+# Cargo.toml — only the [package] version, never a dependency's. Restricted to
+# the first occurrence of a line-anchored `version = "..."`.
+perl -0pi -e 's/^(version\s*=\s*)"[^"]*"/$1"'"$VERSION"'"/m' src-tauri/Cargo.toml
+
+# Cargo.lock — the jellytau entry. Left alone if the lock has not been generated
+# yet; the next cargo invocation writes it. Cargo would otherwise rewrite the
+# lock mid-build and dirty the tree.
+if [ -f src-tauri/Cargo.lock ]; then
+  perl -0pi -e 's/(name = "jellytau"\nversion = )"[^"]*"/$1"'"$VERSION"'"/' src-tauri/Cargo.lock
+fi
+
+# --- Android versionCode ----------------------------------------------------
+# Only when the generated Android project exists (i.e. after `tauri android
+# init`); on Linux/Windows jobs there is nothing to stamp.
+#
+# `tauri android init` derives a versionCode from the semver (0.0.15 -> 15).
+# That is both tiny and NOT monotonic across our history: earlier local/dev
+# builds shipped versionCode 1000 (from a 0.1.0 config), so a plain 15 is a
+# *downgrade* and Android refuses the update.
+#
+#   code = 1000 + major*10000 + minor*100 + patch
+# e.g. 0.0.14 -> 1014, 0.0.15 -> 1015, 0.1.0 -> 1100, 1.0.0 -> 11000.
+PROPS="src-tauri/gen/android/app/tauri.properties"
+if [ -f "$PROPS" ]; then
+  # Strip any -rc1/+build suffix first: it is not numeric, and feeding it to
+  # $(( )) would abort the script under `set -e`.
+  CORE="${VERSION%%-*}"
+  CORE="${CORE%%+*}"
+  MAJ=$(echo "$CORE" | cut -d. -f1)
+  MIN=$(echo "$CORE" | cut -d. -f2)
+  PAT=$(echo "$CORE" | cut -d. -f3)
+  : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
+  CODE=$(( 1000 + MAJ*10000 + MIN*100 + PAT ))
+  echo "   versionCode=$CODE (from $CORE)"
+  if grep -q '^tauri.android.versionCode=' "$PROPS"; then
+    sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
+  else
+    echo "tauri.android.versionCode=$CODE" >> "$PROPS"
+  fi
+fi
+
+# --- Report -----------------------------------------------------------------
+echo "✅ Version stamped:"
+grep -m1 '"version"' package.json | sed 's/^/   package.json:      /'
+grep -m1 '"version"' src-tauri/tauri.conf.json | sed 's/^/   tauri.conf.json:   /'
+grep -m1 '^version' src-tauri/Cargo.toml | sed 's/^/   Cargo.toml:        /'
+[ -f "$PROPS" ] && grep '^tauri.android.versionCode=' "$PROPS" | sed 's/^/   tauri.properties:  /'
+exit 0

scripts/set-version.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Guards for scripts/set-version.sh — the release version stamper.
+ *
+ * TRACES: DR-153 | UT-150
+ *
+ * These run the real script against a throwaway copy of the manifests, because
+ * the failure modes are all in the shell, not in any TS logic: a regex that also
+ * matches a dependency's version, arithmetic that aborts on a `-rc1` suffix, or
+ * a CI ref reaching the validator verbatim.
+ *
+ * The versionCode formula matters most. Android refuses an update whose code is
+ * lower than the installed one, and builds already in the field shipped code
+ * 1000 — so any formula that can emit a smaller number for a *newer* release
+ * bricks updates for those users, silently and irreversibly.
+ */
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const script = path.join(repoRoot, "scripts", "set-version.sh");
+
+let tmp: string;
+
+/** A minimal repo skeleton: just the files the script rewrites. */
+function seed(dir: string) {
+  fs.mkdirSync(path.join(dir, "src-tauri", "gen", "android", "app"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "scripts"), { recursive: true });
+  fs.copyFileSync(script, path.join(dir, "scripts", "set-version.sh"));
+  fs.chmodSync(path.join(dir, "scripts", "set-version.sh"), 0o755);
+
+  fs.writeFileSync(
+    path.join(dir, "package.json"),
+    JSON.stringify({ name: "jellytau", version: "0.0.1", dependencies: { hls: "1.2.3" } }, null, 2)
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "tauri.conf.json"),
+    JSON.stringify({ productName: "jellytau", version: "0.0.1" }, null, 2)
+  );
+  // A dependency carrying its own `version =` is the trap: a greedy regex
+  // rewrites it too and the build then resolves the wrong crate.
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "Cargo.toml"),
+    ['[package]', 'name = "jellytau"', 'version = "0.0.1"', '', '[dependencies]', 'serde = { version = "1.0.100" }', ''].join("\n")
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "Cargo.lock"),
+    ['[[package]]', 'name = "serde"', 'version = "1.0.100"', '', '[[package]]', 'name = "jellytau"', 'version = "0.0.1"', ''].join("\n")
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "gen", "android", "app", "tauri.properties"),
+    "tauri.android.versionCode=1\n"
+  );
+}
+
+function run(version: string, dir = tmp) {
+  return execFileSync("bash", [path.join(dir, "scripts", "set-version.sh"), version], {
+    cwd: dir,
+    encoding: "utf-8",
+  });
+}
+
+function read(rel: string): string {
+  return fs.readFileSync(path.join(tmp, rel), "utf-8");
+}
+
+function versionCode(): number {
+  const m = read("src-tauri/gen/android/app/tauri.properties").match(
+    /^tauri\.android\.versionCode=(\d+)$/m
+  );
+  return m ? Number(m[1]) : NaN;
+}
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "setversion-"));
+  seed(tmp);
+});
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("set-version.sh", () => {
+  it("stamps the version into all four manifests", () => {
+    run("0.5.0");
+    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
+    expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.5.0");
+    expect(read("src-tauri/Cargo.toml")).toContain('version = "0.5.0"');
+    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "jellytau"\nversion = "0\.5\.0"/);
+  });
+
+  it("accepts a leading v, as git tags are written", () => {
+    run("v0.5.0");
+    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
+  });
+
+  // The regression that motivates anchoring the patterns.
+  it("does not rewrite dependency versions", () => {
+    run("0.5.0");
+    expect(read("src-tauri/Cargo.toml")).toContain('serde = { version = "1.0.100" }');
+    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "serde"\nversion = "1\.0\.100"/);
+    expect(JSON.parse(read("package.json")).dependencies.hls).toBe("1.2.3");
+  });
+
+  describe("Android versionCode", () => {
+    // Codes below 1000 are already in the field; a newer release must never
+    // produce a smaller number than an older one.
+    it("clears the 1000 floor shipped by earlier builds", () => {
+      run("0.0.1");
+      expect(versionCode()).toBeGreaterThan(1000);
+    });
+
+    it("uses 1000 + major*10000 + minor*100 + patch", () => {
+      const cases: Array<[string, number]> = [
+        ["0.0.14", 1014],
+        ["0.0.15", 1015],
+        ["0.1.0", 1100],
+        ["0.4.8", 1408],
+        ["0.5.0", 1500],
+        ["1.0.0", 11000],
+      ];
+      for (const [version, code] of cases) {
+        seed(tmp);
+        run(version);
+        expect(versionCode(), `versionCode for ${version}`).toBe(code);
+      }
+    });
+
+    it("increases monotonically across an upgrade sequence", () => {
+      const ordered = ["0.0.14", "0.0.15", "0.1.0", "0.4.8", "0.5.0", "1.0.0"];
+      const codes = ordered.map((v) => {
+        seed(tmp);
+        run(v);
+        return versionCode();
+      });
+      const sorted = [...codes].sort((a, b) => a - b);
+      expect(codes).toEqual(sorted);
+      expect(new Set(codes).size).toBe(codes.length);
+    });
+
+    // `$(( 0-rc1 ))` aborts the script under `set -e`, so the suffix has to be
+    // stripped before the arithmetic.
+    it("derives the code from the numeric core of a prerelease", () => {
+      run("0.6.0-rc1");
+      expect(versionCode()).toBe(1600);
+      expect(JSON.parse(read("package.json")).version).toBe("0.6.0-rc1");
+    });
+  });
+
+  describe("input validation", () => {
+    it("rejects a malformed version without writing anything", () => {
+      expect(() => run("not-a-version")).toThrow();
+      // The manifests must be untouched, not half-written.
+      expect(JSON.parse(read("package.json")).version).toBe("0.0.1");
+      expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.0.1");
+    });
+
+    // CI passes "${GITHUB_REF#refs/tags/}" unconditionally; on a branch build
+    // that is still a full ref, and must not fail the job.
+    it("falls back to a dev version when handed a non-tag ref", () => {
+      const out = run("refs/heads/master");
+      expect(out).not.toMatch(/refs\/heads/);
+      expect(JSON.parse(read("package.json")).version).not.toBe("0.0.1");
+    });
+  });
+});

src-tauri/Cargo.lock

@@ -2018,7 +2018,7 @@ dependencies = [
 
 [[package]]
 name = "jellytau"
-version = "0.4.6"
+version = "0.4.8"
 dependencies = [
  "aes-gcm",
  "async-trait",

src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jellytau"
-version = "0.4.6"
+version = "0.4.8"
 description = "A Tauri App"
 authors = ["you"]
 edition = "2021"

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

@@ -64,6 +64,20 @@ class MainActivity : TauriActivity() {
     // so on devices with a tall opaque 3-button bar. (UR-066)
     WindowInsetsBridge.install(this)
 
+    // Hand the player an Activity reference so it can attach its video
+    // SurfaceView to the content view behind the WebView.
+    //
+    // Without this, JellyTauPlayer.currentActivity stays null forever and
+    // autoAttachSurface() logs "Cannot attach surface - no Activity reference"
+    // and returns — so the SurfaceView is created, wired to ExoPlayer, and then
+    // never added to the view hierarchy. Native video decoded to a surface that
+    // was never on screen. setActivity() stores into a companion-object
+    // WeakReference, so calling it here (before Rust initializes the player over
+    // JNI) is safe and is the case it was written for.
+    //
+    // TRACES: UR-003, UR-041 | DR-151
+    com.dtourolle.jellytau.player.JellyTauPlayer.setActivity(this)
+
     // Configure WebView for media playback after Tauri initialization
     handler.postDelayed({
       configureWebViewForMedia()
@@ -271,6 +285,46 @@ class MainActivity : TauriActivity() {
       }, "AndroidNetworkType")
       android.util.Log.d("MainActivity", "JavaScript interface 'AndroidNetworkType' added")
 
+      // Native video compositing: let the frontend make the WebView transparent
+      // so the ExoPlayer SurfaceView behind it is visible (UR-003, UR-004).
+      //
+      // Toggled rather than set once because a transparent WebView is only
+      // correct while a native video is on screen — every other screen needs its
+      // opaque background, and leaving the window transparent shows the
+      // launcher/wallpaper through the app.
+      //
+      // The CSS in app.css clears the *web* layer's backgrounds; this clears the
+      // WebView widget's own background, which CSS cannot reach. Both are
+      // required — an opaque WebView hides the surface no matter what the page
+      // paints.
+      //
+      // TRACES: UR-003, UR-004 | DR-150
+      webView.addJavascriptInterface(object : Any() {
+        /** Make the WebView background transparent (true) or opaque (false). */
+        @JavascriptInterface
+        fun setTransparent(transparent: Boolean) {
+          handler.post {
+            val color = if (transparent) {
+              android.graphics.Color.TRANSPARENT
+            } else {
+              android.graphics.Color.BLACK
+            }
+            mediaWebView?.setBackgroundColor(color)
+            // The WebView's window/surface must also stop painting opaque, or a
+            // hardware-accelerated WebView still composites its own background.
+            window.setBackgroundDrawable(
+              android.graphics.drawable.ColorDrawable(color)
+            )
+            android.util.Log.d("MainActivity", "WebView transparent = $transparent")
+          }
+        }
+
+        /** Whether native-video compositing is available on this platform. */
+        @JavascriptInterface
+        fun isSupported(): Boolean = true
+      }, "AndroidVideoSurface")
+      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidVideoSurface' added")
+
       // Window insets (safe areas). The push path above races the page load, so
       // the frontend pulls the current values on mount through this bridge.
       webView.addJavascriptInterface(WindowInsetsBridge.jsInterface(), "AndroidInsets")

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

@@ -202,6 +202,27 @@ pub struct PlayItemRequest {
     /// look up the next episode when a background-audio track ends.
     #[serde(default)]
     pub series_id: Option<String>,
+    /// Subtitle tracks to sideload, with URLs the frontend has already resolved.
+    ///
+    /// Only the native backends use these: on Android they become the
+    /// `MediaItem.SubtitleConfiguration`s ExoPlayer renders. The HTML5 path
+    /// builds its own `<track>` children instead and ignores this list.
+    ///
+    /// **Order is the contract.** `player_set_subtitle_track(n)` reaches
+    /// `JellyTauPlayer.setSubtitleTrack(n)`, which indexes into ExoPlayer's
+    /// *text track groups* — i.e. the position of the sideloaded configuration,
+    /// not the Jellyfin stream index (which is kept on each entry for the UI's
+    /// benefit). So `n` must be a position in this very array, and the array
+    /// must not be reordered or filtered between building it and sending it.
+    /// `nativeSubtitleArrayIndex()` on the frontend computes `n` from the same
+    /// list that is sent here, for exactly this reason.
+    ///
+    /// Defaulted so the background-audio handoff and the autoplay/next-episode
+    /// callers, which have no subtitles to offer, need not send the field.
+    ///
+    /// TRACES: UR-020 | IR-016, JA-008 | UT-145
+    #[serde(default)]
+    pub subtitles: Vec<crate::player::SubtitleTrack>,
 }
 
 /// Queue context for remote transfer - what type of queue is this?
@@ -373,7 +394,10 @@ pub(super) async fn create_media_item(
         needs_transcoding: req.needs_transcoding,
         video_width: None,  // Not available from video-only request
         video_height: None, // Not available from video-only request
-        subtitles: vec![],
+        // Sideloaded subtitles, in the order the frontend sent them — that order
+        // is what `player_set_subtitle_track(n)` indexes into on Android.
+        // TRACES: UR-020 | IR-016 | UT-145
+        subtitles: req.subtitles,
         series_id: None, // Not available from video-only request
         server_id: None, // Not available from video-only request
     })
@@ -1630,6 +1654,43 @@ pub async fn player_get_queue(
     Ok(get_queue_status(&controller))
 }
 
+/// What playback facilities this platform's backend actually provides.
+///
+/// The frontend is presentation-only and must not re-derive backend facts from
+/// `navigator.userAgent` — that sniffing was a second copy of the same platform
+/// decision Rust already makes with `cfg!`, and it drifted. These flags are the
+/// single source of truth; the frontend consumes them.
+///
+/// TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+#[derive(specta::Type, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PlaybackCapabilities {
+    /// True when audio is rendered by a webview `<audio>` element rather than a
+    /// native backend. Native audio exists on Linux (mpv) and Android
+    /// (ExoPlayer); everything else (Windows, future desktops) uses the webview.
+    pub uses_webview_audio: bool,
+    /// True when video can be rendered by a native surface composited *behind*
+    /// a transparent webview. Android only: ExoPlayer draws into a SurfaceView
+    /// beneath the WebView. Linux cannot do this (WebKitGTK/Wayland
+    /// compositing), so it stays on the HTML5 element.
+    pub supports_native_video: bool,
+}
+
+/// Report this platform's playback capabilities to the frontend.
+///
+/// TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+#[tauri::command]
+#[specta::specta]
+pub async fn player_get_capabilities() -> Result<PlaybackCapabilities, String> {
+    // Mirrors the cfg gates the backends themselves are built under.
+    let native_audio = cfg!(any(target_os = "android", target_os = "linux"));
+
+    Ok(PlaybackCapabilities {
+        uses_webview_audio: !native_audio,
+        supports_native_video: cfg!(target_os = "android"),
+    })
+}
+
 pub(super) fn get_player_status(controller: &PlayerController) -> PlayerStatus {
     // Determine backend at compile time based on platform
     let (backend, use_html5_element) = if cfg!(target_os = "android") {
@@ -2459,6 +2520,141 @@ pub async fn player_disable_jellyfin(player: State<'_, PlayerStateWrapper>) -> R
 
 #[cfg(test)]
 mod tests {
+    /// The subtitle list the frontend resolved must survive the IPC hop and end
+    /// up on the `MediaItem` the native backend loads.
+    ///
+    /// The bug: `VideoPlayer.svelte` built a fully-resolved subtitle array and
+    /// then dropped it on the floor — `PlayItemRequest` had no field to put it
+    /// in — so `create_media_item` always produced `subtitles: vec![]`,
+    /// `android/mod.rs` serialized `[]` across JNI, and ExoPlayer was handed a
+    /// `MediaItem` with zero `SubtitleConfiguration`s. Every later
+    /// `setSubtitleTrack(n)` then found no text track groups and logged
+    /// "Invalid subtitle track index".
+    ///
+    /// The payload below is exactly what the frontend sends: camelCase for the
+    /// top-level command params (Tauri v2 converts them), and the subtitle
+    /// entries in the casing of `SubtitleTrack` itself — note `mime_type`.
+    ///
+    /// TRACES: UR-020 | IR-016 | UT-145
+    #[tokio::test]
+    async fn test_play_item_request_carries_subtitles_into_media_item() {
+        use super::{create_media_item, PlayItemRequest};
+
+        let payload = serde_json::json!({
+            "id": "ep-1",
+            "title": "Pilot",
+            "streamUrl": "https://jelly.example/Videos/ep-1/master.m3u8",
+            "videoCodec": "h264",
+            "needsTranscoding": false,
+            "subtitles": [
+                {
+                    "index": 2,
+                    "url": "https://jelly.example/Videos/ep-1/2/Subtitles/subtitles.vtt",
+                    "language": "eng",
+                    "label": "English (SRT)",
+                    "mime_type": "text/vtt"
+                },
+                {
+                    "index": 3,
+                    "url": "https://jelly.example/Videos/ep-1/3/Subtitles/subtitles.vtt",
+                    "language": null,
+                    "label": null,
+                    "mime_type": "text/vtt"
+                }
+            ]
+        });
+
+        let req: PlayItemRequest =
+            serde_json::from_value(payload).expect("frontend payload must deserialize");
+        assert_eq!(
+            req.subtitles.len(),
+            2,
+            "PlayItemRequest must carry the subtitle tracks, not silently ignore them"
+        );
+
+        let media = create_media_item(req, None).await.unwrap();
+        assert_eq!(
+            media.subtitles.len(),
+            2,
+            "create_media_item must thread the tracks onto the MediaItem the backend loads"
+        );
+        assert_eq!(media.subtitles[0].index, 2);
+        assert_eq!(media.subtitles[0].language.as_deref(), Some("eng"));
+        assert_eq!(media.subtitles[0].label.as_deref(), Some("English (SRT)"));
+        assert_eq!(media.subtitles[0].mime_type, "text/vtt");
+        // Order is the contract: `player_set_subtitle_track(n)` is a position in
+        // this list (see the note on `PlayItemRequest::subtitles`).
+        assert_eq!(media.subtitles[1].index, 3);
+        assert!(media.subtitles[1].language.is_none());
+    }
+
+    /// A request without subtitles must still deserialize — the field is
+    /// defaulted so the background-audio handoff and the autoplay/next-episode
+    /// callers keep compiling and sending what they always sent.
+    ///
+    /// TRACES: UR-020 | IR-016 | UT-145
+    #[tokio::test]
+    async fn test_play_item_request_without_subtitles_defaults_to_empty() {
+        use super::{create_media_item, PlayItemRequest};
+
+        let req: PlayItemRequest = serde_json::from_value(serde_json::json!({
+            "id": "movie-1",
+            "title": "Movie",
+            "streamUrl": "https://jelly.example/Videos/movie-1/stream.mp4",
+            "videoCodec": "h264",
+            "needsTranscoding": false
+        }))
+        .expect("a subtitle-less payload must still deserialize");
+
+        assert!(req.subtitles.is_empty());
+        assert!(create_media_item(req, None)
+            .await
+            .unwrap()
+            .subtitles
+            .is_empty());
+    }
+
+    /// The JSON handed to Kotlin over JNI must use the keys
+    /// `JellyTauPlayer.load()` actually reads.
+    ///
+    /// `MediaItem` is `rename_all = "camelCase"`, and the instinct (and the
+    /// house IPC rule) is to camelCase nested structs too — but
+    /// `JellyTauPlayer.kt` reads `subtitle.optString("mime_type", …)`. Renaming
+    /// the field would not fail to compile or fail the IPC; it would silently
+    /// fall back to the default MIME type for every track, so this is asserted
+    /// on the exact bytes `android/mod.rs` sends.
+    ///
+    /// TRACES: UR-020 | IR-016, JA-008 | UT-146
+    #[test]
+    fn test_subtitle_json_for_jni_uses_the_keys_kotlin_reads() {
+        use crate::player::media::SubtitleTrack;
+
+        let subtitles = vec![SubtitleTrack {
+            index: 2,
+            url: "https://jelly.example/subs.vtt".to_string(),
+            language: Some("eng".to_string()),
+            label: Some("English".to_string()),
+            mime_type: "text/vtt".to_string(),
+        }];
+
+        // Exactly what player/android/mod.rs passes to loadWithMetadata.
+        let json = serde_json::to_string(&subtitles).unwrap();
+        let parsed: Vec<serde_json::Value> = serde_json::from_str(&json).unwrap();
+        let obj = parsed[0].as_object().unwrap();
+
+        for key in ["url", "language", "label", "mime_type"] {
+            assert!(
+                obj.contains_key(key),
+                "JellyTauPlayer.load() reads `{key}`; serialized keys were {:?}",
+                obj.keys().collect::<Vec<_>>()
+            );
+        }
+        assert!(
+            !obj.contains_key("mimeType"),
+            "camelCasing mime_type silently drops every track's MIME type on Android"
+        );
+    }
+
     /// The audio-only handoff must play a downloaded file when there is one,
     /// rather than fetching an audio-only stream for media already on disk.
     ///

src-tauri/src/lib.rs

@@ -123,6 +123,7 @@ use commands::{
     player_get_audio_settings,
     player_get_autoplay_settings,
     player_get_cache_config,
+    player_get_capabilities,
     player_get_eq_presets,
     player_get_queue,
     // Session management commands
@@ -682,6 +683,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
             player_cycle_repeat,
             player_get_status,
             player_get_queue,
+            player_get_capabilities,
             player_add_to_queue,
             player_add_track_by_id,
             player_add_tracks_by_ids,

src-tauri/src/player/media.rs

@@ -23,6 +23,23 @@ pub enum QueueContext {
 }
 
 /// Represents a subtitle track
+///
+/// 🔴 **Do not add `#[serde(rename_all = "camelCase")]` here.** This is the one
+/// struct in the player that deliberately keeps snake_case on the wire, because
+/// the *same* serialization feeds two consumers that both spell `mime_type`:
+///
+/// * the JNI boundary — `player/android/mod.rs` serializes `MediaItem::subtitles`
+///   with `serde_json` and hands the string to `JellyTauPlayer.loadWithMetadata`,
+///   whose parser reads `url`, `language`, `label` and `optString("mime_type")`;
+/// * the IPC boundary — `PlayItemRequest::subtitles` deserializes this same type
+///   from the frontend, and the generated binding (`SubtitleTrack` in
+///   `bindings.ts`) therefore also declares `mime_type`.
+///
+/// Renaming would not break the build and would not fail the IPC: Kotlin's
+/// `optString` would just fall back to its default MIME type for every track, so
+/// the failure would be silent. UT-146 asserts the serialized keys.
+///
+/// TRACES: UR-020 | IR-016, JA-008 | UT-146
 #[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct SubtitleTrack {
     /// Stream index in the media source
@@ -33,7 +50,8 @@ pub struct SubtitleTrack {
     pub language: Option<String>,
     /// Display title
     pub label: Option<String>,
-    /// MIME type (e.g., "text/vtt", "application/x-subrip")
+    /// MIME type (e.g., "text/vtt", "application/x-subrip").
+    /// Snake_case on purpose — see the note on the struct.
     pub mime_type: String,
 }
 

src-tauri/src/player/mod.rs

@@ -32,7 +32,7 @@ pub mod webview_audio_backend;
 pub use autoplay::{AutoplayDecision, AutoplaySettings};
 pub use backend::{NullBackend, PlayerBackend, PlayerError};
 pub use events::{PlayerEventEmitter, PlayerStatusEvent, TauriEventEmitter};
-pub use media::{MediaItem, MediaSource, MediaType, QueueContext};
+pub use media::{MediaItem, MediaSource, MediaType, QueueContext, SubtitleTrack};
 pub use queue::{QueueManager, RepeatMode};
 pub use seek::{determine_video_seek_strategy, VideoSeekStrategy};
 pub use session::{MediaSessionManager, MediaSessionType};

src-tauri/src/repository/device_profile.rs

@@ -50,10 +50,189 @@ pub fn max_audio_channels() -> u32 {
     clamp_max_audio_channels(reported)
 }
 
+/// Audio codecs the webview's `<video>` element can decode.
+///
+/// Deliberately narrower than what the platform reports: see
+/// [`video_audio_codecs`].
+const WEBVIEW_AUDIO_CODECS: &[&str] = &["aac", "mp3", "opus", "vorbis", "flac"];
+
+/// The codec claimed when a device reports nothing we can use. Every renderer
+/// decodes AAC, and claiming *something* is what makes the server transcode to
+/// it rather than give up.
+const FALLBACK_AUDIO_CODEC: &str = "aac";
+
+/// Narrow a detected audio-codec list to what the renderer that will actually
+/// play the **video** can decode.
+///
+/// The platform list comes from `MediaCodecList`, which describes ExoPlayer —
+/// but video does not play through ExoPlayer. Both Android and Linux render it
+/// in a webview `<video>` element, and Chromium/WebKit decode a much smaller set
+/// than the platform does. Advertising the raw list makes Jellyfin direct-play a
+/// track the webview cannot decode, and the user gets picture with no sound.
+///
+/// The gap is widest on devices whose vendor licenses Dolby: a phone with
+/// `c2.dolby.eac3.decoder` reports `eac3`, so it — and only it — gets a silent
+/// direct play where a leaner device is transcoded to AAC and plays fine.
+///
+/// This applies to the *video* direct-play profile only. Audio-only playback
+/// really is ExoPlayer's, so its profile keeps the full platform list.
+///
+/// TRACES: UR-004 | DR-148 | UT-142
+pub fn video_audio_codecs(detected: &str) -> String {
+    let kept: Vec<&str> = detected
+        .split(',')
+        .filter_map(|codec| {
+            let codec = codec.trim();
+            // Match case-insensitively but emit our own spelling: the platform
+            // list is assembled from MIME strings and its casing is not ours to
+            // forward to the server.
+            WEBVIEW_AUDIO_CODECS
+                .iter()
+                .copied()
+                .find(|supported| supported.eq_ignore_ascii_case(codec))
+        })
+        .collect();
+
+    if kept.is_empty() {
+        FALLBACK_AUDIO_CODEC.to_string()
+    } else {
+        kept.join(",")
+    }
+}
+
+/// Whether the webview `<video>` element can decode this audio codec.
+///
+/// TRACES: UR-004 | DR-149 | UT-148
+pub fn webview_can_decode_audio(codec: &str) -> bool {
+    WEBVIEW_AUDIO_CODECS
+        .iter()
+        .any(|supported| supported.eq_ignore_ascii_case(codec.trim()))
+}
+
+/// Decide whether we must transcode *regardless of what the server negotiated*,
+/// given the source's audio streams as `(codec, is_default)` in source order.
+///
+/// Advertising a narrow profile ([`video_audio_codecs`]) is necessary but not
+/// sufficient: Jellyfin 10.11.5 enforces a `DirectPlayProfile`'s container and
+/// video codec but **ignores its audio codec** — an E-AC-3 track is offered for
+/// direct play even when the profile lists only AAC, and neither a `VideoAudio`
+/// `CodecProfile` nor `MaxAudioChannels` changes that. So the client cannot
+/// delegate this decision; it knows what its own renderer can decode and must
+/// apply that itself.
+///
+/// The track that matters is the one the server will actually serve: the
+/// default, or the first when none is marked. An unknown codec is left alone —
+/// forcing a transcode on a guess would burn server CPU for files that play.
+///
+/// TRACES: UR-004 | DR-149 | UT-148
+pub fn audio_forces_transcode(streams: &[(Option<&str>, bool)]) -> bool {
+    let served = streams
+        .iter()
+        .find(|(_, is_default)| *is_default)
+        .or_else(|| streams.first());
+
+    match served {
+        Some((Some(codec), _)) => !webview_can_decode_audio(codec),
+        // No audio at all, or a codec the server did not name: leave it alone.
+        Some((None, _)) | None => false,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn an_undecodable_default_track_forces_a_transcode() {
+        // The reported bug: one E-AC-3 track, which the webview cannot decode.
+        assert!(audio_forces_transcode(&[(Some("eac3"), false)]));
+        assert!(audio_forces_transcode(&[(Some("ac3"), true)]));
+    }
+
+    #[test]
+    fn a_decodable_track_is_left_to_direct_play() {
+        // Never spend server CPU on a file that already plays.
+        assert!(!audio_forces_transcode(&[(Some("aac"), true)]));
+        assert!(!audio_forces_transcode(&[(Some("mp3"), false)]));
+    }
+
+    #[test]
+    fn the_default_track_decides_not_the_first() {
+        // The webview plays the default track, so that is the one that has to be
+        // decodable — a supported track further down does not save us.
+        assert!(audio_forces_transcode(&[
+            (Some("aac"), false),
+            (Some("eac3"), true)
+        ]));
+        assert!(!audio_forces_transcode(&[
+            (Some("eac3"), false),
+            (Some("aac"), true)
+        ]));
+    }
+
+    #[test]
+    fn with_no_default_marked_the_first_track_decides() {
+        // Jellyfin leaves IsDefault false on every stream for some files; the
+        // server then serves the first, so judge that one.
+        assert!(audio_forces_transcode(&[
+            (Some("eac3"), false),
+            (Some("aac"), false)
+        ]));
+    }
+
+    #[test]
+    fn a_source_with_no_audio_is_not_transcoded() {
+        // Nothing to rescue, and a transcode would not create audio.
+        assert!(!audio_forces_transcode(&[]));
+    }
+
+    #[test]
+    fn an_unknown_codec_is_not_second_guessed() {
+        // The server did not tell us the codec; assuming the worst would
+        // transcode files that play perfectly.
+        assert!(!audio_forces_transcode(&[(None, true)]));
+    }
+
+    #[test]
+    fn a_dolby_device_does_not_advertise_dolby_for_video() {
+        // The bug: a Motorola reporting c2.dolby.eac3.decoder direct-played
+        // E-AC-3 into a webview that cannot decode it — silent video, on that
+        // device only.
+        let codecs = video_audio_codecs("aac,ac3,amrnb,amrwb,eac3,flac,mp3,opus,pcm,vorbis");
+        assert_eq!(codecs, "aac,flac,mp3,opus,vorbis");
+    }
+
+    #[test]
+    fn codecs_the_webview_cannot_decode_are_dropped() {
+        // AMR and raw PCM come from the AOSP set, so this is not a Dolby-only
+        // problem — it is just rarer content.
+        assert_eq!(video_audio_codecs("amrnb,amrwb,pcm,aac"), "aac");
+        assert_eq!(video_audio_codecs("dts,truehd,mp3"), "mp3");
+    }
+
+    #[test]
+    fn a_list_the_webview_fully_supports_is_untouched() {
+        assert_eq!(
+            video_audio_codecs("aac,mp3,opus,vorbis,flac"),
+            "aac,mp3,opus,vorbis,flac"
+        );
+    }
+
+    #[test]
+    fn nothing_decodable_still_claims_aac() {
+        // Claiming an empty list invites the server to give up rather than
+        // transcode. AAC is universally decodable, so ask for it.
+        assert_eq!(video_audio_codecs("eac3,dts"), "aac");
+        assert_eq!(video_audio_codecs(""), "aac");
+    }
+
+    #[test]
+    fn spacing_and_case_in_the_platform_list_are_tolerated() {
+        // The list is assembled from MediaCodecList strings; do not let
+        // whitespace decide whether the user gets sound.
+        assert_eq!(video_audio_codecs("aac, EAC3 , Mp3"), "aac,mp3");
+    }
+
     #[test]
     fn an_unknown_route_falls_back_to_stereo() {
         // Codec detection has not run yet, or the platform has no answer. Never

src-tauri/src/repository/online.rs

@@ -1,9 +1,7 @@
 //! TRACES: UR-002, UR-007 | DR-013 | IR-010
 
 use async_trait::async_trait;
-#[cfg(target_os = "android")]
-use log::warn;
-use log::{debug, error, info};
+use log::{debug, error, info, warn};
 use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 
@@ -1342,6 +1340,9 @@ impl MediaRepository for OnlineRepository {
             index: i32,
             #[serde(default)]
             codec: Option<String>,
+            /// The track the server serves when the client pins none.
+            #[serde(default)]
+            is_default: bool,
         }
 
         // Get detected codecs from Android MediaCodecList or use platform defaults
@@ -1356,8 +1357,9 @@ impl MediaRepository for OnlineRepository {
         // 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, but the PlaybackInfo
-        // profile is shared, so we keep the broadly-supported audio codecs.)
+        // (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());
@@ -1368,8 +1370,19 @@ impl MediaRepository for OnlineRepository {
             "aac,mp3,opus,vorbis,flac".to_string(),
         );
 
+        // Video plays in a webview <video> element on every platform, which
+        // decodes a narrower audio set than the platform does — so the video
+        // profile must claim less than the audio-only profile. Without this a
+        // Dolby-licensed device advertises eac3, gets a direct play, and shows
+        // picture with no sound.
+        let video_audio_codecs = super::device_profile::video_audio_codecs(&audio_codecs);
+
         info!("[DeviceProfile] Using video codecs: {}", video_codecs);
         info!("[DeviceProfile] Using audio codecs: {}", audio_codecs);
+        info!(
+            "[DeviceProfile] Audio codecs for video direct play: {}",
+            video_audio_codecs
+        );
 
         // Bound every profile by what the audio route can actually voice, so a
         // multichannel track is downmixed by the server rather than direct-played
@@ -1388,12 +1401,16 @@ impl MediaRepository for OnlineRepository {
                     profile_type: "Video".to_string(),
                     container: "mp4,mkv,avi,mov,flv,ts,m2ts,webm,ogv,3gp".to_string(),
                     video_codec: Some(video_codecs.clone()),
-                    audio_codec: audio_codecs.clone(),
+                    // The webview decodes this stream, not ExoPlayer/MPV.
+                    audio_codec: video_audio_codecs.clone(),
                 },
                 DirectPlayProfile {
                     profile_type: "Audio".to_string(),
                     container: "mp3,aac,flac,alac,wav,ogg,wma,opus".to_string(),
                     video_codec: None,
+                    // Audio-only really is the native player's, so it keeps the
+                    // full platform list — narrowing it would transcode music
+                    // that plays perfectly well.
                     audio_codec: audio_codecs.clone(),
                 },
             ],
@@ -1459,9 +1476,29 @@ impl MediaRepository for OnlineRepository {
             );
         }
 
+        // Jellyfin 10.11.5 honours a DirectPlayProfile's container and video codec
+        // but ignores its audio codec, so it offers an E-AC-3 track for direct
+        // play even though DR-148 advertises only AAC — and the webview renders
+        // the picture in silence. Judge the track we would actually be served
+        // against what the webview can decode, and override the server's answer.
+        let audio_streams: Vec<(Option<&str>, bool)> = source
+            .media_streams
+            .iter()
+            .filter(|stream| stream.stream_type == "Audio")
+            .map(|stream| (stream.codec.as_deref(), stream.is_default))
+            .collect();
+        let audio_forces_transcode = super::device_profile::audio_forces_transcode(&audio_streams);
+
         // Use TranscodingUrl from response if available (Streamyfin pattern)
         let stream_url = if let Some(transcoding_url) = &source.transcoding_url {
             format!("{}{}", self.server_url, transcoding_url)
+        } else if audio_forces_transcode {
+            warn!(
+                "[PlaybackInfo] Server offered direct play for audio the webview cannot decode ({:?}) — forcing an HLS transcode",
+                audio_streams.first().and_then(|(codec, _)| *codec)
+            );
+            self.get_video_stream_url(item_id, Some(&source.id), None, None)
+                .await?
         } else {
             // Fall back to direct stream URL. No audioStreamIndex: static=true
             // serves the original file untouched, and pinning index 0 (the video
@@ -1482,8 +1519,9 @@ impl MediaRepository for OnlineRepository {
             media_source_id: source.id.clone(),
             play_session_id: response.play_session_id,
             stream_url,
-            direct_play: source.supports_direct_play,
-            needs_transcoding: !source.supports_direct_play && source.supports_transcoding,
+            direct_play: source.supports_direct_play && !audio_forces_transcode,
+            needs_transcoding: audio_forces_transcode
+                || (!source.supports_direct_play && source.supports_transcoding),
         })
     }
 
@@ -1734,6 +1772,7 @@ impl MediaRepository for OnlineRepository {
         )
     }
 
+    /// TRACES: UR-071 | DR-123
     fn get_video_download_url(
         &self,
         item_id: &str,
@@ -1751,27 +1790,43 @@ impl MediaRepository for OnlineRepository {
         // Map the frontend quality preset to concrete transcode params. For
         // "original" we request a direct static copy (no transcode) which is
         // byte-range resumable; other presets ask the server to transcode.
+        //
+        // 🔴 It is `videoBitRate`/`audioBitRate` — **capital R**. Jellyfin binds
+        // query keys case-insensitively, so `maxHeight`/`videoCodec` casing is
+        // free, but `videoBitrate` (lowercase r) is a *different token*: it
+        // fails to bind, is silently dropped, and the requested cap vanishes
+        // with no error. That is why every "480p"/"720p" download came back at
+        // full original quality. See `Jellyfin.Api` BaseEncodingJobOptions.
+        //
+        // `allowVideoStreamCopy=false` forces a real re-encode. Without it the
+        // server may stream-copy the source when it already satisfies the cap —
+        // fine in itself, but it also means a mis-typed cap degrades silently.
+        // Note `enableAutoStreamCopy=false` alone does NOT stop a *video* copy;
+        // video copy is gated by `allowVideoStreamCopy`.
         match quality {
             "high" => {
-                params.push("videoBitrate=8000000".to_string());
+                params.push("videoBitRate=8000000".to_string());
                 params.push("maxHeight=1080".to_string());
-                params.push("audioBitrate=384000".to_string());
+                params.push("audioBitRate=384000".to_string());
                 params.push("videoCodec=h264".to_string());
                 params.push("audioCodec=aac".to_string());
+                params.push("allowVideoStreamCopy=false".to_string());
             }
             "medium" => {
-                params.push("videoBitrate=4000000".to_string());
+                params.push("videoBitRate=4000000".to_string());
                 params.push("maxHeight=720".to_string());
-                params.push("audioBitrate=256000".to_string());
+                params.push("audioBitRate=256000".to_string());
                 params.push("videoCodec=h264".to_string());
                 params.push("audioCodec=aac".to_string());
+                params.push("allowVideoStreamCopy=false".to_string());
             }
             "low" => {
-                params.push("videoBitrate=1500000".to_string());
+                params.push("videoBitRate=1500000".to_string());
                 params.push("maxHeight=480".to_string());
-                params.push("audioBitrate=128000".to_string());
+                params.push("audioBitRate=128000".to_string());
                 params.push("videoCodec=h264".to_string());
                 params.push("audioCodec=aac".to_string());
+                params.push("allowVideoStreamCopy=false".to_string());
             }
             // "original" (and any unknown value) → direct, resumable copy.
             _ => {
@@ -2510,7 +2565,7 @@ mod tests {
         // with no transcode params.
         assert!(url.contains("Static=true"), "url: {url}");
         assert!(
-            !url.contains("videoBitrate"),
+            !url.contains("videoBitRate"),
             "original must not transcode: {url}"
         );
         assert!(
@@ -2530,7 +2585,7 @@ mod tests {
                 "{quality} must use stream.mp4: {url}"
             );
             assert!(
-                url.contains("videoBitrate="),
+                url.contains("videoBitRate="),
                 "{quality} must set bitrate: {url}"
             );
             assert!(
@@ -2546,6 +2601,66 @@ mod tests {
         }
     }
 
+    /// The bitrate params are spelled `videoBitRate`/`audioBitRate` — **capital
+    /// R**. Jellyfin binds query keys case-insensitively, so this is not a
+    /// casing preference: `videoBitrate` is a *different token* that fails to
+    /// bind and is silently discarded, taking the user's quality cap with it.
+    /// Nothing errors — the download just returns the full-size original, which
+    /// is exactly how this bug went unnoticed.
+    #[test]
+    fn test_video_download_url_bitrate_params_use_capital_r_spelling() {
+        let repo = create_test_repository();
+
+        for quality in ["high", "medium", "low"] {
+            let url = repo.get_video_download_url("item123", quality, None);
+
+            assert!(
+                url.contains("videoBitRate="),
+                "{quality} must spell it videoBitRate (capital R): {url}"
+            );
+            assert!(
+                url.contains("audioBitRate="),
+                "{quality} must spell it audioBitRate (capital R): {url}"
+            );
+
+            // The lowercase-r spellings never bind — they must not appear at
+            // all, or the cap is silently dropped by the server.
+            assert!(
+                !url.contains("videoBitrate="),
+                "{quality} emits the unbindable lowercase-r spelling: {url}"
+            );
+            assert!(
+                !url.contains("audioBitrate="),
+                "{quality} emits the unbindable lowercase-r spelling: {url}"
+            );
+        }
+    }
+
+    /// A correctly-spelled cap is still only *conditionally* honored: the server
+    /// may stream-copy the source when it already satisfies the cap. Video copy
+    /// is gated by `allowVideoStreamCopy` (NOT `enableAutoStreamCopy`, which
+    /// only governs audio), so the transcode presets must disable it to
+    /// guarantee a real re-encode at the requested bitrate.
+    #[test]
+    fn test_video_download_url_transcode_presets_forbid_video_stream_copy() {
+        let repo = create_test_repository();
+
+        for quality in ["high", "medium", "low"] {
+            let url = repo.get_video_download_url("item123", quality, None);
+            assert!(
+                url.contains("allowVideoStreamCopy=false"),
+                "{quality} must forbid video stream copy: {url}"
+            );
+        }
+
+        // "original" is a deliberate direct copy — it must NOT disable copying.
+        let original = repo.get_video_download_url("item123", "original", None);
+        assert!(
+            !original.contains("allowVideoStreamCopy=false"),
+            "original must remain a direct copy: {original}"
+        );
+    }
+
     #[test]
     fn test_video_download_url_passes_media_source_id() {
         let repo = create_test_repository();

src-tauri/tauri.android.conf.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "app": {
+    "windows": [
+      {
+        "transparent": true
+      }
+    ]
+  }
+}

src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "jellytau",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "identifier": "com.dtourolle.jellytau",
   "build": {
     "beforeDevCommand": "bun run dev",

src/app.css

@@ -51,6 +51,30 @@ html, body {
   background-color: var(--color-background);
 }
 
+/* Native-video compositing (Android).
+ *
+ * TRACES: UR-003, UR-004 | DR-150
+ *
+ * When ExoPlayer renders into a SurfaceView *behind* the WebView, every opaque
+ * layer between the viewport and that surface hides the video. The WebView
+ * itself is made transparent by `"transparent": true` in
+ * tauri.android.conf.json; these rules clear the app's own painted backgrounds.
+ *
+ * Scoped to `[data-native-video="active"]` — set on <html> by
+ * $lib/stores/nativeVideo.ts only while a native video session is on screen —
+ * because every other screen genuinely needs its opaque background. The app
+ * shell (+layout.svelte) also paints --color-background across the viewport, so
+ * it is cleared here too; the shell is the layer directly over the surface.
+ *
+ * `background: transparent` (not a colour) is required: an alpha-0 colour still
+ * composites in some WebView versions.
+ */
+html[data-native-video="active"],
+html[data-native-video="active"] body,
+html[data-native-video="active"] [data-app-shell] {
+  background: transparent !important;
+}
+
 body {
   @apply text-white antialiased;
   font-family: system-ui, -apple-system, sans-serif;

src/lib/api/bindings.ts

@@ -143,6 +143,14 @@ async playerGetStatus() : Promise<PlayerStatus> {
 async playerGetQueue() : Promise<QueueStatus> {
     return await TAURI_INVOKE("player_get_queue");
 },
+/**
+ * Report this platform's playback capabilities to the frontend.
+ * 
+ * TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+ */
+async playerGetCapabilities() : Promise<PlaybackCapabilities> {
+    return await TAURI_INVOKE("player_get_capabilities");
+},
 async playerAddToQueue(request: AddToQueueRequest) : Promise<QueueStatus> {
     return await TAURI_INVOKE("player_add_to_queue", { request });
 },
@@ -2231,7 +2239,29 @@ itemType?: string | null;
  * Series ID for TV episodes. Needed alongside `item_type` so the backend can
  * look up the next episode when a background-audio track ends.
  */
-seriesId?: string | null }
+seriesId?: string | null; 
+/**
+ * Subtitle tracks to sideload, with URLs the frontend has already resolved.
+ * 
+ * Only the native backends use these: on Android they become the
+ * `MediaItem.SubtitleConfiguration`s ExoPlayer renders. The HTML5 path
+ * builds its own `<track>` children instead and ignores this list.
+ * 
+ * **Order is the contract.** `player_set_subtitle_track(n)` reaches
+ * `JellyTauPlayer.setSubtitleTrack(n)`, which indexes into ExoPlayer's
+ * *text track groups* — i.e. the position of the sideloaded configuration,
+ * not the Jellyfin stream index (which is kept on each entry for the UI's
+ * benefit). So `n` must be a position in this very array, and the array
+ * must not be reordered or filtered between building it and sending it.
+ * `nativeSubtitleArrayIndex()` on the frontend computes `n` from the same
+ * list that is sent here, for exactly this reason.
+ * 
+ * Defaulted so the background-audio handoff and the autoplay/next-episode
+ * callers, which have no subtitles to offer, need not send the field.
+ * 
+ * TRACES: UR-020 | IR-016, JA-008 | UT-145
+ */
+subtitles?: SubtitleTrack[] }
 /**
  * Queue context for remote transfer - what type of queue is this?
  */
@@ -2271,6 +2301,30 @@ export type PlayTracksRequest = { trackIds: string[]; startIndex: number; shuffl
  * over playback from a remote session so we don't restart from 0.
  */
 startPosition?: number | null }
+/**
+ * What playback facilities this platform's backend actually provides.
+ * 
+ * The frontend is presentation-only and must not re-derive backend facts from
+ * `navigator.userAgent` — that sniffing was a second copy of the same platform
+ * decision Rust already makes with `cfg!`, and it drifted. These flags are the
+ * single source of truth; the frontend consumes them.
+ * 
+ * TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+ */
+export type PlaybackCapabilities = { 
+/**
+ * True when audio is rendered by a webview `<audio>` element rather than a
+ * native backend. Native audio exists on Linux (mpv) and Android
+ * (ExoPlayer); everything else (Windows, future desktops) uses the webview.
+ */
+usesWebviewAudio: boolean; 
+/**
+ * True when video can be rendered by a native surface composited *behind*
+ * a transparent webview. Android only: ExoPlayer draws into a SurfaceView
+ * beneath the WebView. Linux cannot do this (WebKitGTK/Wayland
+ * compositing), so it stays on the HTML5 element.
+ */
+supportsNativeVideo: boolean }
 /**
  * Playback information
  */
@@ -2769,6 +2823,23 @@ export type StreamKind = "audio" | "video" | "subtitle" |
 "other"
 /**
  * Represents a subtitle track
+ * 
+ * 🔴 **Do not add `#[serde(rename_all = "camelCase")]` here.** This is the one
+ * struct in the player that deliberately keeps snake_case on the wire, because
+ * the *same* serialization feeds two consumers that both spell `mime_type`:
+ * 
+ * * the JNI boundary — `player/android/mod.rs` serializes `MediaItem::subtitles`
+ * with `serde_json` and hands the string to `JellyTauPlayer.loadWithMetadata`,
+ * whose parser reads `url`, `language`, `label` and `optString("mime_type")`;
+ * * the IPC boundary — `PlayItemRequest::subtitles` deserializes this same type
+ * from the frontend, and the generated binding (`SubtitleTrack` in
+ * `bindings.ts`) therefore also declares `mime_type`.
+ * 
+ * Renaming would not break the build and would not fail the IPC: Kotlin's
+ * `optString` would just fall back to its default MIME type for every track, so
+ * the failure would be silent. UT-146 asserts the serialized keys.
+ * 
+ * TRACES: UR-020 | IR-016, JA-008 | UT-146
  */
 export type SubtitleTrack = { 
 /**
@@ -2788,7 +2859,8 @@ language: string | null;
  */
 label: string | null; 
 /**
- * MIME type (e.g., "text/vtt", "application/x-subrip")
+ * MIME type (e.g., "text/vtt", "application/x-subrip").
+ * Snake_case on purpose — see the note on the struct.
  */
 mime_type: string }
 /**

src/lib/components/player/VideoPlayer.svelte

@@ -1,6 +1,6 @@
 <!-- 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, untrack } from "svelte";
+  import { onMount, onDestroy, tick, untrack } from "svelte";
   import { get } from "svelte/store";
   import { goto } from "$app/navigation";
   import { commands } from "$lib/api/bindings";
@@ -14,12 +14,30 @@
   import SleepTimerIndicator from "./SleepTimerIndicator.svelte";
   import CachedImage from "../common/CachedImage.svelte";
   import { videoFitClass } from "./videoFit";
+  import {
+    resolveSubtitleTracks,
+    reconcileSelectedSubtitle,
+    videoCrossOriginMode,
+    nativeSubtitleTracks,
+    nativeSubtitleArrayIndex,
+    type RenderableSubtitleTrack,
+  } from "./subtitleTracks";
   import { sleepTimerActive, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
   import { playbackPosition, playerState } from "$lib/stores/player";
   import * as html5Adapter from "$lib/player/html5Adapter";
   import { playerController } from "$lib/player";
-  import { Html5PlayerAdapter, type Html5ElementBridge } from "$lib/player/adapters";
+  import {
+    createAdapter,
+    Html5PlayerAdapter,
+    type PlayerAdapter,
+    type Html5ElementBridge,
+  } from "$lib/player/adapters";
   import { createRustReportHost } from "$lib/player/adapters/rustReportHost";
+  import { experimentalNativeVideo } from "$lib/stores/nativeVideo";
+  import {
+    enableNativeVideoCompositing,
+    disableNativeVideoCompositing,
+  } from "$lib/utils/videoSurface";
   import { isPipSupported, enterPip, setAutoEnterEnabled } from "$lib/utils/pictureInPicture";
   import {
     createTapGestureState,
@@ -158,7 +176,10 @@
   // VideoPlayer supplies a narrow bridge for the element/HLS-coupled parts and
   // registers the adapter with the facade so control intents — from UI OR from a
   // backend control event (lockscreen/remote/sleep) — reach this element.
-  let playerAdapter: Html5PlayerAdapter | null = null;
+  // Widened from Html5PlayerAdapter: the native path registers a
+  // NativePlayerAdapter here. Element-coupled work is guarded by
+  // `useHtml5Element`, not by narrowing this type.
+  let playerAdapter: PlayerAdapter | null = null;
 
   function tearDownHls() {
     if (hls) {
@@ -275,6 +296,61 @@
     return tracks;
   });
 
+  // ===== Subtitle <track> sources for the HTML5 element (Linux/WebKitGTK) =====
+  // Resolved asynchronously into state and only then rendered. The URLs come
+  // from an async command, so they must never be bound to `src` directly — the
+  // original markup did exactly that and put "[object Promise]" on every track,
+  // which is why the whole block ended up commented out (and why selecting a
+  // subtitle did nothing: with no <track> children the element has no
+  // textTracks for the adapter to switch on).
+  // TRACES: UR-020 | DR-023 | UT-143, UT-144
+  let renderedSubtitleTracks = $state<RenderableSubtitleTrack[]>([]);
+
+  // The subtitle list actually handed to the native backend at load time
+  // (Android/ExoPlayer). Kept because `player_set_subtitle_track` takes a
+  // *position in this list*, not a Jellyfin stream index — see
+  // nativeSubtitleArrayIndex. It is written once, from onMount, before the
+  // play request; it is not derived, because the request is what fixed the
+  // backend's idea of the track order.
+  // TRACES: UR-020 | IR-016 | UT-147
+  let sentSubtitleTracks = $state<RenderableSubtitleTrack[]>([]);
+
+  // Cross-origin <track> fetches use the media element's CORS setting; see
+  // videoCrossOriginMode for why this is opt-in and same-origin-only.
+  const videoCrossOrigin = $derived(
+    videoCrossOriginMode(currentStreamUrl, subtitleTracks().length)
+  );
+
+  $effect(() => {
+    const streams = media?.mediaStreams ?? null;
+    const itemId = media?.id;
+    const sourceId = mediaSourceId;
+    // Native (ExoPlayer) mode renders subtitles itself; the element has none.
+    if (!useHtml5Element || !itemId || !sourceId) {
+      renderedSubtitleTracks = [];
+      return;
+    }
+
+    let cancelled = false;
+    void (async () => {
+      const tracks = await resolveSubtitleTracks(streams, (index) => getSubtitleUrl(index));
+      if (cancelled) return;
+      renderedSubtitleTracks = tracks;
+      // Keep the menu's checkmark and the element's text tracks in agreement:
+      // a selection that no longer resolves collapses to "Off".
+      const selected = reconcileSelectedSubtitle(tracks, untrack(() => selectedSubtitleIndex));
+      selectedSubtitleIndex = selected;
+      // The <track> children were just (re)created, so re-apply the selection to
+      // the new TextTrack objects — otherwise a surviving selection shows nothing.
+      await tick();
+      if (!cancelled) applySubtitleToElement(selected);
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  });
+
   // Track the last prop value to detect when parent changes the URL (vs internal seeks)
   let lastStreamUrlProp = $state("");
 
@@ -544,28 +620,23 @@
         console.log("[VideoPlayer] Initializing player for:", media.name);
         console.log("[VideoPlayer] Stream URL:", currentStreamUrl);
 
-        // Build subtitle tracks for native player
-        const subtitleTracks = [];
-        if (media.mediaStreams && mediaSourceId) {
-          const subtitles = media.mediaStreams.filter(s => s.kind === "subtitle");
-          for (const sub of subtitles) {
-            try {
-              const url = await getSubtitleUrl(sub.index);
-              if (url) {
-                subtitleTracks.push({
-                  index: sub.index,
-                  url: url,
-                  language: sub.language || null,
-                  label: sub.displayTitle || sub.language || `Track ${sub.index}`,
-                  mime_type: "text/vtt" // Jellyfin converts to WebVTT
-                });
-              }
-            } catch (err) {
-              console.warn(`[VideoPlayer] Failed to build subtitle URL for track ${sub.index}:`, err);
-            }
-          }
-          console.log(`[VideoPlayer] Built ${subtitleTracks.length} subtitle tracks for native player`);
-        }
+        // Resolve subtitle URLs for the native (ExoPlayer) path. These must be
+        // in hand *before* the play request: ExoPlayer sideloads subtitles as
+        // MediaItem.SubtitleConfigurations, which have to exist before
+        // prepare() — there is no way to add one to a loaded item afterwards.
+        //
+        // Awaiting here is safe despite the native-mode pitfall: that rule is
+        // about Svelte *lifecycle* calls (onMount/onDestroy) after an await,
+        // which throw lifecycle_outside_component and used to be misread as an
+        // init failure. Nothing is registered here, and the background-audio
+        // subscriptions above already ran synchronously. resolveSubtitleTracks
+        // fans the requests out in parallel, so this costs one round trip, not
+        // one per subtitle stream as the old serial loop did.
+        // TRACES: UR-020 | IR-016, JA-008 | UT-147
+        sentSubtitleTracks = mediaSourceId
+          ? await resolveSubtitleTracks(media.mediaStreams, (index) => getSubtitleUrl(index))
+          : [];
+        console.log(`[VideoPlayer] Sending ${sentSubtitleTracks.length} subtitle tracks to the backend`);
 
         // Call Rust backend to start playback
         // Rust will choose ExoPlayer (Android), libmpv (Linux), or tell us to use HTML5
@@ -576,6 +647,10 @@
           id: media.id,
           videoCodec: needsTranscoding ? "hevc" : "h264",
           needsTranscoding: needsTranscoding,
+          // Order matters: player_set_subtitle_track(n) is a position in this
+          // array. Previously this array was built and then dropped, so
+          // ExoPlayer got a MediaItem with no subtitles at all.
+          subtitles: nativeSubtitleTracks(sentSubtitleTracks),
         });
 
         // Rust tells us which backend it's using
@@ -583,15 +658,16 @@
         backendChosen = true;
         console.log(`[VideoPlayer] Backend: ${response.backend}, useHtml5Element: ${useHtml5Element}`);
 
-        // INTERIM (until the video-player API refactor lands): always render
-        // through the webview HTML5 element, including Android. The native
-        // ExoPlayer SurfaceView sits behind an opaque webview and has never
-        // actually been visible (an init bug kept the app on the HTML5 path
-        // since the POC), so true native mode plays audio behind a frozen
-        // picture. Stop the native backend and let the webview own playback,
-        // matching Linux behavior and avoiding dual audio.
-        if (!useHtml5Element) {
-          console.warn("[VideoPlayer] Native video backend reported - overriding to HTML5 rendering (native surface not visible through webview)");
+        // Rust reported a native backend (Android/ExoPlayer). Honour it only if
+        // the user opted into the experimental native path; otherwise fall back
+        // to the webview element, which is what shipped by default.
+        //
+        // The flag is a suppressor, never a promoter — see createAdapter(). When
+        // it is off we must also stop the native backend that player_play_item
+        // just started, or ExoPlayer and the <video> element both decode the
+        // same stream and the audio doubles.
+        if (!useHtml5Element && !$experimentalNativeVideo) {
+          console.log("[VideoPlayer] Native backend available but experimentalNativeVideo is off - using HTML5");
           useHtml5Element = true;
           try {
             await commands.playerStop();
@@ -599,6 +675,14 @@
           } catch (err) {
             console.warn("[VideoPlayer] Failed to stop native backend:", err);
           }
+        } else if (!useHtml5Element) {
+          // Native path: clear the opaque layers between the viewport and the
+          // ExoPlayer SurfaceView (webview widget background + page background).
+          // Paired with disableNativeVideoCompositing() in the teardown path —
+          // leaving this on renders the rest of the app over a transparent
+          // window.
+          console.log("[VideoPlayer] Using native ExoPlayer video surface");
+          enableNativeVideoCompositing();
         }
 
         // If using HTML5 element for non-transcoded content, stop the backend player
@@ -617,14 +701,24 @@
           didStartNativePlayback = true; // Track that we need to stop backend on unmount
         }
 
-        // Register the HTML5 player adapter with the facade so control intents
-        // (UI or backend lockscreen/remote/sleep events) route to this element.
-        if (useHtml5Element) {
+        // Register the adapter with the facade so control intents (UI, or a
+        // backend lockscreen/remote/sleep event) route to whatever is actually
+        // rendering. Both paths need one: the native adapter forwards control
+        // intents to ExoPlayer over IPC.
+        {
           const host = createRustReportHost(media.id, {
             onEnded: () => notifyEnded(),
             onStreamUrlChanged: (u) => { currentStreamUrl = u; },
           });
-          playerAdapter = new Html5PlayerAdapter(host, adapterBridge);
+          playerAdapter = createAdapter({
+            backendKind: useHtml5Element ? "html5" : "native",
+            host,
+            bridge: adapterBridge,
+            // useHtml5Element is already the resolved decision above, so the
+            // flag has had its say; pass it through for the invariant check.
+            experimentalNativeVideo: $experimentalNativeVideo,
+          });
+          // No-op for the native adapter, which owns no DOM element.
           playerAdapter.attach(videoElement);
           playerController.setActiveAdapter(playerAdapter);
         }
@@ -718,6 +812,14 @@
   });
 
   onDestroy(async () => {
+    // FIRST, and synchronously: restore the opaque webview/page backgrounds.
+    //
+    // This callback is async, so anything after an `await` may run a frame or
+    // more later. Leaving the window transparent for even that long shows the
+    // launcher/wallpaper through the app as the player unwinds. Unconditional
+    // and idempotent — a no-op when compositing was never enabled.
+    disableNativeVideoCompositing();
+
     // Stop RAF loop
     stopTimeUpdates();
 
@@ -1670,41 +1772,59 @@
     showSubtitleMenu = !showSubtitleMenu;
   }
 
-  async function selectSubtitle(streamIndex: number | null, arrayIndex?: number) {
-    console.log("[VideoPlayer] Selecting subtitle - streamIndex:", streamIndex, "arrayIndex:", arrayIndex);
+  /**
+   * Show exactly one (or no) text track on the HTML5 element. `null` disables
+   * every track, which is what the menu's "Off" entry means.
+   *
+   * TRACES: UR-020 | DR-023
+   */
+  function applySubtitleToElement(streamIndex: number | null) {
+    if (!useHtml5Element || !videoElement || !videoElement.textTracks) return;
+
+    // Disable all text tracks first, so "Off" genuinely turns subtitles off.
+    for (let i = 0; i < videoElement.textTracks.length; i++) {
+      videoElement.textTracks[i].mode = "disabled";
+    }
+    if (streamIndex === null) return;
+
+    // Find the corresponding track element by stream index.
+    videoElement.querySelectorAll("track").forEach((track) => {
+      const trackStreamIndex = parseInt(track.getAttribute("data-stream-index") || "-1");
+      if (trackStreamIndex === streamIndex && track.track) {
+        track.track.mode = "showing";
+        console.log("[VideoPlayer] Enabled subtitle track:", streamIndex);
+      }
+    });
+  }
+
+  /**
+   * Apply the menu's choice. `streamIndex` is always the Jellyfin media-stream
+   * index (or `null` for "Off") — the UI speaks stream indices throughout.
+   *
+   * The native backend does not: `player_set_subtitle_track(n)` reaches
+   * `JellyTauPlayer.setSubtitleTrack(n)`, which indexes ExoPlayer's text track
+   * groups, i.e. the position of the sideloaded subtitle configuration. That
+   * position is derived from `sentSubtitleTracks` — the exact array sent with
+   * the play request — and not from the menu's row number, which counts every
+   * subtitle *stream* including ones whose URL never resolved and so were never
+   * sideloaded.
+   *
+   * TRACES: UR-020 | DR-023, IR-016 | UT-147
+   */
+  async function selectSubtitle(streamIndex: number | null) {
+    console.log("[VideoPlayer] Selecting subtitle - streamIndex:", streamIndex);
     selectedSubtitleIndex = streamIndex;
     showSubtitleMenu = false;
 
     // For HTML5 video element, update the text tracks
-    if (useHtml5Element && videoElement && videoElement.textTracks) {
-      // Disable all text tracks first
-      for (let i = 0; i < videoElement.textTracks.length; i++) {
-        videoElement.textTracks[i].mode = "disabled";
-      }
-
-      // Enable the selected track if not null
-      if (streamIndex !== null) {
-        // Find the corresponding track element by stream index
-        const tracks = videoElement.querySelectorAll("track");
-        tracks.forEach((track) => {
-          const trackStreamIndex = parseInt(track.getAttribute("data-stream-index") || "-1");
-          if (trackStreamIndex === streamIndex) {
-            const textTrack = track.track;
-            if (textTrack) {
-              textTrack.mode = "showing";
-              console.log("[VideoPlayer] Enabled subtitle track:", streamIndex);
-            }
-          }
-        });
-      }
-    } else if (!useHtml5Element) {
+    if (useHtml5Element) {
+      applySubtitleToElement(streamIndex);
+    } else {
       // For native backend (Android), send command to change subtitle track
       try {
-        // Use array index for ExoPlayer (0-based position in subtitle tracks array)
-        // If streamIndex is null (disable), pass null; otherwise use arrayIndex
-        const indexToUse = streamIndex === null ? null : (arrayIndex !== undefined ? arrayIndex : streamIndex);
+        const indexToUse = nativeSubtitleArrayIndex(sentSubtitleTracks, streamIndex);
         await commands.playerSetSubtitleTrack(indexToUse);
-        console.log("[VideoPlayer] Native backend subtitle track changed - arrayIndex:", arrayIndex, "used:", indexToUse);
+        console.log("[VideoPlayer] Native backend subtitle track changed - streamIndex:", streamIndex, "position:", indexToUse);
       } catch (error) {
         console.error("[VideoPlayer] Failed to set subtitle track:", error);
       }
@@ -1743,6 +1863,7 @@
       <video
           bind:this={videoElement}
           src={currentStreamUrl.includes('.m3u8') && Hls.isSupported() ? '' : currentStreamUrl}
+          crossorigin={videoCrossOrigin}
           class={videoFitClass()}
           class:invisible={!isMediaReady}
           style="filter: brightness({brightness})"
@@ -1761,18 +1882,22 @@
           onloadstart={handleLoadStart}
           onclick={handleSurfaceClick}
         >
-          <!-- Temporarily disabled to debug playback issues
-          {#each subtitleTracks() as track}
+          <!--
+            Subtitles for the HTML5 path. `src` is a resolved string (see
+            renderedSubtitleTracks); `data-stream-index` is what
+            Html5PlayerAdapter.selectSubtitle() matches on. No `default`
+            attribute: a default track auto-shows, which would contradict the
+            menu opening on "Off".
+          -->
+          {#each renderedSubtitleTracks as track (track.streamIndex)}
             <track
               kind="subtitles"
-              src={getSubtitleUrl(track.index)}
-              srclang={track.language || "unknown"}
-              label={track.displayTitle || track.language || `Track ${track.index}`}
-              data-stream-index={track.index}
-              default={track.isDefault}
+              src={track.url}
+              srclang={track.srclang}
+              label={track.label}
+              data-stream-index={track.streamIndex}
             />
           {/each}
-          -->
         </video>
     {:else}
       <!-- Android ExoPlayer - video rendered natively in SurfaceView behind WebView -->
@@ -2072,9 +2197,9 @@
                     {/if}
                   </button>
                   <!-- Subtitle tracks -->
-                  {#each subtitleTracks() as track, i}
+                  {#each subtitleTracks() as track}
                     <button
-                      onclick={() => selectSubtitle(track.index, i)}
+                      onclick={() => selectSubtitle(track.index)}
                       class="w-full text-left px-3 py-2 text-white hover:bg-white/10 rounded transition-colors flex items-center justify-between {selectedSubtitleIndex === track.index ? 'bg-white/20' : ''}"
                     >
                       <div class="flex flex-col">

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

@@ -0,0 +1,303 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  subtitleStreamsOf,
+  subtitleTrackLabel,
+  resolveSubtitleTracks,
+  reconcileSelectedSubtitle,
+  videoCrossOriginMode,
+  nativeSubtitleTracks,
+  nativeSubtitleArrayIndex,
+  type SubtitleStreamLike,
+} from "./subtitleTracks";
+
+/**
+ * Subtitles on the Linux / WebKitGTK HTML5 `<video>` path.
+ *
+ * TRACES: UR-020 | DR-023 | UT-143, UT-144
+ *
+ * The bug this guards: VideoPlayer rendered no `<track>` children at all (the
+ * block was commented out "to debug playback issues"), so
+ * `Html5PlayerAdapter.selectSubtitle()` walked an empty `textTracks` list and
+ * the subtitle menu was inert on Linux. The reason it had to be disabled is
+ * visible in the original markup — `src={getSubtitleUrl(track.index)}` bound the
+ * *Promise* returned by an async function to the attribute, so every track's src
+ * stringified to "[object Promise]", an unloadable resource hanging off the
+ * media element.
+ *
+ * So the fix has two halves and both are tested here: URLs must be resolved into
+ * plain strings *before* they reach the markup, and the markup must actually
+ * render the tracks (with the `data-stream-index` the adapter matches on).
+ */
+
+const SUBS: SubtitleStreamLike[] = [
+  { index: 2, kind: "subtitle", language: "eng", displayTitle: "English (SRT)", isDefault: true },
+  { index: 3, kind: "subtitle", language: "fre", displayTitle: "French", isDefault: false },
+];
+
+const STREAMS: SubtitleStreamLike[] = [
+  { index: 0, kind: "video", language: null, displayTitle: "1080p" },
+  { index: 1, kind: "audio", language: "eng", displayTitle: "English AAC" },
+  ...SUBS,
+];
+
+const url = (i: number) => `http://jelly.example/Videos/x/Subtitles/${i}/0/subtitles.vtt?api_key=k`;
+
+describe("subtitleStreamsOf", () => {
+  it("keeps only subtitle streams, in stream order", () => {
+    expect(subtitleStreamsOf(STREAMS).map((s) => s.index)).toEqual([2, 3]);
+  });
+
+  it("tolerates missing media streams", () => {
+    expect(subtitleStreamsOf(null)).toEqual([]);
+    expect(subtitleStreamsOf(undefined)).toEqual([]);
+  });
+});
+
+describe("subtitleTrackLabel", () => {
+  it("prefers the display title, then language, then the index", () => {
+    expect(subtitleTrackLabel({ index: 2, displayTitle: "English (SRT)", language: "eng" })).toBe("English (SRT)");
+    expect(subtitleTrackLabel({ index: 2, displayTitle: null, language: "eng" })).toBe("eng");
+    expect(subtitleTrackLabel({ index: 2 })).toBe("Track 2");
+  });
+});
+
+describe("resolveSubtitleTracks", () => {
+  it("resolves real string URLs — never a Promise — for every subtitle stream", async () => {
+    const tracks = await resolveSubtitleTracks(STREAMS, async (i) => url(i));
+
+    expect(tracks).toHaveLength(2);
+    for (const track of tracks) {
+      expect(typeof track.url).toBe("string");
+      // The exact regression: a Promise bound to src stringifies to this.
+      expect(String(track.url)).not.toContain("[object Promise]");
+      expect(track.url).toContain("subtitles.vtt");
+    }
+    // The adapter matches <track> elements by data-stream-index, so the stream
+    // index has to survive resolution.
+    expect(tracks.map((t) => t.streamIndex)).toEqual([2, 3]);
+    expect(tracks.map((t) => t.label)).toEqual(["English (SRT)", "French"]);
+    expect(tracks.map((t) => t.srclang)).toEqual(["eng", "fre"]);
+    expect(tracks[0].isDefault).toBe(true);
+  });
+
+  it("drops tracks whose URL cannot be built instead of rendering a dead src", async () => {
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) => {
+      if (i === 2) throw new Error("no repository");
+      return url(i);
+    });
+    expect(tracks.map((t) => t.streamIndex)).toEqual([3]);
+  });
+
+  it("drops empty and non-string URLs", async () => {
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) =>
+      i === 2 ? "  " : (undefined as unknown as string),
+    );
+    expect(tracks).toEqual([]);
+  });
+
+  it("returns nothing when there are no subtitle streams", async () => {
+    expect(await resolveSubtitleTracks([STREAMS[0]], async (i) => url(i))).toEqual([]);
+    expect(await resolveSubtitleTracks(null, async (i) => url(i))).toEqual([]);
+  });
+});
+
+describe("reconcileSelectedSubtitle", () => {
+  it("starts off (null) and keeps 'off' selectable", async () => {
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(reconcileSelectedSubtitle(tracks, null)).toBeNull();
+  });
+
+  it("keeps a selection that is still renderable", async () => {
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(reconcileSelectedSubtitle(tracks, 3)).toBe(3);
+  });
+
+  it("falls back to off when the selected track is gone (new item / failed URL)", async () => {
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(reconcileSelectedSubtitle(tracks, 9)).toBeNull();
+    expect(reconcileSelectedSubtitle([], 3)).toBeNull();
+  });
+
+  it("never auto-selects the server's default track", async () => {
+    // The menu opens on "Off" and a <track default> would auto-show, so the UI
+    // would claim subtitles are off while they are burned over the picture.
+    const tracks = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(tracks[0].isDefault).toBe(true);
+    expect(reconcileSelectedSubtitle(tracks, null)).toBeNull();
+  });
+});
+
+describe("videoCrossOriginMode", () => {
+  it("opts into CORS for a server stream that has subtitles", () => {
+    expect(videoCrossOriginMode("http://jelly.example/Videos/x/master.m3u8", 2)).toBe("anonymous");
+    expect(videoCrossOriginMode("https://jelly.example/Videos/x/stream.mp4", 1)).toBe("anonymous");
+  });
+
+  it("leaves a local/offline source alone so playback cannot regress", () => {
+    expect(videoCrossOriginMode("asset://localhost/movie.mkv", 2)).toBeUndefined();
+    expect(videoCrossOriginMode("file:///home/u/movie.mkv", 2)).toBeUndefined();
+  });
+
+  it("stays out of the way when there is nothing to load", () => {
+    expect(videoCrossOriginMode("http://jelly.example/x.m3u8", 0)).toBeUndefined();
+    expect(videoCrossOriginMode("", 0)).toBeUndefined();
+  });
+
+  it("is decided by inputs known at first render, so it cannot flip mid-load", () => {
+    // Same answer before and after the async URL resolution completes.
+    const before = videoCrossOriginMode("http://jelly.example/x.m3u8", SUBS.length);
+    const after = videoCrossOriginMode("http://jelly.example/x.m3u8", SUBS.length);
+    expect(before).toBe(after);
+  });
+});
+
+/**
+ * Subtitles on the Android / ExoPlayer native path.
+ *
+ * TRACES: UR-020 | IR-016, JA-008 | UT-147
+ *
+ * The bug this guards: VideoPlayer built a fully-resolved subtitle array in
+ * onMount and then never sent it — `commands.playerPlayItem({...})` passed only
+ * streamUrl/title/id/videoCodec/needsTranscoding — so every MediaItem reached
+ * ExoPlayer with zero SubtitleConfigurations and `setSubtitleTrack(n)` logged
+ * "Invalid subtitle track index".
+ *
+ * And the second half: `setSubtitleTrack(n)` indexes ExoPlayer's *text track
+ * groups*, i.e. the position of the sideloaded configuration — not the Jellyfin
+ * stream index. The menu used to pass its own row position, which is a position
+ * in the *unresolved* stream list; the moment one subtitle URL failed to
+ * resolve, the two lists diverged and every track below the gap selected the
+ * wrong subtitle.
+ */
+describe("nativeSubtitleTracks", () => {
+  it("maps to the wire shape Rust deserializes and Kotlin parses", async () => {
+    const resolved = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    const payload = nativeSubtitleTracks(resolved);
+
+    expect(payload).toHaveLength(2);
+    // Kotlin reads url/language/label/mime_type; Rust's SubtitleTrack keeps
+    // snake_case for exactly that reason, and so does the generated binding.
+    for (const track of payload) {
+      expect(Object.keys(track).sort()).toEqual(
+        ["index", "label", "language", "mime_type", "url"].sort(),
+      );
+      expect(track).not.toHaveProperty("mimeType");
+      expect(track.mime_type).toBe("text/vtt");
+    }
+    // Jellyfin serves every subtitle stream as WebVTT here, and the stream index
+    // rides along so the UI can keep talking in stream indices.
+    expect(payload.map((t) => t.index)).toEqual([2, 3]);
+    expect(payload[0].url).toContain("subtitles.vtt");
+    expect(payload[0].language).toBe("eng");
+    expect(payload[0].label).toBe("English (SRT)");
+  });
+
+  it("preserves stream order, because that order is the selection index", async () => {
+    const resolved = await resolveSubtitleTracks(STREAMS, async (i) => url(i));
+    expect(nativeSubtitleTracks(resolved).map((t) => t.index)).toEqual(
+      resolved.map((t) => t.streamIndex),
+    );
+  });
+
+  it("has nothing to send when no subtitle URL resolved", async () => {
+    expect(nativeSubtitleTracks(await resolveSubtitleTracks(SUBS, async () => ""))).toEqual([]);
+    expect(nativeSubtitleTracks([])).toEqual([]);
+  });
+
+  it("carries a null language/label through rather than inventing one", () => {
+    const payload = nativeSubtitleTracks([
+      { streamIndex: 5, url: "u.vtt", srclang: "und", label: "Track 5", isDefault: false },
+    ]);
+    expect(payload[0].language).toBeNull();
+    expect(payload[0].label).toBe("Track 5");
+  });
+});
+
+describe("nativeSubtitleArrayIndex", () => {
+  it("returns the position in the list that was actually sent, not the stream index", async () => {
+    const resolved = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(nativeSubtitleArrayIndex(resolved, 2)).toBe(0);
+    expect(nativeSubtitleArrayIndex(resolved, 3)).toBe(1);
+  });
+
+  it("stays aligned when a subtitle URL failed to resolve (the mis-selection bug)", async () => {
+    // Stream 2 has no URL, so it is not among the sideloaded configurations.
+    // The menu's own row for stream 3 is position 1, but ExoPlayer only has one
+    // text track group — position 0. Sending 1 would select nothing.
+    const resolved = await resolveSubtitleTracks(SUBS, async (i) => {
+      if (i === 2) throw new Error("no repository");
+      return url(i);
+    });
+    expect(resolved).toHaveLength(1);
+    expect(nativeSubtitleArrayIndex(resolved, 3)).toBe(0);
+  });
+
+  it("maps 'Off' to null so the backend disables text instead of selecting track 0", async () => {
+    const resolved = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(nativeSubtitleArrayIndex(resolved, null)).toBeNull();
+  });
+
+  it("maps a track that was never sent to null rather than to a wrong position", async () => {
+    const resolved = await resolveSubtitleTracks(SUBS, async (i) => url(i));
+    expect(nativeSubtitleArrayIndex(resolved, 99)).toBeNull();
+    expect(nativeSubtitleArrayIndex([], 3)).toBeNull();
+  });
+});
+
+describe("VideoPlayer markup (the regression that made the menu inert)", () => {
+  const source = readFileSync(
+    resolve(__dirname, "VideoPlayer.svelte"),
+    "utf-8",
+  );
+
+  it("renders <track> elements instead of leaving them commented out", () => {
+    expect(source).not.toContain("Temporarily disabled to debug playback issues");
+    expect(source).toMatch(/<track\b/);
+    expect(source).toContain('kind="subtitles"');
+  });
+
+  /** The rendered element, not a `<track>` mentioned in prose. */
+  const trackElement = source.slice(source.search(/<track\s/), source.search(/<track\s/) + 400);
+
+  it("keeps data-stream-index — Html5PlayerAdapter.selectSubtitle matches on it", () => {
+    expect(trackElement).toContain("data-stream-index");
+  });
+
+  it("never binds the async getSubtitleUrl() Promise to src", () => {
+    expect(source).not.toMatch(/src=\{\s*getSubtitleUrl\(/);
+  });
+
+  it("does not mark any track default (a default track auto-shows)", () => {
+    expect(trackElement).not.toMatch(/\bdefault=/);
+  });
+});
+
+/**
+ * The half of the Android fix that lives in the component: the resolved list has
+ * to actually be handed to `playerPlayItem`, and the index sent to the backend
+ * has to be computed from that same list.
+ *
+ * TRACES: UR-020 | IR-016 | UT-147
+ */
+describe("VideoPlayer -> playerPlayItem (the tracks that were built and thrown away)", () => {
+  const source = readFileSync(resolve(__dirname, "VideoPlayer.svelte"), "utf-8");
+
+  /** The playerPlayItem({...}) argument object. */
+  const playItemCall = (() => {
+    const start = source.indexOf("commands.playerPlayItem(");
+    expect(start).toBeGreaterThan(-1);
+    return source.slice(start, source.indexOf("});", start) + 3);
+  })();
+
+  it("sends the subtitle tracks it resolved", () => {
+    expect(playItemCall).toMatch(/\bsubtitles:/);
+  });
+
+  it("selects by position in the sent list, not by the menu's row number", () => {
+    expect(source).toContain("nativeSubtitleArrayIndex");
+    // The old code forwarded the `{#each}` index straight to the backend.
+    expect(source).not.toMatch(/playerSetSubtitleTrack\(\s*arrayIndex\s*\)/);
+  });
+});

src/lib/components/player/subtitleTracks.ts

@@ -0,0 +1,227 @@
+// Subtitle plumbing for the Linux / WebKitGTK HTML5 `<video>` playback path.
+//
+// Extracted from VideoPlayer.svelte so it is unit-testable, and because the
+// original inline version hid a fatal mistake in plain sight: `getSubtitleUrl()`
+// is async, so `src={getSubtitleUrl(track.index)}` bound a *Promise* to the
+// attribute and every `<track>` pointed at "[object Promise]". The whole block
+// was commented out rather than fixed, which left `<video>` with no text tracks
+// at all — `Html5PlayerAdapter.selectSubtitle()` then iterated an empty
+// `textTracks` list and the subtitle menu silently did nothing.
+//
+// The rule this module enforces: URLs are resolved to plain strings *here*, off
+// the render path, and only tracks that actually resolved are handed to the
+// markup.
+//
+// The Android / ExoPlayer native path shares this module (see
+// nativeSubtitleTracks / nativeSubtitleArrayIndex at the bottom): it needs the
+// exact same "resolve the URLs first, keep only what resolved" list, just handed
+// to Rust instead of to `<track>` elements.
+//
+// TRACES: UR-020 | DR-023, IR-016 | UT-143, UT-144, UT-147
+
+import type { SubtitleTrack } from "$lib/api/bindings";
+
+/**
+ * The subset of `MediaStream` (from the generated bindings) this module needs.
+ * Kept structural so tests do not have to build full binding objects.
+ */
+export interface SubtitleStreamLike {
+  index: number;
+  kind?: string | null;
+  language?: string | null;
+  displayTitle?: string | null;
+  isDefault?: boolean;
+  isForced?: boolean;
+}
+
+/** A subtitle stream whose URL resolved — i.e. one we can actually render. */
+export interface RenderableSubtitleTrack {
+  /** Jellyfin media-stream index; the adapter matches `data-stream-index`. */
+  streamIndex: number;
+  /** Fully resolved WebVTT URL. Always a string, never a Promise. */
+  url: string;
+  srclang: string;
+  label: string;
+  /** Server's "default" flag — shown in the menu, never auto-enabled. */
+  isDefault: boolean;
+}
+
+/** Subtitle streams of a media item, in stream order. */
+export function subtitleStreamsOf(
+  streams: readonly SubtitleStreamLike[] | null | undefined,
+): SubtitleStreamLike[] {
+  if (!streams) return [];
+  return streams.filter((s) => s.kind === "subtitle");
+}
+
+/** Human label for a subtitle stream, matching the menu's own fallback chain. */
+export function subtitleTrackLabel(stream: SubtitleStreamLike): string {
+  return stream.displayTitle || stream.language || `Track ${stream.index}`;
+}
+
+/** A src we are willing to put on a `<track>`: a non-blank plain string. */
+function isRenderableUrl(url: unknown): url is string {
+  return typeof url === "string" && url.trim().length > 0;
+}
+
+/**
+ * Resolve every subtitle stream's URL and return only the tracks that can be
+ * rendered. `resolveUrl` failures are swallowed per track: one unavailable
+ * subtitle must not cost the user the others, and a dead `src` on a media
+ * element is exactly what made this block get disabled in the first place.
+ */
+export async function resolveSubtitleTracks(
+  streams: readonly SubtitleStreamLike[] | null | undefined,
+  resolveUrl: (streamIndex: number) => Promise<string>,
+): Promise<RenderableSubtitleTrack[]> {
+  const subtitles = subtitleStreamsOf(streams);
+  if (subtitles.length === 0) return [];
+
+  const resolved = await Promise.all(
+    subtitles.map(async (stream) => {
+      try {
+        const url = await resolveUrl(stream.index);
+        if (!isRenderableUrl(url)) return null;
+        return {
+          streamIndex: stream.index,
+          url,
+          srclang: stream.language || "und",
+          label: subtitleTrackLabel(stream),
+          isDefault: stream.isDefault === true,
+        } satisfies RenderableSubtitleTrack;
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  return resolved.filter((t): t is RenderableSubtitleTrack => t !== null);
+}
+
+/**
+ * The selection to keep once the rendered track list changes.
+ *
+ * Subtitles are OFF unless the user turns them on: `null` in, `null` out. The
+ * server's `isDefault` flag is deliberately NOT promoted to a selection (and the
+ * markup deliberately omits the `default` attribute, which would auto-show the
+ * track) — the menu opens on "Off", so auto-enabling would make the UI lie about
+ * what is on screen, and it would change behaviour for every user who has never
+ * asked for subtitles.
+ *
+ * A selection that is no longer renderable (new item, or a URL that failed to
+ * resolve) collapses to off, so the menu's checkmark can never point at a track
+ * that does not exist on the element.
+ */
+export function reconcileSelectedSubtitle(
+  tracks: readonly RenderableSubtitleTrack[],
+  selected: number | null,
+): number | null {
+  if (selected === null) return null;
+  return tracks.some((t) => t.streamIndex === selected) ? selected : null;
+}
+
+function originOf(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `crossorigin` value for the `<video>` element, or undefined for none.
+ *
+ * Text-track fetches are CORS-enabled per the HTML spec and use the *media
+ * element's* CORS setting, so a cross-origin `<track>` never loads unless the
+ * element opts in. The webview page's origin is `tauri://localhost`, so every
+ * subtitle served by Jellyfin is cross-origin.
+ *
+ * Opting in is only safe when the media itself comes from an http(s) server —
+ * the same Jellyfin that already answers hls.js' cross-origin XHRs, so we know
+ * it sends the headers. For a local/offline source (`file:`/`asset:`) we leave
+ * the attribute off: subtitles staying dark there is the status quo, whereas
+ * forcing CORS onto the video fetch could break playback outright.
+ *
+ * Deliberately keyed on the *count of subtitle streams* rather than on the
+ * resolved tracks: both inputs are known at first render, so the attribute is
+ * decided before the element starts loading and never flips underneath an
+ * in-flight media fetch.
+ */
+export function videoCrossOriginMode(
+  streamUrl: string,
+  subtitleStreamCount: number,
+): "anonymous" | undefined {
+  if (subtitleStreamCount <= 0) return undefined;
+  return originOf(streamUrl) ? "anonymous" : undefined;
+}
+
+// ===== Native (Android / ExoPlayer) path ====================================
+//
+// The HTML5 element gets `<track>` children; the native backend instead gets the
+// list *up front*, as part of the play request, because ExoPlayer sideloads
+// subtitles as `MediaItem.SubtitleConfiguration`s that must exist before
+// `prepare()`. There is no "add a subtitle later" — a track absent from the
+// MediaItem simply does not exist as far as the player is concerned.
+
+/**
+ * Map resolved tracks onto the wire shape `PlayItemRequest.subtitles` carries.
+ *
+ * The element type is the *generated* `SubtitleTrack` binding on purpose, so
+ * `bun run check` fails if the Rust struct's field names ever move. In
+ * particular `mime_type` is snake_case and must stay that way: the very same
+ * bytes are re-serialized across JNI in `player/android/mod.rs`, and
+ * `JellyTauPlayer.load()` reads `optString("mime_type")`. Renaming it to
+ * `mimeType` would not error anywhere — Kotlin would just silently fall back to
+ * its default MIME type for every track.
+ *
+ * Jellyfin is asked for every subtitle stream as WebVTT (see
+ * `getSubtitleUrl(..., "vtt")`), so the MIME type is fixed rather than derived
+ * from the source subtitle codec.
+ *
+ * TRACES: UR-020 | IR-016, JA-008 | UT-147
+ */
+export function nativeSubtitleTracks(
+  tracks: readonly RenderableSubtitleTrack[],
+): SubtitleTrack[] {
+  return tracks.map((track) => ({
+    index: track.streamIndex,
+    url: track.url,
+    // `srclang` carries "und" for a stream with no language, which is the right
+    // value for a `<track>` but is not a language the native side should claim.
+    language: track.srclang === "und" ? null : track.srclang,
+    label: track.label,
+    mime_type: "text/vtt",
+  }));
+}
+
+/**
+ * The argument for `player_set_subtitle_track` on the native backend.
+ *
+ * 🔴 This is **not** the Jellyfin stream index.
+ * `JellyTauPlayer.setSubtitleTrack(n)` filters ExoPlayer's track groups down to
+ * `C.TRACK_TYPE_TEXT` and indexes that list with `n`, so `n` is the *position of
+ * the sideloaded subtitle configuration* — which is the position in the array
+ * that `nativeSubtitleTracks()` produced and `playerPlayItem` sent.
+ *
+ * The menu's own row number is not that position: the menu lists every subtitle
+ * *stream*, while only the streams whose URL resolved are sent. One failed URL
+ * and everything below it selects the wrong subtitle. So the index is looked up
+ * in the sent list instead of being passed down from the `{#each}`.
+ *
+ * `null` (the menu's "Off") stays `null`, which the backend turns into -1 and
+ * Kotlin turns into "disable text tracks". A stream that was never sent also
+ * maps to `null`: disabling subtitles is a truthful outcome, whereas guessing a
+ * position would show the user a different language than the one they clicked.
+ *
+ * TRACES: UR-020 | IR-016 | UT-147
+ */
+export function nativeSubtitleArrayIndex(
+  tracks: readonly RenderableSubtitleTrack[],
+  streamIndex: number | null,
+): number | null {
+  if (streamIndex === null) return null;
+  const position = tracks.findIndex((t) => t.streamIndex === streamIndex);
+  return position === -1 ? null : position;
+}

src/lib/player/adapters/adapterSelection.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Adapter-selection regression guards.
+ *
+ * TRACES: UR-003, UR-004 | DR-150 | UT-149
+ *
+ * The selection rule has two inputs and one hard safety property:
+ *
+ *   - Rust says which backend the platform has (`backendKind`).
+ *   - The user opts in with `experimentalNativeVideo`.
+ *   - **The flag off must force HTML5 even when Rust says native.** That is the
+ *     regression guard: a broken spike must not be able to ship as the default.
+ *
+ * These are pure functions, so the whole matrix is testable without a device.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createAdapter } from "./index";
+import { Html5PlayerAdapter } from "./html5Adapter";
+import { NativePlayerAdapter } from "./nativeAdapter";
+import type { AdapterHost } from "./types";
+
+const host: AdapterHost = {
+  reportState: () => {},
+  reportPosition: () => {},
+  reportEnded: () => {},
+} as unknown as AdapterHost;
+
+const bridge = {
+  getElement: () => null,
+} as any;
+
+describe("createAdapter", () => {
+  it("returns the native adapter when Rust says native and the flag is on", () => {
+    const adapter = createAdapter({
+      backendKind: "native",
+      host,
+      bridge,
+      experimentalNativeVideo: true,
+    });
+    expect(adapter).toBeInstanceOf(NativePlayerAdapter);
+    expect(adapter.kind).toBe("native");
+  });
+
+  // The regression guard: the flag is a suppressor, so off must beat Rust.
+  it("forces HTML5 when the flag is off even though Rust says native", () => {
+    const adapter = createAdapter({
+      backendKind: "native",
+      host,
+      bridge,
+      experimentalNativeVideo: false,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+    expect(adapter.kind).toBe("html5");
+  });
+
+  it("returns the HTML5 adapter when Rust says html5 and the flag is off", () => {
+    const adapter = createAdapter({
+      backendKind: "html5",
+      host,
+      bridge,
+      experimentalNativeVideo: false,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  // The flag must never *promote* a platform Rust said has no native backend
+  // (e.g. Linux, where WebKitGTK cannot composite a surface behind the webview).
+  it("stays on HTML5 when Rust says html5 even with the flag on", () => {
+    const adapter = createAdapter({
+      backendKind: "html5",
+      host,
+      bridge,
+      experimentalNativeVideo: true,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  it("defaults to HTML5 when the flag is omitted entirely", () => {
+    const adapter = createAdapter({ backendKind: "native", host, bridge });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  it("requires a bridge for the HTML5 adapter", () => {
+    expect(() =>
+      createAdapter({ backendKind: "html5", host, experimentalNativeVideo: false })
+    ).toThrow(/bridge/i);
+  });
+
+  // The native adapter owns no DOM element, so it must not demand a bridge.
+  it("does not require a bridge for the native adapter", () => {
+    expect(() =>
+      createAdapter({ backendKind: "native", host, experimentalNativeVideo: true })
+    ).not.toThrow();
+  });
+});

src/lib/player/adapters/index.ts

@@ -2,13 +2,22 @@
  * Player adapter factory + public exports.
  *
  * `createAdapter` selects the concrete PlayerAdapter for the current platform.
- * It is the single place that encodes the INTERIM Android override: the Rust
- * backend may report a native ExoPlayer backend, but native Android video
- * rendering is blocked upstream (tauri#10152 — transparent webview / SurfaceView
- * compositing), so we render Android video through the HTML5 adapter for now.
- * When that upstream limitation is resolved, flip this to honor `backendKind`.
+ * Rust decides *which backend this platform has* (`useHtml5Element` from
+ * `player_play_item`); this factory consumes that decision rather than
+ * re-deriving it.
  *
- * TRACES: UR-003 | DR-004
+ * The `experimentalNativeVideo` flag is a **suppressor, never a promoter**: it
+ * can force the HTML5 path when Rust says native (so an in-progress spike cannot
+ * ship as a regression), but it can never select native on a platform whose Rust
+ * backend reported HTML5 — Linux has no way to composite a surface behind a
+ * WebKitGTK webview, so promoting there would produce a black screen.
+ *
+ * The previous unconditional HTML5 override cited tauri#10152 as an upstream
+ * blocker. That was stale: #10152 is a dormant *feature request*, the capability
+ * shipped in tauri 27d01834, and the black-screen bug (tauri#8381, #9408) was a
+ * broken `setBackgroundColor` JNI signature fixed in wry 0.39.4 — we ship 0.53.x.
+ *
+ * TRACES: UR-003, UR-004 | DR-004, DR-150 | UT-149
  */
 
 import { Html5PlayerAdapter, type Html5ElementBridge } from "./html5Adapter";
@@ -29,27 +38,36 @@ export interface CreateAdapterArgs {
   host: AdapterHost;
   /** Required for the HTML5 adapter; ignored by the native adapter. */
   bridge?: Html5ElementBridge;
+  /**
+   * User opt-in for the native video path. Defaults to **off**, so omitting it
+   * yields today's behaviour (HTML5 everywhere) rather than silently enabling
+   * the spike.
+   */
+  experimentalNativeVideo?: boolean;
 }
 
 /**
  * Build the adapter for this platform/stream.
  *
- * INTERIM: always returns the HTML5 adapter, because the native surface is not
- * visible through the webview on current Tauri (see module docs). The bridge is
- * therefore required.
+ * Native is chosen only when Rust reports a native backend AND the user has
+ * opted in. Every other combination is HTML5.
  */
-export function createAdapter({ backendKind, host, bridge }: CreateAdapterArgs): PlayerAdapter {
-  // INTERIM OVERRIDE: force HTML5 rendering even when the backend reports native.
-  const effectiveKind: BackendKind = "html5";
+export function createAdapter({
+  backendKind,
+  host,
+  bridge,
+  experimentalNativeVideo = false,
+}: CreateAdapterArgs): PlayerAdapter {
+  const effectiveKind: BackendKind =
+    backendKind === "native" && experimentalNativeVideo ? "native" : "html5";
 
-  if (effectiveKind === "html5") {
-    if (!bridge) {
-      throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
-    }
-    return new Html5PlayerAdapter(host, bridge);
+  if (effectiveKind === "native") {
+    // The native surface is owned by the backend — no DOM element, no bridge.
+    return new NativePlayerAdapter(host);
   }
 
-  // Reached only once the interim override is lifted (native Android unblocked).
-  void backendKind;
-  return new NativePlayerAdapter(host);
+  if (!bridge) {
+    throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
+  }
+  return new Html5PlayerAdapter(host, bridge);
 }

src/lib/services/playbackCapabilities.ts

@@ -0,0 +1,70 @@
+/**
+ * Platform playback capabilities, read from Rust.
+ *
+ * TRACES: UR-003, UR-005 | DR-004, DR-152
+ *
+ * "Which backend does this platform have" is a *backend* fact, so Rust owns it
+ * (`player_get_capabilities`, gated on the same `cfg!` the backends are built
+ * under). This module is a thin cache over that command.
+ *
+ * It exists because the frontend used to re-derive the answer by sniffing
+ * `navigator.userAgent` for "android"/"linux" — a second, silently drifting copy
+ * of a decision Rust already makes. Consume the value; never re-derive it.
+ */
+
+import { commands } from "$lib/api/bindings";
+
+export interface PlaybackCapabilities {
+  /** Audio renders through a webview `<audio>` element, not a native backend. */
+  usesWebviewAudio: boolean;
+  /** Video can render on a native surface behind a transparent webview. */
+  supportsNativeVideo: boolean;
+}
+
+/**
+ * Conservative defaults for when the backend cannot be reached (very early
+ * startup, or a command failure). Both false = "assume no special platform
+ * facilities": no stray `<audio>` element is mounted, and video stays on the
+ * HTML5 path, which is the safe behaviour everywhere.
+ */
+const FALLBACK: PlaybackCapabilities = {
+  usesWebviewAudio: false,
+  supportsNativeVideo: false,
+};
+
+let cached: PlaybackCapabilities | null = null;
+let inflight: Promise<PlaybackCapabilities> | null = null;
+
+/**
+ * Fetch (and memoize) this platform's capabilities. Cached because the answer is
+ * compile-time constant in Rust — it cannot change during a session.
+ */
+export async function getPlaybackCapabilities(): Promise<PlaybackCapabilities> {
+  if (cached) return cached;
+  if (inflight) return inflight;
+
+  inflight = (async () => {
+    try {
+      const caps = (await commands.playerGetCapabilities()) as PlaybackCapabilities;
+      cached = {
+        usesWebviewAudio: !!caps?.usesWebviewAudio,
+        supportsNativeVideo: !!caps?.supportsNativeVideo,
+      };
+      return cached;
+    } catch (err) {
+      console.warn("[capabilities] player_get_capabilities failed:", err);
+      // Do NOT cache the fallback — a later call should get the real answer.
+      return FALLBACK;
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+/** Reset the cache. Test-only. */
+export function __resetPlaybackCapabilitiesCache(): void {
+  cached = null;
+  inflight = null;
+}

src/lib/services/webviewAudio.ts

@@ -23,31 +23,25 @@ import { events } from "$lib/api/bindings";
 import { playerController } from "$lib/player";
 import { createRustReportHost } from "$lib/player/adapters/rustReportHost";
 import { WebviewAudioAdapter } from "$lib/player/adapters/webviewAudioAdapter";
+import { getPlaybackCapabilities } from "$lib/services/playbackCapabilities";
 
 let unlisten: UnlistenFn | null = null;
 let audioEl: HTMLAudioElement | null = null;
 let adapter: WebviewAudioAdapter | null = null;
 
-/** Platforms whose Rust backend renders audio in the webview rather than natively. */
-function usesWebviewAudio(): boolean {
-  // Native audio backends exist only for Linux (mpv) and Android (ExoPlayer).
-  // Everything else (Windows, and any future desktop) uses the webview element.
-  // We detect "not linux/android" rather than "is windows" so new desktop
-  // targets are covered automatically, matching the Rust cfg gate.
-  if (typeof navigator === "undefined") return false;
-  const ua = navigator.userAgent.toLowerCase();
-  const isAndroid = ua.includes("android");
-  const isLinux = ua.includes("linux") && !isAndroid;
-  return !isAndroid && !isLinux;
-}
-
 /**
  * Initialize the webview audio controller. Safe to call unconditionally from the
  * root layout; it self-gates on platform and is idempotent.
  */
 export async function initWebviewAudio(): Promise<void> {
   if (unlisten) return;
-  if (!usesWebviewAudio()) return;
+
+  // Whether this platform needs the webview element is a backend fact, so Rust
+  // answers it. This used to sniff `navigator.userAgent` for "android"/"linux"
+  // — a duplicate of the Rust cfg gate that could drift out of step with the
+  // backends it was trying to describe.
+  const { usesWebviewAudio } = await getPlaybackCapabilities();
+  if (!usesWebviewAudio) return;
 
   audioEl = document.createElement("audio");
   audioEl.hidden = true;

src/lib/stores/nativeVideo.ts

@@ -0,0 +1,91 @@
+// Native-video compositing state.
+//
+// TRACES: UR-003, UR-004 | DR-150, DR-152
+//
+// Two separate concerns live here, deliberately:
+//
+//  1. `experimentalNativeVideo` — the user-facing opt-in flag. Rust already
+//     decides *which backend this platform has* (`useHtml5Element` from
+//     `player_play_item`); this flag only *suppresses* that decision so a
+//     half-working spike cannot ship as a regression. It never turns native on
+//     where Rust says HTML5.
+//
+//  2. `nativeVideoActive` — whether a native surface is on screen right now.
+//     Setting it toggles `data-native-video` on <html>, which is what the CSS in
+//     app.css keys off to clear the app's opaque backgrounds so the SurfaceView
+//     behind the WebView is visible. It is deliberately NOT derived from the
+//     flag: the backgrounds must come back the moment the player unmounts.
+//
+// Frontend-only preference, stored in localStorage per the `jellytau-view-mode`
+// precedent in library.ts — no Rust settings command backs this.
+
+import { writable } from "svelte/store";
+
+const STORAGE_KEY = "jellytau-experimental-native-video";
+
+/** The attribute app.css keys its transparency rules off. */
+const NATIVE_VIDEO_ATTR = "data-native-video";
+
+function load(): boolean {
+  if (typeof localStorage === "undefined") return false;
+  try {
+    return localStorage.getItem(STORAGE_KEY) === "true";
+  } catch {
+    // Private-mode / disabled storage — default to the safe (HTML5) path.
+    return false;
+  }
+}
+
+function persist(enabled: boolean) {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(STORAGE_KEY, String(enabled));
+  } catch {
+    // Quota or private-mode failure — keep the in-memory value.
+  }
+}
+
+function createExperimentalNativeVideoStore() {
+  const { subscribe, set } = writable<boolean>(load());
+
+  return {
+    subscribe,
+    set(enabled: boolean) {
+      persist(enabled);
+      set(enabled);
+    },
+    /** Read the current value without subscribing (init-time decisions). */
+    current: load,
+  };
+}
+
+/** User opt-in for the native Android video path. Default off. */
+export const experimentalNativeVideo = createExperimentalNativeVideoStore();
+
+function createNativeVideoActiveStore() {
+  const { subscribe, set } = writable<boolean>(false);
+
+  return {
+    subscribe,
+    /**
+     * Mark a native video surface as visible (or gone) and sync the <html>
+     * attribute that app.css uses to clear opaque backgrounds.
+     */
+    set(active: boolean) {
+      if (typeof document !== "undefined") {
+        if (active) {
+          document.documentElement.setAttribute(NATIVE_VIDEO_ATTR, "active");
+        } else {
+          document.documentElement.removeAttribute(NATIVE_VIDEO_ATTR);
+        }
+      }
+      set(active);
+    },
+  };
+}
+
+/**
+ * Whether a native video surface is currently on screen. Must be cleared on
+ * player teardown, or the rest of the app renders over a transparent window.
+ */
+export const nativeVideoActive = createNativeVideoActiveStore();

src/lib/utils/videoSurface.ts

@@ -0,0 +1,86 @@
+/**
+ * Native video surface compositing, Android only.
+ *
+ * TRACES: UR-003, UR-004 | DR-150, DR-151
+ *
+ * On Android, ExoPlayer renders video into a SurfaceView that sits *behind* the
+ * Tauri WebView (`setZOrderMediaOverlay(false)`, added at index 0 of the content
+ * view by VideoOverlayManager). For that video to be visible, two independent
+ * opaque layers have to be cleared:
+ *
+ *  1. The **WebView widget's own background** — reachable only from Kotlin, via
+ *     the `AndroidVideoSurface` @JavascriptInterface installed by MainActivity.
+ *  2. The **web page's backgrounds** — the `html`/`body` colour in app.css and
+ *     the app shell's `bg-[var(--color-background)]`. Handled by the
+ *     `data-native-video` attribute, which $lib/stores/nativeVideo.ts sets and
+ *     app.css keys its transparency rules off.
+ *
+ * Clearing only one leaves a black screen with audio, which is exactly the
+ * failure mode the old INTERIM override in VideoPlayer.svelte was working
+ * around. Both must be toggled together, so this module owns both halves.
+ *
+ * Everything here is a no-op off Android — the bridge is simply absent.
+ */
+
+import { nativeVideoActive } from "$lib/stores/nativeVideo";
+
+interface AndroidVideoSurfaceBridge {
+  setTransparent(transparent: boolean): void;
+  isSupported(): boolean;
+}
+
+declare global {
+  interface Window {
+    AndroidVideoSurface?: AndroidVideoSurfaceBridge;
+  }
+}
+
+function bridge(): AndroidVideoSurfaceBridge | undefined {
+  if (typeof window === "undefined") return undefined;
+  return window.AndroidVideoSurface;
+}
+
+/**
+ * Whether the native-surface bridge exists on this platform. This reports only
+ * that the *plumbing* is present; whether native video should actually be used
+ * is Rust's decision (`player_get_capabilities`) gated by the user's
+ * `experimentalNativeVideo` flag.
+ */
+export function isNativeSurfaceBridgeAvailable(): boolean {
+  try {
+    return bridge()?.isSupported() ?? false;
+  } catch (err) {
+    console.warn("[videoSurface] isSupported check failed:", err);
+    return false;
+  }
+}
+
+/**
+ * Make the webview transparent so the video surface behind it shows through.
+ *
+ * MUST be paired with {@link disableNativeVideoCompositing} on teardown — a
+ * transparent window left behind shows the launcher through the whole app.
+ */
+export function enableNativeVideoCompositing(): void {
+  // Page layer first: if the Kotlin call succeeded but this threw, the user
+  // would see through the app to the home screen.
+  nativeVideoActive.set(true);
+  try {
+    bridge()?.setTransparent(true);
+  } catch (err) {
+    console.warn("[videoSurface] setTransparent(true) failed:", err);
+    nativeVideoActive.set(false);
+  }
+}
+
+/** Restore the opaque webview background. Safe to call unconditionally. */
+export function disableNativeVideoCompositing(): void {
+  try {
+    bridge()?.setTransparent(false);
+  } catch (err) {
+    console.warn("[videoSurface] setTransparent(false) failed:", err);
+  }
+  // Always clear the page layer, even if the bridge call failed, so the app is
+  // never left rendering over a transparent window.
+  nativeVideoActive.set(false);
+}

src/routes/settings/+page.svelte

@@ -1,6 +1,6 @@
 <!-- TRACES: UR-023, UR-025, UR-027, UR-029, UR-057 | DR-030, DR-048, DR-077, DR-086, DR-132 -->
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onDestroy, onMount } from "svelte";
   import { commands } from "$lib/api/bindings";
   import type {
     AudioSettings,
@@ -26,6 +26,8 @@
     isNetworkDetectionSupported,
     reportNetworkState,
   } from "$lib/services/networkType";
+  import { experimentalNativeVideo } from "$lib/stores/nativeVideo";
+  import { getPlaybackCapabilities } from "$lib/services/playbackCapabilities";
 
   const episodeLimitOptions = [
     { value: 0, label: "Unlimited" },
@@ -97,8 +99,27 @@
     { label: "Unlimited", bytes: 0 },
   ];
 
+  // Native-video opt-in (Android). `supportsNativeVideo` comes from Rust, which
+  // owns the "does this platform have a native video surface" decision; the
+  // toggle is hidden entirely where it cannot apply.
+  let supportsNativeVideo = $state(false);
+  let nativeVideoEnabled = $state(false);
+
+  const unsubscribeNativeVideo = experimentalNativeVideo.subscribe((v) => {
+    nativeVideoEnabled = v;
+  });
+
+  function handleNativeVideoToggle() {
+    experimentalNativeVideo.set(!nativeVideoEnabled);
+  }
+
+  // Not returned from onMount: that callback is async, so its return value is a
+  // Promise and Svelte would never invoke it as a teardown.
+  onDestroy(unsubscribeNativeVideo);
+
   onMount(async () => {
     await loadSettings();
+    supportsNativeVideo = (await getPlaybackCapabilities()).supportsNativeVideo;
   });
 
   async function loadSettings() {
@@ -659,6 +680,46 @@
             </div>
           {/if}
         </div>
+
+        <!-- Native video (experimental). Only rendered where the platform's Rust
+             backend actually has a native video surface (Android). -->
+        {#if supportsNativeVideo}
+          <div class="bg-[var(--color-surface)] rounded-lg p-6 mt-4">
+            <div class="flex items-center justify-between">
+              <div class="pr-4">
+                <h3 class="text-xl font-semibold text-white">
+                  Native Video
+                  <span
+                    class="ml-2 align-middle text-xs font-medium uppercase tracking-wide text-amber-400 border border-amber-400/40 rounded px-1.5 py-0.5"
+                  >
+                    Experimental
+                  </span>
+                </h3>
+                <p class="text-sm text-gray-400 mt-1">
+                  Decode video with the device's hardware decoder instead of the
+                  built-in web player. Better performance and battery life, but
+                  less tested — turn this off if video fails to appear.
+                </p>
+              </div>
+              <button
+                onclick={handleNativeVideoToggle}
+                class="relative inline-flex h-8 w-14 shrink-0 items-center rounded-full transition-colors {nativeVideoEnabled
+                  ? 'bg-[var(--color-jellyfin)]'
+                  : 'bg-gray-600'}"
+                aria-label="Toggle native video"
+              >
+                <span
+                  class="inline-block h-6 w-6 transform rounded-full bg-white transition-transform {nativeVideoEnabled
+                    ? 'translate-x-7'
+                    : 'translate-x-1'}"
+                ></span>
+              </button>
+            </div>
+            <p class="text-xs text-gray-500 mt-3">
+              Takes effect the next time you start a video.
+            </p>
+          </div>
+        {/if}
       </div>
 
       <!-- Search Settings -->