141 lines
4.7 KiB
Markdown
141 lines
4.7 KiB
Markdown
# OSC Control
|
|
|
|
This is the intended OSC control contract, but OSC ingress is not wired in the current `RenderCadenceCompositor` native host yet. The native host has an OSC service stub that consumes config and reports status in `/api/state`; it does not open a UDP listener or dispatch messages yet. Use the REST layer parameter endpoints or the control UI for live parameter changes today.
|
|
|
|
## Configuration
|
|
|
|
Set the UDP port in `config/runtime-host.json`:
|
|
|
|
```json
|
|
{
|
|
"oscBindAddress": "127.0.0.1",
|
|
"oscPort": 9000,
|
|
"oscSmoothing": 0.18
|
|
}
|
|
```
|
|
|
|
Today, `oscPort: 0` marks the OSC stub disabled and any nonzero port marks it configured but not listening. When OSC ingress is implemented, `oscBindAddress: "127.0.0.1"` should keep OSC local to the host, and `oscBindAddress: "0.0.0.0"` should listen on all IPv4 interfaces. `oscSmoothing` is reserved for a per-frame easing amount on numeric OSC controls.
|
|
|
|
## Address Pattern
|
|
|
|
Send OSC messages to:
|
|
|
|
```text
|
|
/VideoShaderToys/{LayerNameOrID}/{ParameterNameOrID}
|
|
```
|
|
|
|
Examples:
|
|
|
|
```text
|
|
/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.
|
|
|
|
OSC updates are coalesced by target route and applied once per render tick, so rapid controller motion does not force one runtime mutation, disk write, and UI push per incoming UDP packet. Numeric OSC controls can also be slightly smoothed with `oscSmoothing`.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
/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.
|
|
|
|
OSC-driven parameter changes are not autosaved to `runtime/runtime_state.json`. Stack edits made through the UI and preset operations still persist as before. Smoothing only applies to numeric controls such as floats, `vec2`, and `color`; booleans, enums, text, and triggers stay immediate.
|
|
|
|
For `trigger` parameters, the OSC value is treated as a pulse. A simple integer or boolean message is enough:
|
|
|
|
```text
|
|
/VideoShaderToys/trigger-flash/flash 1
|
|
```
|
|
|
|
## Open Stage Control
|
|
|
|
For simple scalar controls, set the widget address and target directly:
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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
|
|
|
|
By default the listener binds to localhost only:
|
|
|
|
```text
|
|
127.0.0.1:<oscPort>
|
|
```
|
|
|
|
This keeps the control surface local to the machine running Video Shader Toys.
|
|
|
|
To accept OSC from other machines on the network, set:
|
|
|
|
```json
|
|
{
|
|
"oscBindAddress": "0.0.0.0",
|
|
"oscPort": 9000
|
|
}
|
|
```
|
|
|
|
That listens on all IPv4 interfaces, so make sure your firewall and network are configured appropriately.
|