Flacker

Flacker turns an audio file into a deterministic, editable lighting show. It analyzes audio but never plays it: during a show, an external position source drives a pure absolute-time renderer. The first implementation includes the hardware-independent workflow, a simulated output, and integration boundaries for external players and Philips Hue Entertainment.

Quick start

Python 3.12 or newer and FFmpeg/FFprobe are required.

uv sync --extra dev
uv run flacker examples ./examples
uv run flacker import examples/demo.wav --project ./show-project
uv run flacker analyze ./show-project
uv run flacker generate ./show-project --rig examples/room.json --style examples/restrained.json --seed 42
uv run flacker preview ./show-project --at 3.25 --svg preview.svg
uv run flacker run ./show-project --sync manual --duration 5 --record frames.ndjson

With pip, create a virtual environment and install -e '.[dev]' instead.

flacker examples writes a small synthetic click track and sanitized example rig/style files. Generation and preview never connect to a bridge. The run command uses simulation/recording output until a Hue client implementing the documented HueStreamingClient protocol is supplied by an integration package. The MPRIS, Jellyfin, and Spotify source classes normalize observations from their respective integration clients without coupling those APIs to the runner.

Design guarantees

• All durable JSON uses strict, versioned Pydantic contracts and content hashes.
• Musical time is canonical integer PCM samples and intervals are half-open.
• Rendering is independent of call history, including after seeks.
• Effect ordering and blending are explicit and deterministic.
• Runner delivery is latest-state only and capped at 30 complete frames/second.
• Credentials and device addresses live only in local patches, never portable rigs.

The full rationale and staged hardware plan are in Flacker_Architecture.md.