OSC Commands for controlling LiveEdit

LiveOSC Protocol Documentation

Version 2.0 - 7 June 2024

Warning: This document is intended for use by developers who want to interface a remote control system with a LiveEdit application. This protocol description has been developed by the LiveEdit team to provide the most reliable and accurate information. However, the content of this document is subject to change at any time without prior notice.

Introduction

LiveControl is a UDP/IP based remote control protocol designed to control the basic functionality of a LiveEdit application. It can modify resources, edit configurations, and control playback. Some commands can read system information such as status or lists of resources.

This protocol is based on Open Sound Control (OSC) messages transmitted over a local network using UDP/IP and Ethernet.

An external control system can connect to port 7014 and control the LiveEdit system with OSC commands. Requests are divided into three namespaces:

/transport: Controls the playback of the system, such as play, jog, or variable speed.
/live: Triggers actions and configures the resources used for playback, such as taking a macro or muting an audio track.
/scene: Edits resources and configures the user interface, such as opening a scene, trimming a shot, or toggling the visibility of the timeline.

In general, requests are read-only, write-only, or read-and-write. Write requests trigger actions or modify resources. Read requests ask for status or lists of resources. Requests with write directions usually require one or more arguments, while requests with read directions do not. Read requests reply on the same socket with the same message address but on port 9014, similar to status reports.

Argument Types in LiveOSC

The LiveOSC protocol uses various types of arguments to define actions and transmit information. Understanding these types is essential for effectively using the protocol. The arguments used by the LiveOSC protocol are as follows:

int: A 32-bit signed integer.
Example: 42
float: A 32-bit floating-point number.
Example: 3.14
string: A variable-length string of characters.
Example: "Hello, World!"
array: A collection of values of various types, specified as a list.
Example: ["uid1", "slug1", "name1", "color1"]

Optional arguments are given inside of [ ]. Alternatives are separated with a |. The argument type is specified after the argument name (e.g., argName: int).

Commands

Transport

/transport/play

Start playback.

/transport/pause

Pause playback.

/transport/playpause

Toggle between play and pause.

/transport/fastbackward

Rewind to the start point of the timeline.

/transport/stepforward [audio: int]

audio: If set to 1, play the next frame audio buffer.
Move forward one frame in the timeline.

/transport/stepbackward [audio: int]

audio: If set to 1, play the previous frame audio buffer.
Move backward one frame in the timeline.

/transport/backward [step: int]

step: Step (in frames).
Move backward by a specified number of frames.

/transport/forward [step: int]

step: Step (in frames).
Move forward by a specified number of frames.

/transport/rec

Toggle recording.

/transport/markers/next

Jump to the next marker in the timeline.

/transport/markers/previous

Jump to the previous marker in the timeline.

/transport/speed/up

Increase playback speed.

/transport/speed/down

Decrease playback speed.

/transport/speed/reset

Reset playback speed to normal.

/transport/speed/rate rate: float

rate: Playback rate between 0.1 and 2.

/transport/jog delta: float

delta: Factor between -1 and 1 for the jog rate.
Move forward or backward in the timeline at a specified rate.
Example: "/transport/jog ,f 0.7"

Live

/live/livemode [state: int]

state: If set to 0, leave Live mode. If set to 1, enter Live mode. If not set, toggle the current state.

/live/override [component: string]

component: Deactivate the specified component. Options: "switcher", "ltc", "midi", "gpo", "ptz", "externaldevices", "audio".
Example: "/live/override" ",s" "ltc"

/live/rearm [component: string]

component: Activate the specified component. Options: "switcher", "ltc", "midi", "gpo", "ptz", "externaldevices", "audio".

/live/emergency/hold

Hold the current shot on any switcher track.

/live/emergency/skip

Execute immediately the next shot on any switcher track.

/live/emergency/replace

Replace the next shot on any switcher track with the default source configured in the project.

/live/macros/list

Request the list of macros located in the current project.

/live/macros/take [uidOrSlug: string[, params: string]]

uidOrSlug: Unique identifier or slug value of the macro.
params: Value(s) to pass to the macro.
Example: "/live/macros/take" ",sss" "foo42" "red" "player1"

Scene

/scene/previous

Move to the previous scene.

/scene/next

Move to the next scene.

/scene/timeline/hide

Hide the timeline.

/scene/timeline/show

Show the timeline.

/scene/cameraboxes/show

Show the camera boxes.

/scene/cameraboxes/hide

Hide the camera boxes.

/scene/tracks/next

Move to the next track.

/scene/tracks/previous

Move to the previous track.

/scene/shots/next

Move to the next shot.

/scene/shots/previous

Move to the previous shot.

/scene/shots/blade

Blade the current shot.

/scene/shots/trim [direction: string]

direction: Could be "in", "out" or "auto". If not specified, the default value is "auto".
Trim the shot at playhead position.

/scene/shots/delete

Delete the current shot. This command has no action if there is no active shot.

/scene/markers/new

Create a new marker at the playhead position.

Status Reports

Status reports are messages reflecting the state of the LiveEdit system, sent through the socket reply port without prior request from the remote control system.

Transport

/transport/running [running: int]

running: Set to 1 if playback has started and 0 if playback has stopped.

/transport/speed/rate [rate: float]

rate: Current playback rate between 0.1 and 2.

Live

/live/livemode [state: int]

state: Set to 1 if Live mode is active and 0 if Live mode is inactive.

/live/macros/list [uid: string, slug: string, name: string, color: string]

uid: Unique identifier of the macro.
slug: Slug value of the macro.
name: Name of the macro.
color: Color of the macro.
The list of macros located in the current project.

Scene

/scene/metadata [uid: string, number: string, name: string, duration: float, startoffset: float, regenoffset: float, chase: int]

uid: Unique identifier of the scene.
number: Number of the scene.
name: Name of the scene.
duration: Duration of the scene (in milliseconds).
startoffset: Start point offset of the scene (in milliseconds).
regenoffset: Timecode regen offset of the scene (in milliseconds).
chase: Set to 1 if the scene is set to chase an incoming Timecode.
The metadata of the current scene.

/scene/timeline/visible [visible: int]

visible: Set to 1 if the timeline is visible and 0 if hidden.

/scene/cameraboxes/visible [visible: int]

visible: Set to 1 if camera boxes are visible and 0 if hidden.