Skip to content

Which system commands and position state does the web player's media session provide, and how does the Android plugin mirror them? #388

Closed

Description

@patricktree

Question

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?

Since Which engine plays the narration track in Cup's Android app?, the page's <audio> is the only source of playback state and every system command reaches the page through its navigator.mediaSession handlers. This may reverse ADR 0011's "system media controls use browser defaults". The iOS simulator probe (How does Cup's WebView audio behave on the iOS simulator?) showed that setPositionState takes over the position iOS shows, so once set it must stay current.

Activity

  1. self-assigned this
    on Nov 16, 2026
  2. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Resolution

    Grilled with the operator on 2026-11-16.

    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.

    One command path. Earbud pauses (AVRCP through the media session) and the noisy receiver both send pause down this command path. ACTION_AUDIO_BECOMING_NOISY is 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?. Whether stop also 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions