OSC Transport

OSC is for QLab, TouchDesigner, Max/MSP, and similar tools. It encodes a playback-control subset of the shared command catalog as OSC addresses—not a second feature set.

Browse full command semantics in the Command Reference (OSC tab). This page covers only connection and encoding rules.

When to choose OSC

Your show tool already speaks OSC
You need one message to express a full cue (play_media with source, cue point, loop)
You need continuous values (seek / volume) patched in realtime

OSC has no success acknowledgement. HTTP can confirm validation and queue admission; use Status when you need to observe whether media is ready or playing.

Connection


Port	`network.base_port` (default `18290`, UDP socket; enable with `network.enable_osc`)
Default	On (`network.enable_osc: true`)
Policy	Loopback is allowed. Other source IPs must match `controller_whitelist` when non-empty; an empty whitelist permits reachable sources. No automatic subnet gate.

Canonical rules live in the repository's player API refactor OSC contract.

OSC maps the stable playback cue set only. Mask and calibration, and app_quit stay on HTTP. /sys/shutdown and /sys/reboot are rejected. The player does not download files.

Address root

Stable OSC addresses only use the short QLab-friendly root:

/player/<action>

Legacy long-root prefixes and old load / seek / seek_abs aliases are removed — they are rejected as unknown addresses. Use prepare, play_media and seek_sec instead.

Address → command

Address	Tags	Command
`/player/prepare`	`s`, `sfi`, or `sii`	`load` (ready/paused)
`/player/play_media`	`s`, `sfi`, or `sii`	`play_media` (play when ready)
`/player/play`	—	`play`
`/player/pause`	—	`pause`
`/player/stop`	—	`stop`
`/player/cue`	—	`cue`
`/player/seek_sec`	`f` or `i`	`seek` (`position_sec`, non-negative)
`/player/volume`	`f` or `i`	`volume_set` (float 0–1; integer 0 or 1)
`/player/mute`	`i`	`mute_set`
`/player/loop`	`i`	`loop_set`

`prepare` / `play_media` parameters

Tags	Arguments	Equivalent load
`s`	source	`cue_position_sec=0`, `loop=false`
`sfi`	source, cue position (float), loop (int)	loop: `0=false`, non-zero `=true`
`sii`	source, cue position (int), loop (int)	cue position is non-negative integer seconds; same loop rule

Only s, sfi, and sii are accepted. si, sf, and other signatures are rejected. Numeric arguments use 32-bit OSC integers (i) or floats (f); 64-bit types and boolean T/F tags are not accepted. For mute and loop, integer zero means false and any non-zero integer means true.

Send one OSC message per datagram. Bundles, wildcard addresses, and trailing bytes are rejected.

Example single-cue playback from QLab:

/player/play_media  "main-show.mp4"  30.0  0

Replies

Address	Tags	When
`/player/error`	`s`	Immediate parsing / validation / unknown-address failure — `CODE: message`

Error replies go to the sender's source IP and UDP source port. Packets blocked by the configured source policy are dropped silently. Error replies do not report later media-loading or playback failures.

Playback cues are fire-and-forget at the OSC layer (canReply=false). OSC never returns playback status and does not publish status updates; use optional HTTP status polling.

Integration tips

TouchDesigner: OSC Out CHOP / DAT
QLab: OSC cue → player-ip:18290 — prefer play_media over load+wait+play
Python: python-osc

Command Reference (switch to OSC)
Choose a transport · HTTP