Euphonium REST API

Every instance of the player exposes a HTTP API, internally used by the web-ui and the web-ide. This API is accessible under the default port.

Warning

This API is not stable yet, and may change in the future. In particular, authentication is not implemented at this moment.

Events

Euphonium's HTTP server exposes a endpoint for receiving live events. The events are sent as JSON objects. This is implemented as a long-lived connection to the /events endpoint. This is used for real time updates in the web ide.

---

Plugins

Manages internal plugins.

---

GET /plugins

Returns list of currently active plugins.

Parameters

This endpoint does not have parameters

Responses

Returns list of plugins

Response type application/json

[
    {
        "type": "plugin",
        "name": "cspot",
        "displayName": "Spotify (cspot)"
    },
    {
        "type": "plugin",
        "name": "webradio",
        "displayName": "WebRadio"
    },
    {
        "type": "app",
        "name": "webradio",
        "displayName": "WebRadio"
    },
]

---

GET /plugins/:pluginName

Returns configuration schema with current values for given plugin.

Parameters

Parameter	type	Description
pluginName	path	string Name of the plugin to retrieve configuration of.

Responses

Returns plugin configuration

Response type application/json. Example of spotify.

{
    "configSchema": {
        "audioBitrate": {
            "value": "160",
            "tooltip": "Audio bitrate",
            "type": "stringList",
            "defaultValue": "160",
            "listValues": [ "96", "160", "320" ]
        },
        "receiverName": {
            "tooltip": "Speaker's name",
            "type": "string",
            "value": "Euphonium (cspot)",
            "defaultValue": "Euphonium (cspot)"
        }
    },
    "themeColor": "#1DB954",
    "displayName": "Spotify (cspot)"
}

POST /plugins/:pluginName

Updates configuration of given plugin schema. This configuration is persisted between reboots.

Parameters

Parameter	type	Description
pluginName	path	string Name of the plugin to retrieve configuration of.
body	body	PluginConfig Content described below.

Requests

Change spotify configuration

Response type application/json.

{
    "audioBitrate": "320",
    "receiverName": "Living room\'s speaker"
}

Responses

Returns plugin configuration

Request type application/json. Example of spotify.

{
    "configSchema": {
        "audioBitrate": {
            "value": "320",
            "tooltip": "Audio bitrate",
            "type": "stringList",
            "defaultValue": "160",
            "listValues": [ "96", "160", "320" ]
        },
        "receiverName": {
            "tooltip": "Speaker's name",
            "type": "string",
            "value": "Living room\'s speaker",
            "defaultValue": "Euphonium (cspot)"
        }
    },
    "themeColor": "#1DB954",
    "displayName": "Spotify (cspot)"
}

Playback

Manages the playback state of the system.

---

GET /playback

Returns complete current state of playback, containing current track, current position, current volume and current eq settings.

Parameters

This endpoint does not have parameters

Responses

Returns current playback state

Response type application/json. Example of spotify.

{
    "song": {
        "icon": "https://i.scdn.co/image/kocz.jpg",
        "songName": "Never Gonna Give You Up",
        "albumName": "Never Gonna Give You Up",
        "sourceName": "cspot",
        "artistName": "Rick Astley",
    },
    "status": "paused",
    "volume": 50,
    "eq": {
        "low": 0,
        "mid": -0.5,
        "high": 0
    }
}

POST /playback/volume

Updates playback current volume.

Parameters

Parameter	type	Description
body	body	Volume Content described below.

Requests

Change volume

Request type application/json. Volume is an integer betwen 0 and 100.

{
    "volume": 100,
}

Responses

Returns current playback state

Response type application/json. Example of spotify.

{
    "song": {
        "icon": "https://i.scdn.co/image/kocz.jpg",
        "songName": "Never Gonna Give You Up",
        "albumName": "Never Gonna Give You Up",
        "sourceName": "cspot",
        "artistName": "Rick Astley",
    },
    "status": "paused",
    "volume": 100,
    "eq": {
        "low": 0,
        "mid": -0.5,
        "high": 0
    }
}

POST /playback/eq

Updates playback current equalizer settings.

Parameters

Parameter	type	Description
body	body	Eq Content described below.

Requests

Change equalizer settings

Request type application/json. Equalizer settings are an object with keys low, mid and high. One value on the scale corresponds to 3 dB.

{
    "low": 1.25,
    "mid": 0,
    "high": 0
}

Responses

Returns current playback state

Response type application/json. Example of spotify.

{
    "song": {
        "icon": "https://i.scdn.co/image/kocz.jpg",
        "songName": "Never Gonna Give You Up",
        "albumName": "Never Gonna Give You Up",
        "sourceName": "cspot",
        "artistName": "Rick Astley",
    },
    "status": "paused",
    "volume": 100,
    "eq": {
        "low": 1.25,
        "mid": 0,
        "high": 0
    }
}

POST /playback/status

Updates playback current playback status.

Parameters

Parameter	type	Description
body	body	Playback Content described below.

Requests

Change playback settings

Request type application/json. Status is either 'playing' or 'paused'

{
    "status": "playing"
}

Responses

Returns current playback state

Response type application/json. Example of spotify.

{
    "song": {
        "icon": "https://i.scdn.co/image/kocz.jpg",
        "songName": "Never Gonna Give You Up",
        "albumName": "Never Gonna Give You Up",
        "sourceName": "cspot",
        "artistName": "Rick Astley",
    },
    "status": "playing",
    "volume": 100,
    "eq": {
        "low": 1.25,
        "mid": 0,
        "high": 0
    }
}

System

Manages the state of the system.

---

GET /system

Returns information about current system state.

Parameters

This endpoint does not have parameters

Responses

Returns current system state

Response type application/json.

{
    "networkState": "online",
    "version": "0.0.14"
}

POST /system/reboot

Returns information about current system state.

Parameters

Calling this endpoint will reboot the system.

Responses

Returns current system state

Response type application/json.

{
    "version": "0.0.14",
    "networkState": "rebooting",
}

WiFi

Manages state of the WiFi connection

---

GET /wifi

Returns current WiFi state.

Parameters

This endpoint does not have parameters

Responses

Returns current WiFi state

Response type application/json. Example of connected to AP.

{
    "state": "connected",
    "ipAddress": "192.168.254.103"
}

POST /wifi/connect

Connects to WiFi network.

Parameters

Parameter	type	Description
body	body	WiFiSettings Content described below.

Requests

WiFi network parameters

Request type application/json.

{
    "ssid": "RandomNetwork",
    "password": "Test123"
}

Responses

Returns current WiFi state

Response type application/json. Example of connected to AP.

{
    "state": "connecting",
}

POST /wifi/scan_start

Starts WiFi network scan.

Parameters

This endpoint does not have parameters

Responses

Returns current WiFi state

Response type application/json. Example of connected to AP.

{
    "state": "scanning",
}