WebSockets API
The OSC and WebSocket APIs allow for low latency communication to Ontime server.
Since the WebSocket API is used by Ontime, this cannot be configured by the user other than changing its port.
The WebSocket server is at the same IP address and port as the main application at
ws://<ip-address>:<port>/ws
State
Get Ontime version
Request
Target: ws://<ip-address>:<port>/wsMessage: {"type": "version"}
Response
{"type":"version","payload":"3.0.0"}
Get Ontime runtime state
Request
Target: ws://<ip-address>:<port>/wsMessage: {"type": "poll"}
Response
The response of a poll request is a runtime data object
{ "type": "poll", "payload": <runtime-data>}
Change event
<localhost:4001>/api/change/<event-id>/<property>/<value>
The change endpoint allows changing some of the properties of a given event (below).
The request should contain a patch of the event to be changed, along with the ID of the event to change.
You can change any field in an event using this endpoint. See below a description of expected values.
Property | Value type |
---|---|
title | string |
note | string |
cue | string (value should be kept under 8 characters) |
isPublic | boolean |
skip | boolean |
colour | string (# hex colour or named css colour) |
custom | target the specific custom field with custom:<fieldname> |
timeWarning | number (in seconds) |
timeDanger | number (in seconds) |
endAction | string (none / load-next / play-next / stop) |
timerType | string (count-down / count-up / time-to-end / clock) |
duration | number (in seconds) |
timeStart | number (in seconds) |
timeEnd | number (in seconds) |
Example: change title of event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "change", "payload": { "<event-id>": { "title": "new-text" } }}
Response
{ "type": "change", "payload": { "<event-id>": { "title": "new-text" } }}
Example: change a custom field
The custom field must exist in the project to be accepted by the API.
See more on custom fields
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "change", "payload": { "<event-id>": { "custom:<field-name>": "new-text" } }}
Response
{ "type": "change", "payload": { "<event-id>": { "custom:<field-name>": "new-text" } }}
Message
The following endpoints allow controlling the messages Ontime sends to the views.
The payload response is the current state of the message data
Example: change the external message text
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "message", "payload": { "external": { "text": "new text" } }}
Response
{ "type":"message", "payload": { "timer": { "text":"", "visible":false, "blink":false, "blackout":false }, "external":{ "text":"new text", "visible":false } }}
Example: change the external message visibility
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "message", "payload": { "external": { "visible": true } }}
Response
{ "type":"message", "payload": { "timer": { "text":"", "visible":false, "blink":false, "blackout":false }, "external":{ "text":"new text", "visible":true } }}
Playback
The following endpoints allow controlling the Ontime’s playback.
The payload response is the current state of the message data
Start event
Start loaded event
Request
Target: ws://<ip-address>:<port>/wsMessage: {"type": "start"}
Start event at index
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "start", "payload": { "index": 1 }}
Start event with ID
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "start", "payload": { "id": "<event-id>" }}
Start event with cue
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "start", "payload": { "cue": "<event-cue>" }}
Start next event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "start", "payload": "next"}
Start previous event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "start", "payload": "previous"}
Pause running timer
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "pause" }
Load event
Load event at index
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "load", "payload": { "index": 1 }}
Load event with ID
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "load", "payload": { "index": "<event-id>" }}
Load event with cue
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "load", "payload": { "index": "<event-cue>" }}
Load next event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "load", "payload": "next"}
Load previous event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "load", "payload": "previous"}
Reload current event
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "reload"}
Stop playback
Target: ws://<ip-address>:<port>/wsMessage: { "type": "stop"}
Activate Roll mode
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "roll"}
User added time
Add time
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "addtime", "payload": { "add": <value-in-seconds> }}
Remove time
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "addtime", "payload": { "remove": <value-in-seconds> }}
Auxiliary timer
Ontime provides an auxiliary timer which does not affect the current playback.
This can be controlled using the API as shown below
Set auxiliary timer duration
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": { "duration": <value-in-seconds> } }}
Set auxiliary timer direction
Auxiliary timer can count up or count down.
Set auxiliary timer to count up
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": { "duration": "count-up" } }}
Set auxiliary timer to count down
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": { "duration": "count-down" } }}
Start auxiliary timer
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": "start" }}
Pause auxiliary timer
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": "pause" }}
Stop auxiliary timer
Request
Target: ws://<ip-address>:<port>/wsMessage: { "type": "auxtimer", "payload": { "1": "stop" }}