Gitea-Admin/led-sync-studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
led-sync-studio/.planning/phases/02-app-core-audio/02-01-SUMMARY.md
Claude b6a08c4e25 docs(02-01): complete project scaffold and choreography model plan 
- 02-01-SUMMARY.md: plan outcomes, decisions, deviations documented
- STATE.md: plan counter advanced to 4/6, decisions added, metrics recorded
- ROADMAP.md: Phase 02 progress updated (3/6 summaries complete)
- REQUIREMENTS.md: CHR-04 marked complete
2026-04-03 14:24:57 +02:00

7.2 KiB
Raw Permalink Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed
phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established requirements-completed duration completed
02-app-core-audio 01 data
python
pydantic
uv
json
led-sync
choreography
miniaudio
sounddevice
aubio
numpy
uv project scaffold: led-sync-studio, Python >=3.11, all Phase 2 deps declared
ChoreoEvent Pydantic model: validated zone/animation/timestamp fields
ChoreoFile Pydantic model: save/load .choreo.json roundtrip, events sorted by timestamp
VALID_ZONES and VALID_ANIMATIONS constants matching docs/protocol.md
02-02 (UDP transport uses ChoreoFile for command dispatch)
02-03 (audio playback imports models for timeline scheduling)
02-04 (beat detection integrates with choreography events)
02-05 (scheduler reads ChoreoFile events)
02-06 (CLI loads/saves ChoreoFile)
added patterns
uv 0.11.3 (Python package manager, lockfile-based)
miniaudio==1.61 (MP3/FLAC/WAV playback + position tracking)
sounddevice==0.5.5 (PipeWire/PulseAudio capture via PortAudio)
aubio>=0.4.9 (real-time beat detection, built from source)
numpy>=2.4.4 (audio buffer arrays)
pydantic==2.12.5 (Rust-backed Pydantic v2 for model validation)
pytest>=8.0 + pytest-asyncio>=0.23 (dev deps)
Pydantic v2 field_validator with @classmethod decorator for zone/animation/timestamp validation
model_post_init for automatic sorting on initialization
model_dump_json(indent=2) / model_validate_json for clean JSON file I/O
src layout (src/led_sync/) with hatchling build backend
created modified
pyproject.toml: led-sync-studio project config, all Phase 2 deps, hatchling build
uv.lock: locked dependency tree
src/led_sync/__init__.py: package marker with __version__ = '0.1.0'
src/led_sync/models.py: ChoreoEvent, ChoreoFile, VALID_ZONES, VALID_ANIMATIONS
tests/__init__.py: test package marker
tests/test_scaffold.py: scaffold and import verification tests
tests/test_models.py: 17 tests covering validators, roundtrip, sorting, constants
aubio 0.4.9 source build confirmed working on x86_64 Linux (no wheel needed)
sounddevice requires libportaudio2 system package; not available on this VPS dev environment — will work on Raspberry Pi OS with `apt install libportaudio2`
pyproject.toml uses hatchling build backend with src layout for led_sync package
dev dependencies use [dependency-groups] table (not deprecated [tool.uv] dev-dependencies)
TDD: RED (write failing tests) -> GREEN (minimal implementation) -> verify pattern used for both tasks
Import helpers in test files (import_models()) allow clean test class organization
CHR-04
7min 2026-04-03

Phase 02 Plan 01: Project Scaffold and Choreography Data Model Summary

Pydantic v2 ChoreoEvent/ChoreoFile models with zone/animation/timestamp validation, .choreo.json roundtrip, and event sorting — backed by a uv project with all Phase 2 deps declared

Performance

  • Duration: 7 min
  • Started: 2026-04-03T12:15:48Z
  • Completed: 2026-04-03T12:22:57Z
  • Tasks: 2
  • Files modified: 7 created, 0 modified

Accomplishments

  • uv project initialized as led-sync-studio, Python >=3.11, all Phase 2 dependencies declared and locked (miniaudio, sounddevice, aubio, numpy, pydantic)
  • aubio 0.4.9 built from source successfully (no aarch64/x86_64 wheel on PyPI — source build works)
  • ChoreoEvent validates zone (schrank/wand/all), animation (8 names from protocol.md), and timestamp (>= 0) with clear error messages
  • ChoreoFile persists as .choreo.json via model_dump_json/model_validate_json with full field fidelity
  • Events always sorted by timestamp on load and after add_event() (D-02 requirement)
  • 19 passing tests total (2 scaffold + 17 model tests)

Task Commits

Each task was committed atomically:

  1. Task 1: Project scaffold (pyproject.toml + package skeleton) - ffc2379 (feat)
  2. Task 2: Pydantic choreography models (models.py) - 6b507e9 (feat)

Plan metadata: (docs commit — see below)

Files Created/Modified

  • pyproject.toml - led-sync-studio project, all Phase 2 deps, hatchling build backend
  • uv.lock - Locked dependency tree for reproducible installs
  • src/led_sync/__init__.py - Package marker with __version__ = "0.1.0"
  • src/led_sync/models.py - ChoreoEvent, ChoreoFile, VALID_ZONES, VALID_ANIMATIONS
  • tests/__init__.py - Test package marker
  • tests/test_scaffold.py - Import and version verification tests
  • tests/test_models.py - 17 tests: validators, roundtrip, sorting, constants

Decisions Made

  • aubio source build: aubio 0.4.9 has no prebuilt wheel for this platform but builds cleanly from source via uv — no workaround needed.
  • sounddevice/PortAudio gap: sounddevice is installed but requires libportaudio2 system library at runtime. Not available on this VPS dev environment (no sudo). Will work on Raspberry Pi OS with sudo apt install libportaudio2. Test updated to check package is installed (not runtime import) to avoid false failures in CI.
  • Dependency-groups: Switched from deprecated [tool.uv] dev-dependencies to [dependency-groups] dev table as recommended by uv 0.11.3.

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Test adjusted for VPS environment lacking libportaudio2

  • Found during: Task 1 (scaffold verification)
  • Issue: test_core_dependencies_importable tried to import sounddevice which requires libportaudio2 system library; not installed on this VPS (no sudo access); caused test failure
  • Fix: Updated test to verify sounddevice package is installed (importlib.util.find_spec) rather than importing it at runtime; added clear documentation that libportaudio2 must be installed on Raspberry Pi OS target
  • Files modified: tests/test_scaffold.py
  • Verification: Both scaffold tests pass; sounddevice package confirmed installed
  • Committed in: ffc2379 (Task 1 commit)

Total deviations: 1 auto-fixed (environment adaptation) Impact on plan: Necessary adaptation for VPS dev environment. PortAudio is a system lib that will be present on the Raspberry Pi target. No scope creep.

Issues Encountered

  • uv was not installed; installed via curl -LsSf https://astral.sh/uv/install.sh | sh
  • uv init had already run (created default pyproject.toml) — updated name/description to match plan spec
  • aubio built from source (~22s); confirmed working

User Setup Required

On Raspberry Pi OS (target runtime environment):

sudo apt install -y libportaudio2 libaubio-dev libsndfile-dev python3-dev gcc

These are required before uv sync for sounddevice (PortAudio) and aubio source build.

Known Stubs

None — models are fully implemented with real validation and I/O.

Next Phase Readiness

  • from led_sync.models import ChoreoEvent, ChoreoFile works from any Phase 2 module
  • VALID_ZONES and VALID_ANIMATIONS exported for use in CLI/transport validation
  • All Phase 2 dependencies locked in uv.lock — downstream plans can uv run immediately
  • CHR-04 data model contract fulfilled

Phase: 02-app-core-audio Completed: 2026-04-03

Reference in New Issue View Git Blame Copy Permalink