[BW-IOS-CARPLAY-01] Add native CarPlay audiobook surface #31

Open
opened 2026-09-18 08:47:10 +02:00 by alexander · 0 comments
Owner

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

Committed future Apple feature. Blocked on #30 iOS Stage 3+ playback and Apple CarPlay audio entitlement.

Product intent

BookWave for iPhone should support CarPlay as a first-class audiobook surface, carrying the product lessons from Android Auto without mechanically copying Android's implementation.

Target experience

  • Continue/resume current locally remembered audiobook;
  • stable browse hierarchy for library/series/authors/history/downloads appropriate to CarPlay templates;
  • native Apple Now Playing;
  • Play/Pause and skip controls;
  • chapter/book metadata where the host permits it;
  • privacy-safe profile switching;
  • downloaded/offline playback after iOS downloads exist.

Platform contract

CarPlay audio apps require Apple's CarPlay audio entitlement. Use native CarPlay templates and the system-provided shared CPNowPlayingTemplate; do not build a custom free-form driving UI.

Request the entitlement early enough that approval does not become a surprise at the end of iOS development, but do not make CarPlay implementation block earlier iPhone stages.

Scope

  • CarPlay scene/app lifecycle integration.
  • Browse model designed for audiobook navigation using CPListTemplate, tab/list structures and other templates permitted for audio apps.
  • Present CPNowPlayingTemplate.shared for playback.
  • Reuse iOS domain/playback owners for remembered book, resume freshness, profile authorization and session state.
  • CarPlay commands route into native iOS playback owner.
  • Profile switch invalidates old-profile browse content and Now Playing metadata.
  • Offline/downloaded titles remain usable when server is unavailable once iOS Stage 5 exists.

Product direction

Use Android Auto as evidence about audiobook user needs, not as an API/UI blueprint. Initial CarPlay information architecture should keep the same spirit:

  • Continue first;
  • chapters/history readily accessible;
  • library exploration shallow enough for driving;
  • no settings-heavy surface in the car.

Explicitly out of scope

  • No CarPlay implementation before a stable native iOS media session/player exists.
  • No Android Media3 code sharing.
  • No custom arbitrary CarPlay visual design outside approved templates.
  • No dependency on Live Activities for playback.

Dependencies

  • #30 BW-IOS-00 through at least Stage 3 native playback; Stage 4 progress correctness should be substantially stable before release.
  • Apple-approved CarPlay audio entitlement.
  • iOS Stage 5 downloads for full offline parity, but initial streaming CarPlay can be developed earlier if useful.

Storage / migration

No CarPlay-specific storage source of truth. Browse/Now Playing are projections of iOS library/playback state.

Privacy / security

  • Profile switch must evict previous profile titles/artwork.
  • Locked/private state follows iOS system privacy contract.
  • No credentials/server URLs in CarPlay template identifiers or diagnostics.

Automated tests

  • pure CarPlay browse-model tests independent of template rendering;
  • profile-switch invalidation;
  • Continue delegates to remembered-book/resume owners;
  • chapter/history/library ordering;
  • missing/offline server behavior;
  • CarPlay lifecycle reconnection.

Device acceptance

  • Apple CarPlay Simulator during development;
  • real CarPlay head unit before release where practical;
  • stream, pause/play/skip, chapter navigation, profile switch, app process restart and offline downloaded playback.

Estimated effort

Medium-Large after iOS playback exists.

Risk

Medium-High due entitlement/host behavior and safety-constrained UI.

Sequence

#30 Stage 3 -> progress correctness -> CarPlay implementation. Request entitlement before the implementation sprint, not after it.

Acceptance criteria

  • BookWave is an approved CarPlay audio app.
  • Now Playing is native/system-owned.
  • Browse/navigation is safe and shallow for driving.
  • Playback/resume/profile correctness is shared with the iPhone app, not reimplemented in CarPlay.
  • Real/simulator evidence is recorded separately from unit-test evidence.
> Migrated from [GitHub issue #122](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/122). Forgejo issue: #31. 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 Committed future Apple feature. **Blocked on #30 iOS Stage 3+ playback and Apple CarPlay audio entitlement.** ## Product intent BookWave for iPhone should support CarPlay as a first-class audiobook surface, carrying the product lessons from Android Auto without mechanically copying Android's implementation. ## Target experience - Continue/resume current locally remembered audiobook; - stable browse hierarchy for library/series/authors/history/downloads appropriate to CarPlay templates; - native Apple Now Playing; - Play/Pause and skip controls; - chapter/book metadata where the host permits it; - privacy-safe profile switching; - downloaded/offline playback after iOS downloads exist. ## Platform contract CarPlay audio apps require Apple's CarPlay audio entitlement. Use native CarPlay templates and the system-provided shared `CPNowPlayingTemplate`; do not build a custom free-form driving UI. Request the entitlement early enough that approval does not become a surprise at the end of iOS development, but do not make CarPlay implementation block earlier iPhone stages. ## Scope - CarPlay scene/app lifecycle integration. - Browse model designed for audiobook navigation using `CPListTemplate`, tab/list structures and other templates permitted for audio apps. - Present `CPNowPlayingTemplate.shared` for playback. - Reuse iOS domain/playback owners for remembered book, resume freshness, profile authorization and session state. - CarPlay commands route into native iOS playback owner. - Profile switch invalidates old-profile browse content and Now Playing metadata. - Offline/downloaded titles remain usable when server is unavailable once iOS Stage 5 exists. ## Product direction Use Android Auto as **evidence about audiobook user needs**, not as an API/UI blueprint. Initial CarPlay information architecture should keep the same spirit: - Continue first; - chapters/history readily accessible; - library exploration shallow enough for driving; - no settings-heavy surface in the car. ## Explicitly out of scope - No CarPlay implementation before a stable native iOS media session/player exists. - No Android Media3 code sharing. - No custom arbitrary CarPlay visual design outside approved templates. - No dependency on Live Activities for playback. ## Dependencies - #30 BW-IOS-00 through at least Stage 3 native playback; Stage 4 progress correctness should be substantially stable before release. - Apple-approved CarPlay audio entitlement. - iOS Stage 5 downloads for full offline parity, but initial streaming CarPlay can be developed earlier if useful. ## Storage / migration No CarPlay-specific storage source of truth. Browse/Now Playing are projections of iOS library/playback state. ## Privacy / security - Profile switch must evict previous profile titles/artwork. - Locked/private state follows iOS system privacy contract. - No credentials/server URLs in CarPlay template identifiers or diagnostics. ## Automated tests - pure CarPlay browse-model tests independent of template rendering; - profile-switch invalidation; - Continue delegates to remembered-book/resume owners; - chapter/history/library ordering; - missing/offline server behavior; - CarPlay lifecycle reconnection. ## Device acceptance - Apple CarPlay Simulator during development; - real CarPlay head unit before release where practical; - stream, pause/play/skip, chapter navigation, profile switch, app process restart and offline downloaded playback. ## Estimated effort Medium-Large after iOS playback exists. ## Risk Medium-High due entitlement/host behavior and safety-constrained UI. ## Sequence #30 Stage 3 -> progress correctness -> CarPlay implementation. Request entitlement before the implementation sprint, not after it. ## Acceptance criteria - BookWave is an approved CarPlay audio app. - Now Playing is native/system-owned. - Browse/navigation is safe and shallow for driving. - Playback/resume/profile correctness is shared with the iPhone app, not reimplemented in CarPlay. - Real/simulator evidence is recorded separately from unit-test evidence.
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#31
No description provided.