You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Which system commands and position state does the web player's media session provide, and how does the Android plugin mirror them? #388
Which system commands does Cup handle (play, pause, seek, skip forward and back), and what position state does the web player report through navigator.mediaSession on the browser, Android and iOS alike? How does the Android plugin's SimpleBasePlayer mirror the page's state, position, duration and metadata, and how does it forward commands to the page's handlers?
Actions, on every platform. The page registers play, pause, stop, seekto, seekbackward and seekforward. stop acts as pause: the audiobook stays loaded and its position is saved as on any pause. Car head units, some headsets, Android Auto and Wear OS send stop, and Media3 drops it unless the player advertises COMMAND_STOP. There is no previoustrack or nexttrack, because there is no queue (CUP-57 is out of scope). The skips use the seekOffset the system sends, and 15 s (the in-app skip, SKIP_MILLISECONDS) when it sends none. iOS's lock screen therefore skips 10 s, matching its icons.
Position state, on every platform. The page reports playbackState (playing or paused, and none once nothing is loaded) and setPositionState:
Duration: the timeline's total of the settled durations, not element.duration.
Position: the player's position including a pending seek, clamped to the duration.
Rate: the element's playback rate.
When: on load, play, pause, seeked, ratechange, waiting, playing and ended, and not on timeupdate; the system extrapolates in between.
Unload: clears metadata, position state and handlers.
This replaces ADR 0011's "system media controls use browser defaults", and the spec's documentation must supersede that bullet. How does Cup's WebView audio behave on the iOS simulator? showed that iOS shows what setPositionState reports, so the reports must stay current.
Port.apps/web-app/src/platform/media-session.ts becomes a port for metadata, playback state, position state and action handlers. It has two implementations:
Browser and iOS: over navigator.mediaSession.
Android: over the Capacitor plugin, which dispatches the plugin's command events to the handlers. Android WebView needs this because it lacks the Media Session API.
Both call the same handler functions, like the account-auth.* adapters. There is no navigator.mediaSession polyfill.
Android SimpleBasePlayer. The player mirrors the last state the page reported:
Media item: one item with the title and the cover image's signed URL as the artwork URI. Media3 loads it without extra headers.
Commands: play/pause, stop, seek in the current item, seek back, seek forward and get metadata.
Playback:playWhenReady comes from playing. The state is STATE_READY while loaded, STATE_BUFFERING between waiting and playing, and STATE_ENDED after ended.
Position: an extrapolating position supplier at the reported rate, so the notification advances without updates every second.
Buttons: set explicitly to back 15, play/pause, forward 15, with no stop button. The seek increments are 15 s.
System commands:handleSetPlayWhenReady, handleStop, handleSeek and the seek back/forward handlers emit a command event to the page (play, pause, stop, seekto with a position, seekbackward or seekforward with 15 s). Each returns an immediately completed future. Media3's placeholder state shows the change until the page's next report corrects it.
The audio itself: the plugin never touches the <audio>. Capacitor 8 turns off mediaPlaybackRequiresUserGesture (Bridge.java), so a play from the bridge can start the element even after an awaited track URL renewal.
ExoPlayer reconsidered. The operator asked what ExoPlayer would gain over this mirror. Its real gain is playback and commands that don't depend on the page's JavaScript running, plus built-in noisy and focus handling. The cost is still a second engine, and position saves would stall while JavaScript is frozen anyway. The decision in Which engine plays the narration track in Cup's Android app? stands. Evidence that commands get lost while Cup is paused in the background would reopen it.
Activity
patricktree commentedon Nov 16, 2026
Resolution
Grilled with the operator on 2026-11-16.
Actions, on every platform. The page registers
play,pause,stop,seekto,seekbackwardandseekforward.stopacts as pause: the audiobook stays loaded and its position is saved as on any pause. Car head units, some headsets, Android Auto and Wear OS send stop, and Media3 drops it unless the player advertisesCOMMAND_STOP. There is noprevioustrackornexttrack, because there is no queue (CUP-57 is out of scope). The skips use theseekOffsetthe system sends, and 15 s (the in-app skip,SKIP_MILLISECONDS) when it sends none. iOS's lock screen therefore skips 10 s, matching its icons.Position state, on every platform. The page reports
playbackState(playingorpaused, andnoneonce nothing is loaded) andsetPositionState:element.duration.play,pause,seeked,ratechange,waiting,playingandended, and not ontimeupdate; the system extrapolates in between.This replaces ADR 0011's "system media controls use browser defaults", and the spec's documentation must supersede that bullet. How does Cup's WebView audio behave on the iOS simulator? showed that iOS shows what
setPositionStatereports, so the reports must stay current.Port.
apps/web-app/src/platform/media-session.tsbecomes a port for metadata, playback state, position state and action handlers. It has two implementations:navigator.mediaSession.commandevents to the handlers. Android WebView needs this because it lacks the Media Session API.Both call the same handler functions, like the
account-auth.*adapters. There is nonavigator.mediaSessionpolyfill.Android
SimpleBasePlayer. The player mirrors the last state the page reported:playWhenReadycomes fromplaying. The state isSTATE_READYwhile loaded,STATE_BUFFERINGbetweenwaitingandplaying, andSTATE_ENDEDafterended.handleSetPlayWhenReady,handleStop,handleSeekand the seek back/forward handlers emit acommandevent to the page (play,pause,stop,seektowith a position,seekbackwardorseekforwardwith 15 s). Each returns an immediately completed future. Media3's placeholder state shows the change until the page's next report corrects it.<audio>. Capacitor 8 turns offmediaPlaybackRequiresUserGesture(Bridge.java), so a play from the bridge can start the element even after an awaited track URL renewal.One command path. Earbud pauses (AVRCP through the media session) and the noisy receiver both send
pausedown this command path.ACTION_AUDIO_BECOMING_NOISYis Android's broadcast for output moving from headphones to the speaker. The plugin registers its receiver itself, because neither WebView nor a mirroring player handles it. When Cup pauses, audio focus and ducking stay with How does Cup's Android app react to earbud pauses, headphone disconnects and audio focus changes?. Whetherstopalso ends the service stays with When does Cup's Android media session service start, leave the foreground and stop?.ExoPlayer reconsidered. The operator asked what ExoPlayer would gain over this mirror. Its real gain is playback and commands that don't depend on the page's JavaScript running, plus built-in noisy and focus handling. The cost is still a second engine, and position saves would stall while JavaScript is frozen anyway. The decision in Which engine plays the narration track in Cup's Android app? stands. Evidence that commands get lost while Cup is paused in the background would reopen it.
No new glossary term.