Websocket API

The Websocket API allows for bidirectional communication between Resolume and the application using the API. This works slightly different from the REST API, which uses the HTTP protocol.

Using the Websocket API allows you to subscribe to parameters in Resolume, allowing for continuous updates between the software and the API. This is useful when you want to create an application that makes changes to Resolume and reads changes from within Resolume.

The "working example" found in under preference > Webserver is a good example of the Websocket API in action. The example allows you to control Resolume Arena from within your browser. The code for the examples can also be found in our public repository. Additionally, an overview of all the API commands can be found in the API Reference (Arena / Wire).

Setup

Before you can use the API you must enable the webserver in the preference.
To do this, navigate to preference > webserver and toggle the "Enable Webserver & REST API" on.

The Websocket API will listen to the same port and address as the REST API.
The Websocket API is available on ws://listen adres:listen port/api/v1
All messages sent must be valid JSON.

Upon connecting to the Websocket you will immediately get three messages:

The sources and effects will be wrapped like this: { "type": "sources_update", "value": <sources> } & { "type": "effects_update", "value": <effects> }.

The messages are repeated whenever relevant. 
For the composition this happens when there are structural changes.
For example: a column or layer is added/removed. 

For sources and effects the message is sent every time a source or effect is added or removed. This will most likely happen when a Wire effect or source is installed in Arena.

The composition state after connecting to the Websocket API , similar to GET /composition


Controlling the Websocket API

The composition state, as demonstrated above, contains parameters.
The available parameters can be found in the reference documentation.

To acces the parameters you will have to perform actions.

Actions

To perform an action you will need to send a message structured like this: 

{ "action": <action>, "parameter": <parameter path> }

The following actions are available:

  • subscribe
  • unsubscribe
  • set
  • get
  • reset
  • trigger

Note: actions are never capitalised.


The action is one of the actions mentioned before, the parameter path can be derived like this:

/parameter/by-id/<parameter id> 

The id is the id of the parameter given in the composition object.
The logical path, based on the paths from the reference documentation, without /api/v1 and with the parameter name appended

Parameters

When looking at the documentation we can find the paths. 
For example: /composition/columns/{column-index} which has a number of parameters.

The parameters are the elements you will most likely want to control. 
Examples of parameters would be name(StringParameter) or colorid(ChoiceParameter). 

Using the "Schema"-option in the documentation gives a clear overview of the parameters.

Continuing with the previous examples, the following paths would be valid:

- /composition/columns/1/name

- /composition/columns/2/colorid

Note that for the 'set' action, an additional key value is required inside the message, which contains the new value to set.

This must be the same type as documented for the value of the parameter, so e.g. a string for a StringParameter.

All these actions will trigger a response message, with the exception of 'trigger' and 'reset. This message contains the param, the additional fields 'type' and 'path. 

Path is the parameter path (as given in the request message), while type can be any of:

  • parameter_subscribed
  • parameter_unsubscribed
  • parameter_get
  • parameter_set
  • parameter_update

Note: parameter_update is sent for parameters that have a subscription where the value is changed.

Websocket Actions

Besides interacting with parameters, the Websocket API also supports executing actions, which allows adding or removing objects in the composition, such as layers, columns and effects.

The messages are objects with the following properties:

  • action: either post or remove
  • id: an optional self-chosen id (to be given in the answer)
  • path: the request path (e.g. to a column or layer)
  • body: the request data (optional, depending on the action)

Note: The post action behaves like the POST actions described in swagger, while the remove actions are like DELETE. remove was chosen instead of delete because it is a javascript (and C++) keyword, which can lead to some issues.

The path is once again the same path as is available in the swagger docs, without the /api/v1. 

For example: if you want to create a new layer, you could send the following message:

{ "action": "post", "id": "my_new_layer", "path", "/composition/layers/add" }

To this you could expect a response like this:

{ "id": "my_new_layer", "error" null }

Related Articles