# RCWeb Music Player

The **RCWeb Music Player** (`app/music-player`) is the big-screen half of the RCWeb music player. It is designed for a TV, projector, monitor, kiosk browser, or any shared display in an RCWeb room.

![icon](pwa-512x512.png "Music Player App Icon")

## Screenshot
![screenshot](screenshot.png "Music Player App")

## Overview

This app turns the browser into a room-controlled music visualization screen. The display plays audio files, renders a full-screen dynamic visualizer, presents a QR code for phones to join as controllers, and receives playback commands from one or more `music-player-c` apps in the same virtual room.

The viewer is designed to be visually engaging on a large screen: focusing on the audio visualizer, with track metadata, a progress bar, and QR code overlays that can be toggled remotely.

## How to use

1. Open `/music-player/` on the display browser.
2. Scan the QR code with a phone, or manually open `/music-player-c/?r=<room>` on another browser.
3. Select local audio files on the control app to build the queue.
4. Use the phone controls to play, pause, seek, skip, reorder, loop, mute, change volume, or change visualizer styles.
5. Tap the viewer screen to toggle fullscreen.

If the browser blocks automatic audio playback, the display shows an **Enable Audio** button. Pressing it gives the page the local user gesture browsers require before audio playback can start.

## Display features

- Plays audio files directly in the browser.
- Removes queued local files when the controller tab that supplied them disconnects or refreshes.
- Renders a responsive full-screen `audioMotion-analyzer` visualizer with multiple presets (Classic Spectrum, LED Bands, Radial Bloom, etc.).
- Shows a QR code that opens the matching `music-player-c` app in the same room.
- Can hide or show the track title overlay, QR code, and stats overlay.
- Supports play, pause, seeking, previous, and next commands.
- Supports queue playback, item selection, item removal, queue clearing, and playlist reordering.
- Supports loop off, loop playlist, and loop current item.
- Supports mute and volume control from the control app.
- Shows diagnostic stats when enabled, including room, player state, volume, loop mode, queue size, and track details.

## Multiple viewers

Several `music-player` display browsers can run in the same RCWeb room. The control app targets all `music-player` viewers while excluding `music-player-c` clients, so every viewer receives the same commands.

When a new viewer opens, it asks existing viewers and active controllers for the current queue and playback state. This lets a refreshed or newly opened display rejoin the room without forcing users to rebuild the playlist.

## Audio playback and state

The display keeps the active queue, current item, position, loop mode, audio state, and overlay state as room state. 

Common MP3 ID3 tags (title, artist, album, year, track, genre) are read by the controller and shown on the display. Large audio files are streamed from the controller browser through the RCWeb `/x-file/` proxy, meaning the controller tab must remain open while those tracks are playing.

## How RCWeb makes it possible

RCWeb gives every browser tab a room, app name, and client ID, then connects clients in the same room over WebSocket. The display and controller are just separate RCWeb apps that exchange JavaScript function calls through `comms.js`.

The display app exposes functions such as queue updates, playback controls, display toggles, audio controls, visualizer controls, and state requests. The control app sends commands to the target `music-player!*-c`, which reaches all `music-player` viewers in the room while excluding controller apps.

The same mechanism works in reverse: displays publish state snapshots to `music-player-c`, allowing controls to reconstruct the active state of the room.

## Related app

Use this app with **RCWeb Music Player Controls** (`app/music-player-c`).