[BW-SYS-01] Expose BookWave actions to Android shortcuts and automation #23

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

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

Planned platform-integration feature. Blocked on playback ownership prerequisites before implementation.

Product intent

BookWave should expose stable Android actions so the user can invoke audiobook behavior from launcher shortcuts, automation tools, Assistant-capable surfaces, widgets, Quick Settings and future in-app schedules without every surface inventing its own playback logic.

Concrete target: it must be possible to build a rule such as when my headset connects, continue the audiobook this phone last played.

Problem / opportunity

Android has several action surfaces but no single universal third-party automation API. Launcher shortcuts, shortcuts.xml capabilities/App Actions, deep links/intents, widgets and automation apps all launch slightly different Android entry points. If BookWave implements them independently, resume ownership, profile privacy and lock behavior will drift.

User value

  • Pin common BookWave commands to the launcher.
  • Invoke stable BookWave actions from automation apps/routines where Android permits it.
  • Reuse the same actions from widgets and Quick Settings.
  • Keep 'Continue' semantics identical whether invoked in-app, from a headset rule, launcher, car or watch.

Scope

Define one typed semantic action contract and Android dispatcher for at least:

  • ContinueListening — continue the book this device locally remembers, then use the shared resume-freshness policy for position.
  • Play
  • Pause
  • TogglePlayback
  • SkipForward
  • SkipBack
  • OpenCurrentBook
  • OpenPlayer
  • OpenLibrary
  • OpenSearch
  • OpenDownloads
  • OpenHistory
  • StartSleepTimer(duration)
  • CancelSleepTimer
  • OpenSleepSettings

Expose appropriate actions through:

  1. stable Android intents/deep-link destinations;
  2. static/dynamic/pinned app shortcuts;
  3. shortcuts.xml capabilities/App Actions where the platform supports them;
  4. a deliberately bounded automation entry point usable by third-party automation apps where practical.

All entry surfaces must dispatch into the same application/domain owners rather than directly controlling ExoPlayer or deriving their own remembered/resume state.

Security model

External automation is opt-in and narrowly scoped.

  • No arbitrary server URL, token, filesystem path or unrestricted book ID execution surface.
  • Actions with identifiers must validate current-profile access before showing or playing content.
  • Locked profiles must not expose title/cover/metadata through shortcuts or action results.
  • Side-effect actions must use an explicit allowlist, typed parameters and safe defaults.
  • Document which actions are callable while the device/profile is locked and which require opening BookWave.

Explicitly out of scope

  • No independent resume algorithm. GitHub PR #93 owns position freshness.
  • No guessing the last book from remote progress.updatedAt; BW-PLAY-01 owns remembered local book identity.
  • No Samsung-only Modes and Routines dependency as the architecture. Vendor integrations may bind to this contract later.
  • No general scripting language inside BookWave.
  • No headset-connect trigger implementation in this issue; a separate automation-trigger issue should consume this contract.

Dependencies

  • GitHub PR #93 — unified resume freshness.
  • BW-PLAY-01 — per-profile locally remembered audiobook identity.

Platform notes

Android app shortcuts are intended for specific repeatable app actions, and current Android guidance recommends keeping launcher-visible shortcuts small in number. shortcuts.xml capabilities can bind supported system/Assistant actions to destinations, but are not a universal scheduler/automation interface. Therefore the semantic action contract must sit below those surfaces rather than equating 'App Actions' with automation.

Storage / migration implications

None for the action contract itself. Any user-defined automation rules/schedules belong in separate issues and must name their own durable state.

Automated tests

  • Every external action maps to exactly one semantic action.
  • Malformed/unknown commands fail safely.
  • Locked profile does not leak metadata.
  • ContinueListening delegates remembered-book selection and resume position to their owners.
  • Cold-start and warm-process dispatch behave the same.
  • Deep-link/intent identifiers are authorization checked.

Device acceptance

  • Launcher shortcut cold/warm start on Samsung and an AOSP/Pixel-style launcher.
  • Invocation from at least one generic Android automation tool capable of launching shortcuts/intents.
  • Locked-profile behavior.
  • Screen-off invocation where Android background-execution rules permit it.

Estimated effort

Medium.

Risk

Medium: an exported automation surface can become a security/privacy hole if it accepts arbitrary data or bypasses profile/playback ownership.

After GitHub #93 + BW-PLAY-01. This is the foundation for Android widgets, Quick Settings, headset rules and Garmin companion controls.

Acceptance criteria

  • One documented semantic action contract exists.
  • Android shortcuts and external entry points delegate to it.
  • ContinueListening means the same thing everywhere.
  • No credentials/private metadata are exposed through action payloads.
  • The contract can be consumed by BW-WIDGET-01, BW-QS-01, BW-GARMIN-01 and headset automation without adding new playback policy.
> Migrated from [GitHub issue #114](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/114). Forgejo issue: #23. 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 Planned platform-integration feature. **Blocked on playback ownership prerequisites before implementation.** ## Product intent BookWave should expose stable Android actions so the user can invoke audiobook behavior from launcher shortcuts, automation tools, Assistant-capable surfaces, widgets, Quick Settings and future in-app schedules without every surface inventing its own playback logic. Concrete target: it must be possible to build a rule such as **when my headset connects, continue the audiobook this phone last played**. ## Problem / opportunity Android has several action surfaces but no single universal third-party automation API. Launcher shortcuts, `shortcuts.xml` capabilities/App Actions, deep links/intents, widgets and automation apps all launch slightly different Android entry points. If BookWave implements them independently, resume ownership, profile privacy and lock behavior will drift. ## User value - Pin common BookWave commands to the launcher. - Invoke stable BookWave actions from automation apps/routines where Android permits it. - Reuse the same actions from widgets and Quick Settings. - Keep 'Continue' semantics identical whether invoked in-app, from a headset rule, launcher, car or watch. ## Scope Define one typed semantic action contract and Android dispatcher for at least: - `ContinueListening` — continue the book this device locally remembers, then use the shared resume-freshness policy for position. - `Play` - `Pause` - `TogglePlayback` - `SkipForward` - `SkipBack` - `OpenCurrentBook` - `OpenPlayer` - `OpenLibrary` - `OpenSearch` - `OpenDownloads` - `OpenHistory` - `StartSleepTimer(duration)` - `CancelSleepTimer` - `OpenSleepSettings` Expose appropriate actions through: 1. stable Android intents/deep-link destinations; 2. static/dynamic/pinned app shortcuts; 3. `shortcuts.xml` capabilities/App Actions where the platform supports them; 4. a deliberately bounded automation entry point usable by third-party automation apps where practical. All entry surfaces must dispatch into the same application/domain owners rather than directly controlling ExoPlayer or deriving their own remembered/resume state. ## Security model External automation is opt-in and narrowly scoped. - No arbitrary server URL, token, filesystem path or unrestricted book ID execution surface. - Actions with identifiers must validate current-profile access before showing or playing content. - Locked profiles must not expose title/cover/metadata through shortcuts or action results. - Side-effect actions must use an explicit allowlist, typed parameters and safe defaults. - Document which actions are callable while the device/profile is locked and which require opening BookWave. ## Explicitly out of scope - No independent resume algorithm. [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) owns position freshness. - No guessing the last book from remote `progress.updatedAt`; BW-PLAY-01 owns remembered local book identity. - No Samsung-only Modes and Routines dependency as the architecture. Vendor integrations may bind to this contract later. - No general scripting language inside BookWave. - No headset-connect trigger implementation in this issue; a separate automation-trigger issue should consume this contract. ## Dependencies - **[GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93)** — unified resume freshness. - **BW-PLAY-01** — per-profile locally remembered audiobook identity. ## Platform notes Android app shortcuts are intended for specific repeatable app actions, and current Android guidance recommends keeping launcher-visible shortcuts small in number. `shortcuts.xml` capabilities can bind supported system/Assistant actions to destinations, but are not a universal scheduler/automation interface. Therefore the semantic action contract must sit below those surfaces rather than equating 'App Actions' with automation. ## Storage / migration implications None for the action contract itself. Any user-defined automation rules/schedules belong in separate issues and must name their own durable state. ## Automated tests - Every external action maps to exactly one semantic action. - Malformed/unknown commands fail safely. - Locked profile does not leak metadata. - `ContinueListening` delegates remembered-book selection and resume position to their owners. - Cold-start and warm-process dispatch behave the same. - Deep-link/intent identifiers are authorization checked. ## Device acceptance - Launcher shortcut cold/warm start on Samsung and an AOSP/Pixel-style launcher. - Invocation from at least one generic Android automation tool capable of launching shortcuts/intents. - Locked-profile behavior. - Screen-off invocation where Android background-execution rules permit it. ## Estimated effort Medium. ## Risk Medium: an exported automation surface can become a security/privacy hole if it accepts arbitrary data or bypasses profile/playback ownership. ## Recommended sequence After [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) + BW-PLAY-01. This is the foundation for Android widgets, Quick Settings, headset rules and Garmin companion controls. ## Acceptance criteria - One documented semantic action contract exists. - Android shortcuts and external entry points delegate to it. - `ContinueListening` means the same thing everywhere. - No credentials/private metadata are exposed through action payloads. - The contract can be consumed by BW-WIDGET-01, BW-QS-01, BW-GARMIN-01 and headset automation without adding new playback policy.
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#23
No description provided.