This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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.

MethodPathDescription
GET, POST/executeExecute a remote control command, passed as parameter command.
POST/actionsExecute an action list, passed as request body. Optional parameters: playlist, timeoffset.
GET/status/onairReturns 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>/contentReturns the content of playlist n as JSON.
GET/playlist/<n>/content.xmlReturns the content of playlist n as XML.
POST/log/startLog the start of an item, passed as JSON body (item, id, optional region).
POST/log/stopLog the stop of an item, passed as JSON body (item, id, optional region and duration).
GET/encoder/summaryReturns the status of the encoder and all connections.
GET/encoder/connectedReturns the connection state of the encoder.
GET/encoder/listenersReturns the total number of current listeners.
GET/encoder/silenceReturns the number of seconds the audio level has been below the silence threshold.
POST/encoder/streamtitleUpdates the stream title on all encoder connections, passed as parameter title.
GET/encoder/connection/<n>/summaryReturns the status of an encoder connection.
GET/encoder/connection/<n>/nameReturns the name of an encoder connection.
GET/encoder/connection/<n>/enabledReturns whether an encoder connection is enabled.
GET/encoder/connection/<n>/connectedReturns whether an encoder connection is established.
GET/encoder/connection/<n>/listenersReturns the number of listeners on an encoder connection.
GET/streammonitor/summaryReturns 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.

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.