aiden/video-shader-toys
1
0
Fork 0
Code Issues Pull Requests Actions Releases 5 Wiki Activity
Page: REST API
Pages
Home Making Shaders OSC Control Operator Interface REST API Runtime Host Configuration Shader 3D LUT Apply Shader Anamorphic Desqueeze Shader Balatro Swirl Shader Black and White Shader Broken Shader Example Shader Composition Guides Shader DVD Bounce Shader Data Mosh Shader Ether Shader False Color Shader Fisheye Equirectangular Mirror Shader Fisheye Reproject Shader Gaussian Blur Shader Greenscreen Key Shader Happy Accident Shader Lift Gamma Gain Shader Multipass Test Shader Pixelate Shader SMPTE Color Bars Shader Safe Area Guides Shader Singularity Shader Solid Color Shader Temporal Echo Shader Temporal Ghost Trail Shader Temporal Low FPS Shader Text Overlay Shader Trigger Ripple Shader UTC Clock Shader VHS Shader Video Cube Shader Video Transform Shader Waveform Overlay Shader XYLA Exposure Chart Shaders
Clone
2
REST API
Aiden edited this page 2026-05-08 19:03:26 +10:00
Table of Contents

REST API

The native host exposes a local REST API on the same server as the browser UI.

Default base URL:

http://127.0.0.1:8080

The API is intended for local automation, custom control panels, and the bundled React UI. Mutating requests return:

{ "ok": true }

Failures return:

{ "ok": false, "error": "Reason here." }

Interactive Docs

When the host is running:

http://127.0.0.1:<serverPort>/docs

The OpenAPI spec is served at:

http://127.0.0.1:<serverPort>/docs/openapi.yaml
http://127.0.0.1:<serverPort>/openapi.yaml

The repository copy is:

docs/openapi.yaml

State

GET /api/state

Returns the full runtime state: app config, runtime status, video status, video I/O status, performance, available shaders, stack presets, and active layers. The older decklink status object may still be present for compatibility, but new clients should prefer videoIO.

Shader summaries include available and error, so a tool can show packages that exist but failed manifest or compile validation.

WebSocket State Stream

Connect to:

ws://127.0.0.1:<serverPort>/ws

The server sends full runtime state JSON when a client connects and whenever state changes. Use this for live control surfaces that need to stay in sync without polling.

Layer Endpoints

Endpoint Body Purpose
POST /api/layers/add { "shaderId": "vhs" } Add a layer using an available shader package.
POST /api/layers/remove { "layerId": "layer-1" } Remove a layer.
POST /api/layers/move { "layerId": "layer-1", "direction": -1 } Move up or down by signed direction.
POST /api/layers/reorder { "layerId": "layer-1", "targetIndex": 0 } Move to an absolute stack index.
POST /api/layers/set-bypass { "layerId": "layer-1", "bypass": true } Set bypass state.
POST /api/layers/set-shader { "layerId": "layer-1", "shaderId": "video-transform" } Change a layer's shader.
POST /api/layers/reset-parameters { "layerId": "layer-1" } Reset layer parameters to defaults.

Update Parameter

POST /api/layers/update-parameter

Body:

{ "layerId": "layer-1", "parameterId": "brightness", "value": 1.25 }

The value type depends on the shader parameter:

Parameter Type JSON Value
float number
vec2 [x, y]
color [r, g, b, a]
bool boolean
enum string option value
text string
trigger number, usually incremented or pulsed

Stack Presets

Endpoint Body Purpose
POST /api/stack-presets/save { "presetName": "live-show-look" } Save current stack.
POST /api/stack-presets/load { "presetName": "live-show-look" } Load a saved stack.

Runtime Actions

Reload Shaders

POST /api/reload

Body:

{}

This rescans the shader library, re-reads manifests, queues shader compilation, and refreshes shader availability/errors.

Queue Screenshot

POST /api/screenshot

Body:

{}

This captures the next completed final output render target and writes a PNG under:

runtime/screenshots/

Successful mutating requests broadcast the updated state over /ws when state changes.