WebSocket external control protocol

!Important: This section is currently under maintenance to improve the knowledge base.
This page may contain information relative to a future release and upgraded implementation of the web socket methods.

It is possible to interact with Modulo Player using the WebSocket protocol (ws).

Modulo Player acts as the WebSocket server and uses the JSON-RPC 2.0 protocol.

Operation principle

A client connects to the Player’s WebSocket server using the ws protocol and sends a payload containing an instruction for the server.

*Note: The server does not implement secure connection and the wss protocol cannot be used.

Payload

The payload is formatted in JSON-RPC and the "method" property contains the instruction to run on the server.

If the payload is properly formatted and contains a valid method, the server will respond with an answer in JSON format containing the result of the instruction.

If the payload contains an invalid method, the JSON answer will contain a Method not found message.

If the payload is not properly formatted, the server will simply send back the payload instead of a JSON answer.

ID

An ID can be specified in the Payload and will be mirrored in the server’s response to filter different payloads by the operator.

If no ID is specified, the server’s JSON response will contain an empty value "" in the "id" property.

UUID

In many targeted methods, you may specify either a name or a uuid to target a specific item (playlist, task, etc.)

The uuid is a Universally Unique Identifier given by the server to an item at creation and will remain identical even if the name of the item is changed.

This allows for more robust instructions to be written that will tolerate items in the show being renamed according to needs.

Syntax

When targetting specific items, it is important to properly syntax the parameters according to the expected types.

If a String type is expected, it should be wrapped in " double brackets ". For examble : "name":"MyName".

If a Boolean type is expected, it does not require double brackets. For example : "triggerEnable":false

If a Color is expected, it should be noted in hexadecimal notation prefixed with the # character. For example : "uiColor":#0099ff

Modulo Player Remote

Unless specified otherwise, Modulo Player Remote automatically refreshes to reflect the changes made using the WebSocket protocol and displays them immediately.

Prototyping tool

We recommend the Web Socket King Client from the Google Chrome extension store for prototyping web socket commands.

It has the advantage of formatting the received JSON in a human friendly manner to facilitate comprehension, as illustrated below.

In this example, the method sent was get.list.playlists and the payload was properly formatted.

The server returned a JSON and the "result" property contains a JSON Object Litteral inside a JSON Array Literal.

The JSON Object Litteral corresponds to the data for the playlist named Playlist and is the first item in the JSON Array Literal.

Since there is only one playlist on the server in this example, it is also the only item in the array.

If there had been several playlists, they would each have been represented in the "result" by their own JSON Object Litteral and would have each been an item in the array.

Available methods

Tasks

Playlists

Cues & Layers

Show

Media