Unify resume freshness across app, media buttons, and realtime progress #9

Closed
opened 2026-09-18 08:44:22 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #91. Forgejo issue: #9. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

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_updated Socket.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:

  1. an acknowledged ResumeBaseline says the position this device and the server last demonstrably agreed on;
  2. realtime may provide a newer server position while the app is connected;
  3. the one-book REST progress route is the authoritative fallback when realtime is absent, stale or missed.

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.onSeekTo delegates directly to PlaybackController.seekTo without 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:

  • identify the loaded book/profile and its acknowledged ResumeBaseline;
  • capture a generation/token for the resume decision;
  • use a profile/book-scoped realtime progress candidate when it is provably newer/fresher than that baseline;
  • otherwise perform the existing one-book REST check under a bounded latency budget;
  • make exactly one decision: resume locally, adopt the remote position, or resume unverified when the server cannot be reached;
  • if adopting, perform the position change before audio and ensure the service/player confirms it;
  • reject the result if its generation is no longer current.

Any explicit local action that changes playback position or ownership must invalidate the pending decision, including:

  • seek-bar movement;
  • chapter navigation;
  • skip forward/back;
  • History return;
  • bookmark return;
  • auto-rewind decision/application where applicable;
  • book/profile switch;
  • stop/reopen/new session;
  • a newer Play/Pause request that supersedes the old one.

The same resume policy must be reachable from:

  • the in-app Play button;
  • notification/system media controls;
  • Bluetooth/headset media buttons;
  • Android Auto / car controllers;
  • playback resumption where BookWave has enough context to make the check.

Realtime rules

Realtime is an optimization/hint, not an authority that directly moves the player.

  • #8 should ingest the affected media progress through the existing conflict-safe repository path and expose/update a fresh profile/book-scoped candidate.
  • A realtime update must not seek active playback. While this device is playing, local listening is authoritative for its live player and its journal/outbox protections remain in force.
  • A realtime update received while paused may satisfy the next resume decision without an extra REST request if its freshness is provable.
  • Missing/stale realtime never suppresses the REST fallback.
  • After disconnect/background/process death, the candidate cannot be assumed complete; REST remains mandatory when freshness cannot be established locally.

Product threshold to settle explicitly

Current DefaultPlaybackRepository.checkServerPosition treats 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:

  • log the resume-decision generation;
  • log evidence source (realtime, rest, local/unverified);
  • log player movement origin/category (remote-adoption, seek-bar, chapter, history, bookmark, skip, auto-rewind, media-session/controller) without media metadata;
  • log when a pending decision is invalidated and why;
  • never log private titles, URLs, tokens or raw server identifiers.

Acceptance criteria

  • One resume policy is exercised by app Play, notification Play, headset/Bluetooth Play and Android Auto Play.
  • A remote move made while BookWave is paused is adopted before audio regardless of which supported Play surface resumes it.
  • A remote update received through realtime can avoid a redundant REST request when its freshness is provable.
  • Missing/stale realtime never suppresses the REST fallback.
  • Active local playback is never auto-seeked by a socket push.
  • Every explicit local seek/move invalidates any older in-flight freshness decision.
  • A stale REST/realtime result cannot move the player after a local action, book change or profile change.
  • Profile/book switches cancel stale checks and cannot apply another profile's progress.
  • Small drift follows the explicitly chosen product threshold; intentional remote rewind is not converted into max(position) behavior.
  • Reproduce the GitHub #89 stress shape (restored old baseline -> remote adoption -> continue playing) for at least 60 seconds with no unexplained return to the old baseline.
  • Device logs identify which evidence and movement origin drove each resume without exposing private metadata.

Relationship to current work

  • GitHub #89 establishes/restores the acknowledged baseline for a paused restored book and remains a required narrow prerequisite. Its acceptance path passed on device.
  • #8 adds the current Audiobookshelf realtime progress event and should feed this policy, not directly move the player.
  • GitHub #81 serializes session transitions and overlaps the same playback handoff area; update/test GitHub #81 after GitHub #89 before implementing this coordinator so the rework is built on the final session ordering.
  • GitHub #78 Android Auto should receive its final car test after the shared resume policy exists.

Do not merge automatically.

> Migrated from [GitHub issue #91](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/91). Forgejo issue: #9. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Why [GitHub PR #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/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_updated` Socket.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: 1. an acknowledged `ResumeBaseline` says the position this device and the server last demonstrably agreed on; 2. realtime may provide a newer server position while the app is connected; 3. the one-book REST progress route is the authoritative fallback when realtime is absent, stale or missed. 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](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/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.onSeekTo` delegates directly to `PlaybackController.seekTo` without 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: - identify the loaded book/profile and its acknowledged `ResumeBaseline`; - capture a generation/token for the resume decision; - use a profile/book-scoped realtime progress candidate when it is provably newer/fresher than that baseline; - otherwise perform the existing one-book REST check under a bounded latency budget; - make exactly one decision: resume locally, adopt the remote position, or resume unverified when the server cannot be reached; - if adopting, perform the position change before audio and ensure the service/player confirms it; - reject the result if its generation is no longer current. Any explicit local action that changes playback position or ownership must invalidate the pending decision, including: - seek-bar movement; - chapter navigation; - skip forward/back; - History return; - bookmark return; - auto-rewind decision/application where applicable; - book/profile switch; - stop/reopen/new session; - a newer Play/Pause request that supersedes the old one. The same resume policy must be reachable from: - the in-app Play button; - notification/system media controls; - Bluetooth/headset media buttons; - Android Auto / car controllers; - playback resumption where BookWave has enough context to make the check. ## Realtime rules Realtime is an optimization/hint, not an authority that directly moves the player. - #8 should ingest the affected media progress through the existing conflict-safe repository path and expose/update a fresh profile/book-scoped candidate. - A realtime update **must not seek active playback**. While this device is playing, local listening is authoritative for its live player and its journal/outbox protections remain in force. - A realtime update received while paused may satisfy the next resume decision without an extra REST request if its freshness is provable. - Missing/stale realtime never suppresses the REST fallback. - After disconnect/background/process death, the candidate cannot be assumed complete; REST remains mandatory when freshness cannot be established locally. ## Product threshold to settle explicitly Current `DefaultPlaybackRepository.checkServerPosition` treats 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: - log the resume-decision generation; - log evidence source (`realtime`, `rest`, `local/unverified`); - log player movement origin/category (`remote-adoption`, `seek-bar`, `chapter`, `history`, `bookmark`, `skip`, `auto-rewind`, media-session/controller) without media metadata; - log when a pending decision is invalidated and why; - never log private titles, URLs, tokens or raw server identifiers. ## Acceptance criteria - One resume policy is exercised by app Play, notification Play, headset/Bluetooth Play and Android Auto Play. - A remote move made while BookWave is paused is adopted before audio regardless of which supported Play surface resumes it. - A remote update received through realtime can avoid a redundant REST request when its freshness is provable. - Missing/stale realtime never suppresses the REST fallback. - Active local playback is never auto-seeked by a socket push. - Every explicit local seek/move invalidates any older in-flight freshness decision. - A stale REST/realtime result cannot move the player after a local action, book change or profile change. - Profile/book switches cancel stale checks and cannot apply another profile's progress. - Small drift follows the explicitly chosen product threshold; intentional remote rewind is not converted into `max(position)` behavior. - Reproduce the [GitHub #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/89) stress shape (restored old baseline -> remote adoption -> continue playing) for at least 60 seconds with no unexplained return to the old baseline. - Device logs identify which evidence and movement origin drove each resume without exposing private metadata. ## Relationship to current work - **[GitHub #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/89)** establishes/restores the acknowledged baseline for a paused restored book and remains a required narrow prerequisite. Its acceptance path passed on device. - **#8** adds the current Audiobookshelf realtime progress event and should feed this policy, not directly move the player. - **[GitHub #81](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/81)** serializes session transitions and overlaps the same playback handoff area; update/test [GitHub #81](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/81) after [GitHub #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/89) before implementing this coordinator so the rework is built on the final session ordering. - **[GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78)** Android Auto should receive its final car test after the shared resume policy exists. Do not merge automatically.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#9
No description provided.