OSC API
Control FXCanvas from external applications and hardware controllers using Open Sound Control (OSC) messages. Integrate with TouchOSC, custom control surfaces, show control systems, or any OSC-capable software.
What is OSC?
Open Sound Control (OSC) is a protocol for networking sound synthesizers, computers, and multimedia devices. It's commonly used in live performance, installation art, and show control applications.
OSC messages consist of:
| Component | Description |
|---|---|
| Address | A path-like string (e.g., /global/dimmer) |
| Arguments | Optional values — floats, integers, or strings |
FXCanvas listens for OSC messages on a dedicated port and responds by changing palettes, triggering cues, adjusting global effects, or returning data.
Getting Started
Enabling the OSC API
- Open Edit → Settings from the menu bar
- Select the OSC tab in the sidebar
- Check Enable OSC API
- The default port is 9000 — change if needed
- Click Apply to start listening
When enabled, the status indicator shows the current state:
| Status | Description |
|---|---|
| Listening on port 9000 (green circle) | Ready to receive OSC messages |
| Enabled but not running (yellow circle) | Service encountered an issue starting |
| Disabled (gray circle) | OSC API is turned off |
Testing Your Connection
To verify the OSC API is working:
- Enable the OSC API in Settings
- Open View → Log Viewer
- Select the OSC tab
- Ensure the API filter is checked
- Send an OSC message from your controller (e.g.,
/palette/next) - You should see the message appear in the log with an "API" source badge
If messages aren't appearing, check your firewall settings and ensure your controller is sending to the correct IP address and port.
OSC Address Reference
Source Type Selection
Control which source type is active.
| Address | Arguments | Description |
|---|---|---|
/source/1, /source/2, etc. | — | Select source by 1-based index |
/source/{type} | — | Select source by type name (e.g., /source/plasma) |
/source/index | int (1–N) | Select source by index argument |
/source/next | float/int (optional) | Advance to next source type |
/source/previous | float/int (optional) | Go to previous source type |
/source/list | — | Query available source types (returns OSC reply) |
Examples:
/source/1 → Selects first source type
/source/plasma → Selects "Plasma" source
/source/warp_speed → Selects "Warp Speed" source
/source/index 3 → Selects third source via argument
/source/next → Advances to the next source type
/source/previous → Goes back to the previous source type
Source Preset Selection
Load a saved source preset (includes source type and parameter values).
| Address | Arguments | Description |
|---|---|---|
/source/preset/1, /source/preset/2, etc. | — | Select preset by 1-based index |
/source/preset/{name} | — | Select preset by name (underscores → spaces) |
/source/preset/index | int (1–N) | Select preset by index argument |
/source/preset/list | — | Query available presets (returns OSC reply) |
Examples:
/source/preset/1 → Selects first source preset
/source/preset/ocean_waves → Selects "Ocean Waves" preset
/source/preset/index 5 → Selects fifth preset via argument
Source presets are ideal for automation scripts — they load both the source type and all parameter values in one command.
Palette Selection
Control which color palette is active.
| Address | Arguments | Description |
|---|---|---|
/palette/1, /palette/2, etc. | — | Select palette by 1-based index |
/palette/{name} | — | Select palette by name (underscores or hyphens → spaces) |
/palette/index | int (1–N) | Select palette by index argument |
/palette/next | float/int (optional) | Advance to next palette |
/palette/previous | float/int (optional) | Go to previous palette |
/palette/list | — | Query available palettes (returns OSC reply) |
Examples:
/palette/1 → Selects first palette
/palette/2 → Selects second palette
/palette/ocean → Selects "Ocean" palette
/palette/deep_space → Selects "Deep Space" palette
/palette/purple-haze → Selects "Purple Haze" palette
/palette/index 3 → Selects third palette via argument
/palette/next → Advances to the next palette
/palette/previous → Goes back to the previous palette
Palette indexing is 1-based — index 1 selects the first palette. When selecting by name, replace spaces with underscores or hyphens. Names are matched case-insensitively.
Cue Selection
Control which cue is active. Cues can be triggered by index, name, or cue number.
| Address | Arguments | Description |
|---|---|---|
/cue/1, /cue/2, etc. | — | Trigger cue by 1-based index |
/cue/{name} | — | Trigger cue by name (underscores or hyphens → spaces) |
/cue/number | float | Trigger cue by cue number (e.g., 1.5) |
/cue/index | int (1–N) | Trigger cue by index argument |
/cue/next | float/int (optional) | Advance to next cue |
/cue/previous | float/int (optional) | Go to previous cue |
/cue/go | — | Re-trigger current cue |
/cue/list | — | Query available cues (returns OSC reply) |
Examples:
/cue/1 → Triggers first cue
/cue/intro_scene → Triggers "Intro Scene" cue
/cue/number 1.5 → Triggers cue with cue number 1.5
/cue/index 2 → Triggers cue at index 2
/cue/next → Advances to the next cue
/cue/go → Re-triggers the current cue
Cue indexing is 1-based. The /cue/next and /cue/previous addresses support an optional float/int argument — they trigger when the value is greater than 0.5 or when no argument is provided. This is useful for button controls that send both press and release events.
Global Controls
Adjust master output effects that apply to the entire composition.
| Address | Arguments | Range | Description |
|---|---|---|---|
/global/dimmer | float | 0.0–1.0 | Master brightness (0 = black, 1 = full) |
/global/hue | float | -1.0 to 1.0 | Hue shift (color wheel rotation) |
/global/saturation | float | 0.0–2.0 | Color saturation (1.0 = normal) |
/global/blackout | int | 0 or 1 | Instant blackout toggle |
/global/reset | — | — | Reset all global effects to defaults |
Examples:
/global/dimmer 0.5 → Sets master brightness to 50%
/global/hue 0.5 → Shift hue 50% around the color wheel
/global/saturation 0.0 → Fully desaturated (grayscale)
/global/blackout 1 → Turn on blackout
/global/reset → Reset dimmer, hue, saturation, and mirrors
Mirror Controls
Control horizontal and vertical mirroring effects.
| Address | Arguments | Description |
|---|---|---|
/global/mirror/x | int (0 or 1) | Horizontal mirror (0 = off, 1 = on) |
/global/mirror/y | int (0 or 1) | Vertical mirror (0 = off, 1 = on) |
/global/mirror/both | int (0 or 1) | Toggle both mirrors simultaneously |
List Endpoints
Query the available sources, presets, palettes, and cues. These endpoints return OSC reply messages to the sender.
| Address | Response | Description |
|---|---|---|
/source/list | Multiple OSC messages | Returns count followed by source types |
/source/preset/list | Multiple OSC messages | Returns count followed by preset details |
/palette/list | Multiple OSC messages | Returns count followed by item details |
/cue/list | Multiple OSC messages | Returns count followed by item details |
Source List Response:
/source/list/count 20
/source/list/item 1 "Plasma"
/source/list/item 2 "Drift"
/source/list/item 3 "Blobs"
...
Source Preset List Response:
/source/preset/list/count 15
/source/preset/list/item 1 "Ocean Waves" "plasma"
/source/preset/list/item 2 "Fire Storm" "explosion"
...
Palette List Response:
/palette/list/count 5
/palette/list/item 1 "Ocean Blues"
/palette/list/item 2 "Sunset Fire"
/palette/list/item 3 "Aurora"
...
Cue List Response:
/cue/list/count 8
/cue/list/item 1 1.0 "Intro Scene"
/cue/list/item 2 1.5 "Build"
/cue/list/item 3 2.0 "Chorus"
...
List responses are sent to the sender's IP address on the reply port (listening port + 1). For example, if FXCanvas listens on port 9000, replies are sent to port 9001. Ensure your controller is configured to receive on this port.
Settings Configuration
OSC Settings Tab
Access OSC API configuration via Edit → Settings → OSC tab.
| Setting | Description |
|---|---|
| Enable OSC API | Turns the OSC listener on or off |
| Incoming Port | UDP port FXCanvas listens on (default: 9000, range: 1024–65535) |
| Status | Shows current service state with colored indicator |
| OSC Address Reference | Collapsible quick reference of available addresses |
The Copy All Addresses button (copy icon) copies a formatted list of all OSC addresses to your clipboard for use in controller configuration.
Changing the Port
- Enter the new port number in the Incoming Port field
- Click Apply
- Update your OSC controller to send to the new port
Changing the port restarts the OSC service. A warning message appears: "Port change requires restart" (warning icon).
Common port numbers:
| Port | Usage |
|---|---|
9000 | Default, commonly used by TouchOSC |
8000 | Alternative if 9000 is in use |
Firewall Configuration
If OSC messages aren't reaching FXCanvas:
- Check Windows Firewall settings
- Allow FXCanvas (or
FXCanvas.exe) through the firewall - Ensure UDP traffic is permitted on your chosen port
- If using a network controller, verify both devices are on the same network
Example Use Cases
TouchOSC Integration
TouchOSC is a popular iOS/Android app for creating custom OSC control surfaces.
Setup:
- Enable the OSC API in FXCanvas Settings (port 9000)
- In TouchOSC, set the Host to your computer's IP address
- Set the Port (outgoing) to 9000
- If using list endpoints, set Port (incoming) to 9001
- Create buttons or faders mapped to FXCanvas addresses
Example TouchOSC Layout:
| Control | OSC Address | Range | Purpose |
|---|---|---|---|
| Button | /palette/next | — | Tap to cycle palettes |
| Fader | /global/dimmer | 0–1 | Slide for brightness |
| XY Pad X | /global/hue | -1 to 1 | Horizontal for hue shift |
| XY Pad Y | /global/saturation | 0–2 | Vertical for saturation |
| Toggle | /global/blackout | 0/1 | Quick blackout control |
For advanced TouchOSC layouts using Lua scripting to query and display palette/cue lists dynamically, see the OSC API Reference (coming soon).
Troubleshooting
Messages Not Being Received
Check the Log Viewer:
- Open View → Log Viewer
- Select the OSC tab
- Ensure the API checkbox is enabled
- Look for incoming messages
If no messages appear:
- Verify OSC API is enabled in Settings
- Confirm port number matches your controller
- Check firewall settings
- Ensure controller is sending to the correct IP address
Wrong Parameter Values
| Parameter | Correct Range | Common Mistake |
|---|---|---|
| Dimmer | 0.0–1.0 | Using 0–100 or 0–255 |
| Hue | -1.0 to 1.0 | Using 0–360 |
| Saturation | 0.0–2.0 | Using 0–100 |
| Toggles | 0 or 1 | Using true/false strings |
Floats should be sent as float type (not strings). Integers should be sent as int32 type.
Palette or Cue Not Found
If selection by name fails:
- Replace spaces with underscores: "Deep Space" →
/palette/deep_space - Hyphens also work: "Purple Haze" →
/palette/purple-haze - Check exact spelling (names are case-insensitive)
- Verify the item exists in your palette/cue list
- Use numeric index as an alternative:
/palette/1,/cue/1
Port Already in Use
If you see a port conflict or service fails to start:
- Another application may be using the port
- Change to a different port in Settings (try 8000 or 7700)
- Or close the conflicting application
Common conflicts: TouchOSC editor, other OSC applications, VPN software
Distinguishing OSC Sources in Logs
FXCanvas receives OSC messages from two sources:
| Source | Description |
|---|---|
| OBC | Messages from the built-in Open Beat Control tempo sync system |
| API | Messages from external controllers via the OSC API |
The Log Viewer's OSC tab provides checkboxes to filter by source:
- OBC — Show/hide messages from Open Beat Control
- API — Show/hide messages from the OSC API
This separation helps you debug your controller setup without being overwhelmed by continuous tempo sync traffic.
Related Topics
- Sources — Learn about source types you can control via OSC
- Palettes — Learn about color palettes you can control via OSC
- Shows and Cues — Understand cues for triggering via OSC
- BPM Sync — The OBC system that also uses OSC internally
- Log Viewer — Monitor OSC message traffic