Skip to content

When does Cup's Android media session service start, leave the foreground and stop? #389

Closed

Description

@patricktree

Question

When does Cup's Android media session service start, leave the foreground and stop? Does it start on Play while Cup is visible? Does it keep running through a pause in the background, so that audio focus regain and a later Play from the notification can resume? And when does it stop: when the audiobook ends, when Cup leaves the player, or on sign-out?

Since Which engine plays the narration track in Cup's Android app?, Media3's MediaSessionService runs the foreground service and the media notification, and it leaves the foreground after 10 minutes paused. Media-session notifications are exempt from POST_NOTIFICATIONS, so the question also settles whether Cup asks for that permission at all. Background service starts are restricted on Android 12+.

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.

    Start: on the first Play, not on load. The page tells the plugin when a loaded audiobook starts playing. Media3's MediaSessionService then starts and goes to the foreground. A Play is always a tap in Cup's visible UI, so Android 12+'s ban on starting foreground services from the background never applies. Loading an audiobook only to seek or skip (loadShown) without playing starts nothing and shows no notification.

    Paused: Media3's 10-minute foreground grace. After a pause, with Cup visible or in the background, the service keeps its media notification and stays in the foreground for 10 minutes, Media3's default. After that it leaves the foreground, and the notification stays but can be swiped away. Android may then freeze Cup and cut its network again (Android background network access and freezing). Play from the notification, the lock screen or the earbuds brings the service back to the foreground, as Android allows for media commands, and forwards the command to the page. Ruled out: stopping at once on a pause in the background, since Play from the notification would then be impossible, and staying in the foreground indefinitely while paused, which Media3 discourages. Unverified: whether a page that was already frozen gets that command and plays, including renewing a stale signed track URL first. Testing must probe this.

    The end of the audiobook counts as a pause. When the track ends, the element pauses at its end, and the notification stays and shows the full duration, the same as any pause, including the grace. Play restarts from the beginning, following the existing timeline rule, and a seek back works too.

    Stop: in exactly three cases. The service stops and its notification goes away when:

    1. the page empties the element: the player host's unload on a change of the signed-in user (sign-out included), or release when the loaded audiobook is deleted;
    2. Cup's activity is destroyed (swiped from recents or killed by the system). Capacitor's Bridge.onDestroy destroys the WebView, so playback can't continue. Unlike Spotify, swiping Cup away stops playback;
    3. the listener swipes away the notification after it left the foreground. The page stays paused, and the next Play in Cup starts the service again.

    Navigating inside Cup never stops it, because the player host keeps one <audio> for the app shell's lifetime and playback continues across navigation.

    No POST_NOTIFICATIONS. Media-session notifications are exempt, so Cup neither declares nor asks for the permission. Cup has no other notifications.

    No playback resumption. Once the service has stopped, a Bluetooth Play or Android's media resumption controls (Media3's onPlaybackResumption with a MediaButtonReceiver) don't relaunch Cup. The listener opens Cup and taps Play. This is ruled out of the map.

    Not discussed: tapping the notification opens Cup's MainActivity, which is the session activity and Media3's usual default. Capacitor's WebView allows play() without a user gesture (setMediaPlaybackRequiresUserGesture(false)), so a command forwarded from the notification can start playback.

  3. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Constraint from Which system commands and position state does the web player's media session provide, and how does the Android plugin mirror them?: every system command reaches the page's JavaScript through the plugin's command event, and the plugin never touches the <audio>. A lock-screen or earbud Play works only while the page can run JavaScript, so this ticket must say what happens to a Play after Cup is paused in the background (the renderer frozen or throttled once the service leaves the foreground). If commands get lost then, the engine decision in Which engine plays the narration track in Cup's Android app? reopens. This ticket also decides whether stop (handled as pause) ends the service.

  4. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Partly superseded by What is the interface between the page and the ExoPlayer in Cup's Android plugin?: with ExoPlayer as the engine, a playing session keeps playing when Cup is swiped from recents (Media3's default onTaskRemoved); only a paused one stops the service. A page that starts while ExoPlayer plays adopts the session.


    Written by @patricktree's agent (Claude Code, Claude Opus 5.5).

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