14. OSC reference¶

This reference matches DL20 0.8.84; source — the bundled OSC documentation (docs/OSC.md).

Controlling a show over the network from a control surface, QLab, TouchOSC, Companion or any other OSC source. Reception over UDP.

Added in version 0.5.58. Before that, the OSC INPUT PORT field in settings was marked PLANNED and listened to nothing — if you have an older version, what is described below will not work.

1. Turning it on¶

SETTINGS → the CONTROLLERS section → the OSC INPUT PORT field.

Enter the port and press Enter (or just leave the field — the value is applied). The standard port for OSC is 7000.

Zero turns reception off. The default is zero: the program does not open a network port on the operator's machine until it is explicitly asked to.

The port is remembered for this machine, not inside the project. Moving the project to another venue will not drag along someone else's port number.

Under the field is a status line:

OFF — порт 0 выключает приём (port 0 turns reception off)
LISTENING udp/7000 · принято 47 (received 47) · /composition/columns/3/connect
ОШИБКА (ERROR): osc: server_thread_new failed (port in use?)

If the line is red, the port is taken by another program. Pick a different number.

2. Commands¶

Launching a scene and launching a window are implemented, and, as of version 0.8.84, track and group addresses for the timeline's track rack. Indices start at one, the same way the buttons in the program are labeled (SCENE 1, SCENE 2, …).

Launch a column (scene)¶

/composition/columns/{N}/connect

N is the column number. /composition/columns/3/connect does exactly what pressing the SCENE 3 button does: it launches every occupied window of that column on every visible layer.

Launch a single cell¶

/composition/layers/{L}/clips/{W}/connect

L is the layer number (top to bottom, L1 = 1), W is the window number in the row. /composition/layers/2/clips/5/connect launches the clip at the intersection of the second layer and the fifth column.

Argument¶

The argument is optional. A message with no arguments (a bang) launches the command.

If there is an argument:

Argument	Action
no argument, a string	launch
integer, non-zero (`1`)	launch
integer `0`	ignored
float `>= 0.5`	launch
float `< 0.5`	ignored

Zero is ignored on purpose: control surfaces and TouchOSC send a button press as 1 and a release as 0. Without this rule, one press by the operator would fire twice.

Tracks and groups (0.8.84)¶

/composition/tracks/{N}/connect
/composition/tracks/{N}/disconnect
/composition/tracks/{N}/toggle
/composition/tracks/{N}/go
/composition/tracks/{N}/position
/composition/tracks/id/{ID}/{the same set}
/composition/groups/{N}/{the same set}
/composition/groups/id/{ID}/{the same set}

N is the track's or group's number, one-based by rack order (the main track is 1), with no leading zeros, 1…999 — the same rules as the column and the cell above. ID is the track's or group's id (no leading zeros, not zero; stable across reordering the rack's rows). A group is fired by its master — members are fanned out the same way the panel's ▶ button does; a member track's address also drives its whole group.

connect starts it (does nothing on an already-playing track/group); disconnect stops it (does nothing on a stopped one); toggle is ▶/■ by the master's state; go is the same as the panel's GO▸ button (jump to the next cue; refuses without the timeline panel open on screen).
position is not a button but a value: a number (float or int) moves the track to that many seconds from the start and fires on any number, including 0.0. A bang or a string (a button mapped to /position by mistake, or the string "2.5") does NOT change the position: the command is refused with the log line osc /composition/tracks/1/position -> refused: position needs a number.

An unknown track or group writes osc track N -> no such track (or no such group) to the log and does nothing; the counter of unrecognized addresses does not count this — the address was understood, only the target was not found.

3. How to check that commands are getting through¶

The status line in SETTINGS → CONTROLLERS shows a counter of received messages and the last address that arrived — whether or not it was understood. If an address arrives with a typo, you will see it with a (не команда) (not a command) mark. This answers two different questions in turn: "is anything arriving at all" and "am I sending the right address".

The log is written to %LOCALAPPDATA%\DL\logs\ (a fresh file for every run):

dl_composition: osc listening on udp/7000
dl_composition: osc launched column 3
dl_composition: scene column 3 launched (2 clips, 0 stopped)
dl_composition: osc cell L2-W7 is empty
dl_composition: osc column 12 out of range (1..8)
dl_composition: osc /composition/layers/1/video/opacity -> not a command
dl_composition: osc track 1 connect -> ok: #1 Main
dl_composition: osc track 99 -> no such track
dl_composition: osc track 1 position 2.500 -> ok: #1 Main

Unrecognized addresses are logged in full the first 20 times, after that they are only counted — a stray control surface broadcasting on the network should not flood the log over a shift. Track command lines (osc track …, osc group …) are capped too: one line per change of target or op (a fader sending position to one track gives one line, not a line per message), at most 50 per run; every command is still executed.

4. What to send it with for testing¶

oscsend (part of liblo, packaged for most distributions):

oscsend 127.0.0.1 7000 /composition/columns/2/connect i 1
oscsend 192.168.0.50 7000 /composition/layers/1/clips/3/connect
oscsend 127.0.0.1 7000 /composition/tracks/1/connect
oscsend 127.0.0.1 7000 /composition/tracks/1/position f 2.5

TouchOSC / Companion / QLab — enter the IP address of the machine running DL20 and the port from settings, the address from section 2. The message type is a button, not a fader.

5. What's not there yet¶

The column and cell addresses are compatible with Resolume; the rest of the Resolume API is not supported — in particular, the following do not work:

/composition/layers/{L}/video/opacity and any other parameters;
/composition/columns/{N}/select (selecting without launching);
/composition/tempocontroller/..., tempo and synchronization;
Art-Net in — in settings it is honestly marked PLANNED.

Honestly, about tracks and groups (0.8.84): there is no addressing by name for a track or a group — only the rack index or a numeric id; go refuses without the timeline panel open on screen. For both the old and the new addresses: sending OSC out of the program and state feedback to a control surface or any OSC client does not exist at all.

Separately: arbitrary OSC addresses can be bound to parameters through MIDI Learn — the binding mechanism is shared between MIDI and OSC. This is a different scenario than the fixed commands above.

More about control: 13.