Restore latest played book into idle Android Auto session #90

Merged
alexander merged 37 commits from mcp/issue-88-android-auto-held-resume into main 2026-09-24 15:03:04 +02:00
Owner

Summary

Implements #88.

  • restores an idle Android Auto / Media3 session with the latest valid resumable book instead of leaving the playback surface empty;
  • keeps a valid device-local remembered book authoritative, then falls back to the newest unfinished server-synced Continue item;
  • reconciles the account from the server only when local/cached resume state is missing;
  • uses an inert app-local Media3 holder for display-only state, without opening Audiobookshelf /play or starting audio;
  • materializes that holder into a fresh server-backed playback queue only after explicit Play;
  • preserves Never, ArmOnly / Ask, and AutoPlay audio-start semantics;
  • withholds resume metadata/playback while the active profile is locked;
  • prevents the display-only holder from creating progress/session writes;
  • keeps Android Auto recent-root child counts consistent with the new fallback semantics;
  • updates ROUTE-001 / ROUTE-003 and adds regression/reachability coverage.

Safety / lifecycle

A held item is presentation state only. It has a tiny inert app-local WAV media configuration because ExoPlayer creates a MediaSource when an item enters its playlist. The placeholder marker prevents it from being treated as a playable pass-through item.

When Play arrives, BookWave:

  1. captures the held profile/book identity;
  2. rejects locked/stale controller state;
  3. opens a fresh Audiobookshelf playback queue;
  4. rechecks controller generation, lock state, owner and holder identity after suspension;
  5. replaces the holder;
  6. only then enters the shared resume-freshness path.

A newer Pause, Stop, seek, media replacement or profile change wins over the suspended request.

Verification status

Tests were added/updated for candidate precedence, server fallback, inert holder construction, MediaSource safety, progress-write exclusion, callback reachability and cold-start wiring.

Per owner instruction, no Forgejo CI / Actions workflow has been started for this PR. The repository PR workflow is manual workflow_dispatch, so opening this PR does not dispatch it automatically.

Physical Android Auto acceptance remains required after CI/build verification is explicitly requested.

Closes #88

## Summary Implements #88. - restores an idle Android Auto / Media3 session with the latest valid resumable book instead of leaving the playback surface empty; - keeps a valid device-local remembered book authoritative, then falls back to the newest unfinished server-synced Continue item; - reconciles the account from the server only when local/cached resume state is missing; - uses an inert app-local Media3 holder for display-only state, without opening Audiobookshelf `/play` or starting audio; - materializes that holder into a fresh server-backed playback queue only after explicit Play; - preserves `Never`, `ArmOnly` / `Ask`, and `AutoPlay` audio-start semantics; - withholds resume metadata/playback while the active profile is locked; - prevents the display-only holder from creating progress/session writes; - keeps Android Auto recent-root child counts consistent with the new fallback semantics; - updates ROUTE-001 / ROUTE-003 and adds regression/reachability coverage. ## Safety / lifecycle A held item is presentation state only. It has a tiny inert app-local WAV media configuration because ExoPlayer creates a MediaSource when an item enters its playlist. The placeholder marker prevents it from being treated as a playable pass-through item. When Play arrives, BookWave: 1. captures the held profile/book identity; 2. rejects locked/stale controller state; 3. opens a fresh Audiobookshelf playback queue; 4. rechecks controller generation, lock state, owner and holder identity after suspension; 5. replaces the holder; 6. only then enters the shared resume-freshness path. A newer Pause, Stop, seek, media replacement or profile change wins over the suspended request. ## Verification status Tests were added/updated for candidate precedence, server fallback, inert holder construction, MediaSource safety, progress-write exclusion, callback reachability and cold-start wiring. Per owner instruction, **no Forgejo CI / Actions workflow has been started** for this PR. The repository PR workflow is manual `workflow_dispatch`, so opening this PR does not dispatch it automatically. Physical Android Auto acceptance remains required after CI/build verification is explicitly requested. Closes #88
Pin sleep claim after holder materialization
Some checks failed
BookWave / PR verification BookWave verification failed
728477d22f
Run Bundle-backed session sync test with Robolectric
All checks were successful
BookWave / PR verification BookWave PR verification passed
f9e4c41718
Author
Owner

CI follow-up for PR #90:

Failed run #273 at 728477d22f42dba4da047631f4404aa17fd1eab4 exposed 2 ktlint findings, 3 Detekt ReturnCount findings, 1 Android Lint UseKtx error, and 1 Bundle-backed unit-test failure. All were repaired on the branch.

Exact-head run #274 at f9e4c41718d0334b50a15cac80e5d904e8f02cdc is now fully green, including verifyDebug and the published BookWave / PR verification success status.

No additional failure class appeared, so the PR workflow has not been changed as part of #88. The small diagnostics-wording issue observed in failed run #273 is better handled in the CI architecture work (#85) rather than changing this feature PR.

CI follow-up for PR #90: Failed run #273 at `728477d22f42dba4da047631f4404aa17fd1eab4` exposed 2 ktlint findings, 3 Detekt ReturnCount findings, 1 Android Lint UseKtx error, and 1 Bundle-backed unit-test failure. All were repaired on the branch. Exact-head run #274 at `f9e4c41718d0334b50a15cac80e5d904e8f02cdc` is now fully green, including `verifyDebug` and the published `BookWave / PR verification` success status. No additional failure class appeared, so the PR workflow has not been changed as part of #88. The small diagnostics-wording issue observed in failed run #273 is better handled in the CI architecture work (#85) rather than changing this feature PR.
Author
Owner

Verification update — exact-head gate is green

Supersedes the earlier PR-body note that CI had not been started.

Current PR head: f9e4c41718d0334b50a15cac80e5d904e8f02cdc
Base: main@88ae231ddc01897d83e24968bed5443ea861aedd
Base freshness: 0 behind; mergeable.

The first manual PR verification exposed formatting/static-policy/lint issues plus one JVM Bundle-fixture mismatch. Those were repaired without changing the intended #88 behavior. The exact repaired head was then verified by Forgejo Actions run #274.

Run #274: PASS

  • resolve target: PASS
  • preflight: PASS
  • full verification / verifyDebug: PASS
  • publish check: PASS
  • commit status BookWave / PR verification: success
  • Gradle result: BUILD SUCCESSFUL (1121 actionable tasks)

No device/emulator is attached to the Forgejo runner, so this does not claim physical Android Auto/DHU acceptance. The remaining acceptance work is the real-car/DHU matrix from #88: fresh state/server fallback, paused prior book, process/service recreation, reconnect, Never-policy display without autoplay, and explicit Play from the held default item.

No merge performed.

## Verification update — exact-head gate is green Supersedes the earlier PR-body note that CI had not been started. Current PR head: `f9e4c41718d0334b50a15cac80e5d904e8f02cdc` Base: `main@88ae231ddc01897d83e24968bed5443ea861aedd` Base freshness: 0 behind; mergeable. The first manual PR verification exposed formatting/static-policy/lint issues plus one JVM Bundle-fixture mismatch. Those were repaired without changing the intended #88 behavior. The exact repaired head was then verified by Forgejo Actions run #274. Run #274: PASS - resolve target: PASS - preflight: PASS - full verification / `verifyDebug`: PASS - publish check: PASS - commit status `BookWave / PR verification`: success - Gradle result: `BUILD SUCCESSFUL` (1121 actionable tasks) No device/emulator is attached to the Forgejo runner, so this does **not** claim physical Android Auto/DHU acceptance. The remaining acceptance work is the real-car/DHU matrix from #88: fresh state/server fallback, paused prior book, process/service recreation, reconnect, Never-policy display without autoplay, and explicit Play from the held default item. No merge performed.
alexander deleted branch mcp/issue-88-android-auto-held-resume 2026-09-24 15:03:04 +02:00
Sign in to join this conversation.
No reviewers
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!90
No description provided.