OSC Protocol

Open Sound Control (OSC) is a message-based protocol used in media servers, show controllers, and creative applications. Use OSC to send variable values and timeline playback commands to WATCHOUT from any OSC-capable device or software.

Enabling OSC

Enable OSC from the Nodes window (Node Info → Protocols, OSC toggle).

Connection Details

WATCHOUT listens for OSC on two ports at the same time, over both UDP and TCP:

  • UDP port 8000 — Standard OSC over UDP. Most OSC controllers use this transport by default.
  • TCP port 8001 — OSC over TCP with length-prefixed framing. Useful for reliable delivery over lossy networks.

Both ports bind to all network interfaces (0.0.0.0). The node accepts OSC messages from any reachable device on the network.

Variable Input via OSC

Any OSC message that does not match a playback control pattern is treated as a variable input. The OSC address and argument index form the external key that maps to a WATCHOUT variable.

The key format is:

osc.addr({address}/{argument_index})

The argument index starts at 0. Sending an OSC message to address /stage/brightness with a single float argument produces the key:

osc.addr(/stage/brightness/0)

If the message carries multiple arguments, each argument gets its own key with an incrementing index:

  • Argument 0: osc.addr(/stage/color/0)
  • Argument 1: osc.addr(/stage/color/1)
  • Argument 2: osc.addr(/stage/color/2)

Supported Value Types

WATCHOUT accepts these OSC argument types:

  • Float (f) — Used directly as the variable value.
  • Int (i) — Converted to a floating-point value.

Other OSC types, such as string and blob, produce an error.

Playback Control via OSC

WATCHOUT also controls timeline playback through OSC messages with the /wo/ address prefix. The supported patterns are:

  • /wo/play/{timeline_id} — Start playback of the timeline.
  • /wo/run/{timeline_id} — Same as play.
  • /wo/pause/{timeline_id} — Pause the timeline.
  • /wo/stop/{timeline_id} — Stop the timeline.

The timeline_id is a numeric identifier (for example, 1 or 2).

Jumping to a cue: Add a cue ID as a third path segment. Playback jumps to that cue's start:

/wo/play/{timeline_id}/{cue_id}

Jumping to a time: Instead of a cue ID, include a time position as an OSC argument:

  • Float argument — Interpreted as seconds (for example, 10.5 = 10 seconds 500 milliseconds).
  • Int argument — Interpreted as milliseconds (for example, 10500 = 10 seconds 500 milliseconds). The value must be non-negative.

For example, send /wo/play/1 with a float argument of 5.0 to start timeline 1 at the 5-second mark.

OSC bundles are not supported. Send each message individually.

Interpolation

OSC variable inputs use the default 50 ms interpolation window. See External Control Overview for how interpolation works. WATCHOUT timestamps each OSC message at the receiver before forwarding it to the Director.

Testing OSC

Test WATCHOUT's OSC input with tools such as:

  • A control-surface app that sends OSC from a tablet or phone.
  • An OSC monitoring tool that can also send messages.
  • A command-line OSC utility for sending test messages.
  • An OSC library for your programming language (available for most languages).

Use Cases

  • Show control — Send OSC cues from a show controller to set WATCHOUT variables and trigger timeline playback.
  • Custom control surfaces — Build tablet-based surfaces with faders, buttons, and XY pads mapped to WATCHOUT variables.
Previous Next