Network
This section covers the remote control interfaces that work over the network
(TCP/IP or UDP). They allow other software, scripts, or devices to send
remote control commands to mAirList, or to query its status.
- The REST interface is an HTTP(S) server with user authentication, and the
recommended choice for new integrations.
- The TCP Server, TCP Client and UDP Server
interfaces receive plain text commands, one per line or packet.
- The JSON Server and JSON Client interfaces exchange
JSON data, which is processed by background scripts.
1 - REST
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.
2 - TCP Server
The TCP Server remote opens a TCP port that other software can connect to and send
remote control commands, e.g. from a telnet client, a script,
or a home automation system.
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface
of type TCP Server (Network category).
- Bind IP:
The local IP address(es) to listen on, separated by commas.
Leave empty to listen on all network interfaces.
- Port:
The TCP port to listen on. The default is 9302.
- Password:
If set, clients must authenticate before they can send commands (see below).
- Command prefix:
If set, only lines starting with this prefix (followed by a space) are executed,
and the prefix is removed before execution. All other lines are ignored.
Usage
Send one command per line, terminated by CR/LF, e.g.:
PLAYER 1-1 START
If a password is set, the first line must be AUTH <password>. mAirList replies with
AUTH OK if the password is correct, or AUTH REQUIRED otherwise. Until the client is
authenticated, all other lines are rejected with AUTH REQUIRED.
Multiple clients can be connected at the same time. Connections and disconnections are
recorded in the System Log.
A script can send data to all connected clients using the SendString and
WriteLine methods of the interface, available through TCPServerRemote(<index>).
3 - TCP Client
The TCP Client remote is the counterpart of the TCP Server: mAirList
connects to a TCP server, and executes each line received from that server as a
remote control command.
This is useful when the device or software sending the commands can only act as a
server, or to connect two mAirList instances (with a TCP Server remote on the
other instance).
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface
of type TCP Client (Network category).
- Host name or IP and Port:
The address of the TCP server to connect to. The default port is 9303.
- Password:
If set, mAirList sends
AUTH <password> to the server after connecting.
Use this when connecting to the TCP Server remote of another mAirList instance. - Command prefix:
If set, only lines starting with this prefix (followed by a space) are executed,
and the prefix is removed before execution. All other lines are ignored.
- Dummy mode:
If checked, all incoming data is discarded and no commands are executed.
Use this option when the connection is only used to send data from a script.
mAirList connects automatically when the interface is started, and tries to reconnect
every few seconds if the connection is lost or cannot be established.
Scripting
A script can send data to the server using the SendString and WriteLine methods of
the interface, available through TCPClientRemote(<index>).
For sending a one-off string to a TCP server without setting up a remote control
interface, scripts can use the TCPSendString(Server, Port, Text) procedure.
4 - UDP Server
The UDP Server remote receives remote control commands as UDP
packets. Unlike TCP, no connection needs to be established, which makes UDP a good
choice for devices that send short, single messages, e.g. GPIO-to-network converters
or broadcast consoles with “UDP trigger” functions.
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface
of type UDP Server (Network category).
- Bind IP:
The local IP address(es) to listen on, separated by commas.
Leave empty to listen on all network interfaces.
- Port:
The UDP port to listen on. The default is 9303.
Usage
Each UDP packet must contain exactly one command, as UTF-8 encoded text, e.g.
PLAYER 1-1 START. There is no authentication, and no reply is sent.
Warning
As there is no authentication, anybody who can reach the UDP port can control
mAirList. Use the Bind IP setting and a firewall to restrict access.
Scripts can send UDP packets with the UDPSendString(Server, Port, Text) procedure,
e.g. to control another mAirList instance.
5 - JSON Server
The JSON Server remote opens a TCP port through which clients can exchange JSON
messages with mAirList. Unlike the TCP Server, the received data is
not executed as commands. Instead, it is passed to
background scripts, which can process it and send
replies. This makes it possible to implement custom protocols.
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface
of type JSON Server (Network category).
- Bind IP:
The local IP address(es) to listen on, separated by commas.
Leave empty to listen on all network interfaces.
- Port:
The TCP port to listen on. The default is 9303.
Protocol
Each message is a JSON document, encoded as UTF-8 and terminated by a null byte
(ASCII 0). Messages that are not valid JSON are ignored.
Scripting
The following event handlers are available in background scripts:
procedure OnJSONServerRemoteClientConnect(Remote: IJSONServerRemote; ClientID: cardinal);
procedure OnJSONServerRemoteClientDisconnect(Remote: IJSONServerRemote; ClientID: cardinal);
procedure OnJSONServerRemoteClientData(Remote: IJSONServerRemote; ClientID: cardinal; Data: IPersistentStorage);
procedure OnJSONServerRemoteClientDataObject(Remote: IJSONServerRemote; ClientID: cardinal; Data: IPersistentObject);
OnJSONServerRemoteClientDataObject is only called when the received document is a JSON
object (rather than an array or a single value).
To send data, use the following methods of the Remote object (or
JSONServerRemote(<index>)):
SendTo(ClientID, Data) – send to a single client,Broadcast(Data) – send to all connected clients,BroadcastExcept(ClientID, Data) – send to all clients except the specified one.
6 - JSON Client
The JSON Client remote is the counterpart of the JSON Server: mAirList
connects to a TCP server, and exchanges JSON messages with it. The received data is
passed to background scripts for processing.
Configuration
In the configuration app or Control Panel, go to Remote Control and add an interface
of type JSON Client (Network category).
Enter the Host name or IP and Port of the server to connect to.
The default port is 9303.
mAirList connects automatically when the interface is started, and tries to reconnect
every few seconds if the connection is lost or cannot be established.
Protocol
Each message is a JSON document, encoded as UTF-8 and terminated by a null byte
(ASCII 0), the same as for the JSON Server.
Scripting
The following event handlers are available in background scripts:
procedure OnJSONClientRemoteConnect(Remote: IJSONClientRemote; ClientID: cardinal);
procedure OnJSONClientRemoteDisconnect(Remote: IJSONClientRemote; ClientID: cardinal);
procedure OnJSONClientRemoteData(Remote: IJSONClientRemote; Data: IPersistentStorage);
procedure OnJSONClientRemoteDataObject(Remote: IJSONClientRemote; Data: IPersistentObject);
OnJSONClientRemoteConnect and OnJSONClientRemoteDisconnect are called whenever the
connection to the server is (re-)established or lost. Their ClientID parameter is always
0; it only exists for compatibility with the JSON Server event handlers.
OnJSONClientRemoteDataObject is only called when the received document is a JSON
object.
To send data to the server, call Remote.Send(Data) (or JSONClientRemote(<index>).Send(Data)).
For sending a single JSON document to a server without setting up a remote control
interface, scripts can use the JSONSendString(Server, Port, Data) procedure.