OSC API Reference
The complete address specification for the FXCanvas OSC API. For setup, enabling the listener, and a TouchOSC walkthrough, see the OSC API guide. This page is the exhaustive reference: every address, its argument type, value range, and the query/reply protocol.
Conventions
| Topic | Detail |
|---|---|
| Transport | UDP. FXCanvas listens on one port (default 9000, configurable 1024–65535). |
| Reply port | Replies are sent to the sender's IP on listening port + 1 (default 9001). The reply target is locked in from the first message FXCanvas receives. |
| License | The OSC API is a licensed feature — the listener refuses to start in the free tier. |
| Indexing | All indices are 1-based — index 1 is the first item, whether passed in the path (/palette/1) or as an argument (/palette/index 1). |
| Name matching | In a path, _ and - are converted to spaces and matched case-insensitively against the display name. /palette/ocean_blue and /palette/ocean-blue both match "Ocean Blue". |
| Trigger gate | For next / previous / go addresses: if you pass an argument, the action fires only when the value is > 0.5 (so a button's release at 0 is ignored). With no argument, it fires immediately. |
| Argument types | OSC type tags below: f = float32, i = int32, s = string. Send floats as floats and ints as ints — type matters. |
Only the /source, /palette, /cue, and /global namespaces are handled natively. Any other address (e.g. one for an effect, BPM, or output) is forwarded to the control-mapping engine and can be learned onto any action — see Controlling Anything Else.
Sources
Select the active source type.
| Address | Args | Notes |
|---|---|---|
/source/{name} | — | Select by type name (e.g. /source/plasma). |
/source/{N} | — | Select by 1-based index in the path (e.g. /source/3). |
/source/index | i | Select by 1-based index argument. |
/source/next | f/i (optional) | Advance to the next source (wraps). |
/source/previous | f/i (optional) | Go to the previous source (wraps). |
/source/list | — | Query all source types — see Query and Reply. |
Source Presets
Load a saved source preset (source type plus its parameter values).
| Address | Args | Notes |
|---|---|---|
/source/preset/{name} | — | Select by preset name (e.g. /source/preset/ocean_waves). |
/source/preset/{N} | — | Select by 1-based index in the path. |
/source/preset/index | i | Select by 1-based index argument. |
/source/preset/list | — | Query all presets — returns name and source type per item. |
Palettes
Select the active color palette.
| Address | Args | Notes |
|---|---|---|
/palette/{name} | — | Select by palette name (e.g. /palette/sunset). |
/palette/{N} | — | Select by 1-based index in the path. |
/palette/index | i | Select by 1-based index argument. |
/palette/next | f/i (optional) | Advance to the next palette (wraps). |
/palette/previous | f/i (optional) | Go to the previous palette (wraps). |
/palette/list | — | Query all palettes. |
Cues
Trigger cues by name, index, or cue number. Triggering a cue loads its complete state.
| Address | Args | Notes |
|---|---|---|
/cue/{name} | — | Trigger by cue name (e.g. /cue/intro_scene). |
/cue/{N} | — | Trigger by 1-based index in the path. |
/cue/index | i | Trigger by 1-based index argument. |
/cue/number | f | Trigger by cue number, including fractional cues (e.g. 1.5). Matched exactly. |
/cue/next | f/i (optional) | Advance to the next cue (wraps). |
/cue/previous | f/i (optional) | Go to the previous cue (wraps). |
/cue/go | f/i (optional) | Re-trigger the current cue. |
/cue/list | — | Query all cues — returns cue number and name per item. |
Global Controls
Master output controls applied to the whole composition.
| Address | Args | Range | Description |
|---|---|---|---|
/global/dimmer | f | 0.0 – 1.0 | Master brightness (0 = black, 1 = full). Clamped. |
/global/hue | f | -1.0 – 1.0 | Hue shift around the color wheel. Clamped. |
/global/saturation | f | 0.0 – 2.0 | Saturation (1.0 = normal, 0 = grayscale). Clamped. |
/global/blackout | i | 0 or 1 | 1 stores the current dimmer and drops to black; 0 restores it. |
/global/reset/canvas | — | — | Reset dimmer, hue, saturation, mirrors, and blackout. |
/global/reset/source | — | — | Reset source global direction and speed overrides. |
Setting /global/dimmer to a value above 0 while blacked out automatically exits blackout, restoring manual control.
Mirror Controls
| Address | Args | Description |
|---|---|---|
/global/mirror/x | i (0/1) | Horizontal mirror on/off. |
/global/mirror/y | i (0/1) | Vertical mirror on/off. |
/global/mirror/both | i (0/1) | Set both horizontal and vertical mirror together. |
Query and Reply Protocol
The /list addresses make FXCanvas reply with the current contents of each collection — ideal for building dynamic control surfaces (for example, a TouchOSC layout that labels its buttons from the live cue list). Each query replies with one count message followed by one message per item, sent to the sender's IP on the reply port (listening port + 1).
/source/list
/source/list/count <i count>
/source/list/item <i index(1-based)> <s name>
/source/preset/list
/source/preset/list/count <i count>
/source/preset/list/item <i index> <s name> <s sourceType>
/palette/list
/palette/list/count <i count>
/palette/list/item <i index> <s name>
/cue/list
/cue/list/count <i count>
/cue/list/item <i index> <f cueNumber> <s name>
Example exchange — your controller sends /cue/list, FXCanvas replies on port 9001:
→ /cue/list
← /cue/list/count 3
← /cue/list/item 1 1.0 "Intro Scene"
← /cue/list/item 2 1.5 "Build"
← /cue/list/item 3 2.0 "Chorus"
Replies go to the listening port + 1 (9000 → 9001), not back to the listening port. Configure your controller's incoming port to match. The reply destination is fixed to the first sender FXCanvas hears from after the listener starts.
In TouchOSC (or similar), send the /list query on connect, parse the …/count and …/item replies, and populate button labels and ranges from the result. Combine with index-based triggers (/cue/index, /palette/index) so the layout keeps working even as the underlying content changes.
Controlling Anything Else
The native namespaces above cover sources, palettes, cues, and global output. Anything not matched — an effect parameter, tap tempo, an output toggle, a specific source slider — is forwarded to the FXCanvas control-mapping engine, where it can be bound to any action with OSC Learn:
- Open Edit → Settings → Shortcuts
- Click New Mapping, then select the action (click the highlighted control, or pick it from the list)
- Send the OSC message you want to use — it's captured and bound
This means the entire action catalog — global controls, BPM, outputs, sources, presets, palettes, cues, every source and effect parameter, effect selection, and media files — is reachable over OSC, even though only a subset has fixed addresses. Bound OSC mappings also support behaviors and value scaling (e.g. mapping an OSC fader 0.0–1.0 onto hue 0–360).
See MIDI Mapping for the full mapping workflow, the behavior modes, and the complete list of mappable actions — OSC, MIDI, keyboard, and REST all share the same action catalog and profiles.
Value Reference
Common ranges, and the mistakes that trip people up:
| Control | Correct range | Type | Common mistake |
|---|---|---|---|
| Dimmer | 0.0 – 1.0 | f | Sending 0–100 or 0–255 |
| Hue | -1.0 – 1.0 | f | Sending 0–360 |
| Saturation | 0.0 – 2.0 | f | Sending 0–100 |
| Blackout / Mirror | 0 or 1 | i | Sending true/false strings |
| Indices | ≥ 1 | i | Using 0-based indices |
| Cue number | exact match | f | Confusing cue number (1.5) with cue index (2) |
Complete Address Index
# Sources
/source/list
/source/index i (1-based)
/source/{name} (e.g. /source/plasma)
/source/{N} (1-based path index)
/source/next [f/i] (>0.5, or no arg)
/source/previous [f/i]
# Source presets
/source/preset/list
/source/preset/index i (1-based)
/source/preset/{name} (e.g. /source/preset/ocean_waves)
/source/preset/{N} (1-based path index)
# Palettes
/palette/list
/palette/index i (1-based)
/palette/{name} (e.g. /palette/sunset)
/palette/{N} (1-based path index)
/palette/next [f/i]
/palette/previous [f/i]
# Cues
/cue/list
/cue/index i (1-based)
/cue/number f (e.g. 1.5)
/cue/{name} (e.g. /cue/intro_scene)
/cue/{N} (1-based path index)
/cue/next [f/i]
/cue/previous [f/i]
/cue/go [f/i]
# Global
/global/dimmer f (0.0-1.0)
/global/hue f (-1.0-1.0)
/global/saturation f (0.0-2.0)
/global/blackout i (0/1)
/global/reset/canvas
/global/reset/source
/global/mirror/x i (0/1)
/global/mirror/y i (0/1)
/global/mirror/both i (0/1)
# Reply messages (sent to sender IP on port+1)
/source/list/count i
/source/list/item i s
/source/preset/list/count i
/source/preset/list/item i s s
/palette/list/count i
/palette/list/item i s
/cue/list/count i
/cue/list/item i f s
Related Topics
- OSC API — setup, enabling the listener, testing, and TouchOSC integration
- MIDI Mapping — bind any OSC address to any action with OSC Learn
- Shows and Cues — the cues you trigger over OSC
- Log Viewer — watch incoming OSC traffic (filter by the API source)