# Native player — verification plan

What to check before the `MediaPlayer` contract and Linux native video reach `master`.

This is not a generic smoke test. Every case below exists because something specific went wrong, and most of them were found on hardware after the automated suites were green. Treat the sequences as load-bearing: several defects only appeared in a particular order of actions, and testing the same features in a different order missed them entirely.

Companion to release-checklist.md, which covers the release mechanics. This covers whether the player is fit to release at all.

## What is risky about this change

- `PlayerController` now talks to a `MediaPlayer` contract instead of `PlayerBackend`. Every engine reaches it through an adapter that did not exist before (DR-245).
- mpv decodes video on Linux for the first time, composited under the webview (DR-231).
- Seek strategy is driven by an ability each engine declares rather than by a truth table (DR-246).
- Two regressions were introduced during this work and caught only on a device: a wrong capability for ExoPlayer (DR-246 follow-up) and a `Duration` panic (DR-252). Both were invisible to the test suites.

The suites originally verified only engines that behave, which is why both regressions passed them. That gap is now partly closed in code rather than in this document: `UT-223` drives a deliberately hostile engine — `C.TIME_UNSET`, NaN, infinities, negatives — through the adapter, and fails with the exact panic that produced a black screen on a tablet. `UT-224` pins the handoff clearing that was previously verified by listening to a device.

Prefer moving cases out of this file and into tests. Anything here that could fail automatically should; a checklist depends on someone remembering to follow it, and the two defects it was written for cost hardware time that would have been better spent making the suites realistic. What is left below is what genuinely needs eyes, ears, or a display — not what merely has not been automated yet.

## 1. Automated gates

Cheap, fast, and non-negotiable. Run from the worktree.

    bun run check                      # 0 errors, 0 warnings
    bun run test                       # frontend
    bun run test:rust                  # Rust
    bun run format:check
    bun run lint                       # 0 errors; warnings at or below the CI ratchet
    bun run check:boundary
    bun run traces:validate
    bun run traces:coverage            # at or above MIN_THRESHOLD
    cd src-tauri && cargo fmt --check && cargo clippy --all-targets -- -D warnings
    cargo clippy --all-targets --features conformance -- -D warnings

The eslint warning count is a ratchet: equal to the CI limit is a pass, one over fails the build. Going one over is how a piece of dead state was found during this work — do not raise the limit to get past it.

## 2. Engine conformance

    bun run test:player                # mpv + legacy, desktop
    bun run test:player:android        # ExoPlayer, on a connected device

Expected, and each deviation is meaningful rather than noise:

Engine | Result | If it differs
--- | --- | ---
`MpvPlayer` | 9/9 | A real regression. Stop.
`LegacyPlayer` | 8/9 | The one failure is `transport_settings_round_trip`: the old trait has no mute or rate. Any other failure is a regression.
ExoPlayer (device) | 7/7 | Two cases are absent because the Kotlin player exposes no mute or rate.

A green conformance run is not sufficient evidence to ship. Both regressions introduced during this work passed conformance.

## 3. Desktop (Linux)

Run with native video on, since that is what is new:

    JELLYTAU_NATIVE_VIDEO=1 bun run tauri dev

- Direct play — a file the server does not transcode. Picture and sound.
- Transcoded play — something the server must re-encode (4K, HEVC, or an audio codec the renderer cannot take).
- Resume — an item watched previously on this install. The prompt appears and playback starts at the offered position, not at zero. (Resume is device-local — see "Known open".)
- Scrub on a direct-play item; position lands and playback continues.
- Scrub on a transcoded item. Separate case on purpose: it takes a different path, and it silently did nothing for months (DR-238).
- Pause and resume — the button follows the player. It stopped doing so when a property was handled but never observed (DR-239).
- Fullscreen — the window really fills the display. Measure it if unsure: the log prints `rendering WxH`, and a height short of the panel means the document went fullscreen and the window did not (DR-240).
- Exit the player — audio stops. Listen; do not assume.
- Audio-only playback still works: mini player, queue, next/previous.
- Nothing in the log matches `PANIC` or `ERROR`.

## 4. Android

The tablet needs the side-by-side build. Do not uninstall the release app to make an install succeed — see "Known open" for why the normal command is currently wrong.

    bun run android:build --device
    ./scripts/sync-android-sources.sh
    cd src-tauri/gen/android && ANDROID_HOME="$HOME/Android/Sdk" ./gradlew \
      :app:assembleUniversalDebug -x :app:rustBuildUniversalDebug \
      -x :app:rustBuildArm64Debug -x :app:rustBuildArmDebug \
      -x :app:rustBuildX86Debug -x :app:rustBuildX86_64Debug
    adb install -r app/build/outputs/apk/universal/debug/app-universal-debug.apk

Confirm the package is `com.dtourolle.jellytau.debug` before installing:

    aapt2 dump packagename <apk>

If it says `com.dtourolle.jellytau`, the suffix was lost — stop, re-sync and re-assemble. Installing it would try to replace the real app.

Then, with `adb logcat` capturing:

- Play a video. Picture, sound, and controls.

- Scrub. The bar has a scale — a duration of `0.0` means the seek bar has nothing to scrub against (DR-251).

- Transcoded seek lands rather than restarting the stream. ExoPlayer seeks a transcode in place; declaring otherwise re-opened it (DR-246).

- PiP.

- Lockscreen: controls respond and position tracks.

- The handoff sequence, in this exact order: 1. play a video 2. enable background audio 3. background the app — audio continues 4. foreground the app — video returns 5. exit the player — everything stops

      Steps 4 and 5 are where two separate defects lived (DR-250, DR-252). Doing
      the same actions in another order finds neither.

- `grep -c 'PANIC at' <logcat>` returns 0.

## 5. Regression checks with a named cause

Each of these presented as something other than its cause, which is why they are listed separately from the feature passes above.

Symptom to look for | Was actually | Ref
--- | --- | ---
Skip on a transcoded item does nothing, or jumps to zero | Seek strategy keyed on the container, not the engine | DR-238, DR-246
Play/pause button does not follow the player | A property handled but never observed, so the event never arrived | DR-239
Fullscreen leaves a strip of desktop | The document went fullscreen, the window did not | DR-240
Resume plays from the beginning | A seek issued before the engine had a file was discarded | DR-241
Scrub bar has no scale | Duration reported as `0.0` and believed | DR-251
Black screen, no controls, after a background-audio round trip | A junk duration converted to a `Duration` panicked the backend | DR-252
Audio still playing after leaving the player | The stop was aimed at whichever renderer bookkeeping believed was active | DR-250

## Known open — decide, do not discover

None of these are fixed. Each needs an explicit ship / do-not-ship call rather than being met with surprise during testing.

- Resume is device-local. Progress is read from the local database and nothing consults the server's `UserData`. A fresh install, a second device or a reinstall offers no resume even though the server knows the position. Not a regression — it has always been so.
- The background-audio handoff is an unconfirmed state swap. `exit_background_audio` marks the video element the player again the moment it is called, while the element has not reloaded. DR-250 makes the visible symptom impossible; the race is intact and can still misdirect a lockscreen command or a position read. See media-player-controller.md.
- 🔴 The side-by-side debug install is broken. `bun run android:dev` produces an APK with the release application id, because the Tauri build regenerates `gen/build.gradle.kts` after the sync drops the `.debug` suffix in. It then fails on signatures, and its own error message advises uninstalling — which would destroy the real app's data. Fix this before anyone else builds for Android.
- `PlayerBackend` still exists behind `LegacyPlayer`, and the frontend still carries some playback state. DR-248 and DR-249 are not started.

## Ship criteria

Ship when:

1. Every automated gate in §1 passes.
2. Conformance matches §2 exactly, deviations included.
3. §3 and §4 are complete, on real hardware, by a person.
4. §5 shows no symptom returning.
5. Every item in "Known open" has a recorded decision.

Do not ship on green suites alone. Both regressions introduced during this work passed every suite and were caught by a person using the app.