Light Wizard
Turn system audio or a local file into color on WiZ lights. Analysis and light control stay on the Mac and local network.
source on GitHubWhat it does
Light Wizard captures macOS system output through ScreenCaptureKit or decodes one local audio file. It measures volume, bass, mids, treble, spectral onsets, beats, and twelve pitch classes, then maps the result to brightness and color.
With several lights, the strongest notes in a chord are spread across the bulbs and can rotate on each beat. With one light, the chord is blended into one color. Updates are capped at 30 frames per second and small changes are dropped instead of being sent over the network.
- System-output capture without a loopback audio driver.
- MP3, FLAC, WAV, Ogg Vorbis, Ogg Opus, and AAC in MP4 or M4A files.
- Automatic WiZ discovery with explicit IP addresses as a fallback.
- Pitch-based color by default, plus the older drifting-palette mode.
Run
Light Wizard needs macOS 13 or newer, a Rust toolchain, and WiZ lights on the same IPv4 network. Check discovery first; this does not request audio-recording permission.
git clone https://github.com/heptanal/light-wizard.git
cd light-wizard
cargo install --path . --locked
light-wizard --discover-only
light-wizardTo play and visualize a file instead of listening to system output:
light-wizard --audio-file song.flacConfiguration
Run light-wizard --config-wizard for the guided setup. It explains and validates every setting before writing light-wizard.toml. Command-line values can override the file for one run.
--dry-run prints the live analysis without discovering or controlling lights. In file mode the audio still plays, which makes it useful for tuning sensitivity, pitch tracking, and playback delay.
The main controls are sensitivity, brightness range, attack and release time, palette, pitch smoothing, beat response, playback delay, and network frame rate.
Limits
- System-audio mode requires macOS 13+ and Screen & System Audio Recording permission.
- The Mac and WiZ lights need to share an IPv4 LAN. Discovery may be blocked by routers or VPNs; explicit light addresses can be used instead.
- File mode handles one file at a time. There is no playlist, pause, seek, loop, or separate application volume.
- Light commands are fire-and-forget UDP. Playback delay can be tuned, but visible bulb latency cannot be measured automatically.
- Previous light state is restored on a best-effort basis after Ctrl+C or when file playback finishes.