The Live Update API is a websocket-based interface that enables web widgets to receive realtime updates on data held by designer and request changes back to the main software. This documentation outlines the API’s connection lifecycle, message protocol, subscription mechanisms, and error handling. It also explains how changes are serialized using JSON and sent to clients.
From a high level, the live update interface provides a mechanism to look up relevant objects in a designer project, and subscribe to properties on it. This is done through a mix of designer and python expressions. We use designer expressions to “find” a relevant object in the project, and then python expressions to read (and potentially write) relevant data from it.
Some examples may be constructive:
| Object | Property | Description |
|---|---|---|
track:track_1 | object.lengthInBeats | The length of “track 1” in beats (seconds). |
track:track_1 | object.layers | The layers associated with the track. |
track:track_1 | object.getLeafLayers(VariableVideoModule) | Retrieves all leaf layers of a specific type from the object. |
screen2:screen_1 | object.description | "screen 1" - the user-visible name of the object. |
It is recommended to use higher-level framework-specific interfaces to work with the functionality provided by this API. By working with this API directly, a developer must consider details relating to data management and integrity, which is largely solved by higher-level interfaces. Badly behaved clients which leak subscriptions have the potential to cause harm to productions.
The API overview below is useful for users of higher level interfaces as well as those interested in implementing the WebSocket API directly.
Disguise have provided a Vue composable for this reason.
The Live Update API provides a bidirectional communication channel via websockets, allowing:
Subscriptions are built from a base object. Objects are referenced using designer expression syntax.
The object serves as the jumping off point for any number of properties. Each property accesses the object using Python syntax, e.g. object.description to get the user-visible name of the object. The object variable is provided by the object expression in order to make property access less repetitive & marginally more efficient.
This object and set of properties are combined into a single subscribe message sent to the director. Any number of subscribe and unsubscribe messages can be made in a given session, the only limit being performance and memory.
Assuming that both the object and property are correctly specified, a subscription list will be returned. The subscription list identifies the unique combination of object and property by a unique, never-repeating id.
The id is an integer value which is used by all subsequent messages to identify the property. This avoids repeating the potentially extremely long object & property names for every update and makes the subscription model of the API clear.
Every subscribe or unsubscribe action returns the full current status of all subscriptions for the client.
If a given client subscribes to the same property multiple times, they use the same id. Each subscription will need to be matched with a corresponding unsubscription for that property id, until the subscription is truly removed. This is achieved via a reference counting mechanism within designer running on the director.
This id reuse is useful when different components on a client page may subscribe to the same value, as the data is shared effectively between them, and resources are conserved. The reuse means it is not advisable to implement a client interface using the id as a primary key for anything related to subscriptions.
When a value is newly subscribed (this does not include a resubscription to the same value), and as the underlying resource values change, updates are pushed to the client.
The id is used to identify the property. Using id as a key into a local store of values is a reasonable idea, as the id will not change over the lifetime of the WebSocket connection.
Clients can update resource properties by sending a set command with the corresponding id and a new value.
The designer-internal live update system will distribute the changes throughout the session to all connected designer software.
Changes made through set commands are undoable on the director, and persistent.
Not all values can be set. For example, a subscription like { object: 'track:track_1', 'properties': [ 'object.getLeafLayers(VariableVideoModule) ] } will return all video layers on the named track, but will not allow the client to change any of those layers. Attempting to do so will result in an error. There is no way to know if setting a property will work before trying it, due to the complexities of the property expressions.
If a property value is a JSON object (e.g. screen2:screen_1 / object.offset -> { x: 0.0, y: 3.0, z: 0.0 }) it is possible to only set one field of the property. e.g. {x: 4.0} - this ensures that the other values are preserved, and is sometimes useful if a subscription over a complex object was made, but the interface focusses on editing individual fields one-by-one. This ensures that fields the user wasn’t actively editing don’t get reverted due to edits by other components or clients.
"object" or "properties" in a subscribe message) will result in an error response."uid", "path", and "type". Arrays: An array is sent, and the elements are serialized as normal.This section focusses on the mechanics and syntax of the JSON messages passed between the client and the director. The client initiates a connection to ws://<director:port>/api/session/liveupdate
These messages are passed from the client to the director.
A subscribe message must include the target object and a list of property paths:
{ "subscribe": {
"object": "objectPath",
"properties": ["propertyPath1", "propertyPath2"]
} }
For each property listed, a new subscription is created (using the provided object path). If the required fields are missing or the properties value is not an array, an error is sent.
Unsubscribe messages support either a single subscription ID or an array of IDs:
{ "unsubscribe": { "id": 123 } }
or
{ "unsubscribe": { "ids": [123, 456] } }
Non-integer values are detected and reported as errors. No further updates are sent after this message is processed. It is recommended to keep track of
The set command allows the client to update values for subscribed resources:
{ "set": [
{ "id": 123, "value": <value> },
{ "id": 456, "value": <value> }
] }
The server locates the subscription by ID and updates its current value using a partial merge strategy. That is, if multiple set commands modify different fields of the same object, later commands merge with previous changes.
These messages are passed from the director to the client.
Errors are reported using a JSON formatted error like so:
{ "error": <message> }
When the set of subscribed properties changes, a full list of all subscribed properties is sent from the server. This is to avoid the client having to do any bookkeeping to keep the current set of subscriptions straight.
{ "subscriptions": [
{ "id": <unique id integer>, "objectPath": <subscribed object>, "propertyPath", <subscribed property> }, ...
]}
When a new subscription is made, or when values subsequently change within designer, the server notifies clients with the following JSON structure:
{ "valuesChanged": [
{ "id": 123, "value": <value> },
{ "id": 456, "value": <value> }
] }
// Open a live update websocket connection
const socket = new WebSocket('ws://director:80/api/session/liveupdate');
// Once connected, subscribe to a Track resource
socket.onopen = () => {
const subscribeMessage = { subscribe: {
object: "track:track_1",
properties: ["object.lengthInBeats", "object.layers"]
} };
socket.send(JSON.stringify(subscribeMessage));
};
// Listen for incoming updates
socket.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Update received:', data);
};
// Assume the subscription id is 123 from a previous subscribe command
const setMessage = {
set: [
{ id: 123, value: 42.0 }
]
};
socket.send(JSON.stringify(setMessage));
// Unsubscribe from a single subscription
const unsubscribeMessage = { unsubscribe: { id: 123 } };
socket.send(JSON.stringify(unsubscribeMessage));