colorchord: turning detected notes into light patterns on LEDs

Notes, not frequency ranges

The README's description of what ColorChord is is unusually compressed: Chromatic Sound to Light Conversion System, it is really that simple.

The distinguishing claim comes next, and it is the whole idea. Unlike so many of the sound responsive systems out there, ColorChord looks at the chromatic properties of the sound. It looks for notes, not ranges. If it hears an E it does not care what octave it is in, it is an E.

The stated consequence is that this provides a good deal more interesting patterns between instruments and music than would be available otherwise. That is the argument, and it is a real one. A band-pass filter bank tells you that energy is present somewhere around 330 Hz. A chromatic detector tells you the note is E, which is a musical fact rather than a spectral fact, and it can therefore distinguish an E played in the bass from an E played on a violin in a way that ranges cannot.

For a light organ, that difference is the difference between the display tracking the performance and the display tracking the volume. For a visualiser reacting to electronic music, it is the difference between something that responds to the chord progression and something that responds to the kick drum.

The project is written in C, its licence is one GitHub cannot classify, and the last push was on 2026-08-17. The tagged releases are v2.0.2 from 2022-10-22 and v2.0.1 from 2021-06-08.

Why version 2 moved everything back to the CPU

The background section explains the rewrite, and the reason is a change of target hardware.

ColorChord has been developed over many years, and ColorChord 2 is now at the alpha stages. It uses the same principles as ColorChord 1, and a brief writeup on that is linked from the project blog. The major difference in ColorChord 2 is the major rewrite to move everything back to the CPU, together with a multitude of algorithmic optimisations to make it possible to run on something other than the brand newest of systems.

Moving back to the CPU is counter to where a lot of real-time signal processing went, so it is worth being precise about the reason. The optimisation work is what makes the CPU path viable, and the point of doing it is to widen the range of hardware the system can run on. A version that assumed a fast desktop could be made to run on a Raspberry Pi, and a version that runs on a Raspberry Pi is a version that can run on a microcontroller with an audio front end.

That connection to the embedded build is the through-line of the project, and it is visible in the repository layout. There is `embeddedcommon/`, `embeddedlinux/`, `embedded8266/`, `embeddedstm32f303/`, `embeddedstm32f407/`, plus `colorchord2/` for the desktop code, and also `attic/`, `docs/`, `experiments/` and a `karaoke/` directory. The attic is the previous generation, and the karaoke directory is a separate application built on the same ideas.

The demonstration videos in the README show the range: ColorChord 2 driving a strip of WS2812 LEDs, a voronoi diagram visualiser running with Mayhem's Dr. Rocker, and the whole thing running on an ESP8266 with websockets.

The embedded build drops floating point from the output path

The embedded version is a different program as much as a smaller one, and the README is clear about the distinction.

There is work on an embedded version of ColorChord which avoids floating point operations anywhere in the output pipeline. The author says he has made efforts to port it to AVRs, but that it does not seem feasible to operate on AVRs without some shifty tricks he would like to avoid, so he retargeted his efforts to 32-bit systems, specifically the STM32F303, the STM32F407, and somehow the ESP8266. ColorChord Embedded uses a different codebase, located in embeddedcommon and distributed among the various embedded folders.

That last point matters for anyone planning a port. The embedded build is not the desktop build with a smaller compiler target, it is a separate implementation sharing some code, and the reason is exactly the floating point constraint. These are 32-bit targets precisely because the author judged AVRs infeasible, and keeping floating point out of the output pipeline is what makes small microcontrollers viable at all.

The build system is also different from the desktop versions, and the README says the build instructions for each supported embedded architecture are in their respective folders. The listed targets are esp8266 with its own README, stm32f303 with its own README, and stm32f407, where the entry says TODO Add readme, so that target is the least documented of the three.

The rest of the README treats the desktop build as the main product and the embedded build as a work in progress, which is the honest ordering.

Building the desktop version on Linux and on Windows

The Linux build is a dependency install, a recursive clone and a make, and the README is explicit that you want colorchord2 rather than the older tree.

From a Linux terminal, use apt-get to install the following packages for Debian, Ubuntu or Mint:

apt-get install build-essential libpulse-dev libasound2-dev libx11-dev libxext-dev libxinerama-dev libusb-1.0-0-dev libudev-dev

The dependency list says a lot about the program. PulseAudio and ALSA development headers for audio capture, X11, Xext and Xinerama for the display output, and libusb plus libudev for the direct USB output path, which is how a controller board gets its colour data without a network round trip.

To get colorchord, clone with submodules:

git clone --recurse-submodules https://github.com/cnlohr/colorchord

The recursive flag is not optional here, since the audio and USB interface pieces live in the submodules. Then move to the build directory, because you really want to be using colorchord2, and compile:

cd colorchord/colorchord2

make

Windows has three supported toolchains and the README explains each with its own catch. With clang, install it, and if you have the Windows SDK you need nothing else; if not, the realistic route is installing Visual Studio Community and selecting the C/C++ Desktop Application development package, because getting the official headers that way is easier than the alternatives. The clang build script outputs to colorchord2/colorchord.exe.

With TCC, the compile script defaults to C:\tcc unless you edit line 17 of colorchord2/windows/compile.bat, and TCC cannot use the Windows SDK, so the unofficial headers are required and are enabled automatically. The README also notes that TCC does not support OpenGL rendering and is limited to software rendering, and suggests the clang method instead if you hit issues.

With MSYS2, you use pacman to set up a MinGW32 toolchain, and there is a specific gotcha: if you see the message about mingw32 existing in the filesystem, you must temporarily rename or relocate the mingw32.exe file at MSYS2's root folder level and restore it afterwards.

Running it, and the output options that are thin

The invocation is a single binary with an optional config file:

./colorchord [config file, by default 'default.conf'] [any additional parameters]

And the configuration is live, which is unusual for this kind of tool. If you edit default.conf while the program is running and resave it, it will use the settings in the newly saved file. So a light show can be adjusted while it is running, and the display is showing the change as it happens, without restarting and losing the beat.

The current state of affairs section is where the honest limits are, and they are worth reading before you plan a build.

ColorChord 2 is designed to run on Linux or Windows. It is not particularly tied to an architecture, but does pretty much need a dedicated FPU to achieve any decent performance.

And the output situation is the weakest part of the project as it stands. There are not very many output options available for it, and the most interesting one used for debugging is a voronoi-diagram-like thing called DisplayShapeDriver. The wording is careful, and it says that the interesting one is a debug visualiser rather than the production path, which means the usual expectation, that this drives a strip of addressable LEDs, is not yet covered by a well documented output driver.

The video evidence in the README shows WS2812 strips and a voronoi diagram running with Mayhem's Dr. Rocker, so the capability exists in some form, but the documentation of the output layer is thin. The `karaoke/` directory at the repository root suggests one concrete application, and the `docs/` directory is where the details would live if they were written down.

For the embedded build, the websocket path shown on the ESP8266 is the interesting one, since it sends colour data over the network to the controller rather than over USB, which is what makes an ESP8266 board a viable target for a lighting rig.

Editorial conclusion

Adopt colorchord if you are building a musical light display and want a detector that understands notes rather than frequency ranges, and pick the embedded build when your controller has no floating point hardware. Do not adopt it if you need a polished, actively developed project with a regular release stream, because the desktop line is described as being at the alpha stages with its newest tagged release from 2022, and check first which output backend you have available, because the README says there are not very many output options and the most interesting one so far is a debug visualiser.

Frequently asked questions

Official sources

1. cnlohr/colorchord on GitHub
2. Issues
3. README
4. Releases