# RCWeb Radio

The **RCWeb Radio** app (`app/radio`) streams internet radio stations to connected speakers. It is designed to be remote controlled using **RCWeb Radio Control** (`app/radio-c`).

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

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

## Overview

This app turns the browser into a room-controlled live radio. The app plays one online radio stream at a time, shows the selected station name, presents playback status, and displays a QR code for phones to join as controllers.

The app is intentionally simple: it focuses on the current station, the stream status, and the controller join code.

## How to use

1. Open `/radio/` on the browser connected to good speakers.
2. Scan the QR code with a phone, or manually open `/radio-c/?r=<room>` on another browser.
3. Choose a station from the controller app.
4. Use the controller to play, pause, mute, change volume, or show and hide display overlays.

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 online radio streams directly through the browser audio element.
- Shows the selected station name and current playback status.
- Shows a QR code that opens the matching `radio-c` app in the same room.
- Can hide or show the station title, QR code, and stats overlay.
- Supports play and pause commands.
- Supports mute and volume control from the control app.
- Shows diagnostic stats when enabled, including room, player state, volume, station name, and stream URL.

## Multiple viewers

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

When a new viewer opens, it asks active controllers for the current station and display settings. This lets a refreshed or newly opened display rejoin the room without requiring the user to select the station again.

## Radio playback and state

The display keeps the active station, stream URL, playback state, volume, mute state, and overlay state as room state.

The browser audio player does not reliably expose stream bitrate, codec, sample rate, or live ICY metadata to JavaScript. The app therefore treats the selected station name and stream URL as the canonical station information.

## 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 separate RCWeb apps that exchange JavaScript function calls through `comms.js`.

The display app exposes functions for station selection, playback controls, display toggles, audio controls, and state requests. The control app sends commands to `radio!*-c`, which reaches all `radio` viewers in the room while excluding controller apps.

State also flows back the other way. Displays publish snapshots to `radio-c`, allowing controls to show what station is currently selected and what playback state the room is in.

## Related app

Use this app with **RCWeb Radio Controls** (`app/radio-c`).