[BW-WIDGET-01] Add Resume / Now Playing Android widget #26

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

Migrated from GitHub issue #117. Forgejo issue: #26. 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 Android platform feature. Blocked on #23 and #24.

Product intent

Add one high-value BookWave Home-screen widget that lets the user see and continue the audiobook this device is using without opening the app.

User value

At a glance:

  • current/remembered audiobook;
  • author;
  • useful progress information;
  • play/pause or Continue;
  • tap through to player/book.

Scope

Build one responsive Jetpack Glance widget.

Recommended layouts:

  • Compact (~2x1): cover/icon, title, Continue/Play.
  • Standard (~4x2): cover, title, author, progress/checkpoint, play/pause, tap to player/book.
  • Expanded: optional series/sequence and chapter/progress detail if space permits.

Rules:

  • Widget is a projection, never a playback/resume source of truth.
  • Actions dispatch through #23.
  • Remembered book comes from #24.
  • Resume position uses GitHub #93 policy when playback starts.
  • Update on meaningful durable/domain events rather than waking every minute to animate a progress bar.
  • Process death must still render a sensible durable state.
  • Profile switch must promptly remove the previous profile's title/artwork.

Privacy / lock behavior

When the active profile is locked, render a generic state such as BookWave — profile locked; no cover, title, author, series or progress.

Do not expose another profile's content during widget update races.

Offline behavior

  • Downloaded book: Continue works normally offline.
  • Streaming-only/unavailable book: dispatch into the normal playback path and surface ordinary failure handling; widget does not invent networking logic.
  • Widget does not open its own realtime socket or REST freshness path.

Explicitly out of scope

  • No multi-book Continue Listening shelf in v1.
  • No sleep widget in this slice.
  • No download-count widget.
  • No independent minute-by-minute background progress ticker.

Dependencies

  • #23 BW-SYS-01 Android action contract.
  • #24 BW-PLAY-01 local remembered audiobook identity.
  • GitHub PR #93 unified resume freshness.

Platform

Use stable Jetpack Glance APIs where possible. Glance/AppWidget runs remotely from the main app process, so state must be derived from durable/app-owned data rather than in-memory ViewModel/player objects.

Storage / migration

Prefer existing durable repository state. A small dedicated widget projection is acceptable only if needed for efficient cross-process rendering and must not become playback truth.

Automated tests

  • projection with/without active playback;
  • remembered book after process death;
  • profile switch clears old content;
  • locked profile generic state;
  • offline downloaded/streaming cases;
  • widget action -> #23 semantic action;
  • sizing/layout selection logic.

Device acceptance

Test on Samsung and Pixel/AOSP-style launchers:

  • add/remove/resize widget;
  • cold process;
  • play/pause;
  • profile lock/switch;
  • offline;
  • remote progress update after BookWave learns it.

Estimated effort

Medium.

Risk

Medium, mainly cross-process freshness/privacy rather than UI construction.

Sequence

After #23/#24. This is the first Android widget; later widgets should justify themselves from observed use.

Acceptance criteria

  • Widget survives process death.
  • Previous-profile metadata never lingers after switch/lock.
  • Continue/Play delegates to BookWave's shared action and playback owners.
  • No separate resume or networking policy exists inside the widget.
> Migrated from [GitHub issue #117](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/117). Forgejo issue: #26. 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 Android platform feature. Blocked on #23 and #24. ## Product intent Add one high-value BookWave Home-screen widget that lets the user see and continue the audiobook this device is using without opening the app. ## User value At a glance: - current/remembered audiobook; - author; - useful progress information; - play/pause or Continue; - tap through to player/book. ## Scope Build one responsive Jetpack Glance widget. Recommended layouts: - **Compact (~2x1):** cover/icon, title, Continue/Play. - **Standard (~4x2):** cover, title, author, progress/checkpoint, play/pause, tap to player/book. - **Expanded:** optional series/sequence and chapter/progress detail if space permits. Rules: - Widget is a projection, never a playback/resume source of truth. - Actions dispatch through #23. - Remembered book comes from #24. - Resume position uses [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) policy when playback starts. - Update on meaningful durable/domain events rather than waking every minute to animate a progress bar. - Process death must still render a sensible durable state. - Profile switch must promptly remove the previous profile's title/artwork. ## Privacy / lock behavior When the active profile is locked, render a generic state such as `BookWave — profile locked`; no cover, title, author, series or progress. Do not expose another profile's content during widget update races. ## Offline behavior - Downloaded book: Continue works normally offline. - Streaming-only/unavailable book: dispatch into the normal playback path and surface ordinary failure handling; widget does not invent networking logic. - Widget does not open its own realtime socket or REST freshness path. ## Explicitly out of scope - No multi-book Continue Listening shelf in v1. - No sleep widget in this slice. - No download-count widget. - No independent minute-by-minute background progress ticker. ## Dependencies - #23 BW-SYS-01 Android action contract. - #24 BW-PLAY-01 local remembered audiobook identity. - [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) unified resume freshness. ## Platform Use stable Jetpack Glance APIs where possible. Glance/AppWidget runs remotely from the main app process, so state must be derived from durable/app-owned data rather than in-memory ViewModel/player objects. ## Storage / migration Prefer existing durable repository state. A small dedicated widget projection is acceptable only if needed for efficient cross-process rendering and must not become playback truth. ## Automated tests - projection with/without active playback; - remembered book after process death; - profile switch clears old content; - locked profile generic state; - offline downloaded/streaming cases; - widget action -> #23 semantic action; - sizing/layout selection logic. ## Device acceptance Test on Samsung and Pixel/AOSP-style launchers: - add/remove/resize widget; - cold process; - play/pause; - profile lock/switch; - offline; - remote progress update after BookWave learns it. ## Estimated effort Medium. ## Risk Medium, mainly cross-process freshness/privacy rather than UI construction. ## Sequence After #23/#24. This is the first Android widget; later widgets should justify themselves from observed use. ## Acceptance criteria - Widget survives process death. - Previous-profile metadata never lingers after switch/lock. - Continue/Play delegates to BookWave's shared action and playback owners. - No separate resume or networking policy exists inside the widget.
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#26
No description provided.