API Reference

API Reference

Sonorium provides a REST API for automation and integration. All endpoints are accessible at http://YOUR_HA_IP:8008/api/.

Streams

Get Theme Stream

GET /stream/{theme_id}

Returns an audio/mpeg stream for direct playback.

Get Channel Stream

GET /stream/channel{n}

Returns the audio stream for channel N (1-6).

Example: GET /stream/channel1

---

Status

Get System Status

GET /api/status

Response:

{
  "version": "1.2.0",
  "current_theme": "Tavern",
  "themes": [...],
  "v2_enabled": true,
  "sessions": 2,
  "speaker_groups": 1,
  "channels": 6,
  "active_channels": 1,
  "cycling_sessions": 0
}

---

Sessions (Channels)

List All Sessions

GET /api/sessions

Response:

[
  {
    "id": "abc123",
    "name": "Living Room",
    "theme_id": "uuid-here",
    "preset_id": "calm_evening",
    "volume": 75,
    "is_playing": true,
    "speakers": ["media_player.living_room"],
    "channel_id": 1
  }
]

Create Session

POST /api/sessions
Content-Type: application/json

{
  "name": "My Session",
  "theme_id": "theme-uuid",
  "speakers": ["media_player.living_room", "media_player.kitchen"]
}

Get Session

GET /api/sessions/{session_id}

Update Session

PUT /api/sessions/{session_id}
Content-Type: application/json

{
  "name": "New Name",
  "theme_id": "new-theme-uuid",
  "preset_id": "intense_storm",
  "speakers": ["media_player.bedroom"]
}

Delete Session

DELETE /api/sessions/{session_id}

Play Session

POST /api/sessions/{session_id}/play

Stop Session

POST /api/sessions/{session_id}/stop

Set Session Volume

POST /api/sessions/{session_id}/volume
Content-Type: application/json

{
  "volume": 50
}

Volume range: 0-100

---

Channels

List All Channels

GET /api/channels

Response:

[
  {
    "id": 1,
    "name": "Channel 1",
    "state": "playing",
    "current_theme": "tavern",
    "current_theme_name": "Tavern",
    "client_count": 2,
    "stream_path": "/stream/channel1"
  }
]

---

Themes

List All Themes

GET /api/themes

Response:

[
  {
    "id": "uuid-here",
    "name": "Tavern",
    "folder": "Tavern",
    "total_tracks": 8,
    "enabled_tracks": 8,
    "url": "http://192.168.1.100:8008/stream/tavern",
    "is_favorite": true,
    "categories": ["Fantasy"],
    "icon": "🍺",
    "description": "A night at a medieval inn."
  }
]

Get Theme Details

GET /api/themes/{theme_id}

Refresh Themes

POST /api/themes/refresh

Rescans the audio folder for new/changed themes.

Toggle Favorite

POST /api/themes/{theme_id}/favorite

Export Theme

GET /api/themes/{theme_id}/export

Returns a zip file containing all theme files.

Import Theme

POST /api/themes/import
Content-Type: multipart/form-data

file: <theme.zip>

---

Tracks

Get Theme Tracks

GET /api/themes/{theme_id}/tracks

Response:

{
  "theme_id": "uuid-here",
  "theme_name": "Tavern",
  "short_file_threshold": 15.0,
  "tracks": [
    {
      "name": "fireplace_663",
      "presence": 1.0,
      "muted": false,
      "is_enabled": true,
      "duration_seconds": 16.2,
      "is_short_file": false,
      "volume": 1.0,
      "playback_mode": "auto",
      "seamless_loop": false,
      "exclusive": false
    }
  ]
}

Set Track Presence

PUT /api/themes/{theme_id}/tracks/{track_name}/presence
Content-Type: application/json

{
  "presence": 0.5
}

Set Track Volume

PUT /api/themes/{theme_id}/tracks/{track_name}/volume
Content-Type: application/json

{
  "volume": 0.8
}

Set Track Muted

PUT /api/themes/{theme_id}/tracks/{track_name}/muted
Content-Type: application/json

{
  "muted": true
}

Set Track Playback Mode

PUT /api/themes/{theme_id}/tracks/{track_name}/playback_mode
Content-Type: application/json

{
  "playback_mode": "sparse"
}

Options: auto, continuous, sparse, presence

Set Track Seamless Loop

PUT /api/themes/{theme_id}/tracks/{track_name}/seamless_loop
Content-Type: application/json

{
  "seamless_loop": true
}

Set Track Exclusive

PUT /api/themes/{theme_id}/tracks/{track_name}/exclusive
Content-Type: application/json

{
  "exclusive": true
}

Reset All Tracks

POST /api/themes/{theme_id}/tracks/reset

Resets all tracks to default settings.

Get Track Audio

GET /api/themes/{theme_id}/tracks/{track_name}/audio

Returns the audio file for browser preview.

---

Presets

List Theme Presets

GET /api/themes/{theme_id}/presets

Create Preset

POST /api/themes/{theme_id}/presets
Content-Type: application/json

{
  "name": "My Preset"
}

Load Preset

POST /api/themes/{theme_id}/presets/{preset_id}/load

Update Preset

PUT /api/themes/{theme_id}/presets/{preset_id}

Saves current track settings to the preset.

Delete Preset

DELETE /api/themes/{theme_id}/presets/{preset_id}

Set Default Preset

POST /api/themes/{theme_id}/presets/{preset_id}/default

Export Preset

GET /api/themes/{theme_id}/presets/{preset_id}/export

Returns preset as JSON file.

Import Preset

POST /api/themes/{theme_id}/presets/import
Content-Type: multipart/form-data

file: <preset.json>

---

Speakers

List Speakers

GET /api/speakers

Get Speaker Hierarchy

GET /api/speakers/hierarchy

Returns speakers organized by floor and area.

Refresh Speakers

POST /api/speakers/refresh

---

Speaker Groups

List Groups

GET /api/speaker-groups

Create Group

POST /api/speaker-groups
Content-Type: application/json

{
  "name": "Downstairs",
  "speakers": ["media_player.living_room", "media_player.kitchen"]
}

Update Group

PUT /api/speaker-groups/{group_id}
Content-Type: application/json

{
  "name": "New Name",
  "speakers": [...]
}

Delete Group

DELETE /api/speaker-groups/{group_id}

---

Home Assistant Automation Examples

Start a Session

service: rest_command.sonorium_play
data:
  session_id: "your-session-id"

First, create the REST command in configuration.yaml:

rest_command:
  sonorium_play:
    url: "http://192.168.1.100:8008/api/sessions/{{ session_id }}/play"
    method: POST

Change Theme

rest_command:
  sonorium_set_theme:
    url: "http://192.168.1.100:8008/api/sessions/{{ session_id }}"
    method: PUT
    content_type: "application/json"
    payload: '{"theme_id": "{{ theme_id }}"}'

Adjust Volume

rest_command:
  sonorium_volume:
    url: "http://192.168.1.100:8008/api/sessions/{{ session_id }}/volume"
    method: POST
    content_type: "application/json"
    payload: '{"volume": {{ volume }}}'