feat: styles own their ringing tone (simple beeps, blink plays music)

Move audio ownership out of the shared runner and into each style via an
injected Sound capability (play_music(path) / play_beep()). The runner now
only owns button sampling and cleanup; the style kicks off its own tone in
start() and drives the LED.

- simple: a repeating square-wave beep (ordinary alarm-clock tone), no music
  file required. The beep is synthesised in memory as signed-16-bit stereo
  PCM (stdlib array+math) and played via pygame.mixer.Sound — no shipped
  audio asset, no new dependency.
- blink: unchanged behaviour — music on an endless loop from --music-file /
  MUSIC_FILE / the default track, via pygame.mixer.music.
- AlarmStyle contract gains sound + music_file in __init__ and a start()
  lifecycle hook; AlarmSound Protocol documents the audio seam for future
  styles that handle their own tone.
- setup() no longer loads music (that is the style's job now).

README updated: per-style ringing tone, the --music-file note (blink only),
and the extended plugin contract.

tests/test_styles_blink.py

@@ -1,3 +1,5 @@
+from unittest.mock import MagicMock
+
 from styles.blink import (
     STATE_BLINKING,
     STATE_EVALUATING,
@@ -8,23 +10,31 @@ from styles.blink import (
 )
 
 
-def _led():
-    """Return (calls list, set_led callable recording each call)."""
+def _make_blink(music_file="music.mp3"):
+    """Return (style, sound_mock) for a BlinkStyle ready to start."""
+    sound = MagicMock()
+    style = BlinkStyle(lambda on: None, sound, music_file)
+    return style, sound
+
+
+def test_start_plays_music_and_led_off():
     calls = []
-    return calls, lambda on: calls.append(on)
+    sound = MagicMock()
+    style = BlinkStyle(lambda on: calls.append(on), sound, "track.mp3")
+    style.start()
+    sound.play_music.assert_called_once_with("track.mp3")
+    assert calls == [False]  # LED off while music plays until a press starts the puzzle
+    assert style.state == 0  # STATE_RINGING until a press
 
 
 def test_press_starts_puzzle():
-    _, set_led = _led()
-    style = BlinkStyle(set_led)
+    style, _ = _make_blink()
     assert style.update(100.0, True) is True
     assert style.state == STATE_WAIT_BEFORE_BLINK
 
 
 def test_blink_correct_sequence_stops(monkeypatch):
-    _, set_led = _led()
-    style = BlinkStyle(set_led)
-
+    style, _ = _make_blink()
     style.update(100.0, True)  # press -> start puzzle
     assert style.state == STATE_WAIT_BEFORE_BLINK
 
@@ -48,8 +58,7 @@ def test_blink_correct_sequence_stops(monkeypatch):
 
 
 def test_blink_incorrect_retries():
-    _, set_led = _led()
-    style = BlinkStyle(set_led)
+    style, _ = _make_blink()
     style.state = STATE_WAIT_FOR_INPUT
     style.target_blinks = 3
 
@@ -65,8 +74,9 @@ def test_blink_incorrect_retries():
 
 
 def test_blinking_non_blocking():
-    calls, set_led = _led()
-    style = BlinkStyle(set_led)
+    calls = []
+    style, _ = _make_blink()
+    style.set_led = calls.append
     style.state = STATE_BLINKING
     style.target_blinks = 2
 
@@ -84,8 +94,7 @@ def test_blinking_non_blocking():
 
 
 def test_blinking_advances_time():
-    _, set_led = _led()
-    style = BlinkStyle(set_led)
+    style, _ = _make_blink()
     style.state = STATE_BLINKING
     style.target_blinks = 4
 

tests/test_styles_simple.py

@@ -1,23 +1,49 @@
+from unittest.mock import MagicMock
+
 from styles.simple import SimpleStyle
 
 
+def _make_style():
+    sound = MagicMock()
+    style = SimpleStyle(lambda on: None, sound)
+    return style, sound
+
+
 def test_simple_keeps_ringing_when_not_pressed():
-    calls = []
-    style = SimpleStyle(lambda on: calls.append(on))
+    style, _ = _make_style()
     assert style.update(0.0, False) is True
-    assert calls[-1] is True  # LED solid on while ringing
 
 
 def test_simple_stops_on_first_press():
-    calls = []
-    style = SimpleStyle(lambda on: calls.append(on))
+    style, _ = _make_style()
     assert style.update(0.0, True) is False  # press -> stop
 
 
-def test_simple_led_off_on_release_after_press():
-    # After a press the style stops; verify it never turns the LED off itself
-    # (the runner's cleanup handles that). It only ever asserts LED on.
+def test_simple_led_solid_on():
     calls = []
-    style = SimpleStyle(lambda on: calls.append(on))
-    style.update(0.0, False)
+    sound = MagicMock()
+    style = SimpleStyle(lambda on: calls.append(on), sound)
+    style.start()
     assert calls == [True]
+    style.update(0.0, False)
+    assert calls[-1] is True  # stays on every tick
+
+
+def test_simple_beeps_on_interval():
+    style, sound = _make_style()
+    style.start()
+    style.update(100.0, False)  # first tick -> beep
+    assert sound.play_beep.called
+    sound.play_beep.reset_mock()
+    style.update(100.4, False)  # before interval -> no beep
+    assert not sound.play_beep.called
+    style.update(100.5, False)  # at interval -> beep
+    assert sound.play_beep.called
+
+
+def test_simple_never_plays_music():
+    style, sound = _make_style()
+    style.start()
+    style.update(0.0, False)
+    style.update(0.0, True)  # press -> stop
+    assert not sound.play_music.called

tests/test_wecker.py

@@ -32,11 +32,14 @@ def test_set_led(mock_gpio):
     mock_gpio.output.assert_called_with(wecker.LED_PIN, mock_gpio.HIGH)
 
 
-@patch("wecker.time.time")
-def test_run_alarm_plays_music(mock_time, mock_gpio, mock_pygame):
-    mock_pygame.mixer.get_init.return_value = True
-    wecker.run_alarm(test_mode=True)
-    assert mock_pygame.mixer.music.play.called
+def test_setup_inits_mixer_and_gpio_not_music(mock_gpio, mock_pygame):
+    wecker.setup()
+    assert mock_pygame.mixer.pre_init.called
+    assert mock_pygame.mixer.init.called
+    assert mock_gpio.setmode.called
+    assert mock_gpio.setup.called
+    # setup() no longer loads music — that is now the style's job.
+    assert not mock_pygame.mixer.music.load.called
 
 
 def test_run_alarm_unknown_style_raises(mock_gpio, mock_pygame):
@@ -47,8 +50,7 @@ def test_run_alarm_unknown_style_raises(mock_gpio, mock_pygame):
 
 
 def test_run_alarm_uses_selected_style(mock_gpio, mock_pygame):
-    """run_alarm looks up the style by name and drives the returned style."""
-    mock_pygame.mixer.get_init.return_value = True
+    """run_alarm looks up the style, injects a Sound, and calls start()."""
     fake = MagicMock()
     fake.update.return_value = True  # keep ringing
     fake_style_cls = MagicMock(return_value=fake)
@@ -57,17 +59,68 @@ def test_run_alarm_uses_selected_style(mock_gpio, mock_pygame):
         wecker.run_alarm(style_name="whatever", test_mode=True)
 
     get_style.assert_called_once_with("whatever")
-    fake_style_cls.assert_called_once_with(wecker.set_led)
+    args = fake_style_cls.call_args.args
+    assert args[0] is wecker.set_led
+    assert isinstance(args[1], wecker.Sound)
+    fake.start.assert_called_once()
     fake.update.assert_called()
 
 
-def test_setup_uses_env_music_file(mock_gpio, mock_pygame, monkeypatch):
-    monkeypatch.setenv("MUSIC_FILE", "/custom/track.mp3")
-    wecker.setup()
-    mock_pygame.mixer.music.load.assert_called_with("/custom/track.mp3")
+def test_run_alarm_default_music_file(mock_gpio, mock_pygame, monkeypatch):
+    monkeypatch.delenv("MUSIC_FILE", raising=False)
+    fake = MagicMock()
+    fake.update.return_value = True
+    fake_style_cls = MagicMock(return_value=fake)
+    with patch("wecker.get_style", return_value=fake_style_cls):
+        wecker.run_alarm(test_mode=True)
+    assert fake_style_cls.call_args.args[2] == wecker.DEFAULT_MUSIC_FILE
 
 
-def test_setup_music_file_argument_overrides_env(mock_gpio, mock_pygame, monkeypatch):
+def test_run_alarm_env_music_file(mock_gpio, mock_pygame, monkeypatch):
     monkeypatch.setenv("MUSIC_FILE", "/env/track.mp3")
-    wecker.setup(music_file="/arg/track.mp3")
-    mock_pygame.mixer.music.load.assert_called_with("/arg/track.mp3")
+    fake = MagicMock()
+    fake.update.return_value = True
+    fake_style_cls = MagicMock(return_value=fake)
+    with patch("wecker.get_style", return_value=fake_style_cls):
+        wecker.run_alarm(test_mode=True)
+    assert fake_style_cls.call_args.args[2] == "/env/track.mp3"
+
+
+def test_run_alarm_music_file_arg_overrides_env(mock_gpio, mock_pygame, monkeypatch):
+    monkeypatch.setenv("MUSIC_FILE", "/env/track.mp3")
+    fake = MagicMock()
+    fake.update.return_value = True
+    fake_style_cls = MagicMock(return_value=fake)
+    with patch("wecker.get_style", return_value=fake_style_cls):
+        wecker.run_alarm(music_file="/arg/track.mp3", test_mode=True)
+    assert fake_style_cls.call_args.args[2] == "/arg/track.mp3"
+
+
+@patch("wecker.time.time")
+def test_run_alarm_blink_plays_music(mock_time, mock_gpio, mock_pygame):
+    """The default (blink) style plays music on an endless loop."""
+    wecker.run_alarm(test_mode=True)
+    assert mock_pygame.mixer.music.play.called
+    assert mock_pygame.mixer.music.play.call_args.args[0] == -1  # endless loop
+
+
+def test_run_alarm_simple_beeps_and_plays_no_music(mock_gpio, mock_pygame):
+    """The simple style beeps and never touches the music stream."""
+    wecker.run_alarm(style_name="simple", test_mode=True)
+    assert mock_pygame.mixer.Sound.return_value.play.called  # beep played
+    assert not mock_pygame.mixer.music.play.called  # no music
+
+
+def test_sound_play_music_loads_and_loops(mock_pygame):
+    s = wecker.Sound()
+    s.play_music("/track.mp3")
+    mock_pygame.mixer.music.load.assert_called_with("/track.mp3")
+    mock_pygame.mixer.music.set_volume.assert_called_with(1.0)
+    mock_pygame.mixer.music.play.assert_called_with(-1)
+
+
+def test_sound_play_beep_plays_buffer(mock_pygame):
+    s = wecker.Sound()
+    s.play_beep()
+    mock_pygame.mixer.Sound.assert_called_once_with(wecker._BEEP_BUFFER)
+    mock_pygame.mixer.Sound.return_value.play.assert_called_once()