[Bug] Headset Play after app update can resume current book at 0:00 #43

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

Migrated from GitHub issue #138. Forgejo issue: #43. 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.

Classification

Playback-correctness field regression. Investigated read-only against main at acccd7c3bccc148038539a581736a0d563686622, after GitHub PR #93 was merged.

No implementation branch or PR was opened as part of this investigation.

Field report

After BookWave had been updated, while the current audiobook was not open in the foreground, pressing Play on a headset resumed the same audiobook from the beginning (0:00) instead of the listener's existing position.

This was not observed during the GitHub PR #93 acceptance testing.

Expected behavior

A physical headset/Bluetooth Play after package update, service recreation or process replacement must resume the remembered/current audiobook at a trustworthy synchronized position. It must not silently start at 0:00 unless zero is genuinely the intended stored position.

Why this is separate from #24 / BW-PLAY-01

#24 owns which audiobook this phone remembers. In this field report, the correct audiobook was selected but the position was wrong. Position freshness/resumption correctness remains a separate playback concern.

Current investigation

1. The reported path is the cold/empty Media3 playback-resumption path

ResumeFreshnessPlayer.handleSetPlayWhenReady(true) deliberately forwards Play directly when mediaItemCount == 0, leaving Media3 to invoke normal playback resumption. That means an empty service does not run the ordinary loaded-item freshness preparation first.

The direct unit test named empty session Play preserves Media3 playback resumption verifies only that Play is forwarded and that the freshness token/preparation is not consumed. It does not exercise MediaSession.Callback.onPlaybackResumption, a non-zero returned start position, process/service recreation, or a package update.

There are currently no playback tests directly referencing onPlaybackResumption or MediaItemsWithStartPosition.

2. Cold resumption trusts the newly opened queue start

For onPlaybackResumption(..., isForPlayback = true), PlaybackService resolves the last book, calls openQueue(..., initialPlayWillFollow = true), and returns:

MediaItemsWithStartPosition(listOf(queue.item), 0, queue.startPositionMs)

The first Play is then intentionally exempted from a second GitHub #93 freshness check because the new /play session is considered fresh server evidence.

That design is sound only if the position returned by the fresh session/queue is trustworthy.

3. GitHub PR #93 appears to have exposed this lifecycle path rather than directly introducing the zero

Before/after GitHub #93, cold resumption already opened a queue and returned its start position. GitHub PR #93's material change in this branch was to pass initialPlayWillFollow = true so the immediately-following Media3 Play would not perform a redundant second freshness check.

So the field report is temporally associated with GitHub #93/update, but the current tree does not prove that GitHub #93 itself changed the cold queue's start-position selection to zero.

4. Confirmed shutdown ordering defect can lose the final server position

PlaybackService.onDestroy() currently does this in order:

  1. flushProgress() (local record launched asynchronously);
  2. sessionSync.onShutdown();
  3. immediately sessionSync.attach(null);
  4. later release the session/player.

SessionSyncCoordinator.onShutdown() itself launches onto the application scope and later calls closeCurrent(ServiceShutdown). closeCurrent() needs a player snapshot, and snapshot() returns null when the coordinator's player has already been detached.

The application scope runs on a SupervisorJob + Dispatchers.Default, while the snapshot switches back to the main dispatcher. Therefore the shutdown close is not ordered ahead of attach(null); the final session close/server progress can be dropped during service teardown.

There is no direct SessionSyncCoordinator.onShutdown() test today.

This strongly fits a package-update/process-replacement edge because the listener may lose the most recent server-acknowledged position before the next cold headset resume. It does not by itself prove why this particular report landed exactly at 0:00.

5. There is also an explicit zero-producing fallback

MediaItems.queueFor() currently uses:

serverStartPositionFor(session)?.inWholeMilliseconds ?: 0L

When BookWave cannot construct a trustworthy whole-book timeline because track durations force the single-file fallback, serverStartPositionFor() deliberately returns null, and the queue starts at zero to avoid confusing book-relative and file-relative positions.

That is a known defensive degradation, but on a cold headset resume it can produce the exact user-visible symptom reported here: correct book, start at 0:00.

The current repository evidence is not enough to tell whether this device run hit that fallback or whether /play itself returned zero/stale progress after the shutdown/lifecycle gap.

6. The captured Audiobookshelf contract proves /play can return non-zero resume positions

The repository's captured item-play.json has both currentTime and startTime at 128.25, and PlaybackMapper maps startTime directly into PlaybackSession.startAt. So a normal fresh /play response is capable of supplying a non-zero position.

Working diagnosis

This is a real cold-resumption correctness gap, with at least one confirmed lifecycle defect and one existing exact-zero fallback:

  • confirmed: service shutdown can detach the player before the final session close captures/sends its position;
  • confirmed test gap: the empty-session test does not cover the actual Media3 resumption callback or a non-zero start;
  • possible exact 0:00 mechanism: single-file fallback converts an otherwise non-zero book position to zero;
  • possible contributing mechanism: package/process replacement leaves server progress stale because the final close did not happen;
  • not yet proven from repository state alone: which of those produced the reported device event.

Required diagnostics for reproduction

Keep logging redaction-safe. Capture enough to distinguish:

  • service/process start and shutdown;
  • /play returned startAt;
  • queue.startPositionMs handed to Media3;
  • whether single-file fallback was active;
  • whether a shutdown/local progress write completed before teardown;
  • whether the cold callback or an already-loaded Play path was used;
  • GitHub #93 resume generation/evidence source where applicable.

Do not log titles, URLs, tokens, raw server identifiers, or private library metadata.

Acceptance criteria for the eventual fix

  • Install/update BookWave over a build where an audiobook has meaningful non-zero progress, leave BookWave out of the foreground, then press a physical headset/Bluetooth Play. The first audible position is the trustworthy resume position, not 0:00 followed by a later correction.
  • Add integration-level coverage for an empty Media3 session where onPlaybackResumption returns a non-zero start position and prove the player receives/applies it.
  • Add teardown coverage proving final progress/session state is captured durably before the player needed for the snapshot is detached.
  • Cover both normal service destruction and process/package-replacement recovery; do not rely on onDestroy() as the only durability guarantee.
  • Preserve GitHub PR #93's bidirectional freshness policy, including intentional remote rewinds; do not replace it with max(local, remote).
  • Cover the single-file fallback explicitly. A trusted non-zero book position must not silently become audible playback from zero without a safe, diagnosable policy.
  • Verify headset/Bluetooth, notification/system media Play and Android Auto cold resumption use the same correctness owner where applicable.
  • Device acceptance must include the exact update/background/headset sequence from this field report.
  • #9 / GitHub PR #93 — unified resume freshness across media control surfaces
  • #24 / BW-PLAY-01 — local remembered audiobook identity, intentionally separate from position correctness
> Migrated from [GitHub issue #138](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/138). Forgejo issue: #43. 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. ## Classification Playback-correctness field regression. Investigated read-only against `main` at `acccd7c3bccc148038539a581736a0d563686622`, after [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) was merged. No implementation branch or PR was opened as part of this investigation. ## Field report After BookWave had been updated, while the current audiobook was not open in the foreground, pressing **Play on a headset** resumed the same audiobook from the **beginning (0:00)** instead of the listener's existing position. This was not observed during the [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) acceptance testing. ## Expected behavior A physical headset/Bluetooth Play after package update, service recreation or process replacement must resume the remembered/current audiobook at a trustworthy synchronized position. It must not silently start at `0:00` unless zero is genuinely the intended stored position. ## Why this is separate from #24 / BW-PLAY-01 #24 owns **which audiobook this phone remembers**. In this field report, the correct audiobook was selected but the **position was wrong**. Position freshness/resumption correctness remains a separate playback concern. ## Current investigation ### 1. The reported path is the cold/empty Media3 playback-resumption path `ResumeFreshnessPlayer.handleSetPlayWhenReady(true)` deliberately forwards Play directly when `mediaItemCount == 0`, leaving Media3 to invoke normal playback resumption. That means an empty service does not run the ordinary loaded-item freshness preparation first. The direct unit test named `empty session Play preserves Media3 playback resumption` verifies only that Play is forwarded and that the freshness token/preparation is not consumed. It does **not** exercise `MediaSession.Callback.onPlaybackResumption`, a non-zero returned start position, process/service recreation, or a package update. There are currently no playback tests directly referencing `onPlaybackResumption` or `MediaItemsWithStartPosition`. ### 2. Cold resumption trusts the newly opened queue start For `onPlaybackResumption(..., isForPlayback = true)`, `PlaybackService` resolves the last book, calls `openQueue(..., initialPlayWillFollow = true)`, and returns: ```text MediaItemsWithStartPosition(listOf(queue.item), 0, queue.startPositionMs) ``` The first Play is then intentionally exempted from a second [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) freshness check because the new `/play` session is considered fresh server evidence. That design is sound only if the position returned by the fresh session/queue is trustworthy. ### 3. [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) appears to have exposed this lifecycle path rather than directly introducing the zero Before/after [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93), cold resumption already opened a queue and returned its start position. [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93)'s material change in this branch was to pass `initialPlayWillFollow = true` so the immediately-following Media3 Play would not perform a redundant second freshness check. So the field report is temporally associated with [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93)/update, but the current tree does **not** prove that [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) itself changed the cold queue's start-position selection to zero. ### 4. Confirmed shutdown ordering defect can lose the final server position `PlaybackService.onDestroy()` currently does this in order: 1. `flushProgress()` (local record launched asynchronously); 2. `sessionSync.onShutdown()`; 3. immediately `sessionSync.attach(null)`; 4. later release the session/player. `SessionSyncCoordinator.onShutdown()` itself launches onto the application scope and later calls `closeCurrent(ServiceShutdown)`. `closeCurrent()` needs a player snapshot, and `snapshot()` returns `null` when the coordinator's player has already been detached. The application scope runs on a `SupervisorJob + Dispatchers.Default`, while the snapshot switches back to the main dispatcher. Therefore the shutdown close is not ordered ahead of `attach(null)`; the final session close/server progress can be dropped during service teardown. There is no direct `SessionSyncCoordinator.onShutdown()` test today. This strongly fits a package-update/process-replacement edge because the listener may lose the most recent server-acknowledged position before the next cold headset resume. It does **not by itself prove** why this particular report landed exactly at `0:00`. ### 5. There is also an explicit zero-producing fallback `MediaItems.queueFor()` currently uses: ```text serverStartPositionFor(session)?.inWholeMilliseconds ?: 0L ``` When BookWave cannot construct a trustworthy whole-book timeline because track durations force the single-file fallback, `serverStartPositionFor()` deliberately returns `null`, and the queue starts at zero to avoid confusing book-relative and file-relative positions. That is a known defensive degradation, but on a cold headset resume it can produce the exact user-visible symptom reported here: correct book, start at `0:00`. The current repository evidence is not enough to tell whether this device run hit that fallback or whether `/play` itself returned zero/stale progress after the shutdown/lifecycle gap. ### 6. The captured Audiobookshelf contract proves `/play` can return non-zero resume positions The repository's captured `item-play.json` has both `currentTime` and `startTime` at `128.25`, and `PlaybackMapper` maps `startTime` directly into `PlaybackSession.startAt`. So a normal fresh `/play` response is capable of supplying a non-zero position. ## Working diagnosis This is a **real cold-resumption correctness gap**, with at least one confirmed lifecycle defect and one existing exact-zero fallback: - confirmed: service shutdown can detach the player before the final session close captures/sends its position; - confirmed test gap: the empty-session test does not cover the actual Media3 resumption callback or a non-zero start; - possible exact `0:00` mechanism: single-file fallback converts an otherwise non-zero book position to zero; - possible contributing mechanism: package/process replacement leaves server progress stale because the final close did not happen; - not yet proven from repository state alone: which of those produced the reported device event. ## Required diagnostics for reproduction Keep logging redaction-safe. Capture enough to distinguish: - service/process start and shutdown; - `/play` returned `startAt`; - `queue.startPositionMs` handed to Media3; - whether single-file fallback was active; - whether a shutdown/local progress write completed before teardown; - whether the cold callback or an already-loaded Play path was used; - [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) resume generation/evidence source where applicable. Do not log titles, URLs, tokens, raw server identifiers, or private library metadata. ## Acceptance criteria for the eventual fix - Install/update BookWave over a build where an audiobook has meaningful non-zero progress, leave BookWave out of the foreground, then press a physical headset/Bluetooth Play. The **first audible position** is the trustworthy resume position, not `0:00` followed by a later correction. - Add integration-level coverage for an empty Media3 session where `onPlaybackResumption` returns a non-zero start position and prove the player receives/applies it. - Add teardown coverage proving final progress/session state is captured durably before the player needed for the snapshot is detached. - Cover both normal service destruction and process/package-replacement recovery; do not rely on `onDestroy()` as the only durability guarantee. - Preserve [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93)'s bidirectional freshness policy, including intentional remote rewinds; do not replace it with `max(local, remote)`. - Cover the single-file fallback explicitly. A trusted non-zero book position must not silently become audible playback from zero without a safe, diagnosable policy. - Verify headset/Bluetooth, notification/system media Play and Android Auto cold resumption use the same correctness owner where applicable. - Device acceptance must include the exact update/background/headset sequence from this field report. ## Related - #9 / [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) — unified resume freshness across media control surfaces - #24 / BW-PLAY-01 — local remembered audiobook **identity**, intentionally separate from position correctness
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#43
No description provided.