docs(02-05): complete BeatDetector plan — AUD-03 and AUD-04 fulfilled
- SUMMARY.md: TDD execution documented, deviation noted (module-level time import) - STATE.md: advanced to plan 3/6, 90% progress, decision logged - ROADMAP.md: 5/6 summaries complete for phase 02 - REQUIREMENTS.md: AUD-03 and AUD-04 marked complete
This commit is contained in:
Claude
107
.planning/phases/02-app-core-audio/02-05-SUMMARY.md
Normal file
107
.planning/phases/02-app-core-audio/02-05-SUMMARY.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
phase: 02-app-core-audio
|
||||
plan: "05"
|
||||
subsystem: audio
|
||||
tags: [beat-detection, sounddevice, aubio, asyncio-bridge, threading]
|
||||
dependency_graph:
|
||||
requires:
|
||||
- 02-02 (UDP transport)
|
||||
- 02-03 (AudioPlayer)
|
||||
provides:
|
||||
- BeatDetector class (AUD-03, AUD-04)
|
||||
affects:
|
||||
- 02-06 (CLI integration — will wire BeatDetector to REPL)
|
||||
- Phase 5 (Live Reactive mode — reuses BeatDetector directly)
|
||||
tech_stack:
|
||||
added:
|
||||
- sounddevice 0.5.x (system audio capture via PortAudio/PipeWire)
|
||||
- aubio 0.4.9 (real-time beat detection, C-backed)
|
||||
patterns:
|
||||
- call_soon_threadsafe bridge: audio thread -> asyncio event loop (D-05)
|
||||
- threading.Lock for shared state (beat_count, bpm, last_beat_time)
|
||||
- Double-trigger suppression via monotonic hold timer (200ms)
|
||||
key_files:
|
||||
created:
|
||||
- src/led_sync/audio/beat_detector.py
|
||||
- tests/test_beat_detector.py
|
||||
modified:
|
||||
- src/led_sync/audio/__init__.py
|
||||
decisions:
|
||||
- "D-04 enforced: sounddevice thread is fully independent from asyncio and miniaudio"
|
||||
- "D-05 enforced: call_soon_threadsafe used in _audio_callback — no direct asyncio calls"
|
||||
- "D-06 noted: device=None for PipeWire default; monitor source for loopback capture"
|
||||
- "import time in _audio_callback removed — time import moved to module level for cleanliness"
|
||||
metrics:
|
||||
duration: "~2 minutes"
|
||||
completed: "2026-04-03"
|
||||
tasks_completed: 1
|
||||
files_created: 2
|
||||
files_modified: 1
|
||||
---
|
||||
|
||||
# Phase 2 Plan 5: BeatDetector — Real-Time Beat Detection Summary
|
||||
|
||||
**One-liner:** sounddevice InputStream + aubio.tempo with call_soon_threadsafe bridge into asyncio — AUD-03 and AUD-04 fulfilled.
|
||||
|
||||
## What Was Built
|
||||
|
||||
`BeatDetector` class in `src/led_sync/audio/beat_detector.py` — a real-time beat detection module that:
|
||||
|
||||
1. Opens a `sounddevice.InputStream` at 44100Hz with 512-sample blocks (~11.6ms latency per hop)
|
||||
2. Runs `aubio.tempo` in the OS audio thread callback to detect beats from the audio stream
|
||||
3. Bridges beat events into the asyncio event loop via `loop.call_soon_threadsafe(loop.create_task, on_beat(beat_time))`
|
||||
4. Uses `threading.Lock` for thread-safe `beat_count` and `bpm` properties
|
||||
5. Implements 200ms double-trigger suppression to avoid false positives on strong transients
|
||||
|
||||
## Public API
|
||||
|
||||
```python
|
||||
detector = BeatDetector(loop=asyncio.get_running_loop(), on_beat=my_async_fn)
|
||||
detector.start(device=None) # None = PipeWire default; pass monitor source for loopback
|
||||
detector.stop() # idempotent, no-op if already stopped
|
||||
detector.bpm: float # current aubio BPM estimate
|
||||
detector.beat_count: int # total beats since start
|
||||
```
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- **D-04 boundary:** `_audio_callback` is a pure OS thread function — zero asyncio dependencies
|
||||
- **D-05 bridge:** `call_soon_threadsafe(loop.create_task, on_beat(beat_time))` is the only crossing point
|
||||
- **D-06 PipeWire:** `device=None` selects the PipeWire default input; for system audio loopback, pass the monitor source name (documented in module docstring)
|
||||
- Constants `SAMPLE_RATE=44100`, `HOP_SIZE=512`, `BUF_SIZE=1024` lock in ~11.6ms latency
|
||||
|
||||
## TDD Execution
|
||||
|
||||
- **RED commit:** 3ad5e91 — 14 failing tests covering import, constants, thread safety, asyncio bridge pattern, and ImportError handling
|
||||
- **GREEN commit:** f1af7ba — Implementation passes all 14 tests + 57 total test suite passes
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
**1. [Rule 1 - Bug] Removed `import time as _time` inline import inside callback**
|
||||
- Found during: implementation review
|
||||
- Issue: Plan code sample had `import time as _time` inside `_audio_callback` — importing inside a hot audio callback runs at ~11ms intervals and is poor practice
|
||||
- Fix: Moved `import time` to module-level imports
|
||||
- Files modified: `src/led_sync/audio/beat_detector.py`
|
||||
- Commit: f1af7ba (included in implementation)
|
||||
|
||||
Otherwise, plan executed exactly as specified.
|
||||
|
||||
## Verification Results
|
||||
|
||||
```
|
||||
BeatDetector class OK: latency=11.6ms, all properties accessible
|
||||
57 passed in 2.80s
|
||||
```
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — BeatDetector is fully implemented. `start()` requires a real audio device to test beat detection live; this is documented in the module as expected behavior (Pi hardware required).
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| src/led_sync/audio/beat_detector.py | FOUND |
|
||||
| tests/test_beat_detector.py | FOUND |
|
||||
| Commit 3ad5e91 (TDD RED) | FOUND |
|
||||
| Commit f1af7ba (TDD GREEN) | FOUND |
|
||||
Reference in New Issue
Block a user