Replace HeadsetHold inference with route-heard ownership #11

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

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

Origin

Follow-up from GitHub PR #78 review and docs/risks.md R-108. This is intentionally separate from GitHub #78: repeated local patches to inferred route state have already produced regressions, and another sticky guard would make the model worse rather than safer.

Problem

The current headset-preservation path infers "this audiobook was actually being heard on this headset" from a combination of heardAudio, the platform's current isActive output, BookWave's selected route, and HeadsetHold memory/release state.

That is weaker than the fact the product actually cares about: which route was carrying the audiobook when playback occurred.

A known remaining failure illustrates it: play through earbuds, explicitly move the audiobook to the phone speaker using the phone/system output chooser, then connect a car. The old headset can remain remembered and be reasserted even though the listener deliberately stopped using it.

The final GitHub #78 review found the inverse ownership problem as well: AudioOutputRoles.startTarget() can see a framework/system-policy route that differs from BookWave's explicit selectedId and replace the explicit choice when playback starts. getAudioDevicesForAttributes describes a route for the audio attributes, not proof of the route carrying BookWave's actual track. With multiple candidate sinks, inferred system-policy state must therefore never outrank an explicit listener choice without stronger BookWave-track evidence.

Classic A2DP ambiguity is not itself the bug. A2DP must remain semantically Ambiguous unless Android/user/device evidence supplies a stronger role.

Desired invariant

Preservation should be owned by an explicit, generation/book-bound record of the route that was actually carrying audio when the service observed playback, rather than by indirect proxies that must be cleared in every path.

  • Capture the strongest trustworthy evidence of the route carrying BookWave playback when the service observes real playback (onIsPlayingChanged(true) or a stronger Media3/platform boundary if one exists).
  • Bind remembered route evidence to the loaded book/session generation so book changes/queue empty cannot inherit it.
  • A merely connected headset must never become remembered.
  • An explicit move to speaker/another route must supersede the old heard route when playback is subsequently observed there.
  • An explicit BookWave output selection must not be replaced merely because getAudioDevicesForAttributes reports a different system-policy route. Explicit listener intent wins until evidence from BookWave's actual track shows that intent is no longer the route carrying playback.
  • Car continues to mean releasing BookWave's preferred device back to Automatic; do not reintroduce dashboard guessing.
  • Headset continues to select only legitimate headset candidates; definite speaker/car routes remain excluded.
  • Do not add another independent sticky boolean to patch one sequence.

Regression cases

  • Headset actually heard -> car arrives: preserve that headset when appropriate.
  • Headset merely connected -> car arrives: do not select it.
  • Headset heard -> explicitly move to phone speaker -> car arrives: do not resurrect the headset (R-108).
  • Explicitly select headset A while the framework/system-policy query reports candidate B -> starting/resuming playback must not replace A solely from that inferred route.
  • Multiple classic-A2DP candidates -> system-policy enumeration/order must not override an explicit BookWave choice.
  • Car pressed -> immediate Headset pressed before route callbacks settle: the explicit Headset choice wins.
  • Remembered headset disconnects: forget it.
  • Queue/book changes or empties: old route evidence cannot affect the next book.
  • Ambiguous classic A2DP remains ambiguous; tests must not relabel it as headset or car just to make routing assertions easy.

Device acceptance

JVM tests can prove ownership/generation/precedence rules, but the active-route observation is an Android/Media3 boundary. Final acceptance needs physical route sequences with a real headset and Android Auto/head unit, including the explicit speaker sequence above and, where possible, multiple simultaneously connected candidate outputs.

Relationship to GitHub #78

GitHub #78 should not grow this redesign. It records the bounded current limitations and leaves the tested behavior intact; this issue is where the stronger state model belongs. The final GitHub #78 P1 review finding about startTarget() is intentionally captured here rather than patched with another inference guard in GitHub #78.

> Migrated from [GitHub issue #100](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/100). Forgejo issue: #11. 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. ## Origin Follow-up from [GitHub PR #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/78) review and `docs/risks.md` R-108. This is intentionally separate from [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78): repeated local patches to inferred route state have already produced regressions, and another sticky guard would make the model worse rather than safer. ## Problem The current headset-preservation path infers "this audiobook was actually being heard on this headset" from a combination of `heardAudio`, the platform's current `isActive` output, BookWave's selected route, and `HeadsetHold` memory/release state. That is weaker than the fact the product actually cares about: **which route was carrying the audiobook when playback occurred**. A known remaining failure illustrates it: play through earbuds, explicitly move the audiobook to the phone speaker using the phone/system output chooser, then connect a car. The old headset can remain remembered and be reasserted even though the listener deliberately stopped using it. The final [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) review found the inverse ownership problem as well: `AudioOutputRoles.startTarget()` can see a framework/system-policy route that differs from BookWave's explicit `selectedId` and replace the explicit choice when playback starts. `getAudioDevicesForAttributes` describes a route for the audio attributes, not proof of the route carrying BookWave's actual track. With multiple candidate sinks, inferred system-policy state must therefore never outrank an explicit listener choice without stronger BookWave-track evidence. Classic A2DP ambiguity is not itself the bug. A2DP must remain semantically `Ambiguous` unless Android/user/device evidence supplies a stronger role. ## Desired invariant Preservation should be owned by an explicit, generation/book-bound record of the route that was actually carrying audio when the service observed playback, rather than by indirect proxies that must be cleared in every path. - Capture the strongest trustworthy evidence of the route carrying BookWave playback when the service observes real playback (`onIsPlayingChanged(true)` or a stronger Media3/platform boundary if one exists). - Bind remembered route evidence to the loaded book/session generation so book changes/queue empty cannot inherit it. - A merely connected headset must never become remembered. - An explicit move to speaker/another route must supersede the old heard route when playback is subsequently observed there. - **An explicit BookWave output selection must not be replaced merely because `getAudioDevicesForAttributes` reports a different system-policy route.** Explicit listener intent wins until evidence from BookWave's actual track shows that intent is no longer the route carrying playback. - Car continues to mean releasing BookWave's preferred device back to Automatic; do not reintroduce dashboard guessing. - Headset continues to select only legitimate headset candidates; definite speaker/car routes remain excluded. - Do not add another independent sticky boolean to patch one sequence. ## Regression cases - Headset actually heard -> car arrives: preserve that headset when appropriate. - Headset merely connected -> car arrives: do not select it. - Headset heard -> explicitly move to phone speaker -> car arrives: do not resurrect the headset (R-108). - Explicitly select headset A while the framework/system-policy query reports candidate B -> starting/resuming playback must not replace A solely from that inferred route. - Multiple classic-A2DP candidates -> system-policy enumeration/order must not override an explicit BookWave choice. - Car pressed -> immediate Headset pressed before route callbacks settle: the explicit Headset choice wins. - Remembered headset disconnects: forget it. - Queue/book changes or empties: old route evidence cannot affect the next book. - Ambiguous classic A2DP remains ambiguous; tests must not relabel it as headset or car just to make routing assertions easy. ## Device acceptance JVM tests can prove ownership/generation/precedence rules, but the active-route observation is an Android/Media3 boundary. Final acceptance needs physical route sequences with a real headset and Android Auto/head unit, including the explicit speaker sequence above and, where possible, multiple simultaneously connected candidate outputs. ## Relationship to [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) should not grow this redesign. It records the bounded current limitations and leaves the tested behavior intact; this issue is where the stronger state model belongs. The final [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) P1 review finding about `startTarget()` is intentionally captured here rather than patched with another inference guard in [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78).
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#11
No description provided.