XOSC
← All docs
Resolume

Resolume — parameter picker & live previews

Both Resolume Out and Resolume In nodes ship with a live composition picker, so instead of memorising paths like /composition/layers/2/clips/3/connect, you can browse Resolume's actual layers, clips, columns, decks, and parameters and pick the one you mean.

How it works under the hood

XOSC's main process talks to Resolume over loopback at http://<host>:<port>/api/v1. When you open the picker for the first time, XOSC issues:

GET /api/v1/composition

Resolume responds with the full composition tree — every layer, clip, column, deck, video block, audio block, and effect, plus every parameter on each (with current value, type, min/max, and choice options where applicable). XOSC walks the tree once and flattens it into a searchable list of paths. The result is cached per host:port so subsequent opens of the picker (on the same target) are instant.

The picker is paired with the WebSocket bridge already wired up in earlier versions. Once you pick a path:

  • Resolume Out sends trigger / set / reset actions over the multiplexed ws://host:port/api/v1 connection, throttled per-stream for continuous values.
  • Resolume In issues subscribe and re-emits each parameter_update frame on XOSC's input bus, so the rest of the mapping graph treats it like any other input source.

Picker controls

Open the dropdown chevron next to any Resolume parameter field:

  • Search box — type to filter by partial path or label. Tokens are AND'd, so layer 1 opac matches Layer 1 / Video / opacity.
  • Refresh button — re-fetch the composition from Resolume. Use this after you add layers / clips / effects, since the cached tree from the last load won't reflect the new structure.
  • Filter — the picker on Resolume Out narrows to triggers when Action = trigger and to parameters otherwise. Resolume In always shows parameters.
  • Manual entry — the text field above the dropdown still accepts hand-typed paths, including by-id paths like /parameter/by-id/123. Press <span class="kbd">Enter</span> or <span class="kbd">Tab</span> to commit.

Live clip previews

When the selected path is a clip endpoint (/composition/layers/{N}/clips/{M} or any sub-parameter underneath one), XOSC fetches the thumbnail from:

GET /api/v1/composition/layers/{N}/clips/{M}/thumbnail

You'll see the preview in three places:

1. Inside the dropdown row, when you hover a clip in the picker — XOSC fetches the thumbnail lazily on hover.
2. Below the parameter field in the inspector, once a clip path is selected.
3. On the node body itself in the canvas, so you can see at a glance which clip a Resolume Out triggers.

When the WebSocket bridge is connected (open), the on-node thumbnail polls every ~1.5 seconds — Resolume regenerates the thumbnail when the clip is repainted, so the preview feels live without saturating the API thread. When the connection is closed or in error, polling stops automatically.

Why not NDI for true 60 fps previews?

Some Resolume integrations (Bitfocus Companion-style controllers) can show buttery-smooth live video by enabling NDI output in Resolume and using an NDI receiver to grab the actual video stream. That works, but:

  • It needs Resolume's NDI output enabled — extra config the user has to do.
  • It pulls a live video frame even when nothing on the surface is interacting with that clip.
  • Bridging an NDI receiver into a Chromium renderer is a non-trivial native dependency.
XOSC sticks to thumbnails over REST. The polled-thumbnail "live feel" is plenty for a mapping UI, and the implementation is one HTTP GET per slot per second — comfortably below Resolume's API thread budget.

Discovering custom endpoints

Resolume mints new dynamic API endpoints whenever you add an effect (each effect's parameters get their own paths). The composition tree fetch already covers these: every effect parameter shows up under its host layer/clip with its value type, range, and choice options when applicable.

If you'd rather work from the canonical OpenAPI spec, Resolume exposes it on the live instance at:

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

That's the same source the static reference at <https://resolume.com/docs/restapi/> is generated from, but it stays in sync with whatever effects and dynamic params are loaded right now. XOSC's picker doesn't require this — the composition tree carries everything we need — but it's the right resource if you're scripting Resolume from outside XOSC.