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 two new math styles have been added
to gain controls. 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.
Connecting to Ardour via OSC
OSC support is not enabled by default, but can be turned on via
.
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:
<Option name="osc-port" value="Your choice
here"/>
Ardour sends any feedback to the port and address that sent any
feedback request. 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
Control surface set up allows the controller to tell Ardour about it's
capabilities. The surface can tell Ardour how many control strips it
has for banking, if it is capable of setting it's 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.
Surface Port Setting is available in the OSC GUI.
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:
- Bank Size: 0—No banking (or infinite bank size).
- Strip Types: All strip types except hidden and special.
- Feedback: 0—All off.
- Fader Mode: 0—gain in dB (not relevant with feedback off)
These values give the same behaviour as prior versions of Ardour. (or the closest possible)
- /set_surface bank_size strip_types
feedback fadermode
-
See below for an explanation of each parameter.
bank_size
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
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
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
Gainmode is a an int that acts as a bool:
- 0 (or false) dB value as a float from -193 to +6. Sent as
/strip/gain SSID value. (-193 or below are the same as -inf)
- 1 (or true) A positional fader based on the same math
as Ardour's GUI. An Float from 0 to 1. Sent as
/strip/fader SSID value
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.
Querying Ardour for 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.
List of OSC messages
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.
Master or Global messages
Transport Control
- /transport_stop
- /transport_play
- /toggle_roll
- Toggles between play and stop
- /set_transport_speed s
- where s is a float ranging from -8.0f to 8.0f
- /ffwd
- /rewind
- /goto_start
- /goto_end
- /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
- /add_marker
- (adds marker to the current transport position)
- /remove_marker
- Removes marker at the current transport position (if there is one)
- /mark_in
- Marks the begining of a range at the current transport position
- /mark_out
- Marks the end of a range at the current transport position
- /next_marker
- /prev_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
- /loop_location start end
- start is the beginning of a loop and end is the
end of a loop both are integer frame positions.
- /set_loop_range
- Uses edit range as loop range
- /set_session_range
- Uses edit range as session range
- /toggle_click
- /midi_panic
- Ardour will send an all notes off to all midi tracks
- /cancel_all_solos
- Cancel All Solos/PFLs/AFLs
Transport Information
- /transport_frame
- Ardour sends /transport_frame current_frame
- /transport_speed
- Ardour sends /transport_speed speed
- /record_enabled
- Ardour sends /record_enabled recordenable_status
Editing-related
- /undo
- /redo
- /save_state
- (this is the regular
operation)
- /quick_snapshot_switch
- Take a snapshot and switch to new version
- /quick_snapshot_stay
- Take a snapshot and keep working on this version
- /fit_*_track(s)
- Were * is one of 1, 2, 4, 8, 16, 32 or all. Fits this
many tracks in editor window. (add s for more than 1)
- /zoom_*
- Zoom editor to include * where * is 100_ms, 1_sec,
10_sec, 1_min, 5_min, 10_min or to_session
- /temporal_zoom_in
- Zoom editor in to show less time
- /temporal_zoom_out
- Zoom editor out to show more time
- /scroll_up_1_track
- Scroll the editor pane up 1 track
- /scroll_up_1_page
- Scroll the editor pane up 1 page
- /scroll_dn_1_track
- Scroll the editor pane down 1 track
- /scroll_dn_1_page
- Scroll the editor pane down 1 page
Recording control
- /toggle_punch_in
- /toggle_punch_out
- /set_punch_range
- Uses edit range as punch range
- /rec_enable_toggle
- /stop_forget
- Stop transport and delete/forget last take
Master and Monitor strip control
- /master/gain dB
- See gain in strips
- /master/fader position
- See fader in strips
- /master/trimdB dB
- see trimdb in strips
- /master/pan_stereo_position position
- See pan_stereo_position in strips
- /master/mute yn
- See mute in strips
- /monitor/gain dB
- See gain in strips
- /monitor/fader position
- See fader in strips
Track specific operations
For each of the following, ssid is the Surface Strip ID for the track
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_down
- Change bank to the next lower bank.
- /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/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
Selected Strip Operations
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.
-
GUI selection: Use /strip/select to set. Selecting
a strip in the GUI will set OSC surface select and the surface
will set GUI selection as well.
-
Local expansion: Use /strip/expand to expand a strip
without changing overall selection. When /strip/expand is set
to 0 or false, the select channel will go back to using the
strip selected by the GUI. While expand is turned on,
selecting a strip on the GUI does not
select the OSC strip. Sending a /strip/select message will
override the expand as if it had been set to false.
Good for more than one OSC controller at a time.
- /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/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/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
Menu actions
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_name
The
list of actions shows all available values of action-name as of
June 2016 for Ardour 5.0.pre0.1. You can get the current list at any
time by running Ardour with the -b flag.