180 lines
11 KiB
Markdown
180 lines
11 KiB
Markdown
# Feature Landscape
|
||
|
||
**Domain:** LED Choreography / Music-Synced Light Show Controller
|
||
**Researched:** 2026-04-03
|
||
**Confidence:** MEDIUM — based on xLights, WLED, LedFx, Jinx! analysis; ESP32/Pi-specific constraints from community sources
|
||
|
||
---
|
||
|
||
## Reference Products Surveyed
|
||
|
||
| Product | Model | Relevance |
|
||
|---------|-------|-----------|
|
||
| xLights | Timeline-based sequencer, open source | Direct analog — timeline + audio + multi-model |
|
||
| WLED | ESP32 firmware + web UI | What runs on the ESP side; preset/segment model |
|
||
| LedFx | Network audio-reactive engine | Live reactive reference implementation |
|
||
| Jinx! | LED matrix control, audio/MIDI sync | Beat detection + sound-to-light baseline |
|
||
| VenueMagic | Professional show control | High-end cue-list model |
|
||
|
||
---
|
||
|
||
## Table Stakes
|
||
|
||
Features users expect. Missing = product feels incomplete or unusable.
|
||
|
||
| Feature | Why Expected | Complexity | Notes |
|
||
|---------|--------------|------------|-------|
|
||
| Audio waveform display on timeline | Every LED sequencer shows this; without it, manual timing is blind | Medium | Display audio amplitude/waveform as scrubbing reference |
|
||
| Play / pause / seek | Fundamental transport controls | Low | Must work while animation preview is live on LEDs |
|
||
| Per-zone independent control | Both zones (WS2801 + SK6812) behave differently; single global control frustrates | Low | Two named zones minimum |
|
||
| Block-based timeline editor | xLights, Vixen, and all sequencers use drag-drop blocks on a horizontal track | High | Blocks represent animation events at timestamps |
|
||
| Animation library (built-in effects) | Users expect ready-made animations: chase, pulse, rainbow, strobe, color wash | Medium | At minimum 8–12 distinct named effects per zone |
|
||
| Per-animation parameter config | Speed, color, intensity — parameterization is baseline since Jinx! v1 | Medium | Each effect has configurable fields exposed in sidebar/panel |
|
||
| Save / load choreography files | Without persistence, no session survives a restart | Low | JSON or YAML; portable between sessions |
|
||
| Live reactive mode (beat detection) | Users familiar with WLED/LedFx expect this as a parallel mode | High | System audio capture via PipeWire/PulseAudio; onset/beat detection |
|
||
| Visual feedback of current position | Playhead showing current song position during playback | Low | Mandatory for sequencing work |
|
||
| Loop / repeat control for blocks | Avoids manually placing repeated blocks; xLights, WLED playlists do this | Low | Repeat N times or until next event |
|
||
| Manual timing mark placement | xLights "tapper" workflow: press key on beat to stamp marks | Low | Core ergonomic feature for choreography |
|
||
|
||
---
|
||
|
||
## Differentiators
|
||
|
||
Features that set the product apart. Not universally expected, but create strong value.
|
||
|
||
| Feature | Value Proposition | Complexity | Notes |
|
||
|---------|-------------------|------------|-------|
|
||
| Cyberpunk TUI (Textual, SSH-native) | No existing LED sequencer runs as a terminal UI over SSH; this is genuinely unique | High | xLights/LedFx all require a desktop or browser on the same machine |
|
||
| Dual-mode in one tool (timeline + live reactive) | Most tools are one or the other; switching modes without restarting is rare | High | Unified session state; reactive mode as a layer on top of timeline |
|
||
| Zone-aware beat-reactive routing | Route bass frequencies → Zone A, treble → Zone B | Medium | LedFx does this with virtuals; no TUI equivalent exists |
|
||
| Auto-beat detection timing marks | VAMP-style beat analysis that stamps timing marks automatically, then user refines | High | xLights uses VAMP plugins; librosa or aubio in Python are viable |
|
||
| Streaming audio source (Spotify) | Playing from Spotify while syncing LEDs to it bridges the "my music is streaming" gap | Very High | Requires Spotify Connect or OS audio loopback — treat as stretch goal |
|
||
| Animation preview in-terminal | ASCII/block-character real-time preview of what LEDs will do, without needing to look at physical strip | High | Textual widget, color simulation |
|
||
| Per-block transition effects | Crossfade, cut, dissolve between adjacent animation blocks | Medium | WLED playlists have transition time; xLights has layer blending |
|
||
| Export / import xLights sequences | Import existing xLights .xsq files to reuse community-built shows | Very High | Complex format; defer unless strong demand |
|
||
| Scripted effect language | Jinx!Script-style: define custom animation logic in a mini-DSL | Very High | Not needed for V1; advanced power-user feature |
|
||
| Undo / redo | Timeline editors without undo are painful; all quality DAWs have it | Medium | Required for comfortable editing; Textual app state management |
|
||
|
||
---
|
||
|
||
## Anti-Features
|
||
|
||
Features to deliberately NOT build.
|
||
|
||
| Anti-Feature | Why Avoid | What to Do Instead |
|
||
|--------------|-----------|-------------------|
|
||
| Web UI / browser interface | Contradicts the entire terminal-SSH design; adds a full stack (server, frontend) | SSH + Textual TUI is the whole point |
|
||
| Frame-by-frame pixel streaming from Pi to ESP | WiFi jitter (47ms+ on ESP8266, 12ms on ESP32) makes real-time frame data unreliable; kills bandwidth | ESP executes animations locally; Pi sends only named commands + params |
|
||
| Support for more than one ESP32 | Multiplies coordination complexity exponentially; no hardware for it | Keep single ESP32-C3 as sole controller |
|
||
| Cloud sync / multi-user collaboration | No network dependency is a feature for a local-first tool | Local files only (JSON/YAML) |
|
||
| DMX / E1.31 / sACN protocol support | xLights is already excellent at this; out of hardware scope | JSON-over-WiFi to ESP32 is the transport layer |
|
||
| Mobile app | Out of scope, contradicts SSH-terminal model | Terminal is accessible anywhere SSH works |
|
||
| 2D matrix effects | Hardware is 1D strips; 2D matrix effects (WLED matrix, xLights matrix) are irrelevant | All effects are 1D strip effects |
|
||
| Automatic Spotify token management (OAuth flow) | Extremely complex auth flow through terminal; security risk | If Spotify is implemented, use device auth flow or OS-level audio capture instead |
|
||
|
||
---
|
||
|
||
## Feature Dependencies
|
||
|
||
```
|
||
Audio waveform display ──────────────────> Audio file loading (MP3/FLAC/WAV)
|
||
|
|
||
Manual timing mark placement ──────────────> Audio waveform display
|
||
|
|
||
Auto-beat detection timing marks ──────────> Audio waveform display + librosa/aubio
|
||
|
||
Block-based timeline editor ───────────────> Per-zone independent control
|
||
|
|
||
Per-block transition effects ──────────────> Block-based timeline editor
|
||
|
|
||
Loop / repeat control ─────────────────────> Block-based timeline editor
|
||
|
||
Live reactive mode ────────────────────────> Beat detection (onset/BPM)
|
||
|
|
||
Zone-aware beat-reactive routing ──────────> Live reactive mode + per-zone control
|
||
|
||
Animation library ─────────────────────────> (standalone, no deps)
|
||
|
|
||
Per-animation parameter config ────────────> Animation library
|
||
|
|
||
Animation preview in-terminal ─────────────> Animation library + Per-animation parameter config
|
||
|
||
Save / load choreography ─────────────────> Block-based timeline editor (saves timeline state)
|
||
|
||
Undo / redo ───────────────────────────────> Block-based timeline editor (wraps edit operations)
|
||
|
||
Dual-mode (timeline + live reactive) ─────> Timeline editor + Live reactive mode (both complete first)
|
||
```
|
||
|
||
---
|
||
|
||
## MVP Recommendation
|
||
|
||
Build in this order — each tier unblocks the next:
|
||
|
||
**Tier 1 — Foundation (without this, nothing works):**
|
||
1. Audio file loading and playback (MP3/FLAC/WAV)
|
||
2. Play / pause / seek transport
|
||
3. Per-zone control model (WS2801 + SK6812 as named zones)
|
||
4. Animation library (8–12 built-in effects with parameter config)
|
||
5. Pi → ESP JSON command protocol
|
||
|
||
**Tier 2 — Core Editor (the actual product):**
|
||
6. Audio waveform display in timeline
|
||
7. Block-based timeline editor (place/move/resize/delete animation blocks)
|
||
8. Manual timing mark placement (tapper)
|
||
9. Loop / repeat per block
|
||
10. Save / load choreography (JSON)
|
||
|
||
**Tier 3 — Live Reactive (second major mode):**
|
||
11. System audio capture (PipeWire/PulseAudio)
|
||
12. Beat / onset detection
|
||
13. Live reactive mode (beat → trigger animation)
|
||
|
||
**Tier 4 — Polish (quality of life):**
|
||
14. Undo / redo
|
||
15. Zone-aware beat-reactive routing
|
||
16. Auto-beat detection timing marks (librosa/aubio)
|
||
17. Per-block transition effects
|
||
|
||
**Defer indefinitely:**
|
||
- Spotify integration (very high complexity, unclear if system audio loopback is simpler)
|
||
- Animation preview in-terminal (nice to have, not critical when you have physical LEDs)
|
||
- Export/import xLights sequences
|
||
|
||
---
|
||
|
||
## Key Observations
|
||
|
||
**What xLights does that this tool must do:**
|
||
- Waveform display with zoom and timing marks is non-negotiable for manual sync work
|
||
- Timing tracks with auto-generated beat marks (xLights uses VAMP plugins; Python has `librosa.beat.beat_track`) dramatically speed up choreography
|
||
|
||
**What WLED does that informs ESP firmware design:**
|
||
- Segments = zones; presets = named animation configs; playlists = ordered preset sequences with timing
|
||
- The WLED mental model (preset per zone, triggered by command) closely matches what this project's JSON protocol needs
|
||
|
||
**What LedFx does that informs live reactive mode:**
|
||
- Melbank (mel-scale filterbank) over raw FFT for audio features is the right approach — perceptually uniform frequency buckets
|
||
- Latency target for reactive mode: ~16ms audio-to-LED pipeline (LedFx achieves this)
|
||
- Virtual device layering (effect → post-process → device) is a useful architecture even for two zones
|
||
|
||
**Latency reality check (MEDIUM confidence — community sources):**
|
||
- WiFi jitter on ESP32: ~12ms variance (acceptable for music sync at ~70ms total budget)
|
||
- System audio monitoring buffer latency: 100–300ms (must be accounted for in beat detection offset)
|
||
- Command-based approach (vs frame streaming) sidesteps most latency problems — the animation runs autonomously on ESP, only start/stop/param-change commands cross WiFi
|
||
|
||
---
|
||
|
||
## Sources
|
||
|
||
- xLights Manual (timing tracks, waveform, effects): https://manual.xlights.org/xlights/
|
||
- xLights 2025 release notes: https://xlights.org/2025/
|
||
- WLED segments/presets/playlists: https://kno.wled.ge/features/segments/ and https://kno.wled.ge/features/presets/
|
||
- LedFx documentation: https://docs.ledfx.app/en/latest/
|
||
- LedFx DeepWiki architecture: https://deepwiki.com/LedFx/LedFx
|
||
- Jinx! LED Matrix Control user manual: https://www.hbksaar.de/vorlesungen/details/raumstrategien-mit-kabelgebundenen-farben?file=files/user_accounts/user_46/jinx-usermanual-2.4.pdf
|
||
- DIY WiFi LED sync pitfalls (latency/jitter): https://www.oreateai.com/blog/diy-wifi-light-shows-syncing-your-leds-without-breaking-the-bank/b284c3a86d52b27010cd88fe5646e558
|
||
- WLED audio reactive (WLED MoonModules): https://mm.kno.wled.ge/WLEDSR/Reactive-Animations/
|
||
- ESP32 audio reactive LED strip: https://www.esp32s.com/blog/ultimate-guide-to-building-a-sound-reactive-led-system-with-esp32-and-wled/
|