3 <abbr title="Open Sound Control"><dfn>OSC</dfn></abbr> lets synthesizers
4 and other devices communicate with Ardour. OSC devices can send commands
5 relating to playback (such as play or stop), performance (such as volume,
6 play, stop, and almost any other function (such as Edit, or Undo).
10 <em>Note:</em> OSC control has changed dramatically since Ardour 4.7.
11 The Path structure has been completely redone, Banking has been introduced,
12 The controller is now able to tell Ardour what kind of feedback it can
13 work with (including bank size) and the gain controls have new math
14 calculations. If you are using an Ardour version of 4.7 or less,
16 href="@@osc-control-for-ardour-4.7-and-prior">
17 Osc control in Ardour 4.7 and prior.</a>
21 <a href="#set-up">Control Surface Set</a>
24 <a href="#global">Master or Global messages</a>
27 <a href="#transport">Transport Control</a>
30 <a href="#recording">Recording control</a>
33 <a href="#information">Transport Information</a>
36 <a href="#editing">Editing-related</a>
39 <a href="#Master-strip">Master and Monitor strip control</a>
42 <a href="#strips">Track specific operations</a>
45 <a href="#select">Selected Strip Operations</a>
48 <a href="#menu">Menu actions</a>
52 Ardour is probably one of the most OSC-controllable audio applications
53 around, but as with all OSC-controllable apps, you can't do much without
54 knowing what <dfn>messages</dfn> can be sent. This document describes the
55 various categories of messages that Ardour understands. It is subject to
56 change, particularly the "Actions" part below, since this relates to the
57 GTK GUI for Ardour rather than the backend.
60 <h2>Connecting to Ardour via OSC</h2>
62 OSC support is not enabled by default, but can be turned on via
63 <kbd class="menu">Edit > Preferences > Control Surfaces</kbd>.
64 Once enabled, Ardour will listen on port <code>3819</code> by default.
65 This port number can be changed by editing <code>$ARDOUR_CONFIG</code>
66 and adding this line within the <code><Config></code> section:
68 <kbd class="input"><Option name="osc-port" value="<em>Your choice
72 Ardour sends any feedback to the port and address that sent any
73 feedback request or to a port set manually in the setup dialog.
74 The port does not have to match Ardour's port. In
75 fact it is better not to. This means that Ardour can deal with more
76 than one controller at a time. The two controllers can bank
77 independently and even use different math for faders. This could be
78 used to allow talent to adjust their own monitor mix using a tablet
79 or phone that can run an OSC controller. For a full explanation of
80 how Ardour's feedback works please read <a
81 href="@@osc58-feedback">
82 OSC feedback In Ardour.</a>
85 <h2 id="set-up">Control Surface Set Up</h2>
88 Control surface set up allows the controller to tell Ardour about its
89 capabilities. The surface can tell Ardour how many control strips it
90 has for banking, if it is capable of setting its faders or buttons
91 to values set by Ardour's GUI or automation, What kind of math the
95 Any time the <em>/set_surface</em> command is sent, the current bank
96 is recalculated and if feedback is turned on, the values of each
97 strip's controls are sent (or refreshed) as well. This will also
98 refresh the Master feedback setup.
101 As of Ardour 5.1, There is now a GUI setup in response to those using
102 tablets with applications such as touchOSC or AndrOSC who need to be
103 able to set a port for Ardour to send to. It can also change the
104 default setting for set_surface. For more information about Ardour's
105 OSC configuration GUI please read <a
106 href="@@osc58-using-the-setup-dialog">
107 Ardour's Setup Dialog.</a>
109 <p>If /set_surface is not sent, the default values are used:
111 <li><em>Bank Size</em>: 0 — No banking (or infinite bank size).</li>
112 <li><em>Strip Types</em>: 159 — All strip types except hidden and special.</li>
113 <li><em>Feedback</em>: 0 — All off.</li>
114 <li><em>Fader Mode</em>: 0 — gain in dB (not relevant with feedback off)</li>
115 <li><em>Send Page Size</em>: 0 — No Send Paging.</li>
116 <li><em>Plugin Page Size</em>: 0 — No Plugin Paging.</li>
117 <li><em>reply port</em>: 8000 — control surface will receive feedback on port 8000</li>
118 <li><em>Link set</em>: 0 — no linking for this control surface</li>
119 <li><em>Link ID</em>: 0 — no link ID</li>
123 These values give the same behaviour as prior versions of Ardour. (or the closest possible)
126 <kbd class="osc">/set_surface <em>bank_size</em> <em>strip_types</em>
127 <em>feedback</em> <em>fadermode</em> <em>send_page_size</em>
128 <em>plugin_page_size</em> <em>port</em> <em>linkset</em> <em>linkid</em></kbd>
130 See below for an explanation of each parameter.
133 The /set_surface message may have all values except the last in-line.
134 For example: <code>/set_surface/8/31/8403/0/8 i 16</code> would be valid.
135 Do be careful of switches which send a 0 on release, it may be necessary
136 to set the value as the release value rather than the press value.
139 The /set_surface message may have less than the full set of parameters.
140 those left out will remain as they were before the /set_surface message was
141 sent. All parameters included must be valid. For example, setting send page
142 size would require also setting bank_size, strip_types, feedback and gain mode.
143 using only two parameters will set bank_size and strip_types. Sending /set_surface with
144 no parameters will result in Ardour returning a /set_surface message with the
145 current settings. Surfaces using /set_surface iiii b st fb gm as was the case
146 in versions of Ardour older than 5.10 will continue to work.
150 Bank Size is the number of channel strips the controller supports
151 without banking. Setting this to 0 turns banking off by setting the
152 bank size to infinite.
155 Bank size can also be set with <em>/set_surface/bank_size size.</em>
159 strip_types is an integer made up of bits. The easy way to
160 deal with this is to think of strip_types items being worth a number and
161 then adding all those numbers together for a value to send.
162 Strip Types will determine what kind of strips will be included in
163 bank. This would include: Audio, MIDI, busses, VCAs, Master, Monitor
164 and hidden or selected strips.
167 Aside from setting the track types for the main mix assignments, using
168 /set_surface/strip_types with more than one surface button will allow
169 switching between modes for example: inputs only, busses only,
170 selected only, hidden only, by having the buttons send values of: 3,
171 12, 256, 512. A full mix button might have a value 31.
174 While Master and Monitor are listed as possibilities, most surfaces
175 will not use them. Using /master and /monitor makes more sense.
176 However, in the case where there are no master or monitor fader strips
177 on the surface, it may be necessary to include them in the banked
181 href="@@osc58-feedback-and-strip-types-values">
182 Calculating Feedback and Strip-types Values.</a>
185 Strip types can also be set with <em>/set_surface/strip_types types.</em>
188 <p>Feedback is an integer made up of bits. The easy way to
189 deal with this is to think of feedback items being worth a number and
190 then adding all those numbers together for a value to send.
193 href="@@osc58-feedback-and-strip-types-values#feedback">
194 Calculating Feedback and Strip-types Values.</a></p>
196 Feedback can also be set with <em>/set_surface/feedback feedback.</em>
203 <li><em>0:</em> dB value as a float from -193 to +6. Sent as
204 <kbd class="osc">/strip/gain SSID value</kbd>. (-193 or below are the same as −∞)</li>
205 <li><em>1:</em> A positional fader based on the same math
206 as Ardour's GUI. A Float from 0 to 1. Sent as
207 <kbd class="osc">/strip/fader SSID value</kbd>. At the same time the
208 gain value in dB is sent to the channel name as text. The name
209 will be restored after a short timeout.</li>
210 <li><em>2:</em> A positional fader based on the same math
211 as Ardour's GUI. A Float from 0 to 1. Sent as
212 <kbd class="osc">/strip/fader SSID value</kbd>. At the same time
213 the gain value in dB is sent as <kbd class="osc">/strip/gain SSID
215 <li><em>3:</em> A positional fader based on the same math
216 as Ardour's GUI. A Float from 0 to 1. Sent as
217 <kbd class="osc">/strip/fader SSID value</kbd>.</li>
221 Gainmode applies only to feedback values. The controller can choose
222 which gain math to use by choosing to use the /*/gain or /*/fader path
223 to send to Ardour. This makes sure a controller that doesn't set up
224 Ardour's OSC can still use either math. The gainmode for feedback also
225 determines the path Ardour uses for feedback so that the feedback
226 messages match the control messages.
229 Gain mode can also be set with <em>/set_surface/gainmode gainmode.</em>
231 <h3>send_page_size</h3>
233 Send_page_size is an int for the number of send channels that can be controlled
234 at one time. Each channel has a name, level and enable control. (added in Ardour 5.10)
237 Send page size can also be set with <em>/set_surface/send_page_size send_page_size.</em>
239 <h3>plugin_page_size</h3>
241 plugin_page_size is an int for the number of plugin controls that can be controlled
242 at one time. Each control has a name and level. As each plugin is different (as is each
243 parameter), the surface should expect to control the plugin parameters with a variable
244 control (pot or slider) with a float value from 0 to 1 (even on/off switches). (added in
248 Plugin page size can also be set with <em>/set_surface/plugin_page_size plugin_page_size.</em>
252 The port the controller would like to receive it's feedback on. Starting
253 with Ardour 6.0, the surface can directly set the manual port or set
254 it's host to <code>auto</code> port mode.
257 The value for <code>port</code> can be 0 for <code>auto</code> port mode or any
258 port value above 1024. It is suggested not to use Ardour's port number
259 of 3819 as controllers on the same machine that try to use the same
263 If the surface does not
264 tell Ardour which port to use, the default is 8000 or the setting
265 set up in the OSC setup GUI. There can only be one port setting per
266 host. If that setting is <code>auto</code>, than more than one
267 controller can be run on that host, but if a manual port is set there
268 can only be one. In the case of <code>auto</code> mode, the control
269 surface must set it's receive port to be the same as it's send port.
270 If that is not possible, then manual port mode must be used. This
271 allows a smart controller to use a number of ports on the same ip while
272 a smartphone set up as a personal monitor control can use the default
276 The host's port can also be set with <em>/set_surface/port port.</em>
279 Changing the port will remove feedback from a device on the same host
280 using a different port.
282 <h3>Link set and Link ID</h3>
284 Please see <a href="@@osc58-linking-surfaces">Linking Surfaces</a>
285 For more information.
287 <h2>Querying Ardour for information</h2>
289 The control Surface may wish to control the type a frequency of
290 updates it receives. It can do this with querying commands. See: <a
291 href="@@osc58-querying-ardour">
292 Querying Ardour with OSC.</a>
294 <h2>Using more than one surface</h2>
296 Ardour can use more than one surface at a time that both control the
297 same controls in Ardour. It is also possible to use two surfaces in
298 concert with each other. See: <a
299 href="@@osc58-linking-surfaces">
300 Linking Surfaces</a> for more information.
302 <h2>List of OSC messages</h2>
304 Parameter types show how the value will be used. However, they may
305 be sent as a different type if needed, see: <a
306 href="@@osc58-parameter-types">
307 Parameter Types in OSC.</a>
309 <h3 id="global">Master or Global messages</h3>
311 <h4 id="transport">Transport Control</h4>
313 <tr><th><kbd class="osc">/transport_stop</kbd></th>
314 <td>Stops a rolling transport</td></tr>
315 <tr><th><kbd class="osc">/transport_play</kbd></th>
316 <td>Puts transport in play mode</td></tr>
317 <tr><th><kbd class="osc">/toggle_roll</kbd></th>
318 <td>Toggles between play and stop</td></tr>
319 <tr><th><kbd class="osc">/stop_forget</kbd></th>
320 <td>Stop transport and delete/forget last take</td></tr>
321 <tr><th><kbd class="osc">/set_transport_speed <em>speed</em></kbd></th>
322 <td>where <em>speed</em> is a float ranging from -8.0f to 8.0f</td></tr>
323 <tr><th><kbd class="osc">/ffwd</kbd></th>
324 <td>Adds 1.5 times to transport speed to maximum +8 times normal speed</td></tr>
325 <tr><th><kbd class="osc">/rewind</kbd></th>
326 <td>Adds -1.5 times to transport speed to maximum -8 times normal speed</td></tr>
327 <tr><th><kbd class="osc">/goto_start</kbd></th>
328 <td>Move playhead to start of session</td></tr>
329 <tr><th><kbd class="osc">/goto_end</kbd></th>
330 <td>Move playhead to end of session</td></tr>
331 <tr><th><kbd class="osc">/jump_bars <em>bars</em></kbd></th>
332 <td>Where <em>bars</em> is a float (+/-) of the number of bars to jump</td></tr>
333 <tr><th><kbd class="osc">/jump_seconds <em>seconds</em></kbd></th>
334 <td>Where <em>seconds</em> is a float (+/-) of the number of seconds to jump</td></tr>
335 <tr><th><kbd class="osc">/toggle_click</kbd></th>
336 <td>Toggle metronome click on and off</td></tr>
337 <tr><th><kbd class="osc">/marker <em>marker</em></kbd></th>
338 <td>Where <em>marker</em> may be a float or int of the nth marker or a
339 string with the marker name to locate to (new Ardour 6.0). If the playhead
340 is at a marker and the <em>marker</em> is unique, the marker at the playhead
341 will be renamed to the string sent</td></tr>
342 <tr><th><kbd class="osc">/add_marker</kbd></th>
343 <td>(adds marker to the current transport position)</td></tr>
344 <tr><th><kbd class="osc">/remove_marker</kbd></th>
345 <td>Removes marker at the current transport position (if there is one)</td></tr>
346 <tr><th><kbd class="osc">/next_marker</kbd></th>
347 <td>Move playhead to next marker</td></tr>
348 <tr><th><kbd class="osc">/prev_marker</kbd></th>
349 <td>Move playhead to previous marker</td></tr>
350 <tr><th><kbd class="osc">/locate <em>spos</em> <em>roll</em></kbd></th>
351 <td>where <em>spos</em> is the target position in samples and
352 <em>roll</em> is a bool/integer defining whether you want transport
353 to be kept rolling or not</td></tr>
354 <tr><th><kbd class="osc">/loop_toggle</kbd></th>
355 <td>Toggle loop mode on and off</td></tr>
356 <tr><th><kbd class="osc">/loop_location <em>start</em> <em>end</em></kbd></th>
357 <td><em>start</em> is the beginning of a loop and <em>end</em> is the
358 end of a loop both are integer frame positions.</td></tr>
359 <tr><th><kbd class="osc">/midi_panic</kbd></th>
360 <td>Ardour will send an all notes off to all midi tracks</td></tr>
361 <tr><th><kbd class="osc">/cancel_all_solos</kbd></th>
362 <td>Cancel All Solos/PFLs/AFLs</td></tr>
368 <tr><th><kbd class="osc">/scrub <em>delta</em></kbd></th>
369 <td>Where <em>delta</em> is a float indicating forward or reverse movement.
370 See <a href="@@osc58-jog-modes#scrub">OSC Scrub Modes</a></td></tr>
371 <tr><th><kbd class="osc">/jog <em>delta</em></kbd></th>
372 <td>Where <em>delta</em> is a float indicating forward or reverse movement</td></tr>
373 <tr><th><kbd class="osc">/jog/mode <em>mode</em></kbd></th>
374 <td>Where <em>mode</em> is an int from 0 to 7 indicating what the <em>/jog</em>
375 command controls. See <a href="@@osc58-jog-modes">
376 OSC Jog Modes</a></td></tr>
379 <h4 id="recording">Recording control</h4>
381 <tr><th><kbd class="osc">/toggle_punch_in</kbd></th>
383 <tr><th><kbd class="osc">/toggle_punch_out</kbd></th>
385 <tr><th><kbd class="osc">/rec_enable_toggle</kbd></th>
386 <td>Toggles master record enable</td></tr>
389 <h4 id="information">Transport Information</h4>
391 <tr><th><kbd class="osc">/transport_frame</kbd></th>
392 <td>Ardour sends /transport_frame <em>current_frame</em></td></tr>
393 <tr><th><kbd class="osc">/transport_speed</kbd></th>
394 <td>Ardour sends /transport_speed <em>speed</em></td></tr>
395 <tr><th><kbd class="osc">/record_enabled</kbd></th>
396 <td>Ardour sends /record_enabled <em>recordenable_status</em></td></tr>
399 <h4 id="editing">Editing-related</h4>
401 <tr><th><kbd class="osc">/undo</kbd></th>
403 <tr><th><kbd class="osc">/redo</kbd></th>
405 <tr><th><kbd class="osc">/save_state</kbd></th>
406 <td>(this is the regular <kbd class="menu">Session > Save</kbd>
408 <tr><th><kbd class="osc">/session_name <em>new_name</em></kbd></th>
409 <td>Set session name to <em>new_name</em> (if new_name is legal and unique)</td></tr>
412 <h4 id="Master-strip">Master and Monitor strip control</h4>
414 <tr><th><kbd class="osc">/master/gain <em>dB</em></kbd></th>
415 <td>dB is a float indicating the desired gain in dB</td></tr>
416 <tr><th><kbd class="osc">/master/fader <em>position</em></kbd></th>
417 <td>position is a float between 0 and 1 setting the desired position of the fader</td></tr>
418 <tr><th><kbd class="osc">/master/db_delta <em>delta</em></kbd></th>
419 <td>where <em>delta</em> is a float that will increase or decrease the gain of master by the amount of the delta. (Ardour 5.11+)</td></tr>
420 <tr><th><kbd class="osc">/master/trimdB <em>dB</em></kbd></th>
421 <td>dB is a float from -20 to +20 representing the desired trim gain in dB</td></tr>
422 <tr><th><kbd class="osc">/master/pan_stereo_position <em>position</em></kbd></th>
423 <td>position is a float from 0 to 1 representing the desired pan position</td></tr>
424 <tr><th><kbd class="osc">/master/mute <em>key</em></kbd></th>
425 <td>key is an optional float 1 representing a master bus select</td></tr>
426 <tr><th><kbd class="osc">/master/select <em>state</em></kbd></th>
427 <td>state is an int of o or 1 representing the desired mute state</td></tr>
428 <tr><th><kbd class="osc">/monitor/gain <em>dB</em></kbd></th>
429 <td>dB is a float indicating the desired gain in dB</td></tr>
430 <tr><th><kbd class="osc">/monitor/fader <em>position</em></kbd></th>
431 <td>position is a float between 0 and 1 setting the desired position of the fader</td></tr>
432 <tr><th><kbd class="osc">/monitor/db_delta <em>delta</em></kbd></th>
433 <td>where <em>delta</em> is a float that will increase or decrease the gain of monitor by the amount of the delta. (Ardour 5.11+)</td></tr>
434 <tr><th><kbd class="osc">/monitor/mute <em>state</em></kbd></th>
435 <td>state is an int of 0 or 1 where 1 is muted</td></tr>
436 <tr><th><kbd class="osc">/monitor/dim <em>state</em></kbd></th>
437 <td>state is an int of 0 or 1 where 1 is dimmed</td></tr>
438 <tr><th><kbd class="osc">/monitor/mono <em>state</em></kbd></th>
439 <td>state is an int of 0 or 1 where 1 is mono mode</td></tr>
442 <h3 id="strips">Track specific operations</h3>
444 For each of the following, <em>ssid</em> is the Surface Strip ID for the track
447 As of Ardour 6.0, the user may use a subset all available strips. See:
448 <a href="@@osc58-custom-strips">
449 Making a user selected strip list.</a>
452 SSID has a different meaning than RID in Ardour version 4.7 and before.
453 Effectively, banking is always being used and the SSID is generated on
454 the fly. The SSID is the position of the strip within bank as an int
455 1 to bank size. There are no gaps as there have been in the past.
456 Depending on the value of strip_types sent to Ardour, Master and
457 Monitor, may be included in the list of SSIDs or not as set in
458 <em>/set_surface</em>.
461 Some Surfaces (many Android applets) are not able to deal with more
462 than one parameter in a command. However, the two parameter commands
463 below can also be sent as /strip/command/ssid param. In this case the
464 param should be a float even if an int is required below.
467 <tr><th><kbd class="osc">/bank_up</kbd></th>
468 <td>Change bank to the next higher bank.</td></tr>
469 <tr><th><kbd class="osc">/bank_up <em>delta</em></kbd></th>
470 <td>Where <em>delta</em> is a float of 1 to bank up and -1 is bank down for use with an encoder (Ardour 5.11+)</td></tr>
471 <tr><th><kbd class="osc">/bank_down </kbd></th>
472 <td>Change bank to the next lower bank.</td></tr>
473 <tr><th><kbd class="osc">/use_group <em>state</em></kbd></th>
474 <td>Where <em>state</em> is a float of 1 to use group or 0 to not use group.
475 <a href="@@osc58-feedback-and-strip-types-values#use-group">more info on use_group</a></td></tr>
476 <tr><th><kbd class="osc">/strip/spill <em>ssid</em></kbd></th>
477 <td> Use strips this strip is grouped with or those that feed this bus
478 (if this strip is a bus) or that this vca (if this is a VCA) controls.
479 See <a href="#spill">Spill Strips</a> for more details</td></tr>
480 <tr><th><kbd class="osc">/strip/hide <em>ssid</em> <em>y/n</em></kbd></th>
481 <td>Where <em>y/n</em> = 1 hide this strip, 0 for show this track.
482 <a href="@@osc58-feedback-and-strip-types-values#hidden">
483 Hiding strips.</a></td></tr>
484 <tr><th><kbd class="osc">/strip/name <em>ssid</em> <em>strip_name</em></kbd></th>
485 <td>where <em>strip_name</em> is a string representing the desired name for the strip</td></tr>
486 <tr><th><kbd class="osc">/strip/group <em>ssid</em> <em>group_name</em></kbd></th>
487 <td>where <em>group_name</em> is a string representing the name of the group desired.
488 See <a href="#groups">groups</a> for more details</td></tr>
489 <tr><th><kbd class="osc">/strip/mute <em>ssid</em> <em>mute_st</em></kbd></th>
490 <td>where <em>mute_st</em> is a bool/int representing the desired mute state of the track</td></tr>
491 <tr><th><kbd class="osc">/strip/solo <em>ssid</em> <em>solo_st</em></kbd></th>
492 <td>where <em>solo_st</em> is a bool/int representing the desired solo state of the track</td></tr>
493 <tr><th><kbd class="osc">/strip/solo_iso <em>ssid</em> <em>state</em></kbd></th>
494 <td>where <em>state</em> is a bool/int representing the desired solo isolate state of the track</td></tr>
495 <tr><th><kbd class="osc">/strip/solo_safe <em>ssid</em> <em>state</em></kbd></th>
496 <td>where <em>state</em> is a bool/int representing the desired solo safe/lock state of the track</td></tr>
497 <tr><th><kbd class="osc">/strip/monitor_input <em>ssid</em> <em>monitor_st</em></kbd></th>
498 <td>where <em>monitor_st</em> is a bool/int where 1 is forced input monitoring.</td></tr>
499 <tr><th><kbd class="osc">/strip/monitor_disk <em>ssid</em> <em>monitor_st</em></kbd></th>
500 <td>where <em>monitor_st</em> is a bool/int where 1 is forced disk monitoring. When input and disk are both off,
501 Auto monitoring is enabled.</td></tr>
502 <tr><th><kbd class="osc">/strip/recenable <em>ssid</em> <em>rec_st</em></kbd></th>
503 <td>where <em>rec_st</em> is a bool/int representing the desired rec state of the track</td></tr>
504 <tr><th><kbd class="osc">/strip/record_safe <em>ssid</em> <em>rec_st</em></kbd></th>
505 <td>where <em>rec_st</em> is a bool/int representing the desired record safe state of the track</td></tr>
506 <tr><th><kbd class="osc">/strip/polarity <em>ssid</em> <em>invert</em></kbd></th>
507 <td>where <em>invert</em> is a bool/int representing the desired polarity of the track</td></tr>
508 <tr><th><kbd class="osc">/strip/gain <em>ssid</em> <em>gain</em></kbd></th>
509 <td>where <em>gain</em> is a float ranging from -193 to 6 representing the desired gain of the track in dB.</td></tr>
510 <tr><th><kbd class="osc">/strip/fader <em>ssid</em> <em>position</em></kbd></th>
511 <td>where <em>position</em> is a float ranging from 0 to 1 representing the fader control position.</td></tr>
512 <tr><th><kbd class="osc">/strip/db_delta <em>ssid</em> <em>delta</em></kbd></th>
513 <td>where <em>delta</em> is a float that will increase or decrease the gain of a track by the amount of the delta. (Ardour 5.11+)</td></tr>
514 <tr><th><kbd class="osc">/strip/*/automation <em>ssid</em> <em>mode</em></kbd></th>
515 <td>where <em>mode</em> is an int ranging from 0 to 3 representing the desired automation mode for the control.
516 <a href="@@osc58-automation">See OSC Automation.</a></td></tr>
517 <tr><th><kbd class="osc">/strip/*/touch <em>ssid</em> <em>state</em></kbd></th>
518 <td>where <em>state</em> is an int of 1 for touched and 0 for released.
519 <a href="@@osc58-automation">See OSC Automation.</a></td></tr>
520 <tr><th><kbd class="osc">/strip/trimdB <em>ssid</em> <em>trim_db</em></kbd></th>
521 <td>where <em>trim_db</em> is a float ranging from -20 to 20 representing the desired trim of the track in dB.</td></tr>
522 <tr><th><kbd class="osc">/strip/pan_stereo_position <em>ssid</em> <em>position</em></kbd></th>
523 <td>where <em>position</em> is a float ranging from 0 to 1 representing the desired pan position of the track</td></tr>
524 <tr><th><kbd class="osc">/strip/pan_stereo_width <em>ssid</em> <em>width</em></kbd></th>
525 <td>where <em>width</em> is a float ranging from 0 to 1 representing the desired pan width of the track</td></tr>
526 <tr><th><kbd class="osc">/strip/send/gain <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></th>
527 <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
528 ranging from -193 to +6 representing the desired gain in dB for the send</td></tr>
529 <tr><th><kbd class="osc">/strip/send/fader <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></th>
530 <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
531 ranging from 0 to 1 representing the desired position for the send as a fader</td></tr>
532 <tr><th><kbd class="osc">/strip/send/enable <em>ssid</em> <em>sendid</em> <em>state</em></kbd></th>
533 <td>where <em>sendid</em> = nth_send, <em>state</em> is 1 for enabled and 0 for disabled</td></tr>
534 <tr><th><kbd class="osc">/strip/list </kbd></th>
535 <td>see: <a href="@@osc58-querying-ardour">
536 Querying Ardour with OSC.</a></td></tr>
537 <tr><th><kbd class="osc">/strip/sends <em>ssid</em></kbd></th>
538 <td>see: <a href="@@osc58-querying-ardour">
539 Querying Ardour with OSC.</a></td></tr>
540 <tr><th><kbd class="osc">/strip/receives <em>ssid</em></kbd></th>
541 <td>see: <a href="@@osc58-querying-ardour">
542 Querying Ardour with OSC.</a></td></tr>
543 <tr><th><kbd class="osc">/strip/plugin/list <em>ssid</em></kbd></th>
544 <td>see: <a href="@@osc58-querying-ardour">
545 Querying Ardour with OSC.</a></td></tr>
546 <tr><th><kbd class="osc">/strip/plugin/descriptor <em>ssid</em></kbd></th>
547 <td>see: <a href="@@osc58-querying-ardour">
548 Querying Ardour with OSC.</a></td></tr>
549 <tr><th><kbd class="osc">/strip/plugin/reset <em>ssid</em> <em>piid</em> </kbd></th>
550 <td>where <em>piid</em> = nth Plugin, will reset all values to the plugin's original values</td></tr>
551 <tr><th><kbd class="osc">/strip/plugin/activate <em>ssid</em> <em>piid</em> </kbd></th>
552 <td>where <em>piid</em> = nth Plugin, will set the plugin's state to active</td></tr>
553 <tr><th><kbd class="osc">/strip/plugin/deactivate <em>ssid</em> <em>piid</em> </kbd></th>
554 <td>where <em>piid</em> = nth Plugin, will set the plugin's state to inactive</td></tr>
555 <tr><th><kbd class="osc">/strip/plugin/parameter <em>ssid</em> <em>piid</em> <em>param</em> <em>value</em></kbd></th>
556 <td>where <em>piid</em> = nth Plugin, <em>param</em> = nth param, <em>value</em>
557 is a float ranging from 0 to 1 representing the desired parameter value</td></tr>
558 <tr><th><kbd class="osc">/strip/name <em>ssid</em> <em>name</em></kbd></th>
559 <td>where <em>name</em> is a string for the desired name of the track</td></tr>
561 <h3 id="select">Selected Strip Operations</h3>
563 New for Ardour 5, A whole set of operations that work on the selected
567 Selected strip operations are complex enough for their own page.
569 href="@@osc58-selection-and-expansion-considerations">
570 Selection Considerations in OSC.</a> This is most important if more
571 than one OSC surface is being used with Ardour.
574 There are two kinds of selection in OSC. GUI selection and local
575 expansion. By default expansion follows selection.
578 GUI selection: Use <em>/strip/select</em> to set. Selecting
579 a strip in the GUI will set OSC surface select and the surface
580 will set GUI selection as well.
583 Local expansion: Use <em>/strip/expand</em> to expand a strip
584 without changing overall selection. When /strip/expand is set
585 to 0 or false, the select channel will go back to using the
586 strip selected by the GUI. While expand is turned on,
587 selecting a strip on the GUI does not
588 select the OSC strip. Sending a /strip/select message will
589 override the expand as if it had been set to false.
590 Good for more than one OSC controller at a time.
596 <tr><th><kbd class="osc">/strip/select <em>ssid</em> <em>y/n</em></kbd></th>
597 <td>Where <em>y/n</em> = 1 for select. Sets both GUI select and strip
598 to expanded mode. (0 is ignored)</td></tr>
599 <tr><th><kbd class="osc">/strip/expand <em>ssid</em> <em>y/n</em></kbd></th>
600 <td>Where <em>y/n</em> = 1 for expanded mode. Sets only local strip to
601 Expanded. Setting to 0 resets the expansion to follow selection.</td></tr>
602 <tr><th><kbd class="osc">/select/expand <em>y/n</em></kbd></th>
603 <td>Where <em>y/n</em> = 1 for expanded mode, 0 for Select mode.</td></tr>
604 <tr><th><kbd class="osc">/select/hide <em>y/n</em></kbd></th>
605 <td>Where <em>y/n</em> = 1 hide this strip, 0 for show this track.
606 <a href="@@osc58-feedback-and-strip-types-values#hidden">
607 Hiding strips.</a></td></tr>
608 <tr><th><kbd class="osc">/select/name <em>strip_name</em></kbd></th>
609 <td>where <em>strip_name</em> is a string representing the desired name for the strip</td></tr>
610 <tr><th><kbd class="osc">/select/comment <em>comment</em></kbd></th>
611 <td>where <em>comment</em> is a string representing the desired comment for the strip</td></tr>
612 <tr><th><kbd class="osc">/select/group <em>group_name</em></kbd></th>
613 <td>where <em>group_name</em> is a string representing the name of the group desired.
614 See <a href="#groups">groups</a> for more details</td></tr>
615 <tr><th><kbd class="osc">/select/group/enable <em>state</em></kbd></th>
616 <td>where <em>state</em> is an int representing the desired enable state
617 of the group the selected strip is a part of</td></tr>
618 <tr><th><kbd class="osc">/select/group/gain <em>state</em></kbd></th>
619 <td>where <em>state</em> is an int which sets the gain sharing of the
620 group the strip belongs to. See <a href="@@track-and-bus-groups">
621 Track and Bus Groups</a> for more details</td></tr>
622 <tr><th><kbd class="osc">/select/group/relative <em>state</em></kbd></th>
623 <td>where <em>state</em> is an int which sets relative state of thew
624 group the strip belongs to. See <a href="@@track-and-bus-groups">
625 Track and Bus Groups</a> for more details</td></tr>
626 <tr><th><kbd class="osc">/select/group/mute <em>state</em></kbd></th>
627 <td>where <em>state</em> is an int which sets the mute sharing of the
628 group the strip belongs to. See <a href="@@track-and-bus-groups">
629 Track and Bus Groups</a> for more details</td></tr>
630 <tr><th><kbd class="osc">/select/group/solo <em>state</em></kbd></th>
631 <td>where <em>state</em> is an int which sets the solo sharing of the
632 group the strip belongs to. See <a href="@@track-and-bus-groups">
633 Track and Bus Groups</a> for more details</td></tr>
634 <tr><th><kbd class="osc">/select/group/recenable <em>state</em></kbd></th>
635 <td>where <em>state</em> is an int which sets the recenable sharing of the
636 group the strip belongs to. See <a href="@@track-and-bus-groups">
637 Track and Bus Groups</a> for more details</td></tr>
638 <tr><th><kbd class="osc">/select/group/select <em>state</em></kbd></th>
639 <td>where <em>state</em> is an int which sets the select sharing of the
640 group the strip belongs to. See <a href="@@track-and-bus-groups">
641 Track and Bus Groups</a> for more details</td></tr>
642 <tr><th><kbd class="osc">/select/group/active <em>state</em></kbd></th>
643 <td>where <em>state</em> is an int which sets the route active sharing of the
644 group the strip belongs to. See <a href="@@track-and-bus-groups">
645 Track and Bus Groups</a> for more details</td></tr>
646 <tr><th><kbd class="osc">/select/group/color <em>state</em></kbd></th>
647 <td>where <em>state</em> is an int which sets the color sharing of the
648 group the strip belongs to. See <a href="@@track-and-bus-groups">
649 Track and Bus Groups</a> for more details</td></tr>
650 <tr><th><kbd class="osc">/select/group/monitoring <em>state</em></kbd></th>
651 <td>where <em>state</em> is an int which sets the monitoring sharing of the
652 group the strip belongs to. See <a href="@@track-and-bus-groups">
653 Track and Bus Groups</a> for more details</td></tr>
654 <tr><th><kbd class="osc">/select/recenable <em>y/n</em></kbd></th>
655 <td>Where <em>y/n</em> is 1 for enabled and 0 for disabled</td></tr>
656 <tr><th><kbd class="osc">/select/record_safe <em>y/n</em></kbd></th>
657 <td>Where <em>y/n</em> is 1 for safe and 0 for unlocked</td></tr>
658 <tr><th><kbd class="osc">/select/mute <em>y/n</em></kbd></th>
659 <td>Where <em>y/n</em> is 1 for enabled and 0 for disabled</td></tr>
660 <tr><th><kbd class="osc">/select/solo <em>y/n</em></kbd></th>
661 <td>Where <em>y/n</em> is 1 for enabled and 0 for disabled</td></tr>
662 <tr><th><kbd class="osc">/select/solo_iso <em>state</em></kbd></th>
663 <td>where <em>state</em> is a bool/int representing the desired solo isolate state of the track</td></tr>
664 <tr><th><kbd class="osc">/select/solo_safe <em>state</em></kbd></th>
665 <td>where <em>state</em> is a bool/int representing the desired solo safe/lock state of the track</td></tr>
666 <tr><th><kbd class="osc">/select/monitor_input <em>y/n</em></kbd></th>
667 <td>Where <em>y/n</em> is 1 for monitor from input and 0 for auto</td></tr>
668 <tr><th><kbd class="osc">/select/monitor_disk <em>y/n</em></kbd></th>
669 <td>Where <em>y/n</em> is 1 for monitor from disk and 0 for auto</td></tr>
670 <tr><th><kbd class="osc">/select/polarity <em>invert</em></kbd></th>
671 <td>where <em>invert</em> is a bool/int representing the desired polarity of the track</td></tr>
672 <tr><th><kbd class="osc">/select/gain <em>gain</em></kbd></th>
673 <td>Where <em>gain</em> is a float ranging from -193 to 6 representing the desired gain of the track in dB.</td></tr>
674 <tr><th><kbd class="osc">/select/fader <em>position</em></kbd></th>
675 <td>Where <em>position</em> is an float ranging from 0 to 1 representing the fader control position.</td></tr>
676 <tr><th><kbd class="osc">/select/db_delta <em>delta</em></kbd></th>
677 <td>where <em>delta</em> is a float that will increase or decrease the
678 gain of the selected track by the amount of the delta. (Ardour 5.11+)</td></tr>
679 <tr><th><kbd class="osc">/select/vca <em>name</em> <em>state</em></kbd></th>
680 <td>where <em>name</em> is a string with the name of the VCA, and
681 <em>state</em> is an int that determines if the named VCA will control
682 this strip. (Ardour 6.0)</td></tr>
683 <tr><th><kbd class="osc">/select/vca/toggle <em>name</em></kbd></th>
684 <td>where <em>name</em> is a string with the name of the VCA. This toggles the
685 use of the named vca with this strip. Any trailing "[_]" will be ignored.
686 (Ardour 6.0)</td></tr>
687 <tr><th><kbd class="osc">/select/spill</kbd></th>
688 <td> show only strips this strip is grouped with or
689 those that feed this bus or that this vca controls.
690 See <a href="#spill">Spill Strips</a> for more details</td></tr>
691 <tr><th><kbd class="osc">/select/*/automation <em>mode</em></kbd></th>
692 <td>where <em>mode</em> is an int ranging from 0 to 3 representing the desired automation mode for the control.
693 <a href="@@osc58-automation">See OSC Automation.</a></td></tr>
694 <tr><th><kbd class="osc">/select/*/touch <em>state</em></kbd></th>
695 <td>where <em>state</em> is an int of 1 for touched and 0 for released.
696 <a href="@@osc58-automation">See OSC Automation.</a></td></tr>
697 <tr><th><kbd class="osc">/select/trimdB <em>trim_db</em></kbd></th>
698 <td>where <em>trim_db</em> is a float ranging from -20 to 20 representing the desired trim of the track in dB.</td></tr>
699 <tr><th><kbd class="osc">/select/pan_stereo_position <em>position</em></kbd></th>
700 <td>where <em>position</em> is a float ranging from 0 to 1 representing the desired pan position of the track</td></tr>
701 <tr><th><kbd class="osc">/select/pan_stereo_width <em>width</em></kbd></th>
702 <td>where <em>width</em> is a float ranging from 0 to 1 representing the desired pan width of the track</td></tr>
703 <tr><th><kbd class="osc">/select/pan_elevation_position <em>position</em></kbd></th>
704 <td>where <em>position</em> is a float ranging from 0 to 1 representing the desired pan elevation of the track</td></tr>
705 <tr><th><kbd class="osc">/select/pan_frontback_position <em>position</em></kbd></th>
706 <td>where <em>position</em> is a float ranging from 0 to 1 representing the desired front to back position of the track</td></tr>
707 <tr><th><kbd class="osc">/select/pan_lfe_control <em>value</em></kbd></th>
708 <td>where <em>value</em> is a float ranging from 0 to 1 representing the desired LFE control value for the track</td></tr>
709 <tr><th><kbd class="osc">/select/send_gain, <em>sendid</em> <em>send_gain</em></kbd></th>
710 <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
711 ranging from -193 to +6 representing the desired gain in dB for the send</td></tr>
712 <tr><th><kbd class="osc">/select/send_fader, <em>sendid</em> <em>send_gain</em></kbd></th>
713 <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
714 ranging from 0 to 1 representing the desired position for the send as a fader</td></tr>
715 <tr><th><kbd class="osc">/select/send_enable, <em>sendid</em> <em>state</em></kbd></th>
716 <td>where <em>sendid</em> = nth_send, <em>state</em> is 1 for enabled and 0 for disabled</td></tr>
717 <tr><th><kbd class="osc">/select/send_page, <em>delta</em></kbd></th>
718 <td>where <em>delta</em> is an int or float selecting another send as a delta from the current send.</td></tr>
719 <tr><th><kbd class="osc">/select/plugin_page, <em>delta</em></kbd></th>
720 <td>where <em>delta</em> is an int or float selecting another plugin parameter as a delta from the current parameter.</td></tr>
721 <tr><th><kbd class="osc">/select/plugin/activate, <em>state</em></kbd></th>
722 <td>where <em>state</em> is an int or float with the desired state of the current plugin activation.(new Ardour 6.0)</td></tr>
723 <tr><th><kbd class="osc">/select/plugin/parameter, <em>plugin</em> <em>parameter</em> <em>value</em></kbd></th>
724 <td>where <em>plugin</em> = nth plugin, <em>parameter</em> = nth parameter and <em>value</em> is a float from 0 to 1</td></tr>
727 <code>/select/send_page</code> and <code>/select/plugin_page</code> may be used
728 with a page up and page down switch by using a switch with a value of <code>1</code>
729 for page up and a switch with a value of <code>-1</code> for page down. An encoder
730 can be used as well. (these commands were added in Ardour version 5.10)
732 <h4 id="groups">Using groups with strip and select (new for Ardour 6.0)</h4>
734 No grouping will occure unless <code>use_group</code> is set either
735 by using <kbd class="osc">/set_surface/strip_types</kbd> with the use groups bit set
736 or by using <kbd class="osc">/use_group i 1</kbd>.
739 The result for <kbd class="osc">/strip/group</kbd> or
740 <kbd class="osc">/select/group</kbd> is determined by the parameter
741 passed in the command and the current group and available list of
742 groups. The group name the control surface sends may be:
746 "none", "" or " " will remove this strip from this group. If this
747 was the only strip in this group, the group is deleted. Some
748 OSC controllers have trouble sending an empty string and a
749 list of groups contains "none" as well so a dropdown can just
750 send a text item and work.
753 The name of a group this strip does not belong to will remove
754 this strip from it's current group and add it to the named group.
755 If this strip was the only strip in the group it was removed from,
756 that group will be deleted.
759 An unused name when this strip is not part of a group will create
760 a new group with the group name sent and add this strip to that
764 An unused name when this strip is already a part of a group will
765 rename this group to the name sent.
768 <p>To create a new group from a strip that is already joined to a group,
769 the strip must first remove itself from the current group.
771 <h4 id="spill">Spill Strips</h4>
772 <p><kbd class="osc">/select/spill</kbd> or <kbd class="osc">/strip/spill</kbd>
776 set the current set of strips in use to include only the strips
777 that are a part of the group the strip is a part of so long
778 as that strip is a track.</li>
780 set the current set of strips to the set of strips that feed
781 this strip if it is a bus. In the case where this strip is
782 being fed by sends rather than strip outputs, the strips that
783 feed this bus will have their names set to the name of the strip
784 with <em>-send</em> appended to it and the fader, pan and mute will
785 control the send rather than the strip. The other strip controls
786 will be disabled in this mode. This only happens when the strip
787 that calls spill is a bus. In the case where a strip that is part
788 of a group is chosen as above where the group all sends to a common
789 bus this will not happen. This can be useful for a group that uses
790 "Add New Aux Bus" to switch from sends to faders.</li>
792 set the current set of strips to the set of strips that are
793 controled by the VCA if this strip is a VCA.</li>
795 <p>spill/group, spill/bus or spill/vca can also be used to force
796 the type of spilling that is done. This may be useful if the strip
797 is a bus that is a part of a group and the group variation is required.</p>
798 <p>In all cases, if there is a bus or VCA attached to the group of strips
799 it will be included as well.</p>
800 <P>What is less obvious, is how to return to the normal set of strips.
801 There are a number of ways of doing so depending on the operator's wishes.
802 The most obvious way is to use <kbd class="osc">/set_surface/strip_types</kbd>
803 to set the strip list as desired. It is expected that a control surface
804 may have more than one strip types button in any case to see only
805 inputs or only busses etc and of course one to give a full mix. Another
806 option is to reselect the custom set of strips with
807 <kbd class="osc">/strip/custom/mode <em>mode</em></kbd>.
810 <h3 id="menu">Menu actions</h3>
812 Every single menu item in Ardour's GUI is accessible via OSC. There is
813 a single common syntax to trigger the action as if it was selected
814 with the mouse (or keyboard):</p>
815 <kbd class="osc">/access_action <em>action_name</em></kbd>
817 As of Ardour 5.9, <em>access_action</em> can be inlined for control surfaces
818 that are unable to send string parameters. The <em>action_name</em> is composed of
819 a group and an action in the form of <em>Group/action</em> which fits very well
820 as an OSC path extension:
822 <kbd class="osc">/access_action/<em>Group/action</em> <em>key_pressed</em></kbd>
824 The key_pressed is optional, but if present is a float 1 or 0 where the
825 command is ignored if key_pressed is 0.
828 Some of the Menu Actions duplicate other OSC commands. In all cases it is better
829 to use the OSC commands rather than the Menu Actions if possible as the OSC commands
833 The <a href="@@list-of-menu-actions"> list of actions</a>
834 shows all available values of <em>action-name</em> for Ardour.
837 <!--p> These listed below are still working but may in the future not work
838 any more. All of them are just short cuts to a menu action and since menu
839 actions can now be "inlined", all known OSC controllers can call them directly.
840 Any of these actions that can be moved to session->action calls may reapear.
843 <tr><th><kbd class="osc">/mark_in</kbd></th>
844 <td>Marks the begining of a range at the current transport position</td></tr>
845 <tr><th><kbd class="osc">/mark_out</kbd></th>
846 <td>Marks the end of a range at the current transport position</td></tr>
847 <tr><th><kbd class="osc">/set_loop_range</kbd></th>
848 <td>Uses edit range as loop range</td></tr>
849 <tr><th><kbd class="osc">/set_session_range</kbd></th>
850 <td>Uses edit range as session range</td></tr>
851 <tr><th><kbd class="osc">/quick_snapshot_switch</kbd></th>
852 <td>Take a snapshot and switch to new version</td></tr>
853 <tr><th><kbd class="osc">/quick_snapshot_stay</kbd></th>
854 <td>Take a snapshot and keep working on this version</td></tr>
855 <tr><th><kbd class="osc">/fit_*_track(s)</kbd></th>
856 <td>Where <em>*</em> is one of 1, 2, 4, 8, 16, 32 or all. Fits this
857 many tracks in editor window. (add s for more than 1)</td></tr>
858 <tr><th><kbd class="osc">/zoom_*</kbd></th>
859 <td>Zoom editor to include <em>*</em> where <em>*</em> is 100_ms, 1_sec,
860 10_sec, 1_min, 5_min, 10_min or to_session</td></tr>
861 <tr><th><kbd class="osc">/temporal_zoom_in</kbd></th>
862 <td>Zoom editor in to show less time</td></tr>
863 <tr><th><kbd class="osc">/temporal_zoom_out</kbd></th>
864 <td>Zoom editor out to show more time</td></tr>
865 <tr><th><kbd class="osc">/scroll_up_1_track</kbd></th>
866 <td>Scroll the editor pane up 1 track</td></tr>
867 <tr><th><kbd class="osc">/scroll_up_1_page</kbd></th>
868 <td>Scroll the editor pane up 1 page</td></tr>
869 <tr><th><kbd class="osc">/scroll_dn_1_track</kbd></th>
870 <td>Scroll the editor pane down 1 track</td></tr>
871 <tr><th><kbd class="osc">/scroll_dn_1_page</kbd></th>
872 <td>Scroll the editor pane down 1 page</td></tr>
873 <tr><th><kbd class="osc">/set_punch_range</kbd></th>
874 <td>Uses edit range as punch range</td></tr>
875 <dt><kbd class="osc">/toggle_all_rec_enables</kbd></th>
876 <td>(toggles all tracks' recording state)</dd-->