The REST remote (REST Remote Access) is a built-in HTTP/HTTPS server, through which other software can execute remote control commands and query the status of mAirList. All requests require authentication with a username and password, or a token.
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface of type REST Remote Access (Network category).
General
- Server Settings: Select the Mode (HTTP only, HTTPS only, or HTTP and HTTPS), and the HTTP Port (default 9300) and HTTPS Port (default 9301).
- SSL Certificate Files: For HTTPS, select the Certificate and Key files (PEM format), and an optional Root Certificate.
- User Management: Select where the user accounts are stored: either in the local configuration (Local configuration (auth.db file)), or in one of the configured mAirListDB databases. Click Manage Users… to add or edit users. When a database is selected, you must first sign in with a database user with administrator level.
In the user management dialog, you can set up users and groups, and set their passwords. For each user or group, the permissions determine which functions of the REST interface they may access, e.g. Command execution, General status (read-only), Playlist read access, Encoder status, or File Server.
File Server
The REST server can also serve static files, e.g. a custom web interface that uses the REST API.
- Enable File Server: Turns on the file server.
- URL Prefix:
The path under which the files are available, e.g.
www. - Document Root: The local folder that contains the files.
- Allow unauthenticated access: If checked, the files can be retrieved without signing in.
Authentication
Clients authenticate using HTTP Basic authentication (username and password),
or with a token (Authorization: Bearer ... header). Tokens can be obtained through the
/auth endpoint.
Endpoints
The following endpoints are available. Numbers in the path (e.g. the playlist number) are counted from 0.
| Method | Path | Description |
|---|---|---|
GET, POST | /execute | Execute a remote control command, passed as parameter command. |
POST | /actions | Execute an action list, passed as request body. Optional parameters: playlist, timeoffset. |
GET | /status/onair | Returns the current ON AIR status (true or false). |
GET | /runtimedata/<name> | Returns the value of a runtime data variable. |
GET | /logic/<name> | Returns the value of an internal logic state. |
GET | /playlist/<n>/content | Returns the content of playlist n as JSON. |
GET | /playlist/<n>/content.xml | Returns the content of playlist n as XML. |
POST | /log/start | Log the start of an item, passed as JSON body (item, id, optional region). |
POST | /log/stop | Log the stop of an item, passed as JSON body (item, id, optional region and duration). |
GET | /encoder/summary | Returns the status of the encoder and all connections. |
GET | /encoder/connected | Returns the connection state of the encoder. |
GET | /encoder/listeners | Returns the total number of current listeners. |
GET | /encoder/silence | Returns the number of seconds the audio level has been below the silence threshold. |
POST | /encoder/streamtitle | Updates the stream title on all encoder connections, passed as parameter title. |
GET | /encoder/connection/<n>/summary | Returns the status of an encoder connection. |
GET | /encoder/connection/<n>/name | Returns the name of an encoder connection. |
GET | /encoder/connection/<n>/enabled | Returns whether an encoder connection is enabled. |
GET | /encoder/connection/<n>/connected | Returns whether an encoder connection is established. |
GET | /encoder/connection/<n>/listeners | Returns the number of listeners on an encoder connection. |
GET | /streammonitor/summary | Returns the status of the StreamMonitor and all streams. |
Example, using curl:
curl -u user:password -d "command=PLAYER 1-1 START" http://localhost:9300/execute
Further endpoints can be implemented in a background script
with the OnRESTRequest event handler.