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>/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)

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

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

Request

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

Request

# 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

# 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

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>
        }
    }
}