From 888f0a2a5d8936e463fc70581652b04ab7ed723e Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 23 Aug 2026 08:58:25 +0200
Subject: [PATCH] docs(specs): the background-audio handoff is an unconfirmed
 state swap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Diagnosed on a device. The likeliest explanation for "audio keeps playing
after I leave the player", which is the report this line of work started from.

enter_background_audio and exit_background_audio are pure bookkeeping: a
boolean and a base offset. Neither confirms the audio stream opened, nor that
the webview <video> came back. exit_background_audio's own comment says the
element "becomes the player again once it reloads" — a future event nothing
waits for, while the flag calls the swap done the moment it is invoked.

Foreground the app, then leave the player before the element has reloaded, and
the stop is aimed at something that does not exist yet while the audio stream
keeps running. The mini player then adopts a live audio session, which is why a
movie reappears as an audio track and why it is intermittent.

Same defect class as DR-238 … DR-241: state asserted rather than confirmed. It
is what Phase::Opening and the open generation exist for — a handoff is an open
in flight, and a close during one must cancel it. Today the handoff never
reaches an engine as an open at all, which is why
close_during_open_never_plays passes on all four engines while the bug
survives.

Credit where due: the sequence came from the user reproducing it deliberately,
not from the logs.
---
 docs/specs/media-player-controller.md | 41 +++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/specs/media-player-controller.md b/docs/specs/media-player-controller.md
index 956a8218..8ca5446a 100644
--- a/docs/specs/media-player-controller.md
+++ b/docs/specs/media-player-controller.md
@@ -66,6 +66,47 @@ produced a regression: routing transcoded seeks to a reload path turned "seek
 does nothing" into "seek jumps to zero", because the reload path's own seek was
 broken in the same way. **Symptom fixes in this area compound.**
 
+## The background-audio handoff is an unconfirmed state swap
+
+Diagnosed on a device, 2026-08-23, and the likeliest explanation for "audio
+keeps playing after I leave the player" — the report this whole line of work
+started from.
+
+`enter_background_audio` and `exit_background_audio` in `PlayerController` are
+pure bookkeeping: they flip a boolean and set or clear a base offset. Neither
+confirms that the audio stream actually opened, nor that the webview `<video>`
+actually came back. `exit_background_audio`'s own doc comment says the element
+"becomes the player again once it reloads" — a future event nothing waits for,
+while the flag declares the swap complete the moment it is called.
+
+The sequence that exposes it:
+
+1. Background audio is enabled.
+2. The app is backgrounded — `enter_background_audio(pos)`, audio stream opens.
+3. The app is foregrounded — `exit_background_audio()` sets the flag back, so
+   the controller believes the video element owns playback again.
+4. The player is exited *before the element has reloaded*. The stop is aimed at
+   an element that does not exist yet; the audio stream is still running.
+5. The mini player sees a live audio session and adopts it — which is why the
+   symptom is a **movie appearing as an audio track**, and why it is
+   intermittent rather than reliable.
+
+Duration reporting `0.0` on Android widens the window: the reload is slower and
+less certain to land at the right position.
+
+**This is the same defect class as DR-238 … DR-241: state asserted rather than
+confirmed.** It is what `Phase::Opening` and `MpvPlayer`'s open generation
+exist for — a handoff *is* an open in flight, and a `close` during one has to
+cancel it rather than race it. The handoff is not modelled as an open at all
+today; it is two booleans and an offset.
+
+The fix therefore belongs with this contract rather than beside it: route the
+handoff through `open`/`close` so the swap has a phase, and so leaving the
+player during one cancels the thing that is actually playing instead of the
+thing the controller believes is playing. `close_during_open_never_plays`
+already states the required behaviour and passes on all four engines — the gap
+is that the handoff never reaches an engine as an open.
+
 ## Layer assignment
 
 | Logic / responsibility | Layer | Why it belongs there |