OSC API

The OSC and WebSocket APIs allow for low latency communication to Ontime server.

Using OSC

To use the OSC API, you will need to configure the feature in Editor -> Settings -> Integrations.

Due to the nature of the protocol, for getting feedback from OSC you will need to configure a feedback loop in both Ontime and your other software/devices.

You can monitor the messages received using the Network log in Editor -> Settings -> Log.

Change event

/ontime/change/<event-id>/<field> <new-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 are therefor therefor throttled

Example: change title of event

OSC Message

/ontime/change/<event-id>/title <new-value>

Example: change a custom field

The custom field must exist in the project to be accepted by the API.
See more on custom fields

OSC Message

/ontime/change/<event-id>/custom:<field-name> <new-value>

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

OSC Message

# Note that this will set the text, however setting its visibility is a separate operation.
# See below
/ontime/message/external <new-text>

Example: secondary source in the timer view

OSC Message

Show auxiliary timer as secondary field

/ontime/message/timer/secondarySource 'aux'

OSC Message

Show external message as secondary field

/ontime/message/timer/secondarySource 'external'

OSC Message

Hide secondary field

# Note: The secondary source can be `aux` or `external`, any other value will assign the property to null (ie: off)
/ontime/message/timer/secondarySource 'off'

Example: blackout timer screens

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

OSC Message

Blackout timer screen

/ontime/message/timer/blackout true

OSC Message

Disable timer screen blackout

/ontime/message/timer/blackout false

Playback

The following endpoints allow controlling the Ontime’s playback.

Start event

Start loaded event

OSC Message

/ontime/start

Start event at index

OSC Message

/ontime/start/index <event-index>

Start event with ID

OSC Message

/ontime/start/id <event-id>

Start event with cue

OSC Message

/ontime/start/cue <event-cue>

Start next event

OSC Message

/ontime/start/next

Start previous event

OSC Message

/ontime/start/previous

Pause running timer

OSC Message

/ontime/pause

Load event

Load event at index

OSC Message

/ontime/load/index <event-index>

Load event with ID

OSC Message

/ontime/load/id <event-id>

Load event with cue

OSC Message

/ontime/load/cue <event-cue>

Load next event

OSC Message

/ontime/load/next

Load previous event

OSC Message

/ontime/load/previous

Reload current event

OSC Message

/ontime/reload

Stop playback

OSC Message

/ontime/stop

Activate Roll mode

OSC Message

/ontime/roll

User added time

Add time

OSC Message

/ontime/addtime/add <value-in-seconds>

Remove time

OSC Message

/ontime/addtime/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

OSC Message

/ontime/auxtimer/1/duration <value-in-seconds>

Set auxiliary timer direction

Auxiliary timer can count up or count down.

Set auxiliary timer to count up

OSC Message

/ontime/auxtimer/1/direction count-up

Set auxiliary timer to count down

OSC Message

/ontime/auxtimer/1/direction count-down

Start auxiliary timer

OSC Message

/ontime/auxtimer/1/start

Pause auxiliary timer

OSC Message

/ontime/auxtimer/1/pause

Stop auxiliary timer

OSC Message

/ontime/auxtimer/1/stop