products:er-audio [Wonder Controlz]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== er-audio ======

Multi-channel audio playback system for escape rooms. Plays multiple audio files simultaneously across multiple USB audio interfaces connected to a single computer — background music, sound effects, voice cues, and ambient sounds, each on its own speaker, all at the same time.

er-audio can run on the [[glossary#main_pc|Main PC]] alongside Node-RED, or on a dedicated machine accessible over LAN. Additional computers can be added to scale beyond 8 channels.

**Status:** Production.

===== Why Multi-Channel Audio Matters =====

Most escape rooms rely on simple, low-cost audio solutions — small embedded MP3 player modules (such as DFPlayer Mini or JQ6500) with an SD card, triggered by a microcontroller pin. These modules are cheap and easy to wire, but each one plays **one file at a time, in mono, with no network control**. They also introduce a startup delay when triggered, which can make it difficult to synchronize audio with fast-paced events in the room. To get sound in multiple locations, builders place a separate module at each prop — each operating independently, with no coordination, no remote volume control, and no way to mix or layer sounds.

More advanced setups use a dedicated audio board (like the SparkFun Tsunami) that supports polyphonic playback and multiple outputs, but these are still standalone devices with no network API — control happens through hardware triggers or serial commands.

er-audio takes a different approach. It is a software-based audio engine that runs on a standard PC, uses standard USB audio interfaces, and is fully controlled over the network via HTTP API from Node-RED. Each speaker in the room is an independent audio channel:

  * A locked drawer plays a //click// when it opens — only from the speaker inside the drawer
  * Background music plays continuously from ceiling speakers — unaffected by sound effects
  * A voice cue whispers from a hidden speaker in the wall — with its own volume and panning
  * A countdown alarm plays from a specific corner — while everything else keeps running

All of these happen simultaneously, on separate physical speakers, with **dynamic volume and stereo panning control** — adjustable in real time from Node-RED during gameplay.

===== Key Features =====

^ Feature ^ Details ^
| Audio channels | Up to **8 independent outputs** per computer |
| Simultaneous tracks | 16+ tracks to work |
| Dynamic volume | 0.0 to 1.0 per player, adjustable in real time during playback |
| Dynamic stereo panning | -1.0 (left) to 1.0 (right) per player, adjustable in real time |
| Global volume | Master volume control across all players |
| Audio formats | WAV, MP3, OGG, FLAC, AAC, and more |
| Latency | Optimized for low-latency, responsive playback |
| Control | HTTP REST API (GET/POST) |
| Web console | Built-in browser interface for testing and monitoring |

===== How It Works =====

Each audio file is assigned to a **player**. A player is configured with:
  * Which audio file to play
  * Which audio output (speaker / sound card) to use
  * Volume and stereo panning

Multiple players can use the same audio output — they are mixed automatically. Multiple players can also play the same file on different outputs, or different files on the same output.

Node-RED controls everything via simple HTTP requests: configure a player, start playback, adjust volume, stop — all from the game logic flow.

===== Deployment Options =====

==== On the Main PC ====

er-audio runs alongside Node-RED on the same computer. USB audio interfaces are plugged directly into the Main PC. This is the simplest setup — no additional hardware, no network configuration.

==== On a Dedicated Machine ====

For rooms with many audio channels or where the Main PC is already busy, er-audio can run on a separate mini-PC accessible over LAN. Node-RED sends HTTP requests to the remote machine. Multiple machines can be used in parallel — each adding up to 8 channels.

==== As a Standalone Product ====

er-audio works with **any x86 Linux PC** and **any ALSA-compatible USB audio interface**. It is not tied to Wonder Controlz hardware — it can be used independently in any escape room, theater installation, museum, or immersive experience. Licensed per device.

===== Audio Interfaces =====

er-audio uses standard USB audio interfaces — compact, affordable devices available from many manufacturers. No proprietary hardware required.

**Requirements:**
  * USB Audio Class–compliant (standard USB audio — no special drivers needed)
  * ALSA-compatible (supported by Linux out of the box)

**Recommendation:**
  * Dual-core CPU or better for low-latency playback with many simultaneous tracks

===== HTTP API =====

All control happens via HTTP REST on port **8080**. Node-RED uses simple HTTP request nodes to drive playback.

→ **[[products:er-audio-api|Full API reference with request/response examples]]**

Quick overview:

^ Endpoint ^ Method ^ Description ^
| ''/api/devices'' | GET | List detected audio interfaces |
| ''/api/media'' | GET | List audio files |
| ''/api/players'' | GET | List all players with state |
| ''/api/player/configure'' | POST | Create/reconfigure a player |
| ''/api/player/play'' | POST | Start playback |
| ''/api/player/pause'' | POST | Pause |
| ''/api/player/stop'' | POST | Stop |
| ''/api/player/set-volume'' | POST | Set volume (0.0–1.0) |
| ''/api/player/set-pan'' | POST | Set panning (-1.0 to 1.0) |
| ''/api/global/set-volume'' | POST | Set master volume |

===== Node-RED Integration =====

er-audio comes with dedicated Node-RED nodes that make setup as simple as dragging and dropping. No HTTP requests needed — everything is configured visually.

==== er-audio-server (config node) ====

Connection to the er-audio instance. Set the host and port once — all player nodes share this configuration.

==== er-audio-player ====

**One node = one audio track.** Each player node represents a single audio file playing on a specific output device.

**Configuration (in the GUI):**
  * **File** — select from a dropdown populated live from the er-audio media directory
  * **Device** — select from a dropdown of detected audio interfaces
  * **Volume** — slider 0.0 – 1.0
  * **Pan** — slider from L (left) through C (center) to R (right)
  * **Mode** — One Shot (play once) or Loop (repeat)
  * **Auto Init** — if checked, the player is automatically created when the flow deploys or restarts

**Commands** (send as ''msg.payload'' or ''msg.command''):
  * ''start'' / ''play'' — start playback (auto-initializes if needed)
  * ''pause'' — pause (resume with start)
  * ''stop'' — stop and reset to beginning
  * ''reset'' / ''reinit'' — destroy and recreate the player (useful on game reset)
  * ''status'' — query current state

**Runtime overrides** — send ''msg.volume'' or ''msg.pan'' with any command to adjust on the fly during playback.

**Built-in testing** — the node editor panel includes Start, Pause, and Stop buttons for immediate playback testing without deploying the flow. Volume and pan can be adjusted live during testing. The test player is automatically cleaned up when the panel is closed.

**Status indicator** — the node icon shows the current state at a glance: green = playing, yellow = paused, blue = ready, red = error.

===== Web Console =====

er-audio also includes a built-in browser-based console for testing and monitoring. It shows all detected audio interfaces and media files, allows creating players, and provides play/pause/stop controls with volume and panning sliders.

The console is intended for setup and troubleshooting — during normal operation, everything is controlled from Node-RED.

===== Scalability =====

^ Setup ^ Channels ^
| Single Main PC | Up to 8 |
| Main PC + 1 dedicated machine | Up to 16 |
| Main PC + N dedicated machines | Up to 8 × (N+1) |

Each machine runs its own instance of er-audio. Node-RED addresses them by IP — no additional configuration needed.

===== Specifications Summary =====

^ Feature ^ Value ^
| Audio channels | Up to 8 per computer |
| Simultaneous playback | 16+ tracks |
| Per-player controls | Volume, stereo panning |
| Supported formats | WAV, MP3, OGG, FLAC, AAC |
| Control interface | HTTP REST API |
| Web console | Built-in (browser-based) |
| Platform | Any x86 Linux PC |
| Audio hardware | Any ALSA-compatible USB audio interface |
| Network | Runs locally or over LAN |
| Licensing | Per device |