Fix shake-to-extend sleep timer lifecycle #58

Merged
alexander merged 8 commits from mcp/issue-7-shake-sleep-timer into main 2026-09-19 10:14:19 +02:00
Owner

Closes #7

Root cause

The motion listener was already owned outside Compose: SleepTimerController is process-singleton state attached by PlaybackService, and ShakeDetector uses the application SensorManager. The failure was in settings/lifecycle reconciliation.

The controller checked its cached shakeToRestart value only once when a timer started. If the persisted settings flow's first value arrived after that start, sensing stayed disabled for the entire timer. Likewise, changing shake-to-extend while a timer was active did not start/stop the listener until another timer.

Change

  • add a narrow ShakeSource seam around the existing application-context sensor implementation;
  • derive registration from exactly two facts: a timer is active and shake-to-extend is enabled;
  • collect settings and reconcile sensing on the timer's main dispatcher;
  • make reconciliation idempotent so repeated emissions/shakes do not re-register;
  • preserve the existing single timer owner and existing shake restart/extension semantics;
  • stop sensing immediately when the timer ends or the setting is disabled.

No wake lock, polling loop, second service, or second timer/state machine is added.

Automated coverage

SleepTimerControllerTest covers:

  • late settings delivery while a timer is already active;
  • active-timer state update after a shake;
  • repeated shakes without duplicate timer sessions or listener registration;
  • disabled/no-timer behavior;
  • setting enable/disable reconciliation;
  • cancellation teardown and Idle UI/domain state.

Android lifecycle evidence

Android's sensor guidance recommends receiving continuous sensor events while foreground or from a foreground service on Android 9+. BookWave's existing playback service is already the correct lifecycle owner while playback is active, so this change does not add another service or keep the CPU awake.

Device acceptance still required

Real accelerometer behavior is not claimed by JVM tests. Verify a deliberate shake with playback + active timer in:

  1. app foreground;
  2. app background with playback continuing;
  3. screen off while playback continues;
    then cancel the timer and confirm further shakes do nothing.
Closes #7 ## Root cause The motion listener was already owned outside Compose: `SleepTimerController` is process-singleton state attached by `PlaybackService`, and `ShakeDetector` uses the application SensorManager. The failure was in settings/lifecycle reconciliation. The controller checked its cached `shakeToRestart` value only once when a timer started. If the persisted settings flow's first value arrived after that start, sensing stayed disabled for the entire timer. Likewise, changing shake-to-extend while a timer was active did not start/stop the listener until another timer. ## Change - add a narrow `ShakeSource` seam around the existing application-context sensor implementation; - derive registration from exactly two facts: a timer is active and shake-to-extend is enabled; - collect settings and reconcile sensing on the timer's main dispatcher; - make reconciliation idempotent so repeated emissions/shakes do not re-register; - preserve the existing single timer owner and existing shake restart/extension semantics; - stop sensing immediately when the timer ends or the setting is disabled. No wake lock, polling loop, second service, or second timer/state machine is added. ## Automated coverage `SleepTimerControllerTest` covers: - late settings delivery while a timer is already active; - active-timer state update after a shake; - repeated shakes without duplicate timer sessions or listener registration; - disabled/no-timer behavior; - setting enable/disable reconciliation; - cancellation teardown and Idle UI/domain state. ## Android lifecycle evidence Android's sensor guidance recommends receiving continuous sensor events while foreground or from a foreground service on Android 9+. BookWave's existing playback service is already the correct lifecycle owner while playback is active, so this change does not add another service or keep the CPU awake. ## Device acceptance still required Real accelerometer behavior is not claimed by JVM tests. Verify a deliberate shake with playback + active timer in: 1. app foreground; 2. app background with playback continuing; 3. screen off while playback continues; then cancel the timer and confirm further shakes do nothing.
Author
Owner

Final implementation-owner status

  • Exact head: f5d49d932b19bece0af60af322a455c4911f199b
  • Forgejo Actions: success, pull-request workflow run #90 (run id 92)
  • Full verifyDebug: BUILD SUCCESSFUL
  • :playback:testDebugUnitTest and :playback:verifyDebug: passed
  • PR remains mergeable; not merged.

Root cause: the accelerometer was already service/process-owned, not Compose-owned. The controller made a one-time decision from the cached shake setting when a timer started. A late DataStore emission, or a setting change during an active timer, was never reconciled, leaving sensing disabled (or stale) for that timer.

The fix makes registration a derived, idempotent property of timer active && shake enabled on the timer's main dispatcher, reusing the existing single timer and existing restart behavior.

Outstanding physical-device acceptance:

  1. Enable shake-to-extend, play an audiobook, start a visible fixed sleep timer.
  2. Foreground: let time visibly elapse, perform one deliberate shake, confirm remaining time returns to the timer's configured length and no second timer appears.
  3. Repeat a deliberate shake after the detector's quiet period; confirm predictable repeated restart/extension.
  4. Background the app while playback continues; repeat and verify the timer updates when returning to the UI.
  5. Turn the screen off while playback continues; shake, wake the device, and verify the timer was extended/restarted.
  6. Disable shake-to-extend during an active timer; confirm further shakes do nothing. Re-enable it during the same active timer and confirm a deliberate shake works.
  7. Cancel the timer; confirm subsequent shakes do nothing.

Actual accelerometer/background/screen-off success remains device-only evidence and is not claimed by the JVM gate.

Final implementation-owner status - Exact head: `f5d49d932b19bece0af60af322a455c4911f199b` - Forgejo Actions: **success**, pull-request workflow run #90 (run id 92) - Full `verifyDebug`: **BUILD SUCCESSFUL** - `:playback:testDebugUnitTest` and `:playback:verifyDebug`: passed - PR remains mergeable; not merged. Root cause: the accelerometer was already service/process-owned, not Compose-owned. The controller made a one-time decision from the cached shake setting when a timer started. A late DataStore emission, or a setting change during an active timer, was never reconciled, leaving sensing disabled (or stale) for that timer. The fix makes registration a derived, idempotent property of `timer active && shake enabled` on the timer's main dispatcher, reusing the existing single timer and existing restart behavior. Outstanding physical-device acceptance: 1. Enable shake-to-extend, play an audiobook, start a visible fixed sleep timer. 2. Foreground: let time visibly elapse, perform one deliberate shake, confirm remaining time returns to the timer's configured length and no second timer appears. 3. Repeat a deliberate shake after the detector's quiet period; confirm predictable repeated restart/extension. 4. Background the app while playback continues; repeat and verify the timer updates when returning to the UI. 5. Turn the screen off while playback continues; shake, wake the device, and verify the timer was extended/restarted. 6. Disable shake-to-extend during an active timer; confirm further shakes do nothing. Re-enable it during the same active timer and confirm a deliberate shake works. 7. Cancel the timer; confirm subsequent shakes do nothing. Actual accelerometer/background/screen-off success remains device-only evidence and is not claimed by the JVM gate.
Author
Owner

Platform acceptance nuance: the implementation correctly keeps shake sensing owned by the existing playback-service lifecycle, which is the right Android boundary for background playback. Screen-off delivery is still device-dependent because SensorManager.getDefaultSensor(TYPE_ACCELEROMETER) is ordinarily a non-wake-up accelerometer; foreground-service ownership alone does not guarantee delivery while the application processor is suspended. This PR intentionally adds no partial wake lock or continuous polling. Physical-device acceptance must therefore explicitly cover screen-off playback. If that case fails on target hardware, treat wake-up/CPU-awake behavior as a measured follow-up rather than adding battery wakeups speculatively.

Platform acceptance nuance: the implementation correctly keeps shake sensing owned by the existing playback-service lifecycle, which is the right Android boundary for background playback. Screen-off delivery is still device-dependent because `SensorManager.getDefaultSensor(TYPE_ACCELEROMETER)` is ordinarily a non-wake-up accelerometer; foreground-service ownership alone does not guarantee delivery while the application processor is suspended. This PR intentionally adds no partial wake lock or continuous polling. Physical-device acceptance must therefore explicitly cover screen-off playback. If that case fails on target hardware, treat wake-up/CPU-awake behavior as a measured follow-up rather than adding battery wakeups speculatively.
alexander force-pushed mcp/issue-7-shake-sleep-timer from f5d49d932b to 5536241169 2026-09-19 10:13:40 +02:00 Compare
alexander deleted branch mcp/issue-7-shake-sleep-timer 2026-09-19 10:14:19 +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!58
No description provided.