Skip to content

Who saves the listening position in Cup's Android app, and how does the page take over from the native player? #425

Closed

Description

@patricktree

Question

Who saves the listening position in Cup's Android app, and how does the page take over from the native player?

The engine decision says the plugin saves natively by the web player's rules (every 5 s while playing, at once on pause, seek and end, and the CUP-71 retry). Open: whether the page's PlaybackSession saves anything on Android, how the two avoid conflicting or duplicate saves, what happens to the device-local position of listeners without an account (getLocalPosition), which position the page shows and saves after Cup returns to the foreground or reloads, and what happens to an unsaved position when the service stops (sign-out, user change, deletion, track URL expiry).


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

Activity

  1. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    From How does the server issue and check the signed position URL?: the signed position URL (narrationTrack.positionUrl) takes the unchanged body (synchronizationUnitId + offsetMilliseconds) with last write wins. If the plugin saves, it needs narrationTrack.startMilliseconds in load to convert ExoPlayer's track position, and the server doesn't order the page's saves against the native ones; this ticket settles both.


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

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

    @patricktree
    CollaboratorAuthor

    Resolution

    Grilled with the operator on 2026-11-16.

    On Android, the plugin is the only writer of the listening position. The page's PlaybackSession saves nothing, so the page and the plugin never send conflicting or duplicate saves.

    • What the plugin saves. It saves by the web player's rules: every 5 s while playing, and at once on pause, seek, end and close. Seeks before the first Play count too, saved while ExoPlayer is idle. When an audiobook ends, the position goes back to the start and the plugin saves 0. When the page loads another audiobook, the plugin saves the old one's position before it replaces the media item.
    • Converting positions. load carries the timeline (each synchronization unit's id and startMilliseconds). The plugin ports listeningPositionAt (findUnitIndexAt and the offset clamp) to Kotlin, with a unit test that mirrors its cases, and saves synchronizationUnitId + offsetMilliseconds without the page.
    • Both URLs travel together. load carries trackUrl and positionUrl, and What is the interface between the page and the ExoPlayer in Cup's Android plugin?'s replaceTrackUrl(url) becomes replaceUrls({ trackUrl, positionUrl }), both taken from the same audiobook response. They expire together, so "the track URL expired" also means the position URL can no longer be used.
    • Failures. The plugin follows PlaybackSession's rules: saves are written in order, and the 15 s retry runs only for the latest failed save, which a newer save replaces. Retries also fire on reconnect (an Android network callback, or Cup returning to the foreground). A lasting refusal (403 or 404 from the position route) stops the retries. The state event adds positionSave: "ok" | "failing" | "refused", the refusal's detail, and when the failures began. The page decides when to show "Your listening position could not be saved yet. Cup keeps trying.", by today's rule (the retry failed too, or saves have failed for 15 s), so the wording stays in one place.
    • No device-local positions on Android. The apps open no trials (ADR 0017) and no audiobook is public yet, so everyone who plays in the Android app is signed in. The native-backed player requires a subject and fails loudly when createPlayer gets subject: null. getLocalPosition stays browser-only. If trials or public audiobooks ever reach the app, that work decides where their positions live.
    • Which position the page shows. While a native session exists, the plugin is the truth: the page shows the position from state events, and from getState() when it becomes visible (back in the foreground, or adopting a running session after a reload). On every state event, the page writes the reported listening position into the cached audiobook's playbackPosition, locally and without a request, as savePlaybackPosition does today, so unloading or opening the audiobook again resumes there. With no session, the page shows the server's playbackPosition from the normal fetch. No merge logic is needed, because only the plugin writes.
    • Closing from the page. close takes "save" | "discard", as PositionOnClose does. Sign-out and a user change send close("save"): the plugin writes one final save through the position URL before it stops. The token is bound to that account's conversion and survives sign-out, so it cannot write into another account. Today's web player effectively loses that last save once the bearer is gone, and the spec notes the difference. Deletion sends close("discard"), because a save would race the deletion.
    • Native stops. Before each native stop (the notification swiped away, a paused session swiped from recents, track URL expiry, a 403), the plugin tries one final save if its last save didn't succeed. If that save fails, or the position URL has expired, the plugin drops the position, and no one sends it to the server. The closed state still reports the last position, so the page's cached audiobook shows it, and a later Play on a live page starts there and saves it.

    Ruled out:

    • The page saving too, through the bearer token: it would race the plugin's saves for no gain.
    • Splitting saves by visibility (the page while visible, the plugin while hidden): it needs a handover, and the WebView suspending the hidden page makes that unreliable.
    • The page taking over a position the plugin could not save, through the bearer token: proposed during the grilling, then dropped. Saves fail only while offline, and offline ExoPlayer plays only its buffer (about 50 s by default), so the gap is small. The position URL expires only after about 24 h of retries, and the page's cached audiobook usually still holds the position. A takeover would also have needed a closed report kept until getState() reads it, plus a rule to stop its retries once a new session saves.

    Accepted loss: a position is lost only if a native stop comes after saves that failed, and the page reloads or Cup cold-starts before the next Play. The loss is at most the buffered audio, or a seek made while offline.


    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