OSC lets synthesizers and other devices communicate with Ardour. OSC devices can send commands relating to playback (such as play or stop), performance (such as volume, play, stop), and almost any other function (such as Edit, or Undo).
Note: OSC control has changed dramatically since Ardour 4.7. The Path structure has been completely redone, Banking has been introduced, The controller is now able to tell Ardour what kind of feedback it can work with (including bank size) and the gain controls have new math calculations. If you are using an Ardour version of 4.7 or less, please read Osc control in Ardour 4.7 and prior.
Ardour is probably one of the most OSC-controllable audio applications around, but as with all OSC-controllable apps, you can't do much without knowing what messages can be sent. This document describes the various categories of messages that Ardour understands. It is subject to change, particularly the "Actions" part below, since this relates to the GTK GUI for Ardour rather than the backend.
OSC support is not enabled by default, but can be turned on via
Edit > Preferences > Control Surfaces.
Once enabled, Ardour will listen on port 3819 by default.
This port number can be changed by editing $ARDOUR_CONFIG
and adding this line within the <Config> section:
Ardour sends any feedback to the port and address that sent any feedback request or to a port set manually in the setup dialog. The port does not have to match Ardour's port. In fact it is better not to. This means that Ardour can deal with more than one controller at a time. The two controllers can bank independently and even use different math for faders. This could be used to allow talent to adjust their own monitor mix using a tablet or phone that can run an OSC controller. For a full explanation of how Ardour's feedback works please read OSC feedback In Ardour.
Control surface set up allows the controller to tell Ardour about its capabilities. The surface can tell Ardour how many control strips it has for banking, if it is capable of setting its faders or buttons to values set by Ardour's GUI or automation, What kind of math the faders use and more.
Any time the /set_surface command is sent, the current bank is recalculated and if feedback is turned on, the values of each strip's controls are sent (or refreshed) as well. This will also refresh the Master feedback setup.
As of Ardour 5.1, There is now a GUI setup in response to those using tablets with applications such as touchOSC or AndrOSC who need to be able to set a port for Ardour to send to. It can also change the default setting for set_surface. For more information about Ardour's OSC configuration GUI please read Ardour's Setup Dialog.
If /set_surface is not sent, the default values are used:
These values give the same behaviour as prior versions of Ardour. (or the closest possible)
/set_surface bank_size strip_types feedback fadermode send_page_size plugin_page_size port linkset linkidSee below for an explanation of each parameter.
The /set_surface message may have all values except the last in-line.
For example: /set_surface/8/31/8403/0/8 i 16 would be valid.
Do be careful of switches which send a 0 on release, it may be necessary
to set the value as the release value rather than the press value.
The /set_surface message may have less than the full set of parameters. those left out will remain as they were before the /set_surface message was sent. All parameters included must be valid. For example, setting send page size would require also setting bank_size, strip_types, feedback and gain mode. using only two parameters will set bank_size and strip_types. Sending /set_surface with no parameters will result in Ardour returning a /set_surface message with the current settings. Surfaces using /set_surface iiii b st fb gm as was the case in versions of Ardour older than 5.10 will continue to work.
Bank Size is the number of channel strips the controller supports without banking. Setting this to 0 turns banking off by setting the bank size to infinite.
Bank size can also be set with /set_surface/bank_size size.
strip_types is an integer made up of bits. The easy way to deal with this is to think of strip_types items being worth a number and then adding all those numbers together for a value to send. Strip Types will determine what kind of strips will be included in bank. This would include: Audio, MIDI, busses, VCAs, Master, Monitor and hidden or selected strips.
Aside from setting the track types for the main mix assignments, using /set_surface/strip_types with more than one surface button will allow switching between modes for example: inputs only, busses only, selected only, hidden only, by having the buttons send values of: 3, 12, 256, 512. A full mix button might have a value 31.
While Master and Monitor are listed as possibilities, most surfaces will not use them. Using /master and /monitor makes more sense. However, in the case where there are no master or monitor fader strips on the surface, it may be necessary to include them in the banked strips.
Please see: Calculating Feedback and Strip-types Values.
Strip types can also be set with /set_surface/strip_types types.
Feedback is an integer made up of bits. The easy way to deal with this is to think of feedback items being worth a number and then adding all those numbers together for a value to send.
Please see: Calculating Feedback and Strip-types Values.
Feedback can also be set with /set_surface/feedback feedback.
Gainmode is an int:
Gainmode applies only to feedback values. The controller can choose which gain math to use by choosing to use the /*/gain or /*/fader path to send to Ardour. This makes sure a controller that doesn't set up Ardour's OSC can still use either math. The gainmode for feedback also determines the path Ardour uses for feedback so that the feedback messages match the control messages.
Gain mode can also be set with /set_surface/gainmode gainmode.
Send_page_size is an int for the number of send channels that can be controlled at one time. Each channel has a name, level and enable control. (added in Ardour 5.10)
Send page size can also be set with /set_surface/send_page_size send_page_size.
plugin_page_size is an int for the number of plugin controls that can be controlled at one time. Each control has a name and level. As each plugin is different (as is each parameter), the surface should expect to control the plugin parameters with a variable control (pot or slider) with a float value from 0 to 1 (even on/off switches). (added in Ardour 5.10)
Plugin page size can also be set with /set_surface/plugin_page_size plugin_page_size.
The port the controller would like to receive it's feedback on. Starting
with Ardour 6.0, the surface can directly set the manual port or set
it's host to auto port mode.
The value for port can be 0 for auto port mode or any
port value above 1024. It is suggested not to use Ardour's port number
of 3819 as controllers on the same machine that try to use the same
port will fail.
If the surface does not
tell Ardour which port to use, the default is 8000 or the setting
set up in the OSC setup GUI. There can only be one port setting per
host. If that setting is auto, than more than one
controller can be run on that host, but if a manual port is set there
can only be one. In the case of auto mode, the control
surface must set it's receive port to be the same as it's send port.
If that is not possible, then manual port mode must be used. This
allows a smart controller to use a number of ports on the same ip while
a smartphone set up as a personal monitor control can use the default
manual port.
The host's port can also be set with /set_surface/port port.
Changing the port will remove feedback from a device on the same host using a different port.
Please see Linking Surfaces For more information.
The control Surface may wish to control the type a frequency of updates it receives. It can do this with querying commands. See: Querying Ardour with OSC.
Ardour can use more than one surface at a time that both control the same controls in Ardour. It is also possible to use two surfaces in concert with each other. See: Linking Surfaces for more information.
Parameter types show how the value will be used. However, they may be sent as a different type if needed, see: Parameter Types in OSC.
| /transport_stop | Stops a rolling transport |
|---|---|
| /transport_play | Puts transport in play mode |
| /toggle_roll | Toggles between play and stop |
| /stop_forget | Stop transport and delete/forget last take |
| /set_transport_speed speed | where speed is a float ranging from -8.0f to 8.0f |
| /ffwd | Adds 1.5 times to transport speed to maximum +8 times normal speed |
| /rewind | Adds -1.5 times to transport speed to maximum -8 times normal speed |
| /goto_start | Move playhead to start of session |
| /goto_end | Move playhead to end of session |
| /jump_bars bars | Where bars is a float (+/-) of the number of bars to jump |
| /jump_seconds seconds | Where seconds is a float (+/-) of the number of seconds to jump |
| /toggle_click | Toggle metronome click on and off |
| /marker marker | Where marker may be a float or int of the nth marker or a string with the marker name to locate to (new Ardour 6.0). If the playhead is at a marker and the marker is unique, the marker at the playhead will be renamed to the string sent |
| /add_marker | (adds marker to the current transport position) |
| /remove_marker | Removes marker at the current transport position (if there is one) |
| /next_marker | Move playhead to next marker |
| /prev_marker | Move playhead to previous marker |
| /locate spos roll | where spos is the target position in samples and roll is a bool/integer defining whether you want transport to be kept rolling or not |
| /loop_toggle | Toggle loop mode on and off |
| /loop_location start end | start is the beginning of a loop and end is the end of a loop both are integer frame positions. |
| /midi_panic | Ardour will send an all notes off to all midi tracks |
| /cancel_all_solos | Cancel All Solos/PFLs/AFLs |
New for Ardour 5.9.
| /scrub delta | Where delta is a float indicating forward or reverse movement. See OSC Scrub Modes |
|---|---|
| /jog delta | Where delta is a float indicating forward or reverse movement |
| /jog/mode mode | Where mode is an int from 0 to 7 indicating what the /jog command controls. See OSC Jog Modes |
| /toggle_punch_in | |
|---|---|
| /toggle_punch_out | |
| /rec_enable_toggle | Toggles master record enable |
| /transport_frame | Ardour sends /transport_frame current_frame |
|---|---|
| /transport_speed | Ardour sends /transport_speed speed |
| /record_enabled | Ardour sends /record_enabled recordenable_status |
| /undo | |
|---|---|
| /redo | |
| /save_state | (this is the regular Session > Save operation) |
| /session_name new_name | Set session name to new_name (if new_name is legal and unique) |
| /master/gain dB | dB is a float indicating the desired gain in dB |
|---|---|
| /master/fader position | position is a float between 0 and 1 setting the desired position of the fader |
| /master/db_delta delta | where delta is a float that will increase or decrease the gain of master by the amount of the delta. (Ardour 5.11+) |
| /master/trimdB dB | dB is a float from -20 to +20 representing the desired trim gain in dB |
| /master/pan_stereo_position position | position is a float from 0 to 1 representing the desired pan position |
| /master/mute key | key is an optional float 1 representing a master bus select |
| /master/select state | state is an int of o or 1 representing the desired mute state |
| /monitor/gain dB | dB is a float indicating the desired gain in dB |
| /monitor/fader position | position is a float between 0 and 1 setting the desired position of the fader |
| /monitor/db_delta delta | where delta is a float that will increase or decrease the gain of monitor by the amount of the delta. (Ardour 5.11+) |
| /monitor/mute state | state is an int of 0 or 1 where 1 is muted |
| /monitor/dim state | state is an int of 0 or 1 where 1 is dimmed |
| /monitor/mono state | state is an int of 0 or 1 where 1 is mono mode |
For each of the following, ssid is the Surface Strip ID for the track
As of Ardour 6.0, the user may use a subset all available strips. See: Making a user selected strip list.
SSID has a different meaning than RID in Ardour version 4.7 and before. Effectively, banking is always being used and the SSID is generated on the fly. The SSID is the position of the strip within bank as an int 1 to bank size. There are no gaps as there have been in the past. Depending on the value of strip_types sent to Ardour, Master and Monitor, may be included in the list of SSIDs or not as set in /set_surface.
Some Surfaces (many Android applets) are not able to deal with more than one parameter in a command. However, the two parameter commands below can also be sent as /strip/command/ssid param. In this case the param should be a float even if an int is required below.
| /bank_up | Change bank to the next higher bank. |
|---|---|
| /bank_up delta | Where delta is a float of 1 to bank up and -1 is bank down for use with an encoder (Ardour 5.11+) |
| /bank_down | Change bank to the next lower bank. |
| /use_group state | Where state is a float of 1 to use group or 0 to not use group. more info on use_group |
| /strip/spill ssid | Use strips this strip is grouped with or those that feed this bus (if this strip is a bus) or that this vca (if this is a VCA) controls. See Spill Strips for more details |
| /strip/hide ssid y/n | Where y/n = 1 hide this strip, 0 for show this track. Hiding strips. |
| /strip/name ssid strip_name | where strip_name is a string representing the desired name for the strip |
| /strip/group ssid group_name | where group_name is a string representing the name of the group desired. See groups for more details |
| /strip/mute ssid mute_st | where mute_st is a bool/int representing the desired mute state of the track |
| /strip/solo ssid solo_st | where solo_st is a bool/int representing the desired solo state of the track |
| /strip/solo_iso ssid state | where state is a bool/int representing the desired solo isolate state of the track |
| /strip/solo_safe ssid state | where state is a bool/int representing the desired solo safe/lock state of the track |
| /strip/monitor_input ssid monitor_st | where monitor_st is a bool/int where 1 is forced input monitoring. |
| /strip/monitor_disk ssid monitor_st | where monitor_st is a bool/int where 1 is forced disk monitoring. When input and disk are both off, Auto monitoring is enabled. |
| /strip/recenable ssid rec_st | where rec_st is a bool/int representing the desired rec state of the track |
| /strip/record_safe ssid rec_st | where rec_st is a bool/int representing the desired record safe state of the track |
| /strip/polarity ssid invert | where invert is a bool/int representing the desired polarity of the track |
| /strip/gain ssid gain | where gain is a float ranging from -193 to 6 representing the desired gain of the track in dB. |
| /strip/fader ssid position | where position is a float ranging from 0 to 1 representing the fader control position. |
| /strip/db_delta ssid delta | where delta is a float that will increase or decrease the gain of a track by the amount of the delta. (Ardour 5.11+) |
| /strip/*/automation ssid mode | where mode is an int ranging from 0 to 3 representing the desired automation mode for the control. See OSC Automation. |
| /strip/*/touch ssid state | where state is an int of 1 for touched and 0 for released. See OSC Automation. |
| /strip/trimdB ssid trim_db | where trim_db is a float ranging from -20 to 20 representing the desired trim of the track in dB. |
| /strip/pan_stereo_position ssid position | where position is a float ranging from 0 to 1 representing the desired pan position of the track |
| /strip/pan_stereo_width ssid width | where width is a float ranging from 0 to 1 representing the desired pan width of the track |
| /strip/send/gain ssid sendid send_gain | where sendid = nth_send, send_gain is a float ranging from -193 to +6 representing the desired gain in dB for the send |
| /strip/send/fader ssid sendid send_gain | where sendid = nth_send, send_gain is a float ranging from 0 to 1 representing the desired position for the send as a fader |
| /strip/send/enable ssid sendid state | where sendid = nth_send, state is 1 for enabled and 0 for disabled |
| /strip/list | see: Querying Ardour with OSC. |
| /strip/sends ssid | see: Querying Ardour with OSC. |
| /strip/receives ssid | see: Querying Ardour with OSC. |
| /strip/plugin/list ssid | see: Querying Ardour with OSC. |
| /strip/plugin/descriptor ssid | see: Querying Ardour with OSC. |
| /strip/plugin/reset ssid piid | where piid = nth Plugin, will reset all values to the plugin's original values |
| /strip/plugin/activate ssid piid | where piid = nth Plugin, will set the plugin's state to active |
| /strip/plugin/deactivate ssid piid | where piid = nth Plugin, will set the plugin's state to inactive |
| /strip/plugin/parameter ssid piid param value | where piid = nth Plugin, param = nth param, value is a float ranging from 0 to 1 representing the desired parameter value |
| /strip/name ssid name | where name is a string for the desired name of the track |
New for Ardour 5, A whole set of operations that work on the selected or expanded strip.
Selected strip operations are complex enough for their own page. Please read: Selection Considerations in OSC. This is most important if more than one OSC surface is being used with Ardour.
There are two kinds of selection in OSC. GUI selection and local expansion. By default expansion follows selection.
| /strip/select ssid y/n | Where y/n = 1 for select. Sets both GUI select and strip to expanded mode. (0 is ignored) |
|---|---|
| /strip/expand ssid y/n | Where y/n = 1 for expanded mode. Sets only local strip to Expanded. Setting to 0 resets the expansion to follow selection. |
| /select/expand y/n | Where y/n = 1 for expanded mode, 0 for Select mode. |
| /select/hide y/n | Where y/n = 1 hide this strip, 0 for show this track. Hiding strips. |
| /select/name strip_name | where strip_name is a string representing the desired name for the strip |
| /select/comment comment | where comment is a string representing the desired comment for the strip |
| /select/group group_name | where group_name is a string representing the name of the group desired. See groups for more details |
| /select/group/enable state | where state is an int representing the desired enable state of the group the selected strip is a part of |
| /select/group/gain state | where state is an int which sets the gain sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/relative state | where state is an int which sets relative state of thew group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/mute state | where state is an int which sets the mute sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/solo state | where state is an int which sets the solo sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/recenable state | where state is an int which sets the recenable sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/select state | where state is an int which sets the select sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/active state | where state is an int which sets the route active sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/color state | where state is an int which sets the color sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/group/monitoring state | where state is an int which sets the monitoring sharing of the group the strip belongs to. See Track and Bus Groups for more details |
| /select/recenable y/n | Where y/n is 1 for enabled and 0 for disabled |
| /select/record_safe y/n | Where y/n is 1 for safe and 0 for unlocked |
| /select/mute y/n | Where y/n is 1 for enabled and 0 for disabled |
| /select/solo y/n | Where y/n is 1 for enabled and 0 for disabled |
| /select/solo_iso state | where state is a bool/int representing the desired solo isolate state of the track |
| /select/solo_safe state | where state is a bool/int representing the desired solo safe/lock state of the track |
| /select/monitor_input y/n | Where y/n is 1 for monitor from input and 0 for auto |
| /select/monitor_disk y/n | Where y/n is 1 for monitor from disk and 0 for auto |
| /select/polarity invert | where invert is a bool/int representing the desired polarity of the track |
| /select/gain gain | Where gain is a float ranging from -193 to 6 representing the desired gain of the track in dB. |
| /select/fader position | Where position is an float ranging from 0 to 1 representing the fader control position. |
| /select/db_delta delta | where delta is a float that will increase or decrease the gain of the selected track by the amount of the delta. (Ardour 5.11+) |
| /select/vca name state | where name is a string with the name of the VCA, and state is an int that determines if the named VCA will control this strip. (Ardour 6.0) |
| /select/vca/toggle name | where name is a string with the name of the VCA. This toggles the use of the named vca with this strip. Any trailing "[_]" will be ignored. (Ardour 6.0) |
| /select/spill | show only strips this strip is grouped with or those that feed this bus or that this vca controls. See Spill Strips for more details |
| /select/*/automation mode | where mode is an int ranging from 0 to 3 representing the desired automation mode for the control. See OSC Automation. |
| /select/*/touch state | where state is an int of 1 for touched and 0 for released. See OSC Automation. |
| /select/trimdB trim_db | where trim_db is a float ranging from -20 to 20 representing the desired trim of the track in dB. |
| /select/pan_stereo_position position | where position is a float ranging from 0 to 1 representing the desired pan position of the track |
| /select/pan_stereo_width width | where width is a float ranging from 0 to 1 representing the desired pan width of the track |
| /select/pan_elevation_position position | where position is a float ranging from 0 to 1 representing the desired pan elevation of the track |
| /select/pan_frontback_position position | where position is a float ranging from 0 to 1 representing the desired front to back position of the track |
| /select/pan_lfe_control value | where value is a float ranging from 0 to 1 representing the desired LFE control value for the track |
| /select/send_gain, sendid send_gain | where sendid = nth_send, send_gain is a float ranging from -193 to +6 representing the desired gain in dB for the send |
| /select/send_fader, sendid send_gain | where sendid = nth_send, send_gain is a float ranging from 0 to 1 representing the desired position for the send as a fader |
| /select/send_enable, sendid state | where sendid = nth_send, state is 1 for enabled and 0 for disabled |
| /select/send_page, delta | where delta is an int or float selecting another send as a delta from the current send. |
| /select/plugin_page, delta | where delta is an int or float selecting another plugin parameter as a delta from the current parameter. |
| /select/plugin/activate, state | where state is an int or float with the desired state of the current plugin activation.(new Ardour 6.0) |
| /select/plugin/parameter, plugin parameter value | where plugin = nth plugin, parameter = nth parameter and value is a float from 0 to 1 |
/select/send_page and /select/plugin_page may be used
with a page up and page down switch by using a switch with a value of 1
for page up and a switch with a value of -1 for page down. An encoder
can be used as well. (these commands were added in Ardour version 5.10)
No grouping will occur unless use_group is set either
by using /set_surface/strip_types with the use groups bit set
or by using /use_group i 1.
The result for /strip/group or /select/group is determined by the parameter passed in the command and the current group and available list of groups. The group name the control surface sends may be:
To create a new group from a strip that is already joined to a group, the strip must first remove itself from the current group.
/select/spill or /strip/spill will:
spill/group, spill/bus or spill/vca can also be used to force the type of spilling that is done. This may be useful if the strip is a bus that is a part of a group and the group variation is required.
In all cases, if there is a bus or VCA attached to the group of strips it will be included as well.
What is less obvious, is how to return to the normal set of strips. There are a number of ways of doing so depending on the operator's wishes. The most obvious way is to use /set_surface/strip_types to set the strip list as desired. It is expected that a control surface may have more than one strip types button in any case to see only inputs or only busses etc and of course one to give a full mix. Another option is to reselect the custom set of strips with /strip/custom/mode mode.
Every single menu item in Ardour's GUI is accessible via OSC. There is a single common syntax to trigger the action as if it was selected with the mouse (or keyboard):
/access_action action_nameAs of Ardour 5.9, access_action can be inlined for control surfaces that are unable to send string parameters. The action_name is composed of a group and an action in the form of Group/action which fits very well as an OSC path extension:
/access_action/Group/action key_pressedThe key_pressed is optional, but if present is a float 1 or 0 where the command is ignored if key_pressed is 0.
Some of the Menu Actions duplicate other OSC commands. In all cases it is better to use the OSC commands rather than the Menu Actions if possible as the OSC commands are more direct.
The list of actions shows all available values of action-name for Ardour.