[BW-SLEEP-01] Add automatic nightly sleep schedule #33

Open
opened 2026-09-18 08:47:24 +02:00 by alexander · 1 comment
Owner

Migrated from GitHub issue #124. Forgejo issue: #33. 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 playback/settings feature. Blocked on GitHub PR #98 for settings UI stability; behavior/state-machine can be specified independently.

Product intent

Allow BookWave to automatically apply the user's normal sleep timer during a chosen nightly window without requiring a manual timer every night.

This is separate from generic Android automation (#23/#25). It is a first-class BookWave sleep behavior because it has audiobook-specific semantics and must interact correctly with manual sleep timers, shake-to-restart and playback state.

Product rules

Settings:

  • enabled;
  • local start time;
  • local end time;
  • use existing configured default sleep-timer duration;
  • existing fade/shake/rewind behavior remains authoritative.

The schedule is an eligibility window, not a hard stop at the end time.

Example: for a 22:00-06:00 window, playback beginning at 05:55 still receives the full configured sleep timer. 06:00 only prevents a new automatic timer from being armed; it does not truncate the one already running.

State model

  • Disabled
  • OutsideWindow
  • EligibleIdle
  • AutomaticTimerActive
  • ManualTimerActive
  • SuppressedForCurrentWindow

Behavior

  • Playback starts outside the window -> no automatic timer.
  • Playback starts inside -> start normal default timer.
  • Playback is already active when the window begins -> start timer at the start boundary.
  • Manual timer always wins/replaces automatic timer.
  • User manually cancels an automatic timer -> suppress automatic rearming for that current schedule-window occurrence.
  • Suppression survives process death and clears for the next nightly window.
  • Automatic timer expires and the user explicitly presses Play while still inside the window -> this is deliberate new playback and may arm a new automatic timer.
  • Shake/restart follows the existing sleep-timer contract rather than a schedule-specific version.
  • Schedule is device-wide like current sleep settings.
  • Timezone/time changes recompute the active window using local wall-clock rules.
  • DST gap/overlap must reconcile deterministically.

Platform implementation direction

Do not begin with AlarmManager/WorkManager as the product design.

If playback is active, the MediaSession/playback service is already alive and can schedule/reconcile the next boundary in-process. If the app/service is dead and nothing is playing, there is no need to wake BookWave merely because a sleep window started.

On next playback/service activation, reconcile against current wall clock and stored suppression state.

Android action integration

Once #23 exists, expose safe semantic actions for:

  • start default sleep timer;
  • start timer with supported duration parameter;
  • cancel sleep timer;
  • open sleep settings.

This allows launcher/automation/Quick Settings surfaces to control the same owner, but #23 must not become a second sleep state machine.

Explicitly out of scope

  • No generic automation scripting engine.
  • No exact-alarm permission unless later evidence proves it necessary.
  • No periodic minute-level WorkManager polling.
  • No separate schedule-specific timer implementation.
  • No changes to GitHub PR #98 beyond integrating the setting after GitHub #98 stabilizes.

Dependencies

  • GitHub PR #98 for final settings-screen integration.
  • Existing sleep-timer domain/behavior.
  • #23 optional for external Android action exposure, not required for the core schedule state machine.

Storage / migration

Persist schedule settings and enough current-window suppression identity to survive process death. Avoid storing derived timer countdown state when the existing timer owner already owns it.

Privacy / security

No new sensitive data.

Automated tests

Pure clock/state-machine tests for:

  • disabled;
  • normal daytime window;
  • overnight window;
  • before/inside/after;
  • playback crossing start boundary;
  • start near window end;
  • manual timer override;
  • manual cancel suppression;
  • next-night reset;
  • expiry + explicit replay;
  • process restart;
  • timezone change;
  • DST forward gap and backward overlap.

Device acceptance

  • screen off/background playback;
  • process death/relaunch;
  • midnight/overnight window;
  • Bluetooth/headset playback;
  • timer notification/state;
  • manual cancel then continued playback;
  • next-night re-arm.

Estimated effort

Medium.

Risk

Medium: time-window edge cases are easy to make surprising if implementation starts before the state contract.

Sequence

After GitHub #98 for UI; state-machine implementation can be prepared once current sleep behavior is stable.

Acceptance criteria

  • Automatic schedule never truncates an already-started timer at the window end.
  • Manual timer/cancel semantics are deterministic.
  • Process death/timezone/DST reconciliation does not accidentally rearm a cancelled timer.
  • No unnecessary wakeup infrastructure is introduced.
> Migrated from [GitHub issue #124](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/124). Forgejo issue: #33. 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 playback/settings feature. Blocked on [GitHub PR #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/98) for settings UI stability; behavior/state-machine can be specified independently. ## Product intent Allow BookWave to automatically apply the user's normal sleep timer during a chosen nightly window without requiring a manual timer every night. This is separate from generic Android automation (#23/#25). It is a first-class BookWave sleep behavior because it has audiobook-specific semantics and must interact correctly with manual sleep timers, shake-to-restart and playback state. ## Product rules Settings: - enabled; - local start time; - local end time; - use existing configured default sleep-timer duration; - existing fade/shake/rewind behavior remains authoritative. The schedule is an **eligibility window**, not a hard stop at the end time. Example: for a 22:00-06:00 window, playback beginning at 05:55 still receives the full configured sleep timer. 06:00 only prevents a new automatic timer from being armed; it does not truncate the one already running. ## State model - Disabled - OutsideWindow - EligibleIdle - AutomaticTimerActive - ManualTimerActive - SuppressedForCurrentWindow ## Behavior - Playback starts outside the window -> no automatic timer. - Playback starts inside -> start normal default timer. - Playback is already active when the window begins -> start timer at the start boundary. - Manual timer always wins/replaces automatic timer. - User manually cancels an automatic timer -> suppress automatic rearming for that **current schedule-window occurrence**. - Suppression survives process death and clears for the next nightly window. - Automatic timer expires and the user explicitly presses Play while still inside the window -> this is deliberate new playback and may arm a new automatic timer. - Shake/restart follows the existing sleep-timer contract rather than a schedule-specific version. - Schedule is device-wide like current sleep settings. - Timezone/time changes recompute the active window using local wall-clock rules. - DST gap/overlap must reconcile deterministically. ## Platform implementation direction Do not begin with AlarmManager/WorkManager as the product design. If playback is active, the MediaSession/playback service is already alive and can schedule/reconcile the next boundary in-process. If the app/service is dead and nothing is playing, there is no need to wake BookWave merely because a sleep window started. On next playback/service activation, reconcile against current wall clock and stored suppression state. ## Android action integration Once #23 exists, expose safe semantic actions for: - start default sleep timer; - start timer with supported duration parameter; - cancel sleep timer; - open sleep settings. This allows launcher/automation/Quick Settings surfaces to control the same owner, but #23 must not become a second sleep state machine. ## Explicitly out of scope - No generic automation scripting engine. - No exact-alarm permission unless later evidence proves it necessary. - No periodic minute-level WorkManager polling. - No separate schedule-specific timer implementation. - No changes to [GitHub PR #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/98) beyond integrating the setting after [GitHub #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/98) stabilizes. ## Dependencies - [GitHub PR #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/98) for final settings-screen integration. - Existing sleep-timer domain/behavior. - #23 optional for external Android action exposure, not required for the core schedule state machine. ## Storage / migration Persist schedule settings and enough current-window suppression identity to survive process death. Avoid storing derived timer countdown state when the existing timer owner already owns it. ## Privacy / security No new sensitive data. ## Automated tests Pure clock/state-machine tests for: - disabled; - normal daytime window; - overnight window; - before/inside/after; - playback crossing start boundary; - start near window end; - manual timer override; - manual cancel suppression; - next-night reset; - expiry + explicit replay; - process restart; - timezone change; - DST forward gap and backward overlap. ## Device acceptance - screen off/background playback; - process death/relaunch; - midnight/overnight window; - Bluetooth/headset playback; - timer notification/state; - manual cancel then continued playback; - next-night re-arm. ## Estimated effort Medium. ## Risk Medium: time-window edge cases are easy to make surprising if implementation starts before the state contract. ## Sequence After [GitHub #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/98) for UI; state-machine implementation can be prepared once current sleep behavior is stable. ## Acceptance criteria - Automatic schedule never truncates an already-started timer at the window end. - Manual timer/cancel semantics are deterministic. - Process death/timezone/DST reconciliation does not accidentally rearm a cancelled timer. - No unnecessary wakeup infrastructure is introduced.
Author
Owner

Canonical acceptance staging — 2026-09-24

Reviewed main / acceptance APK source: 88ae231ddc01897d83e24968bed5443ea861aedd
Merged implementation: PR #63, accepted head b0075a00f88b9868dafb30f8cd859d700e8e7410, merge commit 0182520b5945fc82671b6e3c1da0056273398f66.
Exact-head CI: Forgejo run #156 / backend run 158 — all PR jobs green, including verifyDebug.
Current-main regression evidence: later PR #89 exact head passed run #270 with verifyDebug, 2606 tests / 0 failures, ktlint/detekt/Android Lint/Room schema all green; current-main push run #271 passed at 88ae231d....

Important contract reconciliation

The live issue body still contains the older statement that an automatic timer started near the schedule end should continue for its full duration past the end boundary.

That is no longer the governing repository contract:

  • current PRODUCT_SPEC.md PLAY-008 says the schedule is the eligibility policy and explicitly says a still-running automatic timer is cancelled at the schedule end without pausing playback;
  • it gives the concrete 22:00–07:00 / 15-minute example: playback at 06:46 starts the ordinary 15-minute timer, then the automatic timer is cancelled at 07:00 while playback continues;
  • merged PR #63 states and implements that same rule;
  • AGENTS.md requires work to be driven from PRODUCT_SPEC.md requirement IDs and uses the product spec for Definition of Done.

Therefore the older “automatic timer survives past the end boundary” criterion is classified NO LONGER APPLICABLE under the current repository/product decision. This is issue-text drift, not a current-code implementation defect.

If the intended product behavior is actually to restore the old “survive past end” rule, this acceptance result must be revisited and #33 would need implementation work. Under the current repository authority, however, testing should expect schedule-end cancellation of an automatic timer without pausing playback.

State-model / automated acceptance matrix

  • PROVEN — automated: Disabled — disabled schedule and start==end produce no eligible occurrence.
  • PROVEN — automated: OutsideWindow — same-day and overnight tests cover before/inside/after boundaries.
  • PROVEN — automated: EligibleIdle / transition into eligibility — playback beginning inside an overnight window arms the ordinary configured default timer; already-active playback crossing the start boundary arms it.
  • PROVEN — automated: AutomaticTimerActive — the scheduled timer uses the ordinary SleepTimerController owner and configured default duration; there is no second countdown.
  • PROVEN — automated: current schedule-end contract — an automatic timer near the end is cancelled at the civil end boundary without expiring/pausing playback.
  • PROVEN — automated: ManualTimerActive — a manual timer replaces an automatic timer, does not create schedule suppression, and survives the schedule end.
  • PROVEN — automated: SuppressedForCurrentWindow — manually cancelling an automatic timer prevents immediate rearm; controller recreation retains the suppressed occurrence; the next nightly occurrence clears it and becomes eligible again.
  • PROVEN — automated: natural automatic expiry records replay-required state; passive/lifecycle replay does not rearm, while a later explicit Play inside the same occurrence may create a fresh default timer.
  • PROVEN — automated: timezone eligibility is recomputed from local wall clock.
  • PROVEN — automated: DST forward-gap and backward-overlap behavior is deterministic: gap boundaries resolve to the first valid instant; overlap start uses the earlier instant and overlap end the later instant.
  • PROVEN — repository/product decision: there is no schedule AlarmManager, periodic WorkManager, schedule-only service or second background timer. The live owner uses an in-service coroutine boundary plus TIME_CHANGED / TIMEZONE_CHANGED reconciliation only while playback service ownership exists. Existing WorkManager usage elsewhere is unrelated sync/download infrastructure.
  • PROVEN — automated: #77 integration protects schedule invariants around grace: a claimed automatic grace cannot commit after the occurrence ends; a pre-end valid grace can restart, a post-end shake cannot.
  • PROVEN — automated: manual timer precedence and automatic schedule ownership remain separated.

What remains genuinely physical

JVM/state-machine coverage does not prove Android service recreation, screen-off delivery, real Bluetooth/audio focus, System UI projection or a real accelerometer.

Forgejo Build APK run #272 produced the signed acceptance build:

  • artifact bookwave-debug-0.10.6.1-2272
  • APK bookwave-debug-0.10.6.1-2272.apk
  • package org.homebord.bookwave.debug
  • exact source 88ae231ddc01897d83e24968bed5443ea861aedd
  • signer verified against the configured BookWave keystore
  • build-only workflow; existing verification was not redundantly rerun.

Combined #33 + #77 physical session

Use a short temporary schedule window where practical.

  1. Start playback outside the window → no automatic timer.
  2. Keep playback running across the start boundary → automatic timer starts.
  3. Separately begin playback inside the window → automatic timer starts.
  4. Start playback shortly before window end → confirm the full configured duration is initially armed, then under the current product contract the automatic timer is cancelled at the schedule end while playback continues.
  5. While automatic timer is active, cancel it manually → it must not rearm in the same occurrence.
  6. Recreate activity/playback service/process using the normal device procedure → suppression must still hold.
  7. Reach a distinct next schedule occurrence → it becomes eligible again.
  8. Let an automatic timer expire naturally inside the window; passive restoration must not rearm it, but an explicit Play may.
  9. Verify the active automatic timer appears correctly in Android system media controls via #77.
  10. Repeat representative cases backgrounded/screen-off.
  11. Repeat representative start/cancel/expiry behavior through Bluetooth/headset.
  12. Let a timer expire and shake inside configured grace → playback resumes and same timer mode restarts when the schedule occurrence is still valid.
  13. Shake after grace → nothing happens.
  14. Grace Off → expiry leaves no post-expiry shake effect.
  15. Change Low/Normal/High sensitivity and verify real sensor behavior.
  16. Replace an automatic timer with a manual timer before schedule end → manual timer wins and survives the schedule end.
  17. Relaunch/recreate where feasible and verify current schedule/timer/suppression state reconciles rather than being invented anew.

Physical classifications:

  • STILL REQUIRES PHYSICAL TEST: boundary crossing and start-inside behavior on a real running playback service.
  • STILL REQUIRES PHYSICAL TEST: manual-cancel suppression across actual service/process recreation.
  • STILL REQUIRES PHYSICAL TEST: natural-expiry / explicit-replay behavior across real lifecycle transitions.
  • STILL REQUIRES PHYSICAL TEST: background/screen-off and Bluetooth/headset behavior.
  • STILL REQUIRES PHYSICAL TEST: system-media presentation and real-sensor grace behavior, shared with #77.
  • PROVEN — automated: DST forward/backward semantics; do not disturb a personal device merely to manufacture a DST transition.
  • PROVEN — automated: pure timezone/window calculation. A live timezone/wall-clock spot check is useful if convenient, but is not being made a gating replacement for the deterministic policy tests.

If #36 interrupts the physical session, record that as an external #36 blocker/observation rather than calling the schedule itself failed unless its own state contract is wrong.

Result

READY FOR PHYSICAL ACCEPTANCE

## Canonical acceptance staging — 2026-09-24 **Reviewed main / acceptance APK source:** `88ae231ddc01897d83e24968bed5443ea861aedd` **Merged implementation:** PR #63, accepted head `b0075a00f88b9868dafb30f8cd859d700e8e7410`, merge commit `0182520b5945fc82671b6e3c1da0056273398f66`. **Exact-head CI:** Forgejo run #156 / backend run 158 — all PR jobs green, including `verifyDebug`. **Current-main regression evidence:** later PR #89 exact head passed run #270 with `verifyDebug`, **2606 tests / 0 failures**, ktlint/detekt/Android Lint/Room schema all green; current-main push run #271 passed at `88ae231d...`. ### Important contract reconciliation The live issue body still contains the older statement that an automatic timer started near the schedule end should continue for its full duration past the end boundary. That is no longer the governing repository contract: - current `PRODUCT_SPEC.md` PLAY-008 says the schedule is the eligibility policy **and explicitly says a still-running automatic timer is cancelled at the schedule end without pausing playback**; - it gives the concrete 22:00–07:00 / 15-minute example: playback at 06:46 starts the ordinary 15-minute timer, then the automatic timer is cancelled at 07:00 while playback continues; - merged PR #63 states and implements that same rule; - `AGENTS.md` requires work to be driven from `PRODUCT_SPEC.md` requirement IDs and uses the product spec for Definition of Done. Therefore the older “automatic timer survives past the end boundary” criterion is classified **NO LONGER APPLICABLE** under the current repository/product decision. This is issue-text drift, not a current-code implementation defect. If the intended product behavior is actually to restore the old “survive past end” rule, this acceptance result must be revisited and #33 would need implementation work. Under the current repository authority, however, testing should expect schedule-end cancellation of an automatic timer without pausing playback. ### State-model / automated acceptance matrix - **PROVEN — automated:** **Disabled** — disabled schedule and start==end produce no eligible occurrence. - **PROVEN — automated:** **OutsideWindow** — same-day and overnight tests cover before/inside/after boundaries. - **PROVEN — automated:** **EligibleIdle / transition into eligibility** — playback beginning inside an overnight window arms the ordinary configured default timer; already-active playback crossing the start boundary arms it. - **PROVEN — automated:** **AutomaticTimerActive** — the scheduled timer uses the ordinary `SleepTimerController` owner and configured default duration; there is no second countdown. - **PROVEN — automated:** current schedule-end contract — an automatic timer near the end is cancelled at the civil end boundary without expiring/pausing playback. - **PROVEN — automated:** **ManualTimerActive** — a manual timer replaces an automatic timer, does not create schedule suppression, and survives the schedule end. - **PROVEN — automated:** **SuppressedForCurrentWindow** — manually cancelling an automatic timer prevents immediate rearm; controller recreation retains the suppressed occurrence; the next nightly occurrence clears it and becomes eligible again. - **PROVEN — automated:** natural automatic expiry records replay-required state; passive/lifecycle replay does not rearm, while a later explicit Play inside the same occurrence may create a fresh default timer. - **PROVEN — automated:** timezone eligibility is recomputed from local wall clock. - **PROVEN — automated:** DST forward-gap and backward-overlap behavior is deterministic: gap boundaries resolve to the first valid instant; overlap start uses the earlier instant and overlap end the later instant. - **PROVEN — repository/product decision:** there is no schedule AlarmManager, periodic WorkManager, schedule-only service or second background timer. The live owner uses an in-service coroutine boundary plus `TIME_CHANGED` / `TIMEZONE_CHANGED` reconciliation only while playback service ownership exists. Existing WorkManager usage elsewhere is unrelated sync/download infrastructure. - **PROVEN — automated:** #77 integration protects schedule invariants around grace: a claimed automatic grace cannot commit after the occurrence ends; a pre-end valid grace can restart, a post-end shake cannot. - **PROVEN — automated:** manual timer precedence and automatic schedule ownership remain separated. ### What remains genuinely physical JVM/state-machine coverage does not prove Android service recreation, screen-off delivery, real Bluetooth/audio focus, System UI projection or a real accelerometer. Forgejo **Build APK run #272** produced the signed acceptance build: - artifact `bookwave-debug-0.10.6.1-2272` - APK `bookwave-debug-0.10.6.1-2272.apk` - package `org.homebord.bookwave.debug` - exact source `88ae231ddc01897d83e24968bed5443ea861aedd` - signer verified against the configured BookWave keystore - build-only workflow; existing verification was not redundantly rerun. ### Combined #33 + #77 physical session Use a short temporary schedule window where practical. 1. Start playback **outside** the window → no automatic timer. 2. Keep playback running across the start boundary → automatic timer starts. 3. Separately begin playback **inside** the window → automatic timer starts. 4. Start playback shortly before window end → confirm the full configured duration is initially armed, then under the **current product contract** the automatic timer is cancelled at the schedule end while playback continues. 5. While automatic timer is active, cancel it manually → it must not rearm in the same occurrence. 6. Recreate activity/playback service/process using the normal device procedure → suppression must still hold. 7. Reach a distinct next schedule occurrence → it becomes eligible again. 8. Let an automatic timer expire naturally inside the window; passive restoration must not rearm it, but an explicit Play may. 9. Verify the active automatic timer appears correctly in Android system media controls via #77. 10. Repeat representative cases backgrounded/screen-off. 11. Repeat representative start/cancel/expiry behavior through Bluetooth/headset. 12. Let a timer expire and shake **inside** configured grace → playback resumes and same timer mode restarts when the schedule occurrence is still valid. 13. Shake **after** grace → nothing happens. 14. Grace Off → expiry leaves no post-expiry shake effect. 15. Change Low/Normal/High sensitivity and verify real sensor behavior. 16. Replace an automatic timer with a manual timer before schedule end → manual timer wins and survives the schedule end. 17. Relaunch/recreate where feasible and verify current schedule/timer/suppression state reconciles rather than being invented anew. Physical classifications: - **STILL REQUIRES PHYSICAL TEST:** boundary crossing and start-inside behavior on a real running playback service. - **STILL REQUIRES PHYSICAL TEST:** manual-cancel suppression across actual service/process recreation. - **STILL REQUIRES PHYSICAL TEST:** natural-expiry / explicit-replay behavior across real lifecycle transitions. - **STILL REQUIRES PHYSICAL TEST:** background/screen-off and Bluetooth/headset behavior. - **STILL REQUIRES PHYSICAL TEST:** system-media presentation and real-sensor grace behavior, shared with #77. - **PROVEN — automated:** DST forward/backward semantics; do not disturb a personal device merely to manufacture a DST transition. - **PROVEN — automated:** pure timezone/window calculation. A live timezone/wall-clock spot check is useful if convenient, but is not being made a gating replacement for the deterministic policy tests. If #36 interrupts the physical session, record that as an external #36 blocker/observation rather than calling the schedule itself failed unless its own state contract is wrong. ## Result **READY FOR PHYSICAL ACCEPTANCE**
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#33
No description provided.