LedFx: audio-reactive LED effects over a local network, driven by Python

Audio to light in real time: how LedFx converts sound into LED data

LedFx takes a continuous audio stream, analyzes frequency and amplitude using the aubio-ledfx library, and turns those measurements into color and brightness values sent over the local network to LED controllers. Processing happens without a pre-defined sequence. Whatever audio is playing at a given moment shapes the output at that moment.

On Windows, the default source is the system audio output, so anything playing through the speakers feeds the analysis pipeline. On Linux and macOS, directing audio to LedFx requires a separate step; the documentation points to a dedicated settings page for those platforms because they do not expose system audio capture the same way.

Output from that analysis is a data stream sent to one or more LED controllers on the local network. Each controller receives the stream and translates it into electrical signals for the physical strip. LedFx sits between the audio source and the hardware as a software layer; it does not connect to any strip wire directly.

Host machine runs the Python engine while microcontrollers sit at the strip

LedFx does not run on the LED controller. It runs on a separate computer, analyzes audio, and sends timing and color data over the local network to microcontroller boards wired to the strips. A microcontroller acts as the bridge between the network and the physical LED hardware.

A setup table in the README names a specific example combination: a Windows 10 PC running LedFx, an ESP8266 NODEMCU v3 running WLED firmware, and a DC5V WS2812B strip at 60 LED/m rated IP67, powered by a 5V 10-amp supply. Any WLED-compatible ESP8266 or ESP32 board works in that role; the table illustrates one valid configuration rather than setting a minimum requirement.

Physical assembly is a step no software simplifies away. An addressable LED strip, a compatible microcontroller with supported firmware, correct wiring, and a working power supply must all be in place before LedFx can do anything. Assembling the hardware is described in the README as typically the difficult step, with a pointer to the WLED getting-started guide for the wiring and firmware installation.

Getting LedFx running and reaching port 8888

Windows and macOS users are directed to the project's download page for a pre-built executable (LedFx.exe for Windows). On Linux, pip is the install path under the package name ledfx, though system-level dependencies may be needed first; details are in the installation documentation at ledfx.readthedocs.io/en/latest/installing.html.

For anyone building from source or wanting the bleeding-edge version, the README points to the detailed installation instructions page. That path requires a terminal and comfort with dependency management.

Once running, LedFx serves its browser interface at http://127.0.0.1:8888 by default. Adding `--open-ui` to the launch command opens that address automatically in the default browser. Chrome, Edge, Firefox and Safari are the named compatible browsers. A Python version between 3.11 and 3.15 (exclusive) is required, as specified in pyproject.toml under `requires-python = ">=3.11,<3.15"`.

WLED autodiscovery, the Scan button, and the port 8888 control surface

WLED devices on the same Wi-Fi network should appear in LedFx without manual entry. If they do not, a Scan for WLED devices button on the Home screen triggers a new discovery pass. An Add Device option allows manual addition for stubborn cases, and if devices still refuse to appear, the README directs checking that they are powered and on the correct network.

Effect configuration is through the browser interface. First use in the README goes: click a device, select an effect such as scroll under the Classic category, and the strip responds to audio immediately. Live visualization is also available in the interface without needing physical hardware in the room.

A React frontend handles the browser side, visible as the `frontend` entry in the top-level repository layout and served from the running Python process. No documented config file exists for manual editing outside the application.

Device protocols beyond WLED: E1.31, OpenRGB, LIFX, MQTT, MIDI and Twinkly

Repository topics list e131 alongside wled, pointing to sACN (E1.31) protocol support common in stage lighting. Each additional integration has a dedicated library in the production dependencies in pyproject.toml: openrgb-python for OpenRGB-compatible PC RGB components, lifx-async for LIFX smart bulbs, xled for Twinkly LED products, paho-mqtt for MQTT-connected devices, python-rtmidi for MIDI input as an effect trigger, and flux-led for Magic Home and Flux-LED hardware.

Screen capture is another possible input source. Among production dependencies sits mss, a cross-platform screen-capture library, alongside the audio-processing stack, which points to screen content as a driver for effects independent of audio.

For installations that do not need audio reactivity, WLED's own browser interface handles the strip directly without a separate LedFx host. LedFx adds the audio analysis and multi-device routing layer on top of what the firmware provides on its own.

Sentry SDK in the production dependencies without any opt-out documentation

Pyproject.toml lists the following in its standard runtime dependencies, outside the dev group:

"sentry-sdk>=2.0.0",

Sentry is an error monitoring and performance tracking service that can send crash reports and telemetry to its cloud infrastructure. Any standard install of LedFx via pip includes it.

Neither the README nor the project description mentions Sentry, explains what data is collected, or describes how to disable the integration. For a home automation tool that runs continuously and listens to system audio, that gap is worth investigating before deployment in any environment where outbound connections to third-party services are restricted or audited. This entry appears only in pyproject.toml.

Python 3.11 to 3.15 exclusive and platform-conditional dependencies

Pyproject.toml carries an explicit version constraint:

requires-python = ">=3.11,<3.15"

Python 3.11 is the floor; 3.15, when it ships, falls outside the declared range. Any Python environment outside those bounds is not a supported configuration.

Several dependencies are platform-conditional. The rpi-ws281x package installs only on Linux, covering Raspberry Pi GPIO for direct strip control without an ESP device. Two winrt packages (winrt-Windows.Foundation and winrt-Windows.Media.Control) install only on Windows to enable Windows Media session integration for detecting what is currently playing. That conditional structure means dependency resolution produces a different graph on each platform, which matters when troubleshooting a platform-specific install failure.

For the Linux pip path, a virtual environment avoids conflicts with system Python packages. The Windows installer bundles a Python runtime and bypasses version management entirely. The last push to the repository was on 2026-10-06, and source code is under GPL-3.0.

Editorial conclusion

LedFx is the right tool for builders who already have or are willing to assemble a network-connected addressable LED installation and want audio reactivity without writing timing code for individual tracks. Anyone who wants static or manually programmed scenes without a continuously running Python host should look at WLED's own interface instead. Before running LedFx, confirm that Python 3.11 or newer (but below 3.15) is available on the host, that the strip controller runs compatible firmware, and that an outbound connection from the host to Sentry's servers is acceptable in the deployment environment.

Frequently asked questions

Official sources

1. LedFx/LedFx on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases