Unify resume freshness across app, media buttons, and realtime progress #9
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Why
GitHub PR #89 proves the REST freshness decision can recover a restored paused book when another device has moved it, but the decision currently lives in
PlayerViewModel.onTogglePlayPause. That means only an in-app Play goes through the one-book freshness check. Notification Play, Bluetooth/headset Play, Android Auto, steering-wheel controls and other MediaSession controllers can resume the loaded item without making the same decision.At the same time, issue #8 covers the current Audiobookshelf
user_item_progress_updatedSocket.IO event. Realtime reduces latency while the socket is connected, but it cannot be the sole source of truth: events are not replayed after a disconnect/background/process death, and a remote update must never blindly seek a book that is actively playing on this device.The result is one product question currently split across three mechanisms:
ResumeBaselinesays the position this device and the server last demonstrably agreed on;Those inputs need one serialized resume policy and one execution point rather than separate behaviour per control surface.
Device evidence motivating the rework
The GitHub #89 acceptance run proved its narrow restored-baseline fix: BookWave restored a paused baseline around 56:43, found the server at about 3:53:42, classified it
ahead, confirmed the player landed at the remote position, and subsequently synced progress beyond that adopted position.The same run then exposed a wider coordination problem: a few seconds later playback moved from about 3:53:48 back to about 56:36 without the tester requesting a seek. History recorded this as an ordinary local
Seek. A later seek back to ~3:53:42 was intentional because the tester clicked a History row and must not be counted as a defect.The uncommanded backwards destination being close to the old pre-adoption baseline suggests stale resume/position state may still participate. The current trace does not prove the initiating caller, so this issue must solve the coordination boundary rather than patch History, ExoPlayer or auto-rewind speculatively.
A related code-level race already exists:
PlayerViewModel.onSeekTodelegates directly toPlaybackController.seekTowithout cancelling an in-flight freshness job, while the freshness job only rechecks book identity and whether playback has started before applying its result. A deliberate local seek, chapter jump, History return, bookmark jump or similar listener action must invalidate any older resume decision before it can later move the player.Proposed design
Introduce a playback-layer resume/freshness coordinator owned by the media session/service rather than by the app ViewModel.
For every paused/armed -> play transition that BookWave can mediate:
ResumeBaseline;Any explicit local action that changes playback position or ownership must invalidate the pending decision, including:
The same resume policy must be reachable from:
Realtime rules
Realtime is an optimization/hint, not an authority that directly moves the player.
Product threshold to settle explicitly
Current
DefaultPlaybackRepository.checkServerPositiontreats a difference over roughly 5 seconds as a remote move. Earlier product intent for media-button resume was to ignore small drift and adopt only a materially different position of about two minutes.Do not silently pick one while moving the policy. Define one shared threshold/rule and test it in both directions, including intentional remote rewinds. Do not implement
max(position)semantics; a deliberate rewind on another device is a legitimate remote state.Diagnostics required by the rework
The next implementation should make position ownership visible enough that another unexpected move can be attributed without guesswork:
realtime,rest,local/unverified);remote-adoption,seek-bar,chapter,history,bookmark,skip,auto-rewind, media-session/controller) without media metadata;Acceptance criteria
max(position)behavior.Relationship to current work
Do not merge automatically.