pluriwave/openspec/changes/alarm-clock-module/proposal.md

Proposal: alarm-clock-module

Intent

Build an Android-first musical alarm system for PluriWave that can wake the user with radio/music while keeping reliable fallbacks and clear Android permission diagnostics.

Scope

• Add a new alarm domain separate from the existing sleep timer.
• Support one-shot and recurrent alarms by weekday.
• Support snooze options: 3, 5, and 10 minutes.
• Support a silent pre-alarm notification 30 minutes before the next occurrence, with an action to skip only that next execution.
• Support vacation ranges and per-alarm soundOnVacation behavior. Default: true.
• Support audio fallback chain: selected station, optional fallback station, bundled internal alarm sounds.
• Add Android native scheduling using AlarmManager/setAlarmClock via MethodChannel.
• Add Flutter UI for listing, editing, enabling/disabling, vacation ranges, and reliability diagnostics.

Out of Scope for MVP

• Cloud sync.
• iOS reliable alarm parity.
• Complex alarm-dismiss challenges.
• Multiple fallback station chains beyond one optional fallback station.
• Full background radio streaming implementation independent from existing audio_service if not needed for MVP.

Rollback Plan

• Alarm functionality is isolated behind new services/models/screens and Android receivers.
• Existing radio playback, timer, favorites, EQ, and recording flows should remain untouched except for navigation entry points.
• If native scheduling causes issues, remove Android manifest receiver/service entries and hide the alarms entry point.

Risks

• Android exact alarms require special permissions on Android 12+ and can be denied by default on Android 14+.
• OEM battery managers may still interfere; app must expose diagnostics and guidance.
• DND bypass requires Notification Policy Access and cannot be silently forced.
• Playing a radio stream at alarm time depends on network; bundled sounds must always be present.