[BW-SLEEP-01] Add automatic nightly sleep schedule #33
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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:
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
Behavior
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:
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
Dependencies
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:
Device acceptance
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
Canonical acceptance staging — 2026-09-24
Reviewed main / acceptance APK source:
88ae231ddc01897d83e24968bed5443ea861aeddMerged implementation: PR #63, accepted head
b0075a00f88b9868dafb30f8cd859d700e8e7410, merge commit0182520b5945fc82671b6e3c1da0056273398f66.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 at88ae231d....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:
PRODUCT_SPEC.mdPLAY-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;AGENTS.mdrequires work to be driven fromPRODUCT_SPEC.mdrequirement 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
SleepTimerControllerowner and configured default duration; there is no second countdown.TIME_CHANGED/TIMEZONE_CHANGEDreconciliation only while playback service ownership exists. Existing WorkManager usage elsewhere is unrelated sync/download infrastructure.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:
bookwave-debug-0.10.6.1-2272bookwave-debug-0.10.6.1-2272.apkorg.homebord.bookwave.debug88ae231ddc01897d83e24968bed5443ea861aeddCombined #33 + #77 physical session
Use a short temporary schedule window where practical.
Physical classifications:
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