Resolume — REST & WebSocket

OSC is for performance (low-latency triggers, faders, scrub). Resolume's REST + WebSocket API is for state and configuration (loading decks, querying clip names, adding layers, retrieving thumbnails). You'll typically use both.

This page is the verified surface area, drawn from resolume.com/support/en/{restapi,websocket-api} and live-instance behaviour.

Default endpoints

| Product | TCP port | Default bind |
|---|---|---|
| Arena & Avenue | 8080 | 0.0.0.0 (any interface) |
| Wire | 8081 | 0.0.0.0 |

You can lock the bind address to 127.0.0.1 in Resolume's preferences if you don't want the API exposed on the LAN.

The HTTP base URL is http://<host>:<port>. The static reference is at <https://resolume.com/docs/restapi/>. The live OpenAPI/Swagger spec on a running instance is exposed at:

http://<host>:<port>/api/v1/docs/swagger.json

Fetch this on boot and drive your integration off it — Resolume mints new dynamic endpoints whenever you add an effect to a composition, so a hard-coded path table will rot. Hard-code only the stable skeleton (layers / clips / columns / decks / opacity / connect / bpm); discover the rest at runtime.

What the REST API can do

From the official capability list:

• Add / remove / clear columns, layers, groups
• Manage effects on the composition, groups, layers, and clips
• Retrieve clip thumbnails
• List all available effects and sources
• Subscribe to changes to the composition and parameters via WebSocket

REST verb conventions

Two patterns, both verified:

Trigger a clip — POST

Triggering is an action, not a state replacement:

POST /api/v1/composition/layers/1/clips/3/connect
POST /api/v1/composition/columns/4/connect

No request body required.

Update a parameter — PUT

You replace that parameter's state. The body is flat — no wrapper, just {"value": …}:

PUT /api/v1/composition/layers/1/video/opacity
Content-Type: application/json
{"value": 0.75}

Same shape for any leaf parameter — opacity, scale, an effect value, BPM, etc.

WebSocket — the recommended integration surface

The WebSocket lives at the same port as REST:

ws://<host>:<port>/api/v1

So Arena/Avenue is ws://127.0.0.1:8080/api/v1 by default.

Use the WebSocket for everything that isn't an initial bulk fetch. Polling REST during a live set is the wrong move — Resolume runs the API on a single thread and a tight poll loop will steal cycles from playback. Subscribe via WS and let Resolume push state to you instead.

Message shape

Every message is JSON. The basic envelope is:

{
  "action":    "subscribe | unsubscribe | set | get | reset | trigger | post | remove",
  "parameter": "/composition/layers/1/video/opacity",
  "value":     0.5
}

Action names are always lowercase.

Parameter paths come in two flavours:

• Logical path — /composition/columns/1/name, /composition/layers/2/clips/3/connect. Same as REST paths but without the /api/v1 prefix.
• By-id path — /parameter/by-id/<paramId>. The composition tree exposes a numeric ID for every parameter; this form is stable across renames but requires a tree query first.

Triggering a clip (WS)

{ "action": "trigger", "parameter": "/composition/layers/1/clips/3/connect" }

Setting a value (WS)

{ "action": "set", "parameter": "/composition/layers/1/video/opacity", "value": 0.5 }

Subscribing to live updates

{ "action": "subscribe", "parameter": "/composition/layers/1/video/opacity" }

Resolume then pushes update messages whenever that parameter changes:

{ "type": "parameter_update", "path": "/composition/layers/1/video/opacity", "value": 0.42 }

Response type values: parameter_subscribed, parameter_unsubscribed, parameter_get, parameter_set, parameter_update.

Creating things (post / remove)

post and remove use a slightly different envelope with a path and an optional id and body:

{ "action": "post", "id": "my_new_layer", "path": "/composition/layers/add" }

Choosing OSC vs. WebSocket vs. REST

| Use case | Protocol |
|---|---|
| Fire a clip from a button press | OSC |
| Scrub a clip with a slider | OSC (with throttling) |
| Tap-tempo / BPM nudge | OSC |
| Switch decks | OSC or WebSocket |
| Mirror a Resolume parameter into XOSC | WebSocket subscribe |
| Read clip names / composition tree on startup | REST (one-shot bulk fetch) |
| Get a clip's thumbnail | REST |
| Add or remove a layer programmatically | WebSocket post/remove |
| Discover dynamic endpoints (effects, custom params) | REST /api/v1/docs/swagger.json |

Throttling

Both OSC and the WebSocket pipelines hit Resolume's single API thread. For continuous-value updates (MIDI CC, gamepad axis, slider scrub), throttle each host:port:address key to 20–30ms in your sender. 60Hz is the maximum useful rate; 30Hz is fine for nearly everything.

Roadmap inside XOSC

XOSC v0.1 ships only the OSC output node. v0.2 will add a Resolume WebSocket output node with these inspector fields:

• URL (default ws://127.0.0.1:8080/api/v1)
• Action (trigger | set | subscribe)
• Parameter (logical path, paste from Resolume's Shortcuts panel)
• Value (only for set)