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
What is the interface between the page and the ExoPlayer in Cup's Android plugin? #423
How the Android implementation fills the web player's Player port (apps/web-app/src/app/player/narration-track-player.ts) and where PlayerHost chooses it over the <audio>-backed NarrationTrackPlayer.
The plugin methods (load a track with its URL, title, cover, duration and start position; play, pause, seek, skip; replace the track URL; close) and the events it sends back (state, position, errors), including how often position reaches the page and what the page reads when Cup returns to the foreground.
How ExoPlayer playback errors while locked (network loss mid-listen, a 403 on an expired URL) reach the page and the listener.
Seam.PlayerHostServices.createPlayer(session) replaces createAudioElement(). Browsers build today's NarrationTrackPlayer on an <audio>; Android builds a new native-backed player on the plugin, behind the same Player port. PlayerHost stays platform-agnostic and keeps deciding what loads, when the track URL renews and when to unload; the platform is chosen once, where the services are built.
Commands (page → plugin).
load({ conversionId, trackUrl, title, artworkUrl, durationMilliseconds, startPositionMilliseconds }) sets the media item without preparing it: ExoPlayer stays idle, so no audio is fetched and Media3 shows no notification. Seeks and skips before the first Play only move the start position; the page shows the API's duration until then.
pause(), seekTo(ms), skipBy(deltaMs) (computed natively from ExoPlayer's own position, not from a possibly stale snapshot), replaceTrackUrl(url) (keeps the position) and close().
Loading another audiobook sends load again, replacing the media item in the running service. Only close() (sign-out, user change, deletion) releases ExoPlayer and stops the service.
State (plugin → page). One state event on every ExoPlayer change: playing, buffering, ended, error code, duration, position with the timestamp it was read at, conversionId and the account subject the session was loaded for. No periodic position ticks: the page extrapolates the position from the timestamp while playing. Because events sent while the WebView suspends the hidden page can be lost, the page calls getState() once whenever it becomes visible.
System controls. ExoPlayer's media session reports to the system directly; load carries the title, cover and timeline duration. On Android the web media-session port does nothing (publishMediaMetadata and the action handlers are no-ops), and draft PR #401's media-session.android.ts with its command path is dropped. The browser port from the web media-session slice stays as built.
Errors.
Network loss mid-listen: ExoPlayer retries under its default load-error policy; when it gives up, the plugin pauses, keeps the notification as paused, and reports error: "playback". The page shows "Audio could not be played. Press Play to try again."; Play re-prepares at the same position.
A 403: the plugin reports error: "trackUrlExpired" and the service stops. The next Play on the page renews the track URL whatever its age, not only past 12 h.
Native stops. When the native side stops the service by itself (track URL expiry, the notification swiped away, a paused session swiped from recents), the plugin sends state with closed: true and a reason, and drops its media item. The page keeps the audiobook loaded at its last position; the next Play renews the URL if needed, then sends load and play.
Adopting a running session. When the page starts (WebView reload, renderer crash, live update, or Cup reopened after a swipe from recents) while ExoPlayer plays, PlayerHost calls getState(); for a conversionId it fetches that audiobook and makes it the loaded audiobook without sending load, so playback isn't interrupted and the mini player shows it. If the fetch returns null (deleted) or the subject doesn't match the current account, the page calls close().
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
Activity
patricktree commentedon Nov 16, 2026
Resolution
Grilled with the operator on 2026-11-16. Who saves the listening position is left to Who saves the listening position in Cup's Android app, and how does the page take over from the native player?, and the signed position URL to How does the server issue and check the signed position URL?.
Seam.
PlayerHostServices.createPlayer(session)replacescreateAudioElement(). Browsers build today'sNarrationTrackPlayeron an<audio>; Android builds a new native-backed player on the plugin, behind the samePlayerport.PlayerHoststays platform-agnostic and keeps deciding what loads, when the track URL renews and when to unload; the platform is chosen once, where the services are built.Commands (page → plugin).
load({ conversionId, trackUrl, title, artworkUrl, durationMilliseconds, startPositionMilliseconds })sets the media item without preparing it: ExoPlayer stays idle, so no audio is fetched and Media3 shows no notification. Seeks and skips before the first Play only move the start position; the page shows the API's duration until then.play()prepares and plays; the first Play starts the service in the foreground, as When does Cup's Android media session service start, leave the foreground and stop? decided.pause(),seekTo(ms),skipBy(deltaMs)(computed natively from ExoPlayer's own position, not from a possibly stale snapshot),replaceTrackUrl(url)(keeps the position) andclose().loadagain, replacing the media item in the running service. Onlyclose()(sign-out, user change, deletion) releases ExoPlayer and stops the service.State (plugin → page). One
stateevent on every ExoPlayer change: playing, buffering, ended, error code, duration, position with the timestamp it was read at,conversionIdand the accountsubjectthe session was loaded for. No periodic position ticks: the page extrapolates the position from the timestamp while playing. Because events sent while the WebView suspends the hidden page can be lost, the page callsgetState()once whenever it becomes visible.System controls. ExoPlayer's media session reports to the system directly;
loadcarries the title, cover and timeline duration. On Android the web media-session port does nothing (publishMediaMetadataand the action handlers are no-ops), and draft PR #401'smedia-session.android.tswith itscommandpath is dropped. The browser port from the web media-session slice stays as built.Errors.
error: "playback". The page shows "Audio could not be played. Press Play to try again."; Play re-prepares at the same position.403: the plugin reportserror: "trackUrlExpired"and the service stops. The next Play on the page renews the track URL whatever its age, not only past 12 h.Native stops. When the native side stops the service by itself (track URL expiry, the notification swiped away, a paused session swiped from recents), the plugin sends
statewithclosed: trueand a reason, and drops its media item. The page keeps the audiobook loaded at its last position; the next Play renews the URL if needed, then sendsloadandplay.Swiping Cup from recents. Media3's default
onTaskRemoved: a playing session keeps playing, a paused one stops the service. This reverses When does Cup's Android media session service start, leave the foreground and stop?'s "stops when Cup's activity is destroyed" for a playing session.Adopting a running session. When the page starts (WebView reload, renderer crash, live update, or Cup reopened after a swipe from recents) while ExoPlayer plays,
PlayerHostcallsgetState(); for aconversionIdit fetches that audiobook and makes it the loaded audiobook without sendingload, so playback isn't interrupted and the mini player shows it. If the fetch returnsnull(deleted) or thesubjectdoesn't match the current account, the page callsclose().Written by @patricktree's agent (Claude Code, Claude Opus 5.5).