[BW-DL-08] Show active download queue and live progress in screen and notifications #29

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

Migrated from GitHub issue #120. Forgejo issue: #29. 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 download UX implementation. Depends on #17-#19 for truthful recovery/execution state.

Product intent

Make downloads observable while they are happening.

The Downloads screen should show which books are currently downloading, queued, paused, retrying or waiting, with live progress. Android notifications should also show useful download progress while work is active.

Current gap

BookWave already has a Downloads management screen and BookDownloadWorker foreground progress notification, but the two surfaces do not share a first-class live progress model:

  • the screen is primarily a stored-device-copy management view;
  • live in-file byte progress is held inside the worker rather than projected to the screen;
  • each worker currently uses the same notification ID, which is not a robust model for multiple active book downloads;
  • durable manifest state and transient WorkManager state are intentionally separate, so the UI needs #17/#19's presentation boundary rather than inventing another state machine.

User value

A listener can answer:

  • What is downloading now?
  • How far along is each book?
  • Is it waiting for Wi-Fi, retrying, paused, or actually failed?
  • Can I pause/resume/retry it?
  • How many downloads are active overall?

Scope — Downloads screen

Restructure/evolve the existing Downloads screen into two conceptual areas:

Active / pending

Rows for Queued, Running, Waiting, Retrying, Paused and Failed/recoverable work as defined by #17/#19.

Each visible/authorized row should show:

  • cover where available;
  • title/author;
  • percentage and/or bytes downloaded;
  • status text;
  • Pause / Resume / Retry action from #18;
  • optional remaining-size information where it can be derived truthfully.

Title-hidden rows retain generic metadata privacy.

On device

Keep completed stored copies/device storage management separate from active transfer status. Do not lose pin/remove/verify/storage-location functionality.

Scope — live progress contract

  • Publish worker progress through an Android-supported observable WorkManager progress/evidence seam or an equivalent narrow adapter.
  • Combine live worker evidence with durable manifest bytes/file completion.
  • Progress must survive screen recreation and reconstruct sensibly after process death from WorkManager + manifest state.
  • Do not write every copied buffer into Room merely to animate UI.

Scope — notifications

While downloads are active:

  • show active progress in foreground notification(s);
  • support multiple simultaneous book downloads without workers overwriting one another's notification identity;
  • choose either per-book child notifications with a summary/group, or one aggregate notification, based on the simplest reliable Android behavior;
  • notification tap opens Downloads;
  • keep notification progress/state aligned with the screen's presentation model.

Recommended privacy default: notification may say Downloading 2 books · 42% or generic BookWave download status without exposing book titles on a locked device. If title-bearing notifications are later offered, they must obey explicit privacy/lock settings.

Explicitly out of scope

  • No new download retry policy.
  • No destructive repair/delete changes from #21/#22.
  • No widget in this slice.
  • No arbitrary SAF folder support.
  • No second durable execution-state database.

Dependencies

  • #17 BW-DL-02 safe failure/presentation state.
  • #18 BW-DL-03 correct Pause/Resume/Retry actions.
  • #19 BW-DL-04 WorkManager waiting/retry projection.

#20 removable-storage work may enhance states later but does not need to block the basic active queue.

Android platform review

Before implementation, re-check the current Android/WorkManager guidance for long-running/user-initiated downloads, foreground notification requirements and Android 16+ job quotas. Do not change the execution architecture in this UI slice unless the current implementation is actually incompatible or materially harmful.

Storage / migration

No Room migration expected for live progress. Durable file/manifest state remains existing download storage. WorkManager remains transient execution evidence.

Privacy / security

  • Notification lock-screen content is generic by default.
  • A physical copy owned by another profile can be represented without title/author.
  • Progress information must not accidentally reveal media identity.

Automated tests

  • multiple active books receive distinct stable progress identities;
  • live bytes/percentage projection;
  • queued/waiting/retrying/paused/failed state precedence;
  • screen recreation/process restart;
  • notification tap destination;
  • hidden-profile row redaction;
  • no Room write per byte/buffer;
  • completion removes active row and leaves completed copy in On device.

Device acceptance

  • start 2+ downloads;
  • observe independent progress in Downloads;
  • background app and confirm notification progress;
  • pause/resume one while another continues;
  • remove Wi-Fi under an unmetered policy and observe Waiting rather than Failed;
  • kill/relaunch app while workers continue;
  • complete downloads and verify active rows disappear while stored copies remain.

Estimated effort

Medium.

Risk

Medium because multiple WorkManager workers, foreground notifications and UI state must agree without becoming duplicate state owners.

Sequence

After #17-#19. High-value download UX follow-up.

Acceptance criteria

  • Current downloading books are clearly visible with live progress.
  • Multiple downloads do not overwrite each other's notification state.
  • Notification and screen agree on Waiting/Retrying/Paused/Failed semantics.
  • Completed downloads transition cleanly into the stored-device section.
  • No privacy leak from hidden-profile downloads.
> Migrated from [GitHub issue #120](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/120). Forgejo issue: #29. 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 download UX implementation. Depends on #17-#19 for truthful recovery/execution state. ## Product intent Make downloads observable while they are happening. The Downloads screen should show **which books are currently downloading, queued, paused, retrying or waiting**, with live progress. Android notifications should also show useful download progress while work is active. ## Current gap BookWave already has a Downloads management screen and `BookDownloadWorker` foreground progress notification, but the two surfaces do not share a first-class live progress model: - the screen is primarily a stored-device-copy management view; - live in-file byte progress is held inside the worker rather than projected to the screen; - each worker currently uses the same notification ID, which is not a robust model for multiple active book downloads; - durable manifest state and transient WorkManager state are intentionally separate, so the UI needs #17/#19's presentation boundary rather than inventing another state machine. ## User value A listener can answer: - What is downloading now? - How far along is each book? - Is it waiting for Wi-Fi, retrying, paused, or actually failed? - Can I pause/resume/retry it? - How many downloads are active overall? ## Scope — Downloads screen Restructure/evolve the existing Downloads screen into two conceptual areas: ### Active / pending Rows for Queued, Running, Waiting, Retrying, Paused and Failed/recoverable work as defined by #17/#19. Each visible/authorized row should show: - cover where available; - title/author; - percentage and/or bytes downloaded; - status text; - Pause / Resume / Retry action from #18; - optional remaining-size information where it can be derived truthfully. Title-hidden rows retain generic metadata privacy. ### On device Keep completed stored copies/device storage management separate from active transfer status. Do not lose pin/remove/verify/storage-location functionality. ## Scope — live progress contract - Publish worker progress through an Android-supported observable WorkManager progress/evidence seam or an equivalent narrow adapter. - Combine live worker evidence with durable manifest bytes/file completion. - Progress must survive screen recreation and reconstruct sensibly after process death from WorkManager + manifest state. - Do not write every copied buffer into Room merely to animate UI. ## Scope — notifications While downloads are active: - show active progress in foreground notification(s); - support multiple simultaneous book downloads without workers overwriting one another's notification identity; - choose either per-book child notifications with a summary/group, or one aggregate notification, based on the simplest reliable Android behavior; - notification tap opens Downloads; - keep notification progress/state aligned with the screen's presentation model. Recommended privacy default: notification may say `Downloading 2 books · 42%` or generic BookWave download status without exposing book titles on a locked device. If title-bearing notifications are later offered, they must obey explicit privacy/lock settings. ## Explicitly out of scope - No new download retry policy. - No destructive repair/delete changes from #21/#22. - No widget in this slice. - No arbitrary SAF folder support. - No second durable execution-state database. ## Dependencies - #17 BW-DL-02 safe failure/presentation state. - #18 BW-DL-03 correct Pause/Resume/Retry actions. - #19 BW-DL-04 WorkManager waiting/retry projection. #20 removable-storage work may enhance states later but does not need to block the basic active queue. ## Android platform review Before implementation, re-check the current Android/WorkManager guidance for long-running/user-initiated downloads, foreground notification requirements and Android 16+ job quotas. Do not change the execution architecture in this UI slice unless the current implementation is actually incompatible or materially harmful. ## Storage / migration No Room migration expected for live progress. Durable file/manifest state remains existing download storage. WorkManager remains transient execution evidence. ## Privacy / security - Notification lock-screen content is generic by default. - A physical copy owned by another profile can be represented without title/author. - Progress information must not accidentally reveal media identity. ## Automated tests - multiple active books receive distinct stable progress identities; - live bytes/percentage projection; - queued/waiting/retrying/paused/failed state precedence; - screen recreation/process restart; - notification tap destination; - hidden-profile row redaction; - no Room write per byte/buffer; - completion removes active row and leaves completed copy in On device. ## Device acceptance - start 2+ downloads; - observe independent progress in Downloads; - background app and confirm notification progress; - pause/resume one while another continues; - remove Wi-Fi under an unmetered policy and observe Waiting rather than Failed; - kill/relaunch app while workers continue; - complete downloads and verify active rows disappear while stored copies remain. ## Estimated effort Medium. ## Risk Medium because multiple WorkManager workers, foreground notifications and UI state must agree without becoming duplicate state owners. ## Sequence After #17-#19. High-value download UX follow-up. ## Acceptance criteria - Current downloading books are clearly visible with live progress. - Multiple downloads do not overwrite each other's notification state. - Notification and screen agree on Waiting/Retrying/Paused/Failed semantics. - Completed downloads transition cleanly into the stored-device section. - No privacy leak from hidden-profile downloads.
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#29
No description provided.