Surge XT supports external OSC control of most parameters, including patch and tuning changes. Where appropriate and feasible, Surge parameter and other changes are reported to OSC out, either when they occur or when queried (see below). Notes may also be triggered via OSC, either by frequency or by MIDI note number.
OSC messages are constructed using the exact (case sensitive)
entry listed in the Address column in the tables below.
The form of the message should be /<address> <value>,
where address is one of the ones listed below, and zero or more
values can be*:
If the received value is less than the minimum or greater than the maximum acceptable value, it will be clipped to the associated limit.
Important Note: All numeric values must be sent over OSC as floating point numbers (even if they are listed as integer or boolean type -- the 'Appropriate Values' column describes how the data is used by Surge XT, not how messages are to be formatted for OSC).
OSC Output: All parameter and patch changes made on Surge XT are reported to OSC out, if OSC output is enabled. Floating point parameters are reported both in their 'natural' range, and normalized (0.0 - 1.0). Errors are reported (when feasible) to "/error".
Examples are given in red.
| Address | Description | Value 1 | Value 2 | Value 3 |
|---|---|---|---|---|
| /mnote | MIDI-style note | note number (0 - 127) | velocity (0.0 - 127.0)* | noteID (optional, 0 - maxint)§ |
| /fnote † | frequency note | frequency (8.176 - 12543.853) | velocity (0.0 - 127.0)* | noteID (optional, 0 - maxint)§ |
| /mnote/rel | MIDI-style note release | note number (0 - 127) | release velocity (0.0 - 127.0) | noteID (optional, 0 - maxint)§ |
| /fnote/rel | frequency note release | frequency (8.176 - 12543.853) | release velocity (0.0 - 127.0) | noteID (optional, 0 - maxint)§ |
| /allnotesoff | release all current notes | (none) | (none) | (none) |
| /allsoundoff | stop all sound NOW | (none) | (none) | (none) |
|
* Velocity 0 releases the note; use the .../rel messages to release notes with velocity. If noteIDs are supplied, the note number or frequency value for releases is disregarded. † When using /fnote, Surge XT must be set to standard tuning for proper results! § NoteID can be optionally supplied for more control over the lifecycle of notes, or for Note Expressions. |
||||
/mnote 68 120
/fnote 440.0 120
/mnote 68 0
/fnote 440.0 0
/mnote/rel 68 45
/fnote/rel 440.0 45
| Address | Description | Value 1 | Value 2 | |
|---|---|---|---|---|
| /ne/pitch | pitch note expression | noteID (0 - maxint)§ | pitch offset (-120.0 - 120.0: semitones) | |
| /ne/volume | volume note expression | noteID (0 - maxint)§ | volume multiplier (0.0 - 4.0) | |
| /ne/pan | pan note expression | noteID (0 - maxint)§ | position (0.0 - 1.0: 0.0 = left 0.5 = center 1.0 = right) | |
| /ne/timbre | timbre note expression | noteID (0 - maxint)§ | timbre (0.0 - 1.0) | |
| /ne/pressure | pressure note expression | noteID (0 - maxint)§ | polyphonic aftertouch (0.0 - 1.0) | |
|
§ NoteID should belong to an already initiated note. |
||||
/ne/pitch 24566 0.34
/ne/volume 24566 0.5
/ne/pan 24566 0.9
/ne/timbre 24566 0.18
/ne/pressure 24566 0.4
| Address | Description | Appropriate Values |
|---|---|---|
| /patch/load | load patch | file path (absolute, no extension) |
| /patch/save | save patch | none: overwrites current patch or file path (absolute, no extension, overwrites if file exists) |
| /patch/incr | increment patch | (none) |
| /patch/decr | decrement patch | (none) |
| /patch/incr_category | increment category | (none) |
| /patch/decr_category | decrement category | (none) |
| /patch/random | choose random patch | (none) |
| Address | Description | Appropriate Values |
|---|---|---|
| /tuning/scl | .scl tuning file | file path (absolute or relative)* |
| /tuning/kbm | .kbm mapping file | file path (absolute or relative)* |
| /tuning/path/scl | .scl file default path | file path (absolute only) |
| /tuning/path/kbm | .kbm file default path | file path (absolute only) |
| * no extension; use value = '_reset' to reset path to factory default | ||
/patch/load /Library/Application Support/Surge XT/patches_factory/Plucks/Clean
/patch/save
/patch/incr
/tuning/scl ptolemy
/tuning/scl /Users/jane/scala_tunings/ptolemy
/tuning/path/scl /Users/jane/scala_tunings
| Address | Description | Appropriate Values | Action |
|---|---|---|---|
| /q/all_params | request all parameters | none | Sends a dump of all parameters listed below to OSC out |
| /q/<parameter address> | request one parameter | none | Sends one parameter's value to OSC out |
q/all_params
q/param/b/amp/gain
q/param/global/polyphony_limit
q/param/a/mixer/noise/mute
/param/b/amp/gain 0.63
/param/global/polyphony_limit 12
/param/a/mixer/noise/mute 0
| Address | Description | Appropriate Values |
|---|---|---|
| /param/macro/1 | macro 1 | float (0.0 - 1.0) |
| /param/macro/2 | macro 2 | float (0.0 - 1.0) |
| /param/macro/3 | macro 3 | float (0.0 - 1.0) |
| /param/macro/4 | macro 4 | float (0.0 - 1.0) |
| /param/macro/5 | macro 5 | float (0.0 - 1.0) |
| /param/macro/6 | macro 6 | float (0.0 - 1.0) |
| /param/macro/7 | macro 7 | float (0.0 - 1.0) |
| /param/macro/8 | macro 8 | float (0.0 - 1.0) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/amp/gain | VCA Gain | float (0.0 to 1.0) |
| /param/<s>/amp/pan | Pan | float (0.0 to 1.0) |
| /param/<s>/amp/vel_to_gain | Velocity > VCA Gain | float (0.0 to 1.0) |
| /param/<s>/amp/volume | Volume | float (0.0 to 1.0) |
| /param/<s>/amp/width | Width | float (0.0 to 1.0) |
| /param/<s>/filter/2/link_resonance | Link Resonance | boolean (0 or 1) |
| /param/<s>/filter/2/offset_mode | Filter 2 Offset Mode | boolean (0 or 1) |
| /param/<s>/filter/balance | Filter Balance | float (0.0 to 1.0) |
| /param/<s>/filter/config | Filter Configuration | integer (0 to 7) |
| /param/<s>/filter/feedback | Feedback | float (0.0 to 1.0) |
| /param/<s>/filter/keytrack_root | Keytrack Root Key | integer (0 to 127) |
| /param/<s>/highpass | Highpass | float (0.0 to 1.0) |
| /param/<s>/mixer/noise/color | Noise Color | float (0.0 to 1.0) |
| /param/<s>/octave | Octave | integer (-3 to 3) |
| /param/<s>/osc/drift | Osc Drift | float (0.0 to 1.0) |
| /param/<s>/osc/fm_depth | FM Depth | float (0.0 to 1.0) |
| /param/<s>/osc/fm_routing | FM Routing | integer (0 to 3) |
| /param/<s>/pitch | Pitch | float (0.0 to 1.0) |
| /param/<s>/pitchbend_down | Pitch Bend Down Range | integer (0 to 24) |
| /param/<s>/pitchbend_up | Pitch Bend Up Range | integer (0 to 24) |
| /param/<s>/play_mode | Play Mode | integer (0 to 5) |
| /param/<s>/portamento | Portamento | float (0.0 to 1.0) |
| /param/<s>/send/1/level | Send FX 1 Level | float (0.0 to 1.0) |
| /param/<s>/send/2/level | Send FX 2 Level | float (0.0 to 1.0) |
| /param/<s>/send/3/level | Send FX 3 Level | float (0.0 to 1.0) |
| /param/<s>/send/4/level | Send FX 4 Level | float (0.0 to 1.0) |
| /param/<s>/waveshaper/drive | Waveshaper Drive | float (0.0 to 1.0) |
| /param/<s>/waveshaper/type | Waveshaper Type | integer (0 to 42) |
| /param/fx/chain_bypass | FX Chain Bypass | integer (0 to 3) |
| /param/fx/send/1/return | Send FX 1 Return | float (0.0 to 1.0) |
| /param/fx/send/2/return | Send FX 2 Return | float (0.0 to 1.0) |
| /param/fx/send/3/return | Send FX 3 Return | float (0.0 to 1.0) |
| /param/fx/send/4/return | Send FX 4 Return | float (0.0 to 1.0) |
| /param/global/active_scene | Active Scene | integer (0 to 1) |
| /param/global/character | Character | integer (0 to 2) |
| /param/global/polyphony_limit | Polyphony Limit | integer (2 to 64) |
| /param/global/scene_mode | Scene Mode | integer (0 to 3) |
| /param/global/split_point | Split Point | integer (0 to 127) |
| /param/global/volume | Global Volume | float (0.0 to 1.0) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/osc/<n>/keytrack | Osc <n> Keytrack | boolean (0 or 1) |
| /param/<s>/osc/<n>/octave | Osc <n> Octave | integer (-3 to 3) |
| /param/<s>/osc/<n>/param1 | Osc <n> Morph | (contextual) |
| /param/<s>/osc/<n>/param2 | Osc <n> Skew Vertical | (contextual) |
| /param/<s>/osc/<n>/param3 | Osc <n> Saturate | (contextual) |
| /param/<s>/osc/<n>/param4 | Osc <n> Formant | (contextual) |
| /param/<s>/osc/<n>/param5 | Osc <n> Skew Horizontal | (contextual) |
| /param/<s>/osc/<n>/param6 | Osc <n> Unison Detune | (contextual) |
| /param/<s>/osc/<n>/param7 | Osc <n> Unison Voices | (contextual) |
| /param/<s>/osc/<n>/pitch | Osc <n> Pitch | float (0.0 to 1.0) |
| /param/<s>/osc/<n>/retrigger | Osc <n> Retrigger | boolean (0 or 1) |
| /param/<s>/osc/<n>/type | Osc <n> Type | integer (0 to 11) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/filter/<n>/cutoff | Filter <n> Cutoff | float (0.0 to 1.0) |
| /param/<s>/filter/<n>/feg_amount | Filter <n> FEG Mod Amount | float (0.0 to 1.0) |
| /param/<s>/filter/<n>/keytrack | Filter <n> Keytrack | float (0.0 to 1.0) |
| /param/<s>/filter/<n>/resonance | Filter <n> Resonance | float (0.0 to 1.0) |
| /param/<s>/filter/<n>/subtype | Filter <n> Subtype | integer (0 to 15) |
| /param/<s>/filter/<n>/type | Filter <n> Type | integer (0 to 33) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/aeg/attack | Amp EG Attack | float (0.0 to 1.0) |
| /param/<s>/aeg/attack_shape | Amp EG Attack Shape | integer (0 to 2) |
| /param/<s>/aeg/decay | Amp EG Decay | float (0.0 to 1.0) |
| /param/<s>/aeg/decay_shape | Amp EG Decay Shape | integer (0 to 2) |
| /param/<s>/aeg/mode | Amp EG Envelope Mode | integer (0 to 1) |
| /param/<s>/aeg/release | Amp EG Release | float (0.0 to 1.0) |
| /param/<s>/aeg/release_shape | Amp EG Release Shape | integer (0 to 2) |
| /param/<s>/aeg/sustain | Amp EG Sustain | float (0.0 to 1.0) |
| /param/<s>/feg/attack | Filter EG Attack | float (0.0 to 1.0) |
| /param/<s>/feg/attack_shape | Filter EG Attack Shape | integer (0 to 2) |
| /param/<s>/feg/decay | Filter EG Decay | float (0.0 to 1.0) |
| /param/<s>/feg/decay_shape | Filter EG Decay Shape | integer (0 to 2) |
| /param/<s>/feg/mode | Filter EG Envelope Mode | integer (0 to 1) |
| /param/<s>/feg/release | Filter EG Release | float (0.0 to 1.0) |
| /param/<s>/feg/release_shape | Filter EG Release Shape | integer (0 to 2) |
| /param/<s>/feg/sustain | Filter EG Sustain | float (0.0 to 1.0) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/fx/<s>/<n>/param1 | FX <s><n> Param 1 | (contextual) |
| /param/fx/<s>/<n>/param2 | FX <s><n> Param 2 | (contextual) |
| /param/fx/<s>/<n>/param3 | FX <s><n> Param 3 | (contextual) |
| /param/fx/<s>/<n>/param4 | FX <s><n> Param 4 | (contextual) |
| /param/fx/<s>/<n>/param5 | FX <s><n> Param 5 | (contextual) |
| /param/fx/<s>/<n>/param6 | FX <s><n> Param 6 | (contextual) |
| /param/fx/<s>/<n>/param7 | FX <s><n> Param 7 | (contextual) |
| /param/fx/<s>/<n>/param8 | FX <s><n> Param 8 | (contextual) |
| /param/fx/<s>/<n>/param9 | FX <s><n> Param 9 | (contextual) |
| /param/fx/<s>/<n>/param10 | FX <s><n> Param 10 | (contextual) |
| /param/fx/<s>/<n>/param11 | FX <s><n> Param 11 | (contextual) |
| /param/fx/<s>/<n>/param12 | FX <s><n> Param 12 | (contextual) |
| /param/fx/<s>/<n>/type | FX <s><n> FX Type | int (0 = off; 1 - 29: fx type) |
| /param/fx/<s>/<n>/deactivate | (FX slot Deactivate) | boolean (0 or 1) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/mixer/noise/mute | Noise Mute | boolean (0 or 1) |
| /param/<s>/mixer/noise/route | Noise Route | integer (0 to 2) |
| /param/<s>/mixer/noise/solo | Noise Solo | boolean (0 or 1) |
| /param/<s>/mixer/noise/volume | Noise Volume | float (0.0 to 1.0) |
| /param/<s>/mixer/osc<n>/mute | Osc <n> Mute | boolean (0 or 1) |
| /param/<s>/mixer/osc<n>/route | Osc <n> Route | integer (0 to 2) |
| /param/<s>/mixer/osc<n>/solo | Osc <n> Solo | boolean (0 or 1) |
| /param/<s>/mixer/osc<n>/volume | Osc <n> Volume | float (0.0 to 1.0) |
| /param/<s>/mixer/prefilter_gain | Pre-Filter Gain | float (0.0 to 1.0) |
| /param/<s>/mixer/rm1x2/mute | Ring Modulation 1x2 Mute | boolean (0 or 1) |
| /param/<s>/mixer/rm1x2/route | Ring Modulation 1x2 Route | integer (0 to 2) |
| /param/<s>/mixer/rm1x2/solo | Ring Modulation 1x2 Solo | boolean (0 or 1) |
| /param/<s>/mixer/rm1x2/volume | Ring Modulation 1x2 Volume | float (0.0 to 1.0) |
| /param/<s>/mixer/rm2x3/mute | Ring Modulation 2x3 Mute | boolean (0 or 1) |
| /param/<s>/mixer/rm2x3/route | Ring Modulation 2x3 Route | integer (0 to 2) |
| /param/<s>/mixer/rm2x3/solo | Ring Modulation 2x3 Solo | boolean (0 or 1) |
| /param/<s>/mixer/rm2x3/volume | Ring Modulation 2x3 Volume | float (0.0 to 1.0) |
| Address | Parameter Name | Appropriate Values |
|---|---|---|
| /param/<s>/slfo/<n>/amplitude | Scene LFO <n> Amplitude | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/deform | Scene LFO <n> Deform | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/attack | Scene LFO <n> Attack | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/decay | Scene LFO <n> Decay | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/delay | Scene LFO <n> Delay | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/hold | Scene LFO <n> Hold | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/release | Scene LFO <n> Release | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/eg/sustain | Scene LFO <n> Sustain | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/phase | Scene LFO <n> Phase | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/rate | Scene LFO <n> Rate | float (0.0 to 1.0) |
| /param/<s>/slfo/<n>/trigger_mode | Scene LFO <n> Trigger Mode | integer (0 to 2) |
| /param/<s>/slfo/<n>/type | Scene LFO <n> Type | integer (0 to 9) |
| /param/<s>/slfo/<n>/unipolar | Scene LFO <n> Unipolar | boolean (0 or 1) |
| /param/<s>/vlfo/<n>/amplitude | LFO <n> Amplitude | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/deform | LFO <n> Deform | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/attack | LFO <n> Attack | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/decay | LFO <n> Decay | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/delay | LFO <n> Delay | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/hold | LFO <n> Hold | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/release | LFO <n> Release | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/eg/sustain | LFO <n> Sustain | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/phase | LFO <n> Phase | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/rate | LFO <n> Rate | float (0.0 to 1.0) |
| /param/<s>/vlfo/<n>/trigger_mode | LFO <n> Trigger Mode | integer (0 to 2) |
| /param/<s>/vlfo/<n>/type | LFO <n> Type | integer (0 to 9) |
| /param/<s>/vlfo/<n>/unipolar | LFO <n> Unipolar | boolean (0 or 1) |
Modulation Mapping messages are constructed by selecting one of the '/mod' source addresses listed below (with an appropriate index value, if necessary) and adding a target address selected from the '/param' addresses listed above, then specifying a depth (0.0 - 1.0). If both the source and target addresses are scene-specific (a or b), the scenes must match.
Send a depth of 0 to disconnect a modulator from its target.
Not all parameters can be modulated by all mod. sources. If a given combination is not possible an error will be reported to OSC out.
/mod/b/slfo_1/2 /param/b/amp/gain 0.45
/mod/a/feg /param/a/filter/1/cutoff 0.9
/mod/macro_6 /param/a/pitch 0.75
| Address | Description | <index>=0 | <index>=1 | <index>=2 |
|---|---|---|---|---|
| /mod/vel | Velocity | |||
| /mod/rel_vel | Release Velocity | |||
| /mod/keytrk | Keytrack | |||
| /mod/<s>/lowest_key | Lowest Key | |||
| /mod/<s>/highest_key | Highest Key | |||
| /mod/<s>/latest_key | Latest Key | |||
| /mod/pat | Polyphonic Aftertouch | |||
| /mod/at | Channel Aftertouch | |||
| /mod/mw | Modulation Wheel | |||
| /mod/breath | Breath | |||
| /mod/expr | Expression | |||
| /mod/sus | Sustain Pedal | |||
| /mod/pb | Pitch Bend | |||
| /mod/timbre | Timbre | |||
| /mod/alt_bi | Alternate Bipolar | |||
| /mod/alt_uni | Alternate Unipolar | |||
| /mod/rand_bi/<index> | Random Bipolar | (Uniform) | (Normal) | |
| /mod/rand_uni/<index> | Random Unipolar | (Uniform) | (Half Normal) | |
| /mod/<s>/feg | Filter EG | |||
| /mod/<s>/aeg | Amp EG | |||
| /mod/<s>/vlfo_<n>/<index> | Voice LFO <n>† | (Voice LFO <n>) | (Raw Waveform) | (EG Only) |
| /mod/<s>/slfo_<n>/<index> | Scene LFO <n>† | (Scene LFO <n>) | (Raw Waveform) | (EG Only) |
| /mod/macro_1 | Macro 1 | |||
| /mod/macro_2 | Macro 2 | |||
| /mod/macro_3 | Macro 3 | |||
| /mod/macro_4 | Macro 4 | |||
| /mod/macro_5 | Macro 5 | |||
| /mod/macro_6 | Macro 6 | |||
| /mod/macro_7 | Macro 7 | |||
| /mod/macro_8 | Macro 8 | |||
|
† For Scene or Voice LFOs of "Formula" type, indices [0 - 7] specify "Formula Out" [1 - 8] |
||||