chore: initialize project — LightSync config and PROJECT.md

.planning/PROJECT.md

@@ -0,0 +1,97 @@
+# LightSync
+
+## What This Is
+
+A Python-based music-to-light synchronization system for a personal LED and effects setup. It provides a web UI with a hacker/terminal aesthetic — dark, monospace, DAW-like — where you load a song, configure animations per device, and either manually place effects on a timeline or trigger automatic synchronization via beat detection and AI analysis. Synchronized shows are saved as JSON and played back live, sending control packets via UDP to microcontrollers that drive the physical lights.
+
+## Core Value
+
+Being able to load a song, build a synchronized light show, and play it back live — with precise control over every effect on every device.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+**UI**
+- [ ] Web app with terminal/hacker aesthetic — dark theme, monospace fonts, no generic SaaS look
+- [ ] Song loading via local file or YouTube URL (via yt-dlp + MPV subprocess)
+- [ ] Audio playback controls: play, pause, seek, position display
+- [ ] Timeline editor: per-device tracks, drag-and-place animation blocks
+- [ ] Animation library panel with configurable parameters (speed, colors, length, etc.)
+- [ ] Manual mode: pause playback, assign animation to timestamp, resume
+
+**Synchronization**
+- [ ] Automatic sync via beat detection (librosa) — snaps animation blocks to beats, drops, tempo changes
+- [ ] AI-assisted sync — optional enhancement step on top of beat detection
+- [ ] Show export/import as JSON (timestamps + animation + params per device)
+
+**Communication**
+- [ ] UDP packet sender — animation + params format for manual-mode effects
+- [ ] UDP frame sender — per-frame RGB pixel data for AI-generated sequences
+- [ ] Device registry: name, type, LED count, target IP, port
+
+**Devices (v1 scope)**
+- [ ] SK6812 support (5m, 300 LEDs, wall strip)
+- [ ] WS2801 support (5m, 160 LEDs, shelf U-turn)
+
+**Architecture**
+- [ ] Modular device abstraction — adding new light systems requires minimal code
+- [ ] Python backend (FastAPI or similar), browser frontend
+- [ ] Microcontroller firmware — deferred to last phase
+
+### Out of Scope
+
+- Multi-user / collaborative editing — single-operator system
+- Cloud sync or remote access — local network only
+- Microcontroller firmware in early phases — build and validate the control system first
+- Real-time audio capture / microphone input — file/URL based playback only (for now)
+
+## Context
+
+- **Hardware**: Windows 11 laptop as the control machine; ESP/Pico/Raspberry Pi 4B as microcontrollers (exact choice TBD — firmware is last phase)
+- **LED strips**: SK6812 RGBW (5m, 300 LEDs) along the wall; WS2801 (5m, 160 LEDs) around a shelf in a U-turn
+- **Future devices**: lasers, fog/dust machines, moving heads — not in v1, but architecture must support them
+- **User background**: Has built Textual TUIs before, prefers the hacker aesthetic; now moving to web for richer interactions while keeping the visual style
+- **Audio source**: MPV via subprocess — supports both local files and YouTube URLs (via yt-dlp integration)
+
+## Constraints
+
+- **Language**: Python for all backend logic — non-negotiable
+- **Audio**: MPV subprocess — enables local + YouTube playback, quality output
+- **Protocol**: UDP for device communication — low latency, fire-and-forget suits LED control
+- **Firmware**: Deferred — MicroPython on ESP/Pico/RPi, developed last after protocol is stable
+- **Platform**: Windows 11 as primary dev/runtime environment
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Web UI over TUI | Richer timeline/DAW interactions (drag-drop, color pickers) while keeping terminal aesthetic via CSS | — Pending |
+| MPV via subprocess for audio | Supports yt-dlp passthrough, high quality, flexible source handling | — Pending |
+| Hybrid UDP protocol | Animation+params for manual mode (low bandwidth), raw frames for AI-generated sequences | — Pending |
+| Beat detection + AI sync | librosa as baseline (offline, reliable), AI as optional enhancement step | — Pending |
+| Firmware last | Validate entire control stack and protocol against a simulator before burning firmware | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-04-05 after initialization*

.planning/config.json

@@ -0,0 +1,36 @@
+{
+  "model_profile": "balanced",
+  "commit_docs": true,
+  "parallelization": true,
+  "search_gitignored": false,
+  "brave_search": false,
+  "firecrawl": false,
+  "exa_search": false,
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "gsd/phase-{phase}-{slug}",
+    "milestone_branch_template": "gsd/{milestone}-{slug}",
+    "quick_branch_template": null
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": false,
+    "verifier": true,
+    "nyquist_validation": false,
+    "auto_advance": true,
+    "node_repair": true,
+    "node_repair_budget": 2,
+    "ui_phase": true,
+    "ui_safety_gate": true,
+    "text_mode": false,
+    "research_before_questions": false,
+    "discuss_mode": "discuss",
+    "skip_discuss": false
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "agent_skills": {},
+  "mode": "yolo",
+  "granularity": "standard"
+}