Tech Stack Overview
Relevant source files
The following files were used as context for generating this wiki page:
The BT Speaker project is a specialized Flutter-embedded system designed to transform a Raspberry Pi Zero 2 W into a Bluetooth speaker with a synchronized visual display. The architecture leverages a companion mobile application that acts as a remote control, communicating via WebSocket to manage audio visualization, equalizer settings, and peripheral LED lighting.
This overview details the monorepo structure, hardware requirements, communication protocols, and the software frameworks utilized to achieve high-performance rendering on low-power embedded hardware.
Sources: README.md:3-8, CLAUDE.md:3-7
Architecture and Project Structure
The project is organized as a Melos-managed monorepo containing two primary applications and a shared core package. This structure ensures code reuse and strictly typed data exchange between the Pi and the phone.
Monorepo Components
| Component | Directory | Description |
|---|---|---|
| Pi Application | apps/pi_app/ | Flutter app running via flutter-pi to drive HDMI display and LEDs. |
| Phone Application | apps/phone_app/ | Companion iOS/Android app for remote control. |
| Core Package | packages/bt_speaker_core/ | Shared models and serialization logic. |
Sources: README.md:19-25, CLAUDE.md:9-14, pubspec.yaml:9-12
Dependency Graph
The following diagram illustrates the package relationships within the workspace.
The application packages depend on the local bt_speaker_core package via path references.
Sources: apps/pi_app/pubspec.yaml:29-30, apps/phone_app/pubspec.yaml:37-38
Hardware Stack
The system is optimized for specific embedded hardware, utilizing high-performance rendering techniques to maintain visual fluidness on limited resources.
- Computing: Raspberry Pi Zero 2 W (Quad-core ARM Cortex-A53, 512 MB RAM).
- Architecture:
armv7(32-bit). - Display Output: HDMI Display driven via DRM/KMS (Direct Rendering Manager / Kernel Mode Setting), bypassing the X server for better performance.
- Peripherals:
- WS2812B 16-LED Ring (GPIO 10 via SPI).
- MAX98357A I2S Amp (Planned for Phase 2).
Sources: README.md:10-17, CLAUDE.md:16-19
Communication Protocol
The system utilizes a unidirectional WebSocket communication layer where the Pi acts as a server and the phone acts as a specialized remote control client.
Supported Message Types
Communication is based on a typed JSON protocol defined in the core package:
beat: Carries real-time FFT frequency bars, BPM, and intensity.eq: Controls Bass, Mid, and Treble settings.led: Manages LED mode and color commands.now_playing: Transfers track metadata (Title, Artist, Album Art).
Sources: README.md:27-29, CLAUDE.md:23-28
Software and State Management
Frameworks and Tools
- Flutter 3.x: Primary UI framework. The Pi app specifically uses Flutter 3.41.9 stable.
- flutter-pi: A light-weight Flutter engine embedder for Raspberry Pi that does not require a desktop environment.
- flutter_bloc: Utilized for state management, employing a BLoC-per-feature pattern (
ConnectionBloc,VisualizerBloc,LedBloc, etc.). - Melos 7.x: Monorepo management tool for handling workspace-wide tasks like analysis and testing.
Sources: README.md:46-51, CLAUDE.md:20-21, CLAUDE.md:37-38, melos.yaml:1-3
Build and Deployment
The Pi application uses a specialized build tool chain to target the ARM architecture:
# Build command for Pi Zero 2 W
flutterpi_tool build --arch=arm --cpu=generic --release
Sources: CLAUDE.md:21
Shared Data Models
The bt_speaker_core package provides the standardized data structures used across the network boundary.
| Data Structure | Source | Description |
|---|---|---|
BeatData | bt_speaker_core | Encapsulates FFT audio analysis data. |
EqSettings | bt_speaker_core | Stores frequency gain levels. |
LedCommand | bt_speaker_core | Defines peripheral lighting behavior. |
NowPlaying | bt_speaker_core | Metadata for current audio stream. |
Sources: README.md:24, CLAUDE.md:13-14
Summary
The BT Speaker project represents a modern approach to embedded media systems, combining the cross-platform strengths of Flutter with the low-level performance of flutter-pi. By utilizing a Melos-managed monorepo and a strictly defined WebSocket protocol, the system achieves a responsive, decoupled architecture capable of real-time audio visualization and hardware control on minimal ARM hardware.