Piano LED Visualizer: a WS2812B strip driven by a Raspberry Pi

Lights that follow the keys, and teach them

Piano LED Visualizer is a project that lets you connect an LED strip to a Raspberry Pi and enhance your piano playing with visual effects. The repository provides instructions for setting up the strip, connecting it to a digital piano, and synchronizing the lighting with your playing, and it adds integration with external software such as Synthesia for a learning experience.

The feature list separates into two things that are often confused. The visual effects half makes the panel behave like a sound visualizer, with lights that react to the music, plus animations for atmosphere. The learning half is more interesting technically: lights above the keys show you which ones to play, which is a direct aid to learning a piece, and the MIDI integration lights the next-to-play keys when you run Synthesia, which is how the project supports practice software rather than replacing it.

The rest of the list is about control and reuse. You can change the colors and the brightness of the lights. You can record your piano songs and then download them or play them directly from the visualizer. You can load MIDI files to see which keys to play, which makes learning a new song straightforward. You can create light sequences to switch between different light settings during a performance, so a piece has a lighting plan rather than one look for its whole duration. And there is a simple web interface to set up and control the lights.

The optional Hat extension is worth calling out, because it changes the shape of the project. There is an extra hat with buttons and a screen for easier control, which turns the setup into a standalone device rather than something you configure over the network each time.

The shopping list, and the power supply warning

The hardware section is the most valuable part of the README for anyone actually building this, and it is candid about what works and what does not.

The essentials are a piano with MIDI or USB output, a MIDI to USB interface if the piano has no USB output, a Raspberry Pi Zero WH, a 16 GB microSD card with Class 10 recommended for faster loading, a USB OTG hub with at least two ports for the piano and for a computer or tablet, a WS2812B LED strip of at least 1.5 m with 144 diodes per metre, a power supply, a female DC 5.5x2.5 mm socket with quick connection, and some wire, 22 to 18 AWG, at least a metre and more if the Pi is placed away from the piano.

The warning is the important line, and it is in bold in the README: make sure the power supply is 5V, and using a power supply with more volts will damage both the LED strip and the Raspberry Pi. The sizing guidance next to it is specific, since 5V 6A is enough to light 172 LEDs at 50% power. That is a rounding of the strip density figure, and it tells you the strip is expected to run a few metres.

The MIDI interface gets its own advice, and it is a warning born of experience. Cheap MIDI interfaces might not work as intended, the author recommends hardware from more known brands, and says they personally use iConnectivity mio.

The optional list is where the build becomes neat rather than functional. A custom 3D printed case is offered with an STL file in the repository, plus a link to the original model on Thingiverse, and there are M2.5 standoffs and screws, a Waveshare LCD TFT of 1.44 inches at 128 by 128 pixels, cable braid, heat shrink bands for insulation and for securing the connections, an aluminium LED profile with a diffuser, or a silica gel alternative, and double sided tape to stick everything onto the piano.

Two optional items point at the software side. A Windows 10 laptop or tablet with Bluetooth is for running Synthesia, and a magnetic or mechanical switch can detect whether the keyboard cover is open or closed, with a separate document covering that.

The total cost, excluding the piano and the tablet, should be 75 to 100 USD. The README discloses that the product links are affiliate links, so the author earns a commission on purchases made through them.

Raspberry Pi OS Lite, and three ways to install

The software preparation is specific about the operating system, and that matters because the LED libraries need the right kernel interfaces.

The recommended system is Raspberry Pi OS Lite, Trixie, which is Debian 13. There is a split for the two families of board. On a Pi Zero or Zero W, you want the Lite 32-bit image on Trixie. On a Pi Zero 2 W or newer, the Lite 64-bit image on Trixie is fine.

The flashing step is where the project saves you the most time, because it asks you to configure the image as you write it. With Raspberry Pi Imager, use the OS customisation option to set the hostname to pianoledvisualizer, enable SSH, set the username to plv and the password to visualizer, and configure Wi-Fi if you need it. The result is that when you boot the Pi, it is already reachable over the network with a known name and credentials, which is the difference between a five minute setup and an afternoon with a keyboard and a TV output.

After that there are three routes, and the README lists them as a system image, autoinstall, or manual setup.

The system image route is the preconfigured option, and the release tags are the system image releases, which is a useful thing to notice. The tags are named after the system image version, v1.6 being the most recent at 2025-03-02, with v1.5.1 as a hotfix from 2023-09-26 and v1.5 from 2023-09-17.

The autoinstall route is a script, and the repository carries two of them, autoinstall.sh and autoinstall_bookworm.sh, the second one named for the Debian Bookworm release, which tells you the project supported both Debian 12 and Debian 13 at the time.

The manual route is for people who want to see what is installed, and it is the route to take if you are combining the visualizer with other software on the same Pi.

The dependency list is the architecture

The requirements file is short enough to read at a glance, and every entry tells you which part of the system it serves.

RPi.GPIO
webcolors~=1.13
psutil~=5.9.5
mido~=1.3.0
pillow~=12.3.0
python-rtmidi
rpi-ws281x~=5.0.0
spidev~=3.5
numpy~=1.22
Flask~=3.1.3
waitress~=3.0.1
websockets~=11.0.3
Werkzeug~=3.1.6

The LED side is rpi-ws281x, which is the library that drives the WS2812B strips, and it needs spidev underneath because the WS2812B protocol is a serial protocol on a SPI pin. RPi.GPIO is there for the general purpose pins, which is what the cover detection switch and the optional hat buttons use.

The MIDI side has two libraries. mido handles MIDI messages at a high level, and python-rtmidi is the real time MIDI backend that talks to the kernel MIDI stack. Having both is a deliberate choice, since mido is convenient for parsing and rt midi is what actually connects to the device, and the project uses Synthesia and a physical piano through the same path.

The web interface is Flask with Werkzeug underneath, and it is served by waitress rather than by the Flask development server, which is the correct choice for something that runs continuously on a Pi. The websockets library is there for the live light state, so the browser interface can reflect what the strip is doing in near real time rather than only sending commands.

The remaining entries are utility libraries with specific jobs. numpy handles the sampling and analysis behind the sound visualisation, Pillow deals with images, including the remote wallpapers and any rendering, webcolors is the colour name to RGB mapping that makes the colour configuration readable, and psutil gives the process and system information the interface displays.

The repository layout matches that split. The main program is visualizer.py, with the supporting code in lib, the web interface in its own webinterface directory, configuration in config, colour maps in Colormaps, recorded songs in Songs, the systemd unit files in systemd, tests in tests, and the documentation, including the cover detection guide and the 3D print model, in Docs.

Learning mode, Synthesia, and what a hat adds

The learning features are the part of this project that other similar projects tend to skip, and they are the reason to build it rather than simply buying a strip and a controller.

The key lighting is per key, which means the strip has to be dense enough to put a diode above each key, and that is where the 144 diodes per metre figure comes from. When you are learning a piece, the lights above the keys show you which ones to play, so the information is spatial rather than a list in a panel, and your eyes stay on the keyboard.

Synthesia support does the same thing from the other direction. Since Synthesia is a learning application that runs on a Windows machine with Bluetooth, the project can take the next-to-play key information from it and light the strip accordingly, so you get the visual feedback on the real keyboard while the software runs on the tablet or laptop.

The record and play feature closes the loop. You record your piano songs, and then you can download them or play them directly from the visualizer, and the MIDI file support means you can load a piece you already have and use the lights to learn it rather than to practise it. Light sequences are the performance layer, letting a piece move between lighting configurations as it goes.

The Hat extension is described as an extra hat with buttons and a screen for easier control, making it a standalone device. In hardware terms that is the Waveshare TFT of 1.44 inches at 128 by 128 pixels from the optional parts list, plus the buttons, mounted on the Pi. The idea is that once it is built, you do not need a browser or a phone to change what the lights are doing, which is the difference between a demonstration and something you would leave on your piano.

The cover detection switch, with its own documentation, is a smaller version of the same idea: the panel knows whether the lid is closed, so it can go to sleep and wake up, rather than lighting up an unused piano all evening.

Cost, licence, and how far the project has moved

The economics of the project are stated plainly, and they are the reason to think twice before building one for every instrument in a studio.

The total cost, excluding the piano and the tablet, should be 75 to 100 USD. The dominant line items are the Raspberry Pi, the LED strip, the power supply, and the MIDI interface, and the strip is the one that scales with the length of the keyboard. Add the optional case, the display hat, and the wiring, and a professional setup for a full sized piano becomes a project rather than a purchase, which is why the README suggests looking for screws, standoffs, and wires in local hardware stores to avoid buying in bulk.

The licence is MIT, and the repository carries the usual files alongside it, a code of conduct, and a documentation folder that includes a features page with images.

On maintenance, the picture is mixed and worth stating accurately. The last push to the repository was on 2026-10-16, so the code is being worked on. The most recent published release, though, is the v1.6 system image from 2025-03-02, with the v1.5.1 hotfix from 2023-09-26 and v1.5 from 2023-09-17 before that. So the source is current and the ready made image is a year and a half old.

That gap is not a criticism of the project so much as a description of what kind of thing it is. A system image is tied to a specific base OS and a specific set of preinstalled packages, and rebuilding it is a maintenance decision rather than an automatic step, so the image lags the code. If you are installing today, the autoinstall script against a current Raspberry Pi OS Lite is the route most likely to give you the current features, and the preconfigured image is the route most likely to give you a working system in ten minutes.

Editorial conclusion

Piano LED Visualizer fits a piano owner with a MIDI or USB output who wants the learning mode, the visual effects, and the Synthesia integration, and who is comfortable wiring a strip, a power supply, and a Raspberry Pi. It does not fit someone who wants a plug and play accessory, since the total hardware is a shopping list of six items and a small amount of soldering. Verify first that your piano can send MIDI or USB output and that your MIDI interface is a known brand, because the README warns that cheap interfaces may not work as intended, that your power supply is exactly 5 volts, since anything more will damage both the strip and the Pi, and that the strip density is at least 144 diodes per metre, which is what the light above each key depends on.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. onlaj/Piano-LED-Visualizer on GitHub
4. README
5. Releases