FW16 LED Matrix Visualizer
FW16 LED Matrix Visualizer is a real-time PC-audio visualizer and pixel-art animation player for the Framework Laptop 16's dual LED Matrix Input Modules, developed by community member Imdad3456. It talks to the two 9×34 modules directly over serial (no ledmatrixctl calls in the hot loop) for fast, responsive updates, and runs persistently in the background via a system-tray app that survives reboots through a Windows Scheduled Task1. It is Windows 10/11 only and licensed under MIT1.
Features
Audio Visualizer
Captures real Windows system audio via WASAPI loopback and splits it into 18 frequency bars across both panels. Three display modes are available1:
| Mode | Behavior |
|---|---|
| Split spectrum | One 18-bar spectrum — low frequencies on the left panel, high on the right |
| Stereo | Each panel shows its own audio channel's complete spectrum (true L/R separation) |
| Mono | The same spectrum duplicated on both panels |
Live-tunable controls include gain, fall speed, brightness, flip, rotate 90°, centered growth, and mirror (bass-in-the-middle) — all adjustable while running1.
Pixel Hero
A scripted pixel-art scene (hero vs. monster battle, HP bars, a level-up celebration) that spans both panels as one combined 18×34 canvas, looping forever1.
Background Operation
A system-tray app drives the panels persistently, survives reboots (via a Scheduled Task, not a fragile Startup folder shortcut), and auto-recovers if it ever loses the serial ports. Modes can be switched from the tray menu or the GUI without touching hardware or restarting1.
Resilient COM Port Handling
The two identical LED Matrix modules don't reliably keep the same COM port (or even the same USB "location") across reboots. The app identifies each module by its USB serial number where available, and by elimination otherwise, so it finds the correct left/right panel even when Windows renumbers the ports1.
Features Table
| Feature | Details |
|---|---|
| Language | Python, Inno Setup1 |
| Platform | Windows 10/11 only |
| Audio backend | WASAPI loopback (real system audio) |
| Frequency bars | 18 across both panels |
| Audio modes | Split spectrum, Stereo, Mono |
| Animation | Pixel Hero pixel-art scene (18×34) |
| Background runner | Headless system-tray app (pystray) |
| Auto-start | Windows Scheduled Task (survives reboots) |
| COM port resilience | Identifies modules by USB serial number |
| GUI | Tkinter control panel |
| Serial | Direct pyserial (no ledmatrixctl in hot loop) |
| License | MIT1 |
| Stars | 01 |
| Created | July 10, 20261 |
Installation
Download the Installer
- Download
FW16LEDMatrixVisualizer-Setup-*.exefrom the latest release on GitHub. No admin rights are needed to install (only the optional "start at login" checkbox needs admin, prompted via normal Windows UAC)1. - Launch from the Start Menu or Desktop shortcut.
- In the GUI: pick left/right COM ports (Setup → "Refresh ports"), pick a speaker (or use system default), and hit Start.
- Optional: check "Start automatically at Windows login" for persistent background operation.
Build from Source
py -m pip install soundcard pyserial numpy pystray Pillow
python fw16_gui.py
To build the standalone installer1:
py -m pip install pyinstaller
python -m PyInstaller fw16_installer.spec --noconfirm
"C:\path\to\Inno Setup 6\ISCC.exe" installer\fw16_installer.iss
Project Layout
| File | Purpose |
|---|---|
fw16_viz_core.py | Shared DSP, serial protocol, port resolution, settings persistence |
fw16_gui.py | Tkinter control panel |
fw16_background.py | Headless system-tray background runner |
fw16_animations.py | Pixel Hero animation engine |
fw16_pc_audio_visualizer.py | Standalone CLI version of the audio visualizer |
fw16_installer.spec | PyInstaller build spec |
installer/fw16_installer.iss | Inno Setup installer script |
Technical Details
| Detail | Value |
|---|---|
| Language | Python, Inno Setup1 |
| License | MIT1 |
| Platform | Windows 10/11 |
| Audio capture | WASAPI loopback (via soundcard) |
| Display | Two 9×34 LED Matrix modules (RP2040 + IS31FL3741A) |
| Combined canvas | 18×34 (612 LEDs) |
| Serial protocol | Framework magic bytes 0x32 0xAC + command byte + payload2 |
| GUI toolkit | Tkinter |
| Tray | pystray |
| Installer | Inno Setup (NSIS-style) |
| Stars | 01 |
| Created | July 10, 20261 |
Related Projects
| Project | Description |
|---|---|
| Dual LED Matrix Audio Visualizer | Stereo frequency bars across both modules (Nix/Python) |
| fw16-ledvu | PipeWire/CAVA audio visualizer for the LED matrix (Linux) |
| dark-matrix | Full daemon + web UI with an audio-reactive mode |
| fw16-led-matrixd | Cross-platform Rust daemon with image rendering and pair mode |
| fw16-pongwars | Pong Wars game for the FW16 LED Matrix |