Now Playing Metadata
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Now Playing Metadata system is a core feature of the BT Speaker Studio project, responsible for synchronizing and displaying real-time music information across the ecosystem. It enables the companion phone application to transmit track details—such as title, artist, and playback progress—to a Raspberry Pi Zero 2 W acting as a Bluetooth speaker display.
This system facilitates a rich visual experience on the Pi's HDMI display, complementing the live audio visualizer by providing context to the audio being played. The metadata is handled through a shared package architecture, ensuring consistent data structures between the sender (Phone) and the receiver (Pi).
Sources: CLAUDE.md:6-10, README.md:1-5, README.md:27-30
Architecture and Data Flow
The metadata system follows a unidirectional communication model where the phone app acts as the primary data source and the Raspberry Pi serves as the display client.
System Components
| Component | Responsibility |
|---|---|
phone_app | Captures local music metadata and sends JSON-encoded messages via WebSocket. |
bt_speaker_core | Defines the NowPlaying data model and serialization logic used by both apps. |
pi_app | Hosts the WebSocket server, parses incoming metadata, and updates the UI. |
NowPlayingBloc | Manages the state of current track information within the Pi application. |
NowPlayingBar | The UI widget on the Pi that renders track metadata. |
Sources: CLAUDE.md:12-16, CLAUDE.md:23-28, README.md:27-40
Metadata Synchronization Flow
The synchronization process begins on the mobile device and terminates at the Raspberry Pi display. The following diagram illustrates the lifecycle of a metadata update:
The system uses a WebSocket protocol on port 8080. Messages are keyed with a 'type' field, specifically now_playing for metadata updates.
Sources: CLAUDE.md:23-28, README.md:27-35
Data Modeling
The metadata is encapsulated in the NowPlaying model located within the bt_speaker_core package. This shared model ensures that both the Pi and Phone applications interpret the track information identically.
Metadata Schema
While the full implementation of fields is part of the core package, the system is designed to handle the following attributes as evidenced by the UI requirements:
| Field | Description | Purpose |
|---|---|---|
| Title | Name of the current track | Display in NowPlayingBar |
| Artist | Name of the performer/group | Display in NowPlayingBar |
| Album Art | Visual representation of the album | Background or icon in UI |
| Progress | Current playback timestamp | Syncing seek bars or timers |
Sources: CLAUDE.md:15-16, CLAUDE.md:27-28, README.md:37-40
Implementation Details
State Management on Raspberry Pi
The Pi application utilizes flutter_bloc to handle metadata updates. The NowPlayingBloc subscribes to the shared WebSocket event stream. When a message with the type now_playing is received, it is parsed into a typed NowPlayingEvent, which then triggers a state change to update the NowPlayingBar.
Sources: CLAUDE.md:23-28, README.md:36-40
Pi-Specific Rendering
On the Raspberry Pi, metadata is displayed alongside the visualizer. While the visualizer uses a CustomPainter for high-performance rendering (30–60 Hz), the NowPlayingBar typically uses standard Flutter widgets to display text and imagery, as these updates occur less frequently (e.g., on track change or periodic progress updates).
Sources: CLAUDE.md:65-68, README.md:43-46
Conclusion
The Now Playing Metadata system provides the essential link between audio playback and visual feedback in the BT Speaker Studio. By leveraging a shared core library and WebSocket-based communication, the project ensures that track information is synchronized efficiently between the mobile controller and the Raspberry Pi display, allowing for a cohesive user experience.
Sources: CLAUDE.md:7-10, README.md:27-30