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

Note

Any WebSocket client that connects to ontime, will receive a snapshot of the application state as defined in the Runtime data.

State

Get Ontime version

Request

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

Response

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

Get Ontime runtime state

Request

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

<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 / none)
duration	number (in seconds)
timeStart	number (in seconds)
timeEnd	number (in seconds)

Caution

Changing the properties skip endAction duration timeStart timeEnd
cause the rundown to be recalculated and writing to them is therefore throttled

Example: change title of event

Request

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

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

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

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

Start event at index

Request

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

Start event with ID

Request

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

Start event with cue

Request

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

Start next event

Request

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

Start previous event

Request

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

Pause running timer

Request

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

Load event

Load event at index

Request

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

Load event with ID

Request

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

Load event with cue

Request

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

Load next event

Request

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

Load previous event

Request

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

Reload current event

Request

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

Stop playback

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

Activate Roll mode

Request

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

User added time

Add time

Request

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

Remove time

Request

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

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

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

Set auxiliary timer to count down

Request

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

Start auxiliary timer

Request

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

Pause auxiliary timer

Request

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

Stop auxiliary timer

Request

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

Add / remove time to auxiliary timer

Request

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