video-shader-toys/docs/OSC_CONTROL.md

OSC Control

Video Shader Toys can listen for local OSC messages and map them onto shader layer parameters.

Configuration

Set the UDP port in config/runtime-host.json:

{
  "oscPort": 9000
}

Set oscPort to 0 to disable the OSC listener.

Address Pattern

Send OSC messages to:

/VideoShaderToys/{LayerNameOrID}/{ParameterNameOrID}

Examples:

/VideoShaderToys/layer-1/brightness
/VideoShaderToys/VHS/intensity
/VideoShaderToys/TemporalLowFPS/frameRate
/VideoShaderToys/fisheye-reproject/panDegrees
/VideoShaderToys/video-transform/pan

Layer keys are resolved against:

• Layer ID, such as layer-1
• Shader package ID, such as vhs
• Shader display name, such as VHS

Parameter keys are resolved against:

• Parameter ID from shader.json
• Parameter label from shader.json

Matching is exact first. If that fails, names are compared in a simplified form that ignores spaces, underscores, hyphens, and casing.

If multiple layers use the same shader package ID or display name, the first matching layer in the stack is controlled. Use the internal layer ID shown in the UI when you need to target one duplicate layer precisely.

In the control UI, each parameter row has a small OSC button. Clicking it copies that parameter's exact OSC address to the clipboard, which is the safest way to target controls with long names or duplicate shader layers.

Values

The listener accepts these OSC argument types:

• f: float
• d: double
• i: integer
• s: string
• T / F: boolean true/false

Single-argument messages become scalar JSON values. Multi-argument messages become JSON arrays, which lets OSC drive vec2 and color parameters.

Examples:

/VideoShaderToys/fisheye-reproject/panDegrees 45.0
/VideoShaderToys/fisheye-reproject/fisheyeModel "equisolid"
/VideoShaderToys/video-transform/pan 0.25 -0.5
/VideoShaderToys/safe-area-guides/lineColor 1.0 0.8 0.1 1.0

Values are validated with the same shader parameter rules used by the REST API. Invalid values or unknown addresses are ignored and reported to the native debug output.

For trigger parameters, the OSC value is treated as a pulse. A simple integer or boolean message is enough:

/VideoShaderToys/trigger-flash/flash 1

Open Stage Control

For simple scalar controls, set the widget address and target directly:

{
  "address": "/VideoShaderToys/fisheye-reproject/panDegrees",
  "target": "127.0.0.1:9000",
  "decimals": "2f"
}

For an XY pad controlling a vec2 parameter, send two float arguments in onValue:

var x = Array.isArray(value) ? Number(value[0]) : 0;
var y = Array.isArray(value) ? Number(value[1]) : 0;
send(
  '127.0.0.1:9000',
  '/VideoShaderToys/video-transform/pan',
  {type: 'f', value: x},
  {type: 'f', value: y}
);

For an XY pad controlling two separate scalar parameters:

var pan = Array.isArray(value) ? Number(value[0]) : 0;
var tilt = Array.isArray(value) ? Number(value[1]) : 0;
send('127.0.0.1:9000', '/VideoShaderToys/fisheye-reproject/panDegrees', {type: 'f', value: pan});
send('127.0.0.1:9000', '/VideoShaderToys/fisheye-reproject/tiltDegrees', {type: 'f', value: tilt});

Network

The listener binds to localhost only:

127.0.0.1:<oscPort>

This keeps the control surface local to the machine running Video Shader Toys.