# RCWeb Soundboard

The **RCWeb Soundboard** (`app/soundboard`) is a shared room sound effects board. It is designed for phones, tablets, laptops, kiosks, or shared displays where any participant in the same RCWeb room can trigger sounds for everyone.

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

## Screenshot

![screenshot](screenshot.png "Soundboard App")

## Overview

Soundboard turns each browser in a room into the same set of large sound effect buttons. Pressing a sound button on one device broadcasts a play command to every open `soundboard` app in that room, so all connected browsers attempt to play the same effect.

The app includes bundled sound effects, supports adding new audio files, and can record microphone audio directly in the browser. Added sounds become new buttons on the board and are shared with other room members through RCWeb's file proxy.

## How to use

1. Open `/soundboard/` in a browser.
2. Scan the QR code in the top-right corner to open the same room on another device.
3. Tap any sound effect button to play it on every `soundboard` app in the room.
4. Use **Upload Audio** to add local audio files as new sound buttons.
5. Use **Record** to capture a short sound from the microphone and add it to the board.
6. Use each button's `...` menu to rename or remove a sound.
7. Use **Reset to Defaults** to restore the bundled sound set, or **Clear Board** to remove all buttons.

If the browser blocks audio playback, tap anywhere on that browser once. Browsers usually require a local user gesture before remote audio commands can produce sound.

## Sound board features

- Large touch-friendly sound effect buttons.
- Plays sound commands across every `soundboard` client in the same room.
- Shows a per-button playback progress bar for longer effects.
- Bundles common reaction sounds such as applause, rimshot, sad trombone, wrong buzzer, crickets, scream, explosion, oof, and fart.
- Supports uploaded audio files as new sound buttons.
- Supports microphone recording as new sound buttons.
- Allows renaming and removing any sound, including bundled defaults.
- Shows an in-app confirmation modal before removing a sound.
- Exports and imports board state as JSON.
- Shows unavailable sounds with a faded button and error marker when audio cannot be loaded or played.
- Keeps the QR code visible for quickly adding more controllers or players to the room.

## Uploaded and recorded sounds

Uploaded and recorded sounds are not stored on the RCWeb server. The browser that added the sound keeps the `File` or `Blob` locally and shares it through RCWeb's `/x-file/` proxy.

That means the source browser must stay open while other browsers use those added sounds. If the source browser closes, refreshes, or leaves the room, other clients may no longer be able to load that audio. When this happens, Soundboard fades the affected button and marks it with an error indicator instead of silently failing.

## Room sync

Soundboard is a symmetric RCWeb app: every browser runs the same app and can both control and play sounds. New or reconnected clients request the current board from peers so they can pick up renamed, removed, uploaded, and recorded sounds.

Board edits such as adding, renaming, removing, clearing, resetting, and importing are broadcast to the room. Playback errors are local to each browser, because a sound may be available on one client but unavailable on another.

## 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. Soundboard exposes a small global API and uses `rc.sendFunctionCall()` to broadcast sound playback and board updates to other `soundboard` clients.

Large audio data is not sent through WebSocket messages. Instead, the source browser advertises a proxy URL such as `/x-file/<room>/<client>/<file-id>/<file-name>`. When another browser needs the sound, the RCWeb server asks the source browser for file chunks through `rc.sendFileChunk()`, and the source browser uploads those chunks back to the requester.

## Related app

Soundboard is a single symmetric app. Open the same `/soundboard/?r=<room>` URL on every device that should trigger or hear sounds.