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 engine plays the narration track in Cup's Android app? #376
Which engine plays the narration track in Cup's Android app? Is it the WebView <audio> with minimal native pieces, which keeps ADR 0011, or a native player, which supersedes its "native players removed"? For the WebView option, which plugin, own or community, provides the foreground service and system controls?
changed the title [-]Which engine plays the narration track in Cup's Android and iOS apps?[/-][+]Which engine plays the narration track in Cup's Android app?[/+]on Nov 16, 2026
The WebView <audio> stays the engine and keeps ADR 0011's one element; Cup's Android app gets no native player. Does a mediaPlayback foreground service keep Cup's WebView audio and network alive on the Android emulator? removed the main reason to go native, since the service stops freezing and the network cut. A native player (hand-written ExoPlayer or Capawesome Audio Player) would add a second engine behind the web player's timeline and PlaybackSession, which is a lasting cost on every player change.
Native pieces: an own, app-local Java Capacitor plugin around Media3's MediaSessionService.
It lives in apps/mobile-app/android/app/src/main/java/audio/cup/app/ and is registered in MainActivity, like AndroidSharePlugin. Media3 (androidx.media3, Jetpack's recommended media library) is added to the app's Gradle dependencies.
A SimpleBasePlayer sits behind the session. Media3 runs the mediaPlayback foreground service and the media notification. Media-session notifications are exempt from POST_NOTIFICATIONS.
The manifest declares FOREGROUND_SERVICE and FOREGROUND_SERVICE_MEDIA_PLAYBACK plus the service, as Media3 documents.
The noisy receiver, and audio focus handling if WebView's own doesn't suffice, live in this plugin.
It is Android-only, so iOS keeps WebKit's own Now Playing.
The page's <audio> is the only source of playback state. The native player mirrors what the page reports: playing or paused, position, duration, title and cover. It forwards every system command (notification, lock screen, earbuds, noisy receiver) to the page, which acts on it through its navigator.mediaSession handlers. That is one command path on every platform: the browser calls the handlers directly, and on Android the bridge calls them.
Ruled out:
Paid, closed-source plugins (Capawesome Media Session and Audio Player): their manifest can't be audited before buying, and they tie Cup to a subscription.
@capgo/capacitor-media-session: it lacks FOREGROUND_SERVICE_MEDIA_PLAYBACK, handles neither noisy nor focus, which would split Cup's native code from the session, and writes MPNowPlayingInfoCenter on iOS.
@jofr/capacitor-media-session: Capacitor 6 and unmaintained.
Operator observation. Today's app keeps playing when one Pixel Bud leaves the ear, while Spotify, ZDF and web media in Chrome pause. Most likely the buds send a pause command (AVRCP) to the active media session, and Cup's WebView has none, since Android WebView disables the Media Session API. Both buds back in the case is a real disconnect (ACTION_AUDIO_BECOMING_NOISY). The physical-device protocol must check both cases. The AVRCP part is unverified.
Reopened by the spec's frozen-page gate (#392, ticket #397): on the Pixel 10 Pro (Android 17, WebView 157), a Play from the earbuds after a pause reaches Cup's Media3 session and returns the service to the foreground. The WebView, though, has suspended the hidden page's JavaScript by then, so the command never reaches the <audio> and nothing plays. Neither Cup's process nor its renderer is frozen by Android, and Capacitor doesn't pause timers. The evidence is in #397: #397 (comment)
Questions this reopening has to settle:
Can the WebView be kept running while Cup is paused in the background, for example by keeping the WebView's visibility or renderer priority up, or by some other engine-side means?
Or does Cup need a native player after all, one of the options this decision ruled out?
#398 and #399 stay blocked until this is decided again.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
A native Media3 ExoPlayer plays the narration track in Cup's Android app. The WebView <audio> lost because, on the Pixel 10 Pro (Android 17, WebView 157), the WebView suspends a hidden page that plays nothing: an earbud Play after a pause reached Cup's media session, but never the page. The operator also noticed that notification play and pause lag, since every command went from Media3 to the page and back.
Where it lives: in Cup's own app-local plugin, inside the existing MediaPlaybackService. ExoPlayer replaces MirroringPlayer; the media session, notification and its back 15 s / play-pause / forward 15 s buttons stay.
Android only. Browsers keep the web player's <audio> and its navigator.mediaSession handlers and position state; iOS is decided on Map: iOS app that plays the narration track. A new ADR, written with the build, supersedes ADR 0011's single <audio> element for Android.
ExoPlayer is the only source of playback state on Android. The page loads the track into it, sends play, pause and seek as commands, and renders the state it reports (playing or paused, position, duration), behind the same player port the browser implementation fills. The page creates no <audio> on Android. System commands act on the player directly. This reverses the earlier "the page is the only source, the native side mirrors".
Listening-position saves are native, through a signed position URL. The server issues it alongside the signed track URL, scoped to one listener and one audiobook, with the same lifetime. The plugin saves by the web player's rules: every 5 s while playing, at once on pause, seek and end, and the CUP-71 retry of a failed save. Reusing the page's Supabase session was rejected: the access token lasts about an hour, the page can't refresh it while suspended (and refreshes only in the foreground by design), and a second, native refresher would race supabase-js on the rotating refresh token, so reuse detection would revoke the session and sign the listener out.
Track URL: every Play started on the page renews the URL when it is older than 12 h, as today, and hands it to the player. Native code never renews. When a paused session's track URL expires (fetch time + 24 h, the server's minimum validity), or a Play from outside Cup gets a 403, the service stops and removes its notification. Opening Cup renews the URL and starts again on Play.
Audio focus and headphone disconnects: ExoPlayer handles both (handleAudioFocus with speech audio attributes, setHandleAudioBecomingNoisy), replacing the plugin's own noisy receiver. A duck request, such as a navigation prompt, now pauses Cup and resumes it afterwards instead of lowering the volume to 20 %. Calls and other apps behave as decided before.
Playback resumption stays out of scope, now also because it would need a track URL and save credential stored past the session. Without it, System UI hides the paused player after about 10 minutes; an earbud Play still reaches the session.
Ruled out:
The WebView <audio> with a mirroring Media3 session: commands get lost once the WebView suspends the hidden page.
A Trusted Web Activity for Android, with Capacitor kept for iOS: it runs in whatever TWA-capable browser the listener has and otherwise falls back to a Custom Tab or WebView; it cannot ship its own Chrome.
The paid plugins and @capgo/capacitor-media-session, for the reasons in the first resolution.
Activity
[-]Which engine plays the narration track in Cup's Android and iOS apps?[/-][+]Which engine plays the narration track in Cup's Android app?[/+]patricktree commentedon Nov 16, 2026
Resolution
Grilled with the operator on 2026-11-16.
The WebView
<audio>stays the engine and keeps ADR 0011's one element; Cup's Android app gets no native player. Does a mediaPlayback foreground service keep Cup's WebView audio and network alive on the Android emulator? removed the main reason to go native, since the service stops freezing and the network cut. A native player (hand-written ExoPlayer or Capawesome Audio Player) would add a second engine behind the web player's timeline andPlaybackSession, which is a lasting cost on every player change.Native pieces: an own, app-local Java Capacitor plugin around Media3's
MediaSessionService.apps/mobile-app/android/app/src/main/java/audio/cup/app/and is registered inMainActivity, likeAndroidSharePlugin. Media3 (androidx.media3, Jetpack's recommended media library) is added to the app's Gradle dependencies.SimpleBasePlayersits behind the session. Media3 runs themediaPlaybackforeground service and the media notification. Media-session notifications are exempt fromPOST_NOTIFICATIONS.FOREGROUND_SERVICEandFOREGROUND_SERVICE_MEDIA_PLAYBACKplus the service, as Media3 documents.The page's
<audio>is the only source of playback state. The native player mirrors what the page reports: playing or paused, position, duration, title and cover. It forwards every system command (notification, lock screen, earbuds, noisy receiver) to the page, which acts on it through itsnavigator.mediaSessionhandlers. That is one command path on every platform: the browser calls the handlers directly, and on Android the bridge calls them.Ruled out:
@capgo/capacitor-media-session: it lacksFOREGROUND_SERVICE_MEDIA_PLAYBACK, handles neither noisy nor focus, which would split Cup's native code from the session, and writesMPNowPlayingInfoCenteron iOS.@jofr/capacitor-media-session: Capacitor 6 and unmaintained.Operator observation. Today's app keeps playing when one Pixel Bud leaves the ear, while Spotify, ZDF and web media in Chrome pause. Most likely the buds send a pause command (AVRCP) to the active media session, and Cup's WebView has none, since Android WebView disables the Media Session API. Both buds back in the case is a real disconnect (
ACTION_AUDIO_BECOMING_NOISY). The physical-device protocol must check both cases. The AVRCP part is unverified.patricktree commentedon Nov 16, 2026
Reopened by the spec's frozen-page gate (#392, ticket #397): on the Pixel 10 Pro (Android 17, WebView 157), a Play from the earbuds after a pause reaches Cup's Media3 session and returns the service to the foreground. The WebView, though, has suspended the hidden page's JavaScript by then, so the command never reaches the
<audio>and nothing plays. Neither Cup's process nor its renderer is frozen by Android, and Capacitor doesn't pause timers. The evidence is in #397: #397 (comment)Questions this reopening has to settle:
#398 and #399 stay blocked until this is decided again.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
patricktree commentedon Nov 16, 2026
Resolution (revised)
Grilled with the operator again on 2026-11-16, after the frozen-page probe in Frozen-page probe on the emulator and the Pixel. This replaces the resolution of 2026-11-16 08:24 above.
A native Media3 ExoPlayer plays the narration track in Cup's Android app. The WebView
<audio>lost because, on the Pixel 10 Pro (Android 17, WebView 157), the WebView suspends a hidden page that plays nothing: an earbud Play after a pause reached Cup's media session, but never the page. The operator also noticed that notification play and pause lag, since every command went from Media3 to the page and back.MediaPlaybackService. ExoPlayer replacesMirroringPlayer; the media session, notification and its back 15 s / play-pause / forward 15 s buttons stay.<audio>and itsnavigator.mediaSessionhandlers and position state; iOS is decided on Map: iOS app that plays the narration track. A new ADR, written with the build, supersedes ADR 0011's single<audio>element for Android.<audio>on Android. System commands act on the player directly. This reverses the earlier "the page is the only source, the native side mirrors".403, the service stops and removes its notification. Opening Cup renews the URL and starts again on Play.handleAudioFocuswith speech audio attributes,setHandleAudioBecomingNoisy), replacing the plugin's own noisy receiver. A duck request, such as a navigation prompt, now pauses Cup and resumes it afterwards instead of lowering the volume to 20 %. Calls and other apps behave as decided before.Ruled out:
<audio>with a mirroring Media3 session: commands get lost once the WebView suspends the hidden page.@capgo/capacitor-media-session, for the reasons in the first resolution.Partly superseded:
playto the page goes; track URL expiry becomes a fourth reason the service stops.SimpleBasePlayerand thecommandevent path to the page go.Written by @patricktree's agent (Claude Code, Claude Opus 5.5).