Audio Visualizer Capability
Relevant source files
The following files were used as context for generating this wiki page:
The Audio Visualizer Capability is a core feature of the BT Speaker Studio project, designed to provide a real-time graphical representation of audio data on a Raspberry Pi Zero 2 W display. The system utilizes a Flutter-embedded application (pi_app) that renders high-frequency updates received from a companion phone application via a WebSocket communication layer.
At its high level, the visualizer consumes Fast Fourier Transform (FFT) data, beats per minute (BPM), and audio intensity to drive both an on-screen CustomPainter and a synchronized physical WS2812B LED ring. The system is optimized for low-resource hardware, targeting the armv7 architecture and utilizing flutter-pi for direct DRM/KMS rendering without an X server.
Sources: README.md:1-15, CLAUDE.md:1-20
Architecture and Data Flow
The visualizer architecture follows a unidirectional data flow where the phone app acts as the primary data source and the Raspberry Pi acts as the rendering engine. The Pi app hosts a WebSocket server that listens for BeatData packets.
Communication Flow
The phone app transmits typed JSON messages to the Pi. These messages are parsed into a sealed class hierarchy of events within the pi_app. The VisualizerBloc specifically handles events related to live audio visualization.
The visualizer renders at the WebSocket data rate of approximately 30–60 Hz.
Sources: README.md:38-55, CLAUDE.md:33-40
Visualizer Components
The visualization system is divided into software rendering and hardware synchronization.
Rendering Engine (VisualizerPainter)
The on-screen visualizer uses a CustomPainter to draw frequency bars directly to the Flutter Canvas. To maintain performance on the Pi Zero 2 W's limited hardware, the system avoids intermediate animation controllers, rendering updates immediately as data arrives from the WebSocket stream.
LED Synchronization
In addition to the HDMI output, the visualizer controls a physical WS2812B 16-LED ring wired to GPIO 10 (SPI). The LED ring pulses in synchronization with the BeatData intensity and BPM, providing a multi-sensory feedback loop.
Core Data Structures
The visualization logic relies on shared models defined in the bt_speaker_core package.
| Data Structure | Description | Relevant Fields |
|---|---|---|
BeatData | Primary visualization payload | FFT bars, BPM, Intensity |
LedCommand | Physical lighting control | Mode, Color, Pulse patterns |
Sources: README.md:57-65, CLAUDE.md:12-15, apps/pi_app/pubspec.yaml:32-34
Implementation Details
The system is built using the flutter_bloc state management library, ensuring that the visualization state is isolated from other features like EQ settings or metadata displays.
Block Architecture
- VisualizerBloc: Subscribes to the WebSocket stream, filters for
beatevents, and emits new states containingBeatData. - UI Interaction: The
HomeScreeninpi_appprovides the layout for the visualizer, while aConnectionBannerindicates if the visualizer is currently receiving data from a client.
Build and Deployment
The visualizer must be compiled specifically for the Raspberry Pi hardware to ensure hardware acceleration is utilized correctly via flutter-pi.
- Target CPU: Generic quad-core ARM Cortex-A53.
- Build Command:
flutterpi_tool build --arch=arm --cpu=generic --release - Dependency: The
pi_appdepends onbt_speaker_corefor the sharedBeatDatadefinition.
Sources: CLAUDE.md:22-31, apps/pi_app/pubspec.yaml:27-28, README.md:20-25
Summary
The Audio Visualizer Capability provides high-performance, real-time audio feedback by leveraging a custom Flutter rendering path and a low-latency WebSocket protocol. By offloading audio analysis to a companion phone app and focusing the Raspberry Pi on rendering (HDMI and SPI-based LEDs), the system achieves fluid visualization on resource-constrained embedded hardware.
Sources: README.md:67-75, CLAUDE.md:83-90