4 <a href="@@generic-midi-learn"><dfn>MIDI learning</dfn></a>
5 for more or less any control. This was a nice feature that quite a few other
6 DAWs are providing by now, but it didn't allow Ardour to work "out of the
7 box" with sensible defaults for existing commercial MIDI
8 controllers. In Ardour 3 and later versions, we have augmented the
9 MIDI learn feature with the ability to load a <dfn>MIDI binding map</dfn>
10 for a given controller, which can set up an arbitrary number of physical
11 controls with anything inside Ardour that can be controlled.
14 Currently (August 2016), we have presets for the following devices/modes:
17 <li>AKAI MidiMix (2 layouts)</li>
22 <li>Arturia KeyLab49</li>
23 <li>Behringer BCF2000</li>
24 <li>Behringer BCF2000 (Mackie Emulation mode; better to use
25 Ardour's actual Mackie Control Protocol support)</li>
26 <li>Behringer DDX3216</li>
27 <li>Korg nanoKONTROL (3 layouts)</li>
28 <li>Korg nanoKONTROL 2 (2 layouts)</li>
30 <li>M-Audio Axiom 25</li>
31 <li>M-Audio Axiom 61</li>
32 <li>M-Audio Axiom Air 25</li>
33 <li>M-Audio Axiom Air Mini 32</li>
34 <li>M-Audio Oxygen 8v2</li>
35 <li>M-Audio Oxygen 25</li>
36 <li>M-Audio Oxygen 49</li>
37 <li>M-Audio Oxygen 61v3 (2 layouts)</li>
38 <li>Novation Impulse 49</li>
39 <li>Novation Impulse 61</li>
40 <li>Novation LaunchControl XL</li>
41 <li>Novation LaunchKey 25</li>
42 <li>Novation LaunchKey 49</li>
44 <li>Roland V Studio 20</li>
49 At this time, new binding maps need to be created with a text editor.
51 MIDI binding maps are accessible by double-clicking <kbd class="menu">Edit
52 > Preferences > Control Surfaces > Generic MIDI</kbd>. Ardour will
53 retain your selection after you choose one.
56 <h2>Creating new MIDI maps</h2>
57 <h3>The Basic Concept</h3>
59 Since the beginning of time (well, sometime early in the 2.X series),
60 Ardour has had the concept of identifying each track and bus with a
61 <dfn>remote control ID</dfn>. This ID uniquely identifies a track or bus
62 so that when messages arrive from elsewhere via MIDI or OSC , we can determine
63 which track or bus they are intended to control. See
64 <a href="@@controlling-track-ordering">
65 remote control IDs</a> for more information.
66 You just need to know that there is a "first track" and its remote control
69 <h3>Getting Started</h3>
71 MIDI bindings are stored in files with the suffix ".map" attached to their
72 name. The minimal content looks like this:
75 <?xml version="1.0" encoding="UTF-8"?>
76 <ArdourMIDIBindings version="1.0.0" name="The name of this set of
78 </ArdourMIDIBindings>
81 So, to start, create a file with that as the initial contents.
84 The file should be located in the midi_maps sub directory located in
85 the <a href="@@files-and-directories-ardour-knows-about">Ardour configuration directory</a>
88 <h3>Finding out what your MIDI control surface sends</h3>
90 This is the most complex part of the job, but its still not very hard.
91 You need to connect the control surface to an application that will show
92 you the information that the device sends each time you modify a knob,
93 slider, button etc. There are a variety of such applications (notably
94 <code>gmidimon</code> and <code>kmidimon</code>, but you can actually use
95 Ardour for this if you want. Start Ardour in a terminal window, connect
96 MIDI ports up, and in the Preferences window, enable "Trace Input" on the
97 relevant MIDI port. A full trace of the MIDI data received will show up in
98 the terminal window. (Note: in Ardour3, you get a dedicated, custom dialog
99 for this kind of tracing.)
101 <h3>Types of Bindings</h3>
103 There are two basic kinds of bindings you can make between a MIDI message
104 and something inside Ardour. The first is a binding to a specific parameter
105 of a track or bus. The second is a binding to something that will change
106 Ardour's state in some way (the "something" could either be called a
107 function or an action, see below).
109 <h4>Binding to Track/Bus controls</h4>
111 A track/bus binding has one of three basic structures
114 <Binding <em>msg specification</em> uri="<em>… control address …</em>"/></br>
115 <Binding <em>msg specification</em> function="<em>… function name …</em>"/></br>
116 <Binding <em>msg specification</em> action="<em>… action name …</em>"/>
119 <h4>Message specifications</h4>
121 You can create a binding for either 3 types of channel messages, or for a
122 system exclusive ("sysex") message. A channel message specification looks
126 <Binding channel="1" ctl="13" …
129 This defines a binding for a MIDI Continuous Controller message involving
130 controller 13, arriving on channel 1. There are 16 MIDI channels, numbered
131 1 to 16. Where the example above says <code>ctl</code>, you can alternatively
132 use <code>note</code> (to create binding for a Note On message) or
133 <code>pgm</code> (to create a binding for a Program Change message).
136 Continous Controlers (CCs) have coninued to evolve for different controlers.
137 The use of Encoders, RPN, NRPN, and controller buttons that give a 0 value
138 when released instead of toggling are now supported. These all have their
139 own type. The whole list of CC types are:
143 <li>ctl - sets a CC to the value sent (works the same as
144 <code>note</code> with the <code>momentary</code> parameter set)</li>
145 <li>ctl-toggle - for CC controls that send a 127 for button press
146 and 0 for button release. The release is ignored and the value is
147 toggled with each press. (works the same as <code>note</code>)</li>
148 <li>ctl-dial - passes the CC value to the controlled object</li>
149 <li>rpn - The CC value may be a 14 bit value</li>
150 <li>nrpn - The CC number and the value may both be 14 bit values</li>
151 <li>rpn-delta - The value is expected to be a signed 14bit value
152 that is added to the current value. For use with encoders</li>
153 <li>nrpn-delta - The value is expected to be a signed 14bit value
154 that is added to the current value. For use with encoders</li>
155 <li>enc-r, enc-l, enc-2 and enc-b - For 7 bit encoders.
156 <a href="@@generic-midi-and-encoders"> Learn more about working
157 with encoders </a></li>
162 Ardour 5.12 has a bug with the encoder detection where the first
163 encoder message resets the control to 0. Setting "Enable Feedback"
164 on allows encoders to work as expected.
167 You can also bind sysex messages:
170 <Binding sysex="f0 0 0 e 9 0 5b f7" ….</br>
171 <Binding sysex="f0 7f 0 6 7 f7" ….
174 The string after the <code>sysex=</code> part is the sequence of MIDI bytes,
175 as hexadecimal values, that make up the sysex message.
178 Finally, you can bind a totally arbitrary MIDI message:</p>
180 <Binding msg="f0 0 0 e 9 0 5b f7" ….</br>
181 <Binding msg="80 60 40" ….
184 The string after the <code>msg=</code> part is the sequence of MIDI bytes, as
185 hexadecimal values, that make up the message you want to bind. Using this is
186 slightly less efficient than the other variants shown above, but is useful for
187 some oddly designed control devices.
191 As of Ardour 4.6 it is possible to use multi-event MIDI strings such as
192 two event CC messages, RPN or NRPN.
196 The <code>sysex=</code> and <code>msg=</code> bindings will only work with
197 <code>function=</code> or <code>action=</code> control addresses. They
198 will <em>not</em> work with the <code>uri=</code> control addresses.
199 Controls used with <code>uri=</code> require a <em>Value</em> which is
200 only available in a known place with channel mode MIDI events.
203 <h4>Control address</h4>
205 A <dfn>control address</dfn> defines what the binding will actually control.
206 There are quite a few different things that can be specified here:
209 Enable Feeback applies to these "Control Addresses" only.
212 <tr><th>/route/gain</th>
213 <td>the gain control ("fader") for the track/bus</td></tr>
214 <tr><th>/route/trim</th>
215 <td>the trim control for the track/bus (new in 4.1)</td></tr>
216 <tr><th>/route/solo</th>
217 <td>a toggleable control for solo (and listen) of the track/bus</td></tr>
218 <tr><th>/route/mute</th>
219 <td>a toggleable control to mute/unmute the track/bus</td></tr>
220 <tr><th>/route/recenable</th>
221 <td>a toggleable control to record-enable the track</td></tr>
222 <tr><th>/route/panwidth</th>
223 <td>interpreted by the track/bus panner, should control image "width"</td></tr>
224 <tr><th>/route/pandirection</th>
225 <td>interpreted by the track/bus panner, should control image "direction"</td></tr>
226 <tr><th>/route/plugin/parameter</th>
227 <td>the Mth parameter of the Nth plugin of a track/bus
229 <tr><th>/route/send/gain</th>
230 <td>the gain control ("fader") of the Nth send of a track/bus</td></tr>
232 <p>Each of the specifications needs an address, which takes various forms too. For track-level controls (solo/gain/mute/recenable), the address is one the following:</p>
234 <tr><th>a number, e.g. "1"
236 <td>identifies a track or bus by its remote control ID
238 <tr><th>B, followed by a number
240 <td>identifies a track or bus by its remote control ID within the current bank (see below for more on banks)
242 <tr><th>S, followed by a number
244 <td>identifies a selected track in order they have been selected, S1 should be the same track as the Editor Mixer
246 <tr><th>one or more words
248 <td>identifies a track or bus by its name
252 For send/insert/plugin controls, the address consists of a track/bus
253 address (as just described) followed by a number identifying the plugin/send
254 (starting from 1). For plugin parameters, there is an additional third
255 component: a number identifying the plugin parameter number (starting from
259 One additional feature: for solo and mute bindings, you can also add
260 <code>momentary="yes"</code> after the control address. This is useful
261 primarily for NoteOn bindings—when Ardour gets the NoteOn it
262 will solo or mute the targetted track or bus, but then when a NoteOff
263 arrives, it will un-solo or un-mute it.
266 <h4>Bindings to Ardour "functions"</h4>
268 There is currently no feedback available for functions.
271 Rather than binding to a specific track/bus/plugin control, it may be useful to
272 have a MIDI controller able to alter some part of Ardour's
273 state. Ardour's Generic MIDI support provides a small number of
274 easily-used "functions" to do the most common operations, using a
275 binding that looks like this:
278 <Binding channel="1" note="13" function="transport-roll"/>
281 In this case, a NoteOn message for note number 13 (on channel 1) will
282 start the transport rolling.
285 Note that a much greater number of operations are possible using
286 actions, described below.
289 The following function names are available:
293 <code>transport-stop</code>
295 <td>stop the transport
298 <code>transport-roll</code>
300 <td>start the transport "rolling"
303 <code>transport-zero</code>
305 <td>move the playhead to the zero position
308 <code>transport-start</code>
310 <td>move the playhead to the start marker
313 <code>transport-end</code>
315 <td>move the playhead to the end marker
318 <code>loop-toggle</code>
320 <td>turn on loop playback
323 <code>rec-enable</code>
325 <td>enable the global record button
328 <code>rec-disable</code>
330 <td>disable the global record button
333 <code>next-bank</code>
335 <td>Move track/bus mapping to the next bank (see Banks below)
338 <code>prev-bank</code>
340 <td>Move track/bus mapping to the previous bank (see Banks below)
344 <h4>Binding to Ardour "actions"</h4>
346 It is not possible to have feedback available for actions because
347 these represent keyboard shortcuts which are input only.
350 You can also bind a sysex or arbitrary message to any of the items
351 that occur in Ardour's main menu (and its submenus). The <a
352 href="@@list-of-menu-actions">
353 list of actions</a> shows all available values of <em>action-name</em>.
355 To create a binding between an arbitrary MIDI message (we'll use a
356 note-off on channel 1 of MIDI note 60 (hex) with release velocity
357 40 (hex)), the binding file would contain:
360 <Binding msg="80 60 40" action="Editor/temporal-zoom-in"/>
363 The general rule, when taken an item from the keybindings file and
364 using it in a MIDI binding is to simply strip the
365 <code><Action></code> prefix of the second field in the
366 keybinding definition.
369 <h3>Banks and Banking</h3>
371 Because many modern control surfaces offer per-track/bus controls
372 for far fewer tracks & busses than many users want to control,
373 Ardour offers the relatively common place concept of <dfn>banks</dfn>. Banks
374 allow you to control any number of tracks and/or busses easily,
375 regardless of how many faders/knobs etc. your control surface has.<br>
376 To use banking, the control addresses must be specified using the
377 <dfn>bank relative</dfn> format mentioned above ("B1" to identify
378 the first track of a bank of tracks, rather than "1" to identify
382 One very important extra piece of information is required to use
383 banking: an extra line near the start of the list of bindings
384 that specifies how many tracks/busses to use per bank. If the
385 device has 8 faders, then 8 would be a sensible value to use for
386 this. The line looks like this:</p>
388 <DeviceInfo bank-size="8"/>
391 In addition, you probably want to ensure that you bind something
392 on the control surface to the <code>next-bank</code> and
393 <code>prev-bank</code> functions, otherwise you and other users
394 will have to use the mouse and the GUI to change banks, which
395 rather defeats the purpose of the bindings.
397 <h3>The Selected Strip</h3>
399 Often times one wants to just deal with the strip currently
400 selected by the GUI (or the control surface). In the same way as with
401 banks above the selected strip can be designated with <em>S1</em>.
403 <h2>A Complete (though muddled) Example</h2>
405 <?xml version="1.0" encoding="UTF-8"?>
406 <ArdourMIDIBindings version="1.0.0" name="pc1600x transport controls">
407 <DeviceInfo bank-size="16"/>
408 <Binding channel="1" ctl="1" uri="/route/gain B1"/>
409 <Binding channel="1" ctl="2" uri="/route/gain B2"/>
410 <Binding channel="1" ctl="3" uri="/route/send/gain B1 1"/>
411 <Binding channel="1" ctl="4" uri="/route/plugin/parameter B1 1 1"/>
412 <Binding channel="1" ctl="6" uri="/bus/gain master"/>
414 <Binding channel="1" note="1" uri="/route/solo B1"/>
415 <Binding channel="1" note="2" uri="/route/solo B2" momentary="yes"/>
417 <Binding channel="1" note="15" uri="/route/mute B1" momentary="yes"/>
418 <Binding channel="1" note="16" uri="/route/mute B2" momentary="yes"/>
420 <Binding channel="1" enc-r="11" uri="/route/pandirection B1"/>
421 <Binding channel="1" enc-r="12" uri="/route/pandirection B2"/>
423 <Binding sysex="f0 0 0 e 9 0 5b f7" function="transport-start"/>
424 <Binding sysex="f0 7f 0 6 7 f7" function="rec-disable"/>
425 <Binding sysex="f0 7f 0 6 6 f7" function="rec-enable"/>
426 <Binding sysex="f0 0 0 e 9 0 53 0 0 f7" function="loop-toggle"/>
428 <Binding channel="1" note="13" function="transport-roll"/>
429 <Binding channel="1" note="14" function="transport-stop"/>
430 <Binding channel="1" note="12" function="transport-start"/>
431 <Binding channel="1" note="11" function="transport-zero"/>
432 <Binding channel="1" note="10" function="transport-end"/>
433 </ArdourMIDIBindings>
436 Please note that channel, controller and note numbers are specified as
437 decimal numbers in the ranges 1-16, 0-127 and 0-127 respectively
438 (the channel range may change at some point).