pluriwave/openspec/changes/archive/2026-07-12-native-alarm-ring/specs/native-alarms/spec.md

Delta for native-alarms

Ring audio moves from the Dart/native handoff + STREAM_MUSIC override to one native owner on STREAM_ALARM for the whole ring. System volumes are never written; nothing needs restoring.

ADDED Requirements

Requirement: Sole native ring-audio ownership

PluriWaveAlarmService MUST be the only audio source for the whole ring, on STREAM_ALARM via its own MediaPlayer. No Dart player or second audible source MUST play.

Scenario: Media volume 0 does not silence the ring

Testability: on-device QA (audio routing) + flutter test with fakes

• GIVEN device STREAM_MUSIC volume is 0
• WHEN an alarm fires
• THEN it MUST be audible via the service's STREAM_ALARM player
• AND no Dart audio path (EstadoRadio) MUST run

Scenario: Fire notification posts with no sound

Testability: code-inspection + on-device QA

• GIVEN channel pluriwave_alarm_fire_v3
• WHEN the ringing notification posts
• THEN it MUST carry no sound; the player MUST be the only audible source

Scenario: Three-stage fallback preserved, single fade anchor

Testability: code-inspection + on-device QA

• GIVEN the primary station fails within its timeout
• WHEN the service advances station -> fallback station -> WAV
• THEN whichever stage starts MUST get the same fade curve, anchored at ring start

Requirement: Exponential dB fade-in ceiling

With fadeInSegundos > 0: gainDb = fraction*40-40, curve = 10^(gainDb/20) on a 50ms tick, setVolume(s * curve), s = per-alarm volumen as ceiling. With fadeInSegundos == 0: start directly at s.

Scenario: Fade rises exponentially to the ceiling

Testability: code-inspection (curve formula)

• GIVEN fadeInSegundos > 0, volumen = s
• WHEN the ring starts
• THEN volume at t=0 MUST equal s * 10^(-40/20) (~1% of s), rising every 50ms
• AND volume at t=fadeInSegundos MUST equal exactly s

Scenario: No-fade path starts pop-free

Testability: code-inspection + on-device QA

• GIVEN fadeInSegundos == 0
• WHEN the ring starts
• THEN setVolume(s) MUST be applied before start(), with no pop

Requirement: Manual transient focus; no system volume writes

The service MUST request AUDIOFOCUS_GAIN_TRANSIENT on STREAM_ALARM and abandon it at ring end. setStreamVolume MUST NOT be called on any stream, ever.

Scenario: Focus requested at start, abandoned at end

Testability: code-inspection + on-device QA (dumpsys audio)

• GIVEN the ring is about to start
• WHEN startAlarm runs
• THEN AUDIOFOCUS_GAIN_TRANSIENT MUST be requested on STREAM_ALARM
• AND WHEN the ring ends THEN focus MUST be abandoned

Scenario: Dismiss, snooze, and back tear down with nothing to restore

Testability: on-device QA + flutter test with fakes

• GIVEN an alarm is ringing
• WHEN the user dismisses, snoozes, or triggers back
• THEN the player MUST stop, focus MUST be abandoned, and foreground removed
• AND no setStreamVolume call MUST have occurred for this ring

Requirement: Notification channel migration v2 -> v3

The service MUST create pluriwave_alarm_fire_v3 (no sound) and delete pluriwave_alarm_fire_v2 exactly once, guarded by a migration flag (same pattern as v1->v2).

Scenario: v2 deleted exactly once on upgrade

Testability: code-inspection (migration guard) + on-device QA

• GIVEN a device with pluriwave_alarm_fire_v2 already created
• WHEN the service next ensures its channel
• THEN _v3 MUST be created and _v2 deleted; a re-run MUST be a no-op

Requirement: Ring screen is pure UI

PantallaAlarmaSonando MUST only call EstadoAlarmas.finalizarEjecucion/posponerAlarma from Stop/Snooze/back. It MUST NOT control any audio player or volume/handoff channel. PuertoAlarmasAndroid MUST NOT expose confirmarAudioFlutter, forzarVolumenMediaParaAlarma, or restaurarVolumenMedia.

Scenario: Buttons and back call only EstadoAlarmas

Testability: flutter test with fakes

• GIVEN the ringing screen is displayed
• WHEN Stop, a Snooze option, or back is triggered
• THEN only finalizarEjecucion/posponerAlarma MUST be called
• AND zero calls MUST reach EstadoRadio.audio or a removed channel method

Scenario: Reduced Android port surface

Testability: static/compile-verifiable (Dart analyzer) + flutter test

• GIVEN PuertoAlarmasAndroid and its implementations/fakes
• WHEN inspected after this change
• THEN confirmarAudioFlutter, forzarVolumenMediaParaAlarma, restaurarVolumenMedia MUST NOT exist

REMOVED Requirements

Requirement: Ring-scoped device-volume override

(Reason: STREAM_MUSIC is never overridden now — native rings exclusively on STREAM_ALARM, independent of the media-volume knob. Replaced by "Sole native ring-audio ownership" and "Manual transient focus; no system volume writes" above.)

Requirement: Single fade-in driver across native-to-Flutter handoff

(Reason: the handoff no longer exists; native owns the fade for the whole ring, so only one ramp ever runs. Replaced by "Exponential dB fade-in ceiling" above.)

Non-Functional Notes

• No new user-visible strings; no l10n work required across the 13 supported locales.