[BW-IOS-LIVE-01] Add a purposeful BookWave Live Activity for sleep/download status #32

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

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

Apple feature candidate with a committed evaluation. Do not implement as a duplicate Now Playing surface. Blocked on #30 iOS foundation and the underlying feature it represents.

What a Live Activity is

A Live Activity is Apple's glanceable, continuously updated system surface built with ActivityKit/WidgetKit. It can appear on the iPhone/iPad Lock Screen and Home Screen, Dynamic Island, Apple Watch Smart Stack, Mac menu bar and CarPlay Home Screen. It can also expose small interactive controls.

It is designed for an activity with a meaningful beginning/end and changing status over minutes or hours — for example a delivery, sports event, timer or transfer.

BookWave product decision

Ordinary audiobook playback should continue to use the system Now Playing experience, not a second Live Activity that repeats title/play/pause/progress.

The two BookWave cases worth implementing/evaluating are:

1. Sleep timer — preferred first use

Show:

  • BookWave stops in 23 min / end time;
  • Extend timer;
  • Cancel timer;
  • optional restart behavior if it maps cleanly to the existing sleep contract.

This is distinct from Now Playing and has a natural start/end lifecycle.

2. Active downloads — secondary candidate

While one or more books are downloading:

  • number of active books;
  • aggregate/per-current progress;
  • Waiting for Wi-Fi / Paused / Retrying state where meaningful;
  • tap to Downloads.

Do not expose private book titles by default on public system surfaces.

Scope

  • Define a portable presentation/state contract for the chosen activity.
  • Implement ActivityKit start/update/end lifecycle from the native iOS owner.
  • Add only interactions that perform a real action without needing to open the app where Apple permits it.
  • Deep-link/tap into the corresponding BookWave screen.
  • End the activity promptly when the timer/download task ends or becomes irrelevant.

Explicitly out of scope

  • No duplicate audiobook Now Playing Live Activity.
  • No Live Activity as a playback state owner.
  • No server push infrastructure solely to keep audiobook position ticking.
  • No CarPlay dependency; CarPlay can surface Live Activities automatically where the system supports them, while #31 owns the actual audio app experience.

Dependencies

  • #30 BW-IOS-00 Stage 6 system integrations.
  • For sleep-timer implementation: Android/product sleep-schedule/timer semantics should be stable enough to share behavior, but Apple implementation remains native.
  • For download implementation: iOS Stage 5 download/background-transfer state must exist.

Privacy / security

  • Generic lock-screen-safe presentation by default.
  • Never include server URL, account/profile identifier or credential-bearing data.
  • End/redact activity immediately on profile lock/switch when its content could identify media.

Automated tests

  • activity state mapping;
  • start/update/end transitions;
  • process relaunch/reconciliation;
  • profile lock/switch redaction/end behavior;
  • interaction -> native semantic action;
  • timer extension/cancel or download completion transitions.

Device acceptance

Real iPhone with Dynamic Island where available, Lock Screen, Apple Watch if available, and CarPlay Simulator observation where supported. Confirm system placement separately from app logic tests.

Estimated effort

Small-Medium after underlying iOS state exists.

Risk

Low-Medium if kept narrow; high product-noise risk if it merely duplicates Now Playing.

Prefer sleep timer Live Activity first. Add download Live Activity only if iOS download activity proves long-lived enough to benefit.

Acceptance criteria

  • Live Activity solves a task that Now Playing does not.
  • It has a clear start/end lifecycle.
  • Interactions delegate to BookWave owners.
  • Lock/profile transitions cannot strand private metadata on system surfaces.
> Migrated from [GitHub issue #123](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/123). Forgejo issue: #32. 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 Apple feature candidate with a committed evaluation. **Do not implement as a duplicate Now Playing surface.** Blocked on #30 iOS foundation and the underlying feature it represents. ## What a Live Activity is A Live Activity is Apple's glanceable, continuously updated system surface built with ActivityKit/WidgetKit. It can appear on the iPhone/iPad Lock Screen and Home Screen, Dynamic Island, Apple Watch Smart Stack, Mac menu bar and CarPlay Home Screen. It can also expose small interactive controls. It is designed for an activity with a meaningful beginning/end and changing status over minutes or hours — for example a delivery, sports event, timer or transfer. ## BookWave product decision **Ordinary audiobook playback should continue to use the system Now Playing experience, not a second Live Activity that repeats title/play/pause/progress.** The two BookWave cases worth implementing/evaluating are: ### 1. Sleep timer — preferred first use Show: - `BookWave stops in 23 min` / end time; - Extend timer; - Cancel timer; - optional `restart` behavior if it maps cleanly to the existing sleep contract. This is distinct from Now Playing and has a natural start/end lifecycle. ### 2. Active downloads — secondary candidate While one or more books are downloading: - number of active books; - aggregate/per-current progress; - Waiting for Wi-Fi / Paused / Retrying state where meaningful; - tap to Downloads. Do not expose private book titles by default on public system surfaces. ## Scope - Define a portable presentation/state contract for the chosen activity. - Implement ActivityKit start/update/end lifecycle from the native iOS owner. - Add only interactions that perform a real action without needing to open the app where Apple permits it. - Deep-link/tap into the corresponding BookWave screen. - End the activity promptly when the timer/download task ends or becomes irrelevant. ## Explicitly out of scope - No duplicate audiobook Now Playing Live Activity. - No Live Activity as a playback state owner. - No server push infrastructure solely to keep audiobook position ticking. - No CarPlay dependency; CarPlay can surface Live Activities automatically where the system supports them, while #31 owns the actual audio app experience. ## Dependencies - #30 BW-IOS-00 Stage 6 system integrations. - For sleep-timer implementation: Android/product sleep-schedule/timer semantics should be stable enough to share behavior, but Apple implementation remains native. - For download implementation: iOS Stage 5 download/background-transfer state must exist. ## Privacy / security - Generic lock-screen-safe presentation by default. - Never include server URL, account/profile identifier or credential-bearing data. - End/redact activity immediately on profile lock/switch when its content could identify media. ## Automated tests - activity state mapping; - start/update/end transitions; - process relaunch/reconciliation; - profile lock/switch redaction/end behavior; - interaction -> native semantic action; - timer extension/cancel or download completion transitions. ## Device acceptance Real iPhone with Dynamic Island where available, Lock Screen, Apple Watch if available, and CarPlay Simulator observation where supported. Confirm system placement separately from app logic tests. ## Estimated effort Small-Medium after underlying iOS state exists. ## Risk Low-Medium if kept narrow; high product-noise risk if it merely duplicates Now Playing. ## Recommended sequence Prefer **sleep timer Live Activity first**. Add download Live Activity only if iOS download activity proves long-lived enough to benefit. ## Acceptance criteria - Live Activity solves a task that Now Playing does not. - It has a clear start/end lifecycle. - Interactions delegate to BookWave owners. - Lock/profile transitions cannot strand private metadata on system surfaces.
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#32
No description provided.