Skip to content

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",
}