Phone App Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Phone App Interface serves as the companion controller for the BT Speaker Studio ecosystem. It is a Flutter-based application designed for iOS and Android, acting as a WebSocket client that communicates directly with a Raspberry Pi Zero 2 W host. Its primary purpose is to provide users with a remote interface to manage audio settings, visualizer behavior, and hardware peripherals like LED rings.
Within the project architecture, the phone app is located in apps/phone_app/ and relies on the shared bt_speaker_core package for standardized data models. It facilitates unidirectional communication (in Phase 1) to send commands such as EQ adjustments, LED mode changes, and "now playing" metadata to the speaker display.
Sources: CLAUDE.md:8-12, README.md:20-24
Architecture and Communication
The phone app operates as a client in a client-server relationship with the pi_app. Communication is established over WebSockets on port 8080. The app sends typed JSON messages that are structured based on shared models defined in the core package.
Communication Flow
The following diagram illustrates the unidirectional data flow from the Phone App Interface to the Raspberry Pi hardware:
The phone app transmits data to the Pi, which then handles visual rendering and hardware control.
Sources: CLAUDE.md:25-29, README.md:26-30
Core Features and Data Models
The interface is organized around several key control modules. These modules utilize shared models from bt_speaker_core to ensure message consistency across the monorepo.
| Feature | Description | Shared Model |
|---|---|---|
| EQ Settings | Remote adjustment of Bass, Mid, and Treble frequencies. | EqSettings |
| LED Control | Commands for the WS2812B LED ring (modes and colors). | LedCommand |
| Metadata | Syncing current track info (Title, Artist, Album Art). | NowPlaying |
| Visualizer Sync | Transmission of beat, BPM, and FFT intensity data. | BeatData |
Sources: CLAUDE.md:12-14, README.md:23-25, README.md:32-38
WebSocket Message Types
Messages sent from the phone app include a mandatory type field to allow the server to route events correctly.
beat: Updates related to audio analysis.eq: Changes to the equalizer profile.led: Changes to lighting effects.now_playing: Updates to track metadata.
Sources: CLAUDE.md:28-29
Technical Specifications
Dependencies
The Phone App Interface leverages several specific Flutter and Dart packages to handle storage, networking, and deep linking:
- State Management:
flutter_bloc(v9.1.1) for feature-based state logic. - Networking:
http(v1.2.2) and standard WebSockets. - Storage:
flutter_secure_storage(v9.2.4) for sensitive data. - Deep Linking:
app_links(v6.3.2) for handling external URL schemes. - Core Library: Local path dependency to
../../packages/bt_speaker_core.
Sources: apps/phone_app/pubspec.yaml:35-46
Project Configuration
The application is configured for multiple platforms, including mobile and web, with specific orientations and themes.
# apps/phone_app/pubspec.yaml
name: bt_speaker
version: 1.0.0+1
environment:
sdk: ^3.11.5
flutter:
uses-material-design: true
Sources: apps/phone_app/pubspec.yaml:1-20
For Android, the interface is restricted to specific hardware acceleration and soft input modes to ensure a smooth UI experience while interacting with the visualizer controls.
Sources: apps/phone_app/app/src/main/AndroidManifest.xml:7-15
For Web/PWA, the app defines a specific theme color and orientation:
{
"short_name": "bt_speaker",
"display": "standalone",
"background_color": "#0175C2",
"orientation": "portrait-primary"
}
Sources: apps/phone_app/web/manifest.json:3-10
Implementation Constraints
State Management Patterns
The app follows a BLoC-per-feature pattern. Developers must adhere to the following file structure for new interface features:
lib/features/<feature>/bloc/: Contains the business logic.lib/features/<feature>/widgets/: Contains UI components.
Connection State Naming
A critical hazard exists due to the ConnectionState class existing in both dart:async and flutter/material.dart. The phone app interface must use the following import pattern to avoid conflicts when implementing connection banners:
import 'package:flutter/material.dart' hide ConnectionState;
Sources: CLAUDE.md:32-38
Summary
The Phone App Interface acts as the primary control point for the BT Speaker Studio. By utilizing a WebSocket-based unidirectional communication protocol and shared data models, it provides a responsive experience for managing remote Raspberry Pi hardware. The architecture relies heavily on flutter_bloc for state management and bt_speaker_core for ensuring cross-package type safety.