OSC API Reference
This page is the complete address specification for the FXCanvas OSC API. It gives every address, its argument type, its value range, and the query and reply protocol. For setup, for how to enable the listener, and for a TouchOSC walkthrough, see the OSC API guide.
Conventions
| Topic | Detail |
|---|---|
| Transport | UDP. FXCanvas listens on one port. The default is 9000, and you can set any port in the range 1024–65535. |
| Reply port | FXCanvas sends replies to the sender's IP on listening port + 1 (default 9001). The first message FXCanvas receives sets the reply target. |
| License Pro | OSC control needs a license. In the free tier, the listener does not start, and FXCanvas drops outgoing messages. See What requires a license. |
| Indexing | All indices are 1-based. Index 1 is the first item, both in the path (/palette/1) and as an argument (/palette/index 1). |
| Name matching | In a path, FXCanvas converts _ and - to spaces. It matches the result against the display name, and the match is case-insensitive. /palette/ocean_blue and /palette/ocean-blue both match "Ocean Blue". |
| Trigger gate | For the next, previous, and go addresses: if you send an argument, the action fires only for a value > 0.5. A button release at 0 does nothing. With no argument, the action fires at once. |
| Argument types | The OSC type tags in this page are f = float32, i = int32, and s = string. Send a float as a float, and an int as an int. The type is important. |
FXCanvas handles the /source, /palette, /cue, and /global namespaces natively. It forwards any other address to the control-mapping engine, for example an address for an effect, the BPM, or an output. You can then learn that address onto any action. See Controlling Anything Else.
Sources
These addresses select the active source type.
| Address | Args | Notes |
|---|---|---|
/source/{name} | — | Selects the source by type name (for example /source/plasma). |
/source/{N} | — | Selects by 1-based index in the path (for example /source/3). |
/source/index | i | Selects by a 1-based index argument. |
/source/next | f/i (optional) | Goes to the next source. It wraps at the end. |
/source/previous | f/i (optional) | Goes to the previous source. It wraps at the start. |
/source/list | — | Queries all source types. See Query and Reply. |
Source Presets
These addresses load a saved source preset. A preset holds the source type plus its parameter values.
| Address | Args | Notes |
|---|---|---|
/source/preset/{name} | — | Selects the preset by name (for example /source/preset/ocean_waves). |
/source/preset/{N} | — | Selects by 1-based index in the path. |
/source/preset/index | i | Selects by a 1-based index argument. |
/source/preset/list | — | Queries all presets. Each item gives the name and the source type. |
Palettes
These addresses select the active color palette.
| Address | Args | Notes |
|---|---|---|
/palette/{name} | — | Selects the palette by name (for example /palette/sunset). |
/palette/{N} | — | Selects by 1-based index in the path. |
/palette/index | i | Selects by a 1-based index argument. |
/palette/next | f/i (optional) | Goes to the next palette. It wraps at the end. |
/palette/previous | f/i (optional) | Goes to the previous palette. It wraps at the start. |
/palette/list | — | Queries all palettes. |
Cues
These addresses trigger a cue by name, by index, or by cue number. When you trigger a cue, FXCanvas loads the complete state of that cue.
| Address | Args | Notes |
|---|---|---|
/cue/{name} | — | Triggers the cue by name (for example /cue/intro_scene). |
/cue/{N} | — | Triggers by 1-based index in the path. |
/cue/index | i | Triggers by a 1-based index argument. |
/cue/number | f | Triggers by cue number. A fractional cue number works (for example 1.5). The match is exact. |
/cue/next | f/i (optional) | Recalls the next cue by cue number. The step is relative to the current cue and does not wrap. At the last cue, nothing happens. |
/cue/previous | f/i (optional) | Recalls the previous cue by cue number. It does not wrap. At the first cue, nothing happens. |
/cue/go | f/i (optional) | Triggers the current cue again. |
/cue/list | — | Queries all cues. Each item gives the cue number and the name. |
Global Controls
These are the master output controls for the whole composition.
| Address | Args | Range | Description |
|---|---|---|---|
/global/dimmer | f | 0.0 – 1.0 | Master brightness (0 = black, 1 = full). FXCanvas clamps the value. |
/global/hue | f | -1.0 – 1.0 | Hue shift around the color wheel. FXCanvas clamps the value. |
/global/saturation | f | 0.0 – 2.0 | Saturation (1.0 = normal, 0 = grayscale). FXCanvas clamps the value. |
/global/blackout | i | 0 or 1 | 1 stores the current dimmer and goes to black. 0 restores the dimmer. |
/global/reset/canvas | — | — | Resets the dimmer, hue, saturation, mirrors, and blackout. |
/global/reset/source | — | — | Resets the global overrides for source direction and source speed. |
If you send /global/dimmer with a value above 0 during blackout, FXCanvas ends the blackout. Manual control of the dimmer returns.
Mirror Controls
| Address | Args | Description |
|---|---|---|
/global/mirror/x | i (0/1) | Enables or disables the horizontal mirror. |
/global/mirror/y | i (0/1) | Enables or disables the vertical mirror. |
/global/mirror/both | i (0/1) | Enables or disables the horizontal mirror and the vertical mirror together. |
Query and Reply Protocol
The /list addresses make FXCanvas reply with the current contents of a collection. A dynamic control surface uses these replies, for example a TouchOSC layout that labels its buttons from the live cue list. Each query gets one count message, and then one message for each item. FXCanvas sends the replies to the IP of the sender, 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 — the controller sends /cue/list, and 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 to the listening port. Set the incoming port of your controller to that port. FXCanvas fixes the reply destination on the first sender it hears after the listener starts.
In TouchOSC, or in a similar tool, send the /list query when the controller connects. Then read the …/count and …/item replies. Fill the button labels and ranges from those replies. Use index-based triggers (/cue/index, /palette/index), so that the layout still works after the content changes.
Controlling Anything Else
The native namespaces in this page cover sources, palettes, cues, and global output. FXCanvas forwards every other address to the control-mapping engine. Examples are an effect parameter, tap tempo, an output toggle, and one source slider. In that engine you can bind the address to any action with OSC Learn:
- Open Edit → Settings → Shortcuts
- Click New Mapping. Then select the action: click the highlighted control, or select the action in the list
- Send the OSC message that you want to use. FXCanvas captures the message and binds it to the action
In this way OSC reaches the entire action catalog: global controls, BPM, outputs, sources, presets, palettes, cues, every source and effect parameter, effect selection, and media files. Only a part of that catalog has a fixed address. A bound OSC mapping also supports behaviors and value scaling, for example an OSC fader 0.0–1.0 onto hue 0–360.
For the full mapping workflow, the behavior modes, and the complete list of mappable actions, see MIDI Mapping. OSC, MIDI, keyboard, and REST all share the same action catalog and the same profiles.
Value Reference
This table gives the common ranges, and the mistake that users make most often for each one:
| Control | Correct range | Type | Common mistake |
|---|---|---|---|
| Dimmer | 0.0 – 1.0 | f | A value from 0–100 or 0–255 |
| Hue | -1.0 – 1.0 | f | A value from 0–360 |
| Saturation | 0.0 – 2.0 | f | A value from 0–100 |
| Blackout / Mirror | 0 or 1 | i | The string true or false |
| Indices | ≥ 1 | i | A 0-based index |
| Cue number | exact match | f | A cue number (1.5) in place of a 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, how to enable the listener, tests, 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)