Table of Contents
er-audio — API Reference
This is the advanced, low-level method of controlling er-audio. For most use cases, we recommend using the dedicated er-audio Node-RED nodes — see Node-RED Integration on the main er-audio page.
The API below is useful for custom integrations, debugging, or when you need fine-grained control beyond what the Node-RED nodes offer.
HTTP REST API served on port 8080. All POST endpoints accept JSON body and return JSON. All GET endpoints return JSON (except /health).
Default media directory: /home/er/media
Health & Status
GET /health
Returns “OK” if the service is running.
GET /api/engine-status
Returns engine status as a plain text string.
Device Discovery
GET /api/devices
Lists all detected audio interfaces (excluding system defaults).
Response:
[ { "alsa_device_string": "dmix_hw_1_0", "display_name": "USB Audio Device" }, { "alsa_device_string": "dmix_hw_2_0", "display_name": "USB Audio Device #2" } ]
Media Files
GET /api/media
Lists all audio files found in the media directory (recursive). Supported extensions: mp3, wav, flac, ogg, m4a, aac, wma, aiff, opus.
Response:
[ {"name": "ambiance/forest.mp3", "path": "/home/er/media/ambiance/forest.mp3"}, {"name": "effects/click.wav", "path": "/home/er/media/effects/click.wav"} ]
Global Volume
GET /api/global/status
Returns the current master volume.
Response:
{"volume": 0.8}
POST /api/global/set-volume
Sets the master volume (applied to all players).
Request:
{"volume": 0.8}
| Field | Type | Range | Description |
|---|---|---|---|
| volume | float | 0.0 – 1.0 | Master volume level |
Response: Same as GET /api/global/status.
Player Management
GET /api/players
Lists all players with their current state.
Response:
[ { "id": "bg-music", "file": "/home/er/media/ambiance/forest.mp3", "device": "dmix_hw_1_0", "state": "playing", "volume": 0.6, "pan": 0.0, "play_mode": "loop", "loop_pause_ms": 0, "fade_in_ms": 0, "fade_out_ms": 0 } ]
Player state values: “playing”, “paused”, “stopped”
Play mode values: “oneshot” (play once, then stop), “loop” (repeat)
POST /api/player/configure
Creates a new player or reconfigures an existing one. If id is empty, a unique ID is generated automatically.
Request:
{ "id": "bg-music", "file": "/home/er/media/ambiance/forest.mp3", "device": "dmix_hw_1_0", "volume": 0.6, "pan": 0.0, "play_mode": "loop", "loop_pause_ms": 0, "fade_in_ms": 0, "fade_out_ms": 0 }
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string | yes | (auto) | Player identifier. Use a meaningful name (e.g. “bg-music”, “door-click”). |
| file | string | yes | — | Full path to the audio file. |
| device | string | yes | — | ALSA device string from /api/devices. |
| volume | float | no | 1.0 | Initial volume (0.0 – 1.0). |
| pan | float | no | 0.0 | Stereo panning (-1.0 left, 0.0 center, 1.0 right). |
| play_mode | string | no | “oneshot” | “oneshot” or “loop”. |
| loop_pause_ms | int | no | 0 | Pause between loops in milliseconds. |
| fade_in_ms | int | no | 0 | Fade-in duration in milliseconds. |
| fade_out_ms | int | no | 0 | Fade-out duration in milliseconds. |
Response: Player object (same format as in GET /api/players).
POST /api/player/play
Starts or resumes playback.
Request:
{"id": "bg-music"}
Response: Player object with updated state.
POST /api/player/pause
Pauses playback. Can be resumed with /play.
Request:
{"id": "bg-music"}
Response: Player object with updated state.
POST /api/player/stop
Stops playback and releases audio resources.
Request:
{"id": "bg-music"}
Response: Player object with updated state.
POST /api/player/remove
Removes a player entirely (stops playback if active).
Request:
{"id": "bg-music"}
Response: HTTP 200 on success, HTTP 404 if player not found.
Dynamic Controls
These can be called at any time during playback — changes take effect immediately.
POST /api/player/set-volume
Adjusts player volume in real time.
Request:
{"id": "bg-music", "volume": 0.3}
| Field | Type | Range | Description |
|---|---|---|---|
| id | string | — | Player identifier |
| volume | float | 0.0 – 1.0 | Volume level (0.0 = silent, 1.0 = full) |
Response: Player object with updated volume.
POST /api/player/set-pan
Adjusts stereo panning in real time.
Request:
{"id": "bg-music", "pan": -0.5}
| Field | Type | Range | Description |
|---|---|---|---|
| id | string | — | Player identifier |
| pan | float | -1.0 – 1.0 | Stereo position (-1.0 = full left, 0.0 = center, 1.0 = full right) |
Response: Player object with updated pan.
Node-RED Integration Example
A typical Node-RED flow for er-audio uses HTTP request nodes:
- Configure — on flow start, create players for each audio zone (POST /api/player/configure)
- Play/Stop — trigger playback from game logic (POST /api/player/play, /stop)
- Dynamic volume — fade music when a hint is playing (POST /api/player/set-volume)
- Panning — shift a sound source as a player moves through the room (POST /api/player/set-pan)
All requests are simple JSON over HTTP — no special libraries or plugins needed. The upcoming Wonder Controlz Node-RED nodes will provide drag-and-drop integration.