Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
BT Speaker Studio is a Flutter-embedded monorepo project designed to transform a Raspberry Pi Zero 2 W into a feature-rich Bluetooth speaker display. The system integrates high-performance audio visualization, real-time hardware control, and a companion mobile interface. The Raspberry Pi serves as the primary display and hardware host, while a smartphone acts as a remote controller via a dedicated WebSocket communication layer.
The project encompasses two primary Flutter applications and a shared core logic package. The Pi-based application manages a live audio visualizer and hardware peripherals like LED rings, while the phone application provides a user interface for managing EQ settings, LED modes, and media playback metadata.
Sources: README.md:1-7, CLAUDE.md:3-6
System Architecture
The project is structured as a Melos monorepo comprising three distinct packages. This architecture ensures code reuse for data models and communication protocols while maintaining separation between the embedded Pi environment and the mobile client environment.
Monorepo Components
| Component | Path | Description |
|---|---|---|
| pi_app | apps/pi_app/ | Flutter application for Raspberry Pi using flutter-pi. Runs a WebSocket server. |
| phone_app | apps/phone_app/ | Flutter companion app for iOS/Android. Acts as a WebSocket client. |
| bt_speaker_core | packages/bt_speaker_core/ | Shared library containing data models and JSON serialization logic. |
Sources: README.md:21-27, CLAUDE.md:8-13, pubspec.yaml:7-11
Data Flow and Communication
The communication between the phone and the Pi is unidirectional (Phone → Pi) in its current implementation. The Pi hosts a WebSocket server on port 8080, which accepts connections from a single phone client.
The Pi application processes incoming JSON messages into typed events using a sealed class hierarchy defined in the core package.
Sources: README.md:29-38, CLAUDE.md:24-28
Hardware Specifications
The system is optimized for low-power ARM hardware, specifically the Raspberry Pi Zero 2 W. The Pi application bypasses standard desktop environment overhead by using flutter-pi with DRM/KMS.
- Processor: Quad-core ARM Cortex-A53 (armv7 32-bit architecture).
- Display: HDMI output rendering the Flutter UI at 30–60 Hz.
- Audio Output: MAX98357A I2S Amplifier (Phase 2).
- Lighting: WS2812B 16-LED Ring connected via GPIO 10 (SPI).
Sources: README.md:11-17, CLAUDE.md:15-18
State Management and Implementation
The project utilizes flutter_bloc for state management, following a BLoC-per-feature pattern. This allows each hardware or UI component to independently react to the WebSocket stream.
Key BLoC Modules
- ConnectionBloc: Manages the lifecycle of the WebSocket server, handling states such as
waitingandconnected. - VisualizerBloc: Handles real-time
BeatData, including FFT frequency bars, BPM, and pulse intensity. - NowPlayingBloc: Manages track metadata including title, artist, album art, and progress.
- EqBloc: Controls audio equalizer settings (bass, mid, treble).
- LedBloc: Controls the LED ring's color and animation mode.
Sources: README.md:40-47, CLAUDE.md:37-43
Specialized Rendering
For high-performance visualization on limited hardware, the VisualizerPainter uses a CustomPainter to draw directly to the Canvas. This approach avoids the overhead of AnimationController by rendering updates at the same rate as incoming WebSocket data (~30–60 Hz).
Sources: README.md:49-52
Technical Configuration
The project uses Melos 7.x for workspace management and requires pubspec workspace resolution.
Development Environment
- SDK: Dart/Flutter SDK ^3.11.5.
- Flutter Version: 3.41.9 stable.
- Build Tooling:
flutterpi_toolfor Pi deployment. - Build Command:
flutterpi_tool build --arch=arm --cpu=generic --release.
Sources: CLAUDE.md:19-22, apps/pi_app/pubspec.yaml:23-25, pubspec.yaml:4-5
Dependency Overview
| Package | Key Dependencies |
|---|---|
| pi_app | bt_speaker_core, flutter_bloc, equatable |
| phone_app | app_links, flutter_secure_storage, http, crypto, url_launcher |
| bt_speaker_core | flutter |
Sources: apps/pi_app/pubspec.yaml:31-37, apps/phone_app/pubspec.yaml:38-48, packages/bt_speaker_core/pubspec.yaml:11-12
Project Roadmap
The development is divided into phases focusing on core infrastructure, UI, and hardware integration.
- Phase 1 (Complete): Pi app BLoC layer and UI implementation (Visualizers, Connection Banners).
- Phase 2 (In Progress): Phone app WebSocket client and UI screens (EQ, LED).
- Phase 3 (Planned): Hardware wiring for WS2812B and audio pipeline integration using
dart_peripheryand I2S components.
Sources: README.md:55-66, CLAUDE.md:58-64
BT Speaker Studio represents a sophisticated integration of Flutter's embedded capabilities and real-time communication. By utilizing a monorepo structure and efficient BLoC-based state management, the project provides a scalable framework for headless hardware control and visualization.