Implement automatic nightly sleep schedule (#33) #63

Merged
alexander merged 75 commits from mcp/issue-33-nightly-sleep-schedule into main 2026-09-20 10:08:14 +02:00
Owner

Summary

Implements Forgejo issue #33 / BW-SLEEP-01 as a Playback & Lifecycle-owned feature.

  • adds an optional local-time nightly sleep schedule under Playback settings;
  • reuses the existing configured default sleep-timer duration and the existing SleepTimerController;
  • supports same-day and overnight windows with explicit DST gap/overlap rules;
  • persists manual-cancel suppression for the current civil window occurrence;
  • distinguishes automatic expiry followed by explicit Play from passive playback restoration;
  • cancels a still-running automatic timer at the schedule end without pausing playback;
  • leaves manually-created/replaced timers independent of the schedule end;
  • projects active timer state in the full-player Sleep position;
  • promotes the existing playback-owned notification timer action into the compact forward media slot while active.

Example end behavior: with 22:00–07:00 and a 15-minute default, playback at 06:46 arms the ordinary timer; at 07:00 that automatic timer is cancelled and playback continues.

Ownership

There remains exactly one timer/countdown owner: SleepTimerController. The schedule is civil-window policy and persistence around that owner, not a second timer.

No AlarmManager, WorkManager polling, schedule-only service, independent Compose timer or notification-owned countdown is introduced.

Time semantics

  • start == end is an empty automatic window.
  • Spring-forward gap boundaries resolve to the first valid instant after the gap.
  • Overlapped starts use the earlier instant.
  • Overlapped ends use the later instant.
  • Timezone/manual wall-clock changes reconcile through the existing live playback service only.
  • Nothing wakes BookWave solely for a schedule boundary while no playback owner is alive.

Manual precedence

  • a manual timer replaces an automatic timer through the ordinary timer path;
  • a manual timer is not cancelled by the schedule end;
  • manually cancelling an automatic timer suppresses rearming for that occurrence, persisted across service/process recreation;
  • natural automatic expiry records a replay-required occurrence, so only a later explicit Play can rearm inside that same occurrence.

Surfaces

Full player:

  • idle: existing Sleep action;
  • active: authoritative remaining time replaces that presentation in the same action position;
  • tap opens the same existing sleep-timer interaction;
  • TalkBack semantics include remaining time.

Media notification/system controls:

  • active timer remains derived from SleepTimerController.state;
  • expanded/overflow action and compact forward-slot preference use the same action/state;
  • required back-side audiobook/car control and central transport remain available;
  • no activity/Compose state is required.

Android host rendering still requires the documented device acceptance pass; JVM/verifyDebug is not claimed as proof of System UI or Bluetooth behavior.

Verification

Focused policy, owner, notification-layout and real FullPlayer Compose tests are included. Final Forgejo pull-request verification will be run with the repository-required forced rerun before review.

Device runbook: docs/device-test-sleep-schedule.md.

No unrelated Android automation (#23/#26/#27), downloads, routing, dependency or toolchain work is included.

## Summary Implements Forgejo issue #33 / BW-SLEEP-01 as a Playback & Lifecycle-owned feature. - adds an optional local-time nightly sleep schedule under Playback settings; - reuses the existing configured default sleep-timer duration and the existing SleepTimerController; - supports same-day and overnight windows with explicit DST gap/overlap rules; - persists manual-cancel suppression for the current civil window occurrence; - distinguishes automatic expiry followed by explicit Play from passive playback restoration; - cancels a still-running **automatic** timer at the schedule end without pausing playback; - leaves manually-created/replaced timers independent of the schedule end; - projects active timer state in the full-player Sleep position; - promotes the existing playback-owned notification timer action into the compact forward media slot while active. Example end behavior: with 22:00–07:00 and a 15-minute default, playback at 06:46 arms the ordinary timer; at 07:00 that automatic timer is cancelled and playback continues. ## Ownership There remains exactly one timer/countdown owner: `SleepTimerController`. The schedule is civil-window policy and persistence around that owner, not a second timer. No AlarmManager, WorkManager polling, schedule-only service, independent Compose timer or notification-owned countdown is introduced. ## Time semantics - `start == end` is an empty automatic window. - Spring-forward gap boundaries resolve to the first valid instant after the gap. - Overlapped starts use the earlier instant. - Overlapped ends use the later instant. - Timezone/manual wall-clock changes reconcile through the existing live playback service only. - Nothing wakes BookWave solely for a schedule boundary while no playback owner is alive. ## Manual precedence - a manual timer replaces an automatic timer through the ordinary timer path; - a manual timer is not cancelled by the schedule end; - manually cancelling an automatic timer suppresses rearming for that occurrence, persisted across service/process recreation; - natural automatic expiry records a replay-required occurrence, so only a later explicit Play can rearm inside that same occurrence. ## Surfaces Full player: - idle: existing Sleep action; - active: authoritative remaining time replaces that presentation in the same action position; - tap opens the same existing sleep-timer interaction; - TalkBack semantics include remaining time. Media notification/system controls: - active timer remains derived from `SleepTimerController.state`; - expanded/overflow action and compact forward-slot preference use the same action/state; - required back-side audiobook/car control and central transport remain available; - no activity/Compose state is required. Android host rendering still requires the documented device acceptance pass; JVM/verifyDebug is not claimed as proof of System UI or Bluetooth behavior. ## Verification Focused policy, owner, notification-layout and real FullPlayer Compose tests are included. Final Forgejo pull-request verification will be run with the repository-required forced rerun before review. Device runbook: `docs/device-test-sleep-schedule.md`. No unrelated Android automation (#23/#26/#27), downloads, routing, dependency or toolchain work is included.
alexander force-pushed mcp/issue-33-nightly-sleep-schedule from dde2734037 to 786ddb7f1c 2026-09-19 23:28:56 +02:00 Compare
alexander deleted branch mcp/issue-33-nightly-sleep-schedule 2026-09-20 10:08:14 +02:00
Sign in to join this conversation.
No reviewers
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!63
No description provided.