====== 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 [[products:er-audio#node-red_integration|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:**
<code javascript>
[
  {
    "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"
  }
]
</code>

===== 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:**
<code javascript>
[
  {"name": "ambiance/forest.mp3", "path": "/home/er/media/ambiance/forest.mp3"},
  {"name": "effects/click.wav", "path": "/home/er/media/effects/click.wav"}
]
</code>

===== Global Volume =====

==== GET /api/global/status ====

Returns the current master volume.

**Response:**
<code javascript>
{"volume": 0.8}
</code>

==== POST /api/global/set-volume ====

Sets the master volume (applied to all players).

**Request:**
<code javascript>
{"volume": 0.8}
</code>

^ 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:**
<code javascript>
[
  {
    "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
  }
]
</code>

**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:**
<code javascript>
{
  "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
}
</code>

^ 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:**
<code javascript>
{"id": "bg-music"}
</code>

**Response:** Player object with updated state.

==== POST /api/player/pause ====

Pauses playback. Can be resumed with /play.

**Request:**
<code javascript>
{"id": "bg-music"}
</code>

**Response:** Player object with updated state.

==== POST /api/player/stop ====

Stops playback and releases audio resources.

**Request:**
<code javascript>
{"id": "bg-music"}
</code>

**Response:** Player object with updated state.

==== POST /api/player/remove ====

Removes a player entirely (stops playback if active).

**Request:**
<code javascript>
{"id": "bg-music"}
</code>

**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:**
<code javascript>
{"id": "bg-music", "volume": 0.3}
</code>

^ 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:**
<code javascript>
{"id": "bg-music", "pan": -0.5}
</code>

^ 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.