Skip to content

How does Cup's Android app react to earbud pauses, headphone disconnects and audio focus changes? #390

Closed

Description

@patricktree

Question

How does Cup's Android app react to an earbud pause (one Pixel Bud out of the ear), a headphone disconnect (ACTION_AUDIO_BECOMING_NOISY), a call, and another app taking audio focus? Is WebView's own audio focus handling enough, or does the plugin request and handle focus itself? Should playback resume after a transient loss of focus?

Since Which engine plays the narration track in Cup's Android app?, these handlers live in the Android plugin and pause through the page's command path. The operator observed that today's app keeps playing when one Pixel Bud leaves the ear, while other apps pause. That is most likely an AVRCP pause sent to a media session Cup doesn't have yet, which is unverified.

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, with facts checked against Chromium (main @ cac798bf), AOSP and Media3 (release @ 8c6678b6) source.

    Headphone disconnect. The plugin's ACTION_AUDIO_BECOMING_NOISY receiver sends pause to the page down the command path. Cup never resumes when headphones reconnect; the position is saved as on any pause. Neither Media3 (for a SimpleBasePlayer) nor WebView handles this broadcast, so the receiver is needed.

    Earbud pauses. Cup has no in-ear logic of its own. Earbuds with in-ear detection send AVRCP Pause when a bud leaves the ear and Play when it goes back in: a hardware capture on a JBL LIVE PRO 2 shows exactly this (omacom/omarchy#10980), and on Linux the commands were dropped until a player registered. Android's Bluetooth stack delivers AVRCP passthrough as media-button key events to the active media session (AvrcpTargetService.java, audio_util/MediaPlayerList.java), which is why every app with a media session (Spotify, ZDF, Chrome) pauses and Cup's WebView, which has none, does not. With the Media3 session, a bud's Pause and Play reach the page as pause and play, so reinserting a bud resumes, as Pixel Buds help describes. A comment on the same PR reports that Pixel Buds Pro 2 multipoint switching follows the AVRCP play status, so the mirror's playing/paused state matters there too. That Pixel Buds send AVRCP (rather than something Android interprets) is inferred, not captured.

    Audio focus stays with WebView; the plugin neither requests nor handles it.

    • Android WebView requests focus: it turns off only the Blink Media Session API (aw_main_delegate.cc), and Chromium's MediaSessionImpl creates an AudioFocusDelegate. A track over 5 s gets AUDIOFOCUS_GAIN, requested once the page is audible (kDeferAudioFocusUntilAudible).
    • Transient loss (calls: Telecom requests AUDIOFOCUS_GAIN_TRANSIENT for ringing and the call) pauses the element, and the page sees pause; regaining focus resumes only what the loss paused, and the page sees play/playing.
    • Permanent loss (another media app plays) pauses and abandons focus; no resume. It is an ordinary pause on the paused-service path of When does Cup's Android media session service start, leave the foreground and stop?.
    • A duck request plays at 20 % volume instead of pausing; Cup accepts that rather than add a second focus owner. Since Android 8 the system often ducks without telling the app.
    • The page reports all of these as ordinary playback events, so the native mirror follows without focus code.

    Android 15 ordering. An app targeting API 35+ gets AUDIOFOCUS_REQUEST_FAILED unless it is the top app or runs a foreground service, and Chromium then pauses the element at once and rejects play(). The spec requires the plugin to bring the service back to the foreground before it sends play to the page (a Play from the notification or earbuds after the 10-minute grace). If the device probe shows this fails, Which engine plays the narration track in Cup's Android app? reopens.

    A call longer than the grace. After 10 minutes the service leaves the foreground and Cup may be frozen, so WebView's resume at the call's end may not come; the listener presses Play. Accepted.

    Out of this map. Rewinding a few seconds on resume after an interruption: a listening-UX feature for every platform, a Linear issue of its own if wanted.

    For the testing ticket. Probe steps: a Pixel Bud out and back in (check with the Bluetooth HCI snoop log that a pause reaches Cup's session), headphone disconnect, a call (adb emu gsm call on the emulator), another app taking focus, a ducking prompt, a notification or earbud Play after the 10-minute grace (Android 15 ordering), and a call longer than the grace.

    No new glossary term and no ADR from this ticket; the engine ADR the documentation patch plans carries these points.

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