Skip to content

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

Terminal window
ws://<ip-address>:<port>/ws

State

Get Ontime version

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {"type": "version"}

Response

{"type":"version","payload":"3.0.0"}

Get Ontime runtime state

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {"type": "poll"}

Response
The response of a poll request is a runtime data object

{
"type": "poll",
"payload": <runtime-data>
}

Change event

Terminal window
<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.

PropertyValue type
titlestring
notestring
cuestring (value should be kept under 8 characters)
isPublicboolean
skipboolean
colourstring (# hex colour or named css colour)
customtarget the specific custom field with custom:<fieldname>
timeWarningnumber (in seconds)
timeDangernumber (in seconds)
endActionstring (none / load-next / play-next / stop)
timerTypestring (count-down / count-up / time-to-end / clock)
durationnumber (in seconds)
timeStartnumber (in seconds)
timeEndnumber (in seconds)

Example: change title of event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"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

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"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 timer view.
The payload response is the current state of the message data.

Example: change the external message text

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"external": "new text"
}
}

Response

{
"type":"message",
"payload": {
"external": "new text",
"timer": {
"text": "",
"visible": true,
"blink": false,
"blackout": false,
"secondarySource": null
},
}
}

Example: secondary source in the timer view

Request

Show auxiliary timer as secondary field
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"timer": {
"secondarySource": "aux"
}
}
}

Request

Show external message as secondary field
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"timer": {
"secondarySource": "external"
}
}
}

Request

Hide secondary field
# Note: The secondary source can be `aux` or `external`, any other value will assign the property to null (ie: off)
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"timer": {
"secondarySource": null
}
}
}

Response

{
"payload": {
"external": "new text",
"timer": {
"text": "",
"visible": true,
"blink": false,
"blackout": false,
"secondarySource": "external"
},
}
}

Example: blackout timer screens

You can remotely blackout every screen that is in the timer view.

Request

Blackout timer screen
# Note: The secondary source can be `aux` or `external`, any other value will assign the property to null (ie: off)
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"timer": {
"blackout": true
}
}
}

Request

Disable timer screen blackout
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "message",
"payload": {
"timer": {
"blackout": false
}
}
}

Response

{
"payload": {
"external": "",
"timer": {
"text": "",
"visible": true,
"blink": true,
"blackout": false,
"secondarySource": null
},
}
}

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

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {"type": "start"}

Start event at index

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "start",
"payload": {
"index": 1
}
}

Start event with ID

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "start",
"payload": {
"id": "<event-id>"
}
}

Start event with cue

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "start",
"payload": {
"cue": "<event-cue>"
}
}

Start next event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "start",
"payload": "next"
}

Start previous event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "start",
"payload": "previous"
}

Pause running timer

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: { "type": "pause" }

Load event

Load event at index

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "load",
"payload": {
"index": 1
}
}

Load event with ID

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "load",
"payload": {
"index": "<event-id>"
}
}

Load event with cue

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "load",
"payload": {
"index": "<event-cue>"
}
}

Load next event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "load",
"payload": "next"
}

Load previous event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "load",
"payload": "previous"
}

Reload current event

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "reload"
}

Stop playback

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "stop"
}

Activate Roll mode

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "roll"
}

User added time

Add time

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "addtime",
"payload": {
"add": <value-in-seconds>
}
}

Remove time

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"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

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"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

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "auxtimer",
"payload": {
"1": {
"duration": "count-up"
}
}
}

Set auxiliary timer to count down

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "auxtimer",
"payload": {
"1": {
"duration": "count-down"
}
}
}

Start auxiliary timer

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "auxtimer",
"payload": {
"1": "start"
}
}

Pause auxiliary timer

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "auxtimer",
"payload": {
"1": "pause"
}
}

Stop auxiliary timer

Request

Terminal window
Target: ws://<ip-address>:<port>/ws
Message: {
"type": "auxtimer",
"payload": {
"1": "stop"
}
}