Open Sound Control (OSC)
Send commands to DMXDesktop and receive state broadcasts via OSC
What is OSC?
Open Sound Control (OSC) is a protocol for networking sound synthesizers, computers, and other multimedia devices for purposes such as musical performance or show control. DMXDesktop implements OSC for bidirectional communication - receive commands from external controllers and broadcast state changes to other applications.
How It Works
DMXDesktop supports both OSC Input and Output. The OSC Input server listens for incoming messages to control various aspects of the software. OSC Output broadcasts state changes and events to external applications, enabling real-time synchronization with video software, visualizers, and custom integrations. Both support UDP protocol for low-latency communication.
Getting Started
- Open DMXDesktop and navigate to Settings → General
- In the OSC section, you'll find:
- Enable/Disable OSC Input toggle
- Network Interface selection
- Input Port number (default: 8000)
- Protocol selection (UDP/TCP)
- Enable/Disable OSC Output toggle
- Output Host and Port (default: 127.0.0.1:9000)
- The discovery service runs on port 9000 and allows compatible apps to automatically find DMXDesktop on the network
Connecting with TouchOSC
TouchOSC is a popular tool for controlling multitudes of different types of applications, and can be used to control DMXDesktop via the OSC Protocol.
Please note: TouchOSC is paid software, please refer to the official website for details.
- Download and install TouchOSC on your device:
- iOS: App Store
- Android: Google Play
- Desktop: Desktop
- Open TouchOSC and create a new connection:
- Protocol: OSC
- Host: Your computer's IP address (shown in DMXDesktop settings)
- Send Port: 8000 (default)
- Receive Port: 9000 (for discovery service)
- Use the discovery feature in TouchOSC to automatically find DMXDesktop on your network
- Create your layout using the OSC paths listed in the table below
Network Tips
- Ensure your device and computer are on the same network
- If using a firewall, allow incoming connections on ports 8000 and 9000
- For optimal performance, use a dedicated network or 5GHz WiFi connection
- For OSC Output, configure the target host IP and port in Settings
Additional Resources
- Official OSC Website - Learn more about the OSC protocol
- TouchOSC Documentation - Detailed guide for TouchOSC
- OSC Protocol Specification - Technical details of the OSC protocol
OSC Input Commands
Send these commands to DMXDesktop to control your lighting. All paths are case-sensitive.
| OSC Path | Parameters | Description |
|---|---|---|
| MASTER CONTROLS | ||
| /master/dimmer | float (0-1) | Controls master dimmer intensity |
| LIVE EFFECTS | ||
| /live/strobe/{on|off|pulse} | none | Controls strobe state |
| /live/blackout/{on|off|pulse} | none | Controls blackout state |
| /live/blinder/{on|off|pulse} | none | Controls blinder state |
| /live/freeze/{on|off|pulse} | none | Controls freeze state |
| /live/fog/{on|off|pulse} | none | Controls fog machine state |
| SPECIAL EFFECTS | ||
| /effects/{effect}/start | none | Starts specified effect (wave, paparazzi, colorsweep, thunder, pulse, sparkle, random) |
| /effects/{effect}/stop | none | Stops the specified special effect |
| /effects/stop | none | Stops all currently running special effects |
| /effects/bpm | float (0-1) | Sets BPM for special effects timing (maps 0-1 to 60-200 BPM) |
| LIVE EDITS | ||
| /live/edit/{action}/{name} | action: enable|disable|toggle | Controls live edit state by name |
| /live/edit/group/{action}/{name} | action: enable|disable|toggle | Controls live edit group state by name |
| /live/edit/disable-all | none | Disables all live edits |
| CUE CONTROLS | ||
| /cue/effect/play/{name} | string | Plays specific effect cue by name |
| /cue/effect/{action} | play|stop|next|prev | Controls effect cue playback navigation |
| DJ CONTROLS | ||
| /dj/app/{app} | musicplayer|virtualdj|traktor | Toggle specific DJ application |
| /dj/deck{1|2}/{action} | play|stop|eject | Deck transport controls |
| /dj/deck{1|2}/volume | float (0-1) | Controls deck volume |
| /dj/crossfader | float (0-1) | Controls crossfader position |
| DIRECT DMX CONTROL | ||
| /dmx/{universe}/{channel} | float (0-1) | Sets DMX channel value (maps 0-1 to 0-255) |
| /dmx/{universe}/{channel}/clear | none | Clears DMX channel override |
| /dmx/clear | none | Clears ALL DMX channel overrides |
| STACK CONTROLS | ||
| /stack/{id}/go | none | Fires the next cue in the specified stack |
| /stack/{id}/back | none | Steps back to the previous cue |
| /stack/{id}/halt | none | Freezes the current crossfade mid-transition |
| /stack/{id}/stop | none | Stops playback on the specified stack |
| /stack/{id}/level | float (0-1) | Sets the stack master level |
| EXECUTE GRID | ||
| /execute/{row}/{col} | none | Triggers the execute grid button at the specified position |
Live Wire and Tempo Commands
Live Wire mode, Live Wire Hold and the half and double tempo controls can all be driven over OSC. Live Wire is a Standard and Pro feature. Available from v1.0.52
| OSC Path | Parameters | Description |
|---|---|---|
| Live Wire | ||
| /livewire/mode/{band|dj|ambient} | none | Switches Live Wire to that mode, and starts Live Wire if it is not already the running audio app |
| /livewire/hold/{on|off|toggle} | none | Holds Live Wire on the mode's standby look, or releases it back to listening. Refused when the running mode has no standby look to hold |
| TEMPO | ||
| /live/tempo/{half|double|normal} | none | Runs the rig at half or double time, or returns it to normal. Half and double latch, so sending the same one again returns to normal |
One tempo setting, everywhere. Half and double tempo is a single setting that the desk, MIDI pads, OSC and the mobile remote all read and write, so they cannot disagree about the speed the rig is running at.
OSC can no longer silence audio a running feature depends on. Live Wire needs live audio capture and BPM detection, and an OSC message could previously switch either off underneath it, leaving it enabled but deaf. Those messages are now refused while a running feature depends on them.
OSC Output Messages
DMXDesktop broadcasts state and events to external applications via OSC. Configure the target host and port in Settings. Available from v1.0.46
Live Controls
/dmxdesktop/v1/master float 0-1 (0-100%)/dmxdesktop/v1/blackout int 0|1/dmxdesktop/v1/strobe int 0|1/dmxdesktop/v1/blinder int 0|1/dmxdesktop/v1/freeze int 0|1/dmxdesktop/v1/fog int 0|1/dmxdesktop/v1/effect int 0|1/dmxdesktop/v1/specialeffect/{name} int 0|1 (wave, thunder, etc.)Audio & BPM
/dmxdesktop/v1/bpm float (BPM value)/dmxdesktop/v1/beat float, int, int, float (bpm, ts_high, ts_low, confidence)/dmxdesktop/v1/audio/level float 0-1 (RMS level)/dmxdesktop/v1/audio/energy float 0-1 (energy level)Effect Cues
/dmxdesktop/v1/cue/active string (cue name or "")/dmxdesktop/v1/cue/name string (current cue)/dmxdesktop/v1/cue/action string (play|stop)/dmxdesktop/v1/cue/lifecycle string (fadeIn/OutStarted/Finished)/dmxdesktop/v1/cue/lifecycle/duration int (ms)/dmxdesktop/v1/cue/lifecycle/newCue string (next cue name)Cue Stacks
/dmxdesktop/v1/stack/{id}/step int (step index)/dmxdesktop/v1/stack/{id}/fading int 0|1/dmxdesktop/v1/stack/{id}/paused int 0|1Live Edits & Overrides
/dmxdesktop/v1/liveedit/{id} int 0|1/dmxdesktop/v1/liveedit/group/{id} int 0|1/dmxdesktop/v1/override/color string (palette ID or "")/dmxdesktop/v1/override/position string (preset or "")DJ Mode
/dmxdesktop/v1/dj/enabled int 0|1/dmxdesktop/v1/dj/app string (app name or "")/dmxdesktop/v1/dj/master int 1-4 (master deck)/dmxdesktop/v1/dj/crossfader float 0-1/dmxdesktop/v1/dj/deck{1-4}/playing int 0|1/dmxdesktop/v1/dj/deck{1-4}/paused int 0|1/dmxdesktop/v1/dj/deck{1-4}/track string (Artist - Title)/dmxdesktop/v1/dj/deck{1-4}/loaded int 0|1 (track loaded)/dmxdesktop/v1/dj/deck{1-4}/loading int 0|1 (analyzing)/dmxdesktop/v1/dj/deck{1-4}/showready int 0|1 (DMX show ready)/dmxdesktop/v1/dj/deck{1-4}/vu float (VU meter level)Live Wire
/dmxdesktop/v1/livewire/mode/active string (band|dj|ambient, or "")/dmxdesktop/v1/livewire/hold/state string (held|listening|unavailable)/dmxdesktop/v1/livewire/mode string (mode selected)/dmxdesktop/v1/livewire/hold int 0|1QuickShow - Beam Effects
/dmxdesktop/v1/quickshow/beam string (effect name or "")/dmxdesktop/v1/quickshow/beam/speed int (raw slider value)/dmxdesktop/v1/quickshow/beam/phase int (raw slider value)/dmxdesktop/v1/quickshow/beam/background int (raw slider value)/dmxdesktop/v1/quickshow/beam/spread int (raw slider value)/dmxdesktop/v1/quickshow/beam/intensity int (raw slider value)QuickShow - Movement Effects
/dmxdesktop/v1/quickshow/move string (effect name or "")/dmxdesktop/v1/quickshow/move/speed int (raw slider value)/dmxdesktop/v1/quickshow/move/size int (raw slider value)/dmxdesktop/v1/quickshow/move/phase int (raw slider value)/dmxdesktop/v1/quickshow/move/fanning int (raw slider value)/dmxdesktop/v1/quickshow/move/direction int -1|0|1QuickShow - General
/dmxdesktop/v1/quickshow/theme int (theme ID)/dmxdesktop/v1/quickshow/themecount int (8|16|24|32)/dmxdesktop/v1/quickshow/preset string (preset ID or "")/dmxdesktop/v1/quickshow/groups string (JSON array)/dmxdesktop/v1/quickshow/groups/move string (JSON array)/dmxdesktop/v1/quickshow/stopall int 1 (pulse event)QuickShow - Encoders
/dmxdesktop/v1/quickshow/encoder/beam/{id} int 0-255 (DMX value)/dmxdesktop/v1/quickshow/encoder/move/{id} int 0-255 (DMX value)Encoder IDs are in the format: beam_aux_{groupId}_{channelKey} or move_aux_{groupId}_{channelKey}
Note: OSC Output requires a paid subscription and must be enabled in Settings. Default port is 9000.
Beat timestamps are split into two 32-bit integers (ts_high, ts_low) since OSC doesn't support 64-bit values.
