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 As of this writing we offer presets for the following devices/modes:
16 <ul> <!-- generated by: grep name= /opt/Ardour-6.7.0/share/midi_maps/*.map -->
17 <li>AKAI MPD32 by samtuke</li>
18 <li>Akai MidiMix EQ Mode</li>
19 <li>Akai MidiMix Normal Mode</li>
24 <li>Arturia KeyLab 49</li>
25 <li>Arturia MiniLab mkII</li>
26 <li>Behringer BCF2000 Factory Preset 2</li>
27 <li>Behringer BCF2000 Mackie Control</li>
29 <li>Korg nanoKONTROL</li>
30 <li>Korg nanoKONTROL2</li>
31 <li>Korg nanoKONTROL2 With Master</li>
32 <li>Korg nanoKONTROL w/Master</li>
33 <li>Korg nanoKONTROL Studio</li>
34 <li>Korg Taktile ( mode 9 )</li>
35 <li>M-Audio Oxygen61 V3 by samtuke</li>
36 <li>M-Audio Axiom 25 - Transport Controls</li>
37 <li>M-Audio Axiom 61</li>
38 <li>M-Audio Axiom Air 25 (2015 Model) - Transport Controls</li>
39 <li>M-Audio Axiom AIR Mini 32</li>
40 <li>M-Audio Oxygen25 (factory default)</li>
41 <li>M-Audio Oxygen25 (3rd Gen)</li>
42 <li>M-Audio Oxygen 49</li>
43 <li>M-Audio Oxygen 61 v3</li>
44 <li>M-Audio Oxygen8 V2</li>
45 <li>WiiMote via midikb</li>
46 <li>Nektar Panorama</li>
47 <li>Novation Impulse 49</li>
48 <li>Novation Impulse 61</li>
49 <li>Novation Launch Control XL</li>
50 <li>Novation Launchkey 25</li>
51 <li>Novation LaunchKey 49</li>
53 <li>Roland V-Studio 20</li>
55 <li>Yamaha KX25 Transport Controls</li>
57 At this time, new binding maps need to be created with a text editor.
59 MIDI binding maps are accessible by double-clicking <kbd class="menu">Edit
60 > Preferences > Control Surfaces > Generic MIDI</kbd>. Ardour will
61 retain your selection after you choose one.
64 <h2>Creating new MIDI maps</h2>
65 <h3>The Basic Concept</h3>
67 Since the beginning of time (well, sometime early in the 2.X series),
68 Ardour has had the concept of identifying each track and bus with a
69 <dfn>remote control ID</dfn>. This ID uniquely identifies a track or bus
70 so that when messages arrive from elsewhere via MIDI or OSC , we can determine
71 which track or bus they are intended to control. See
72 <a href="@@controlling-track-ordering">
73 remote control IDs</a> for more information.
74 You just need to know that there is a "first track" and its remote control
77 <h3>Getting Started</h3>
79 MIDI bindings are stored in files with the suffix ".map" attached to their
80 name. The minimal content looks like this:
83 <?xml version="1.0" encoding="UTF-8"?>
84 <ArdourMIDIBindings version="1.0.0" name="The name of this set of
86 </ArdourMIDIBindings>
89 So, to start, create a file with that as the initial contents.
92 The file should be located in the midi_maps sub directory located in
93 the <a href="@@files-and-directories-ardour-knows-about">Ardour configuration directory</a>
96 <h3>Finding out what your MIDI control surface sends</h3>
98 This is the most complex part of the job, but its still not very hard.
99 You need to connect the control surface to an application that will show
100 you the information that the device sends each time you modify a knob,
101 slider, button etc. There are a variety of such applications (notably
102 <code>gmidimon</code> and <code>kmidimon</code>, but you can actually use
103 Ardour for this if you want. Start Ardour in a terminal window, connect
104 MIDI ports up, and in the Preferences window, enable "Trace Input" on the
105 relevant MIDI port. A full trace of the MIDI data received will show up in
106 the terminal window. (Note: in Ardour3, you get a dedicated, custom dialog
107 for this kind of tracing.)
109 <h3>Types of Bindings</h3>
111 There are two basic kinds of bindings you can make between a MIDI message
112 and something inside Ardour. The first is a binding to a specific parameter
113 of a track or bus. The second is a binding to something that will change
114 Ardour's state in some way (the "something" could either be called a
115 function or an action, see below).
117 <h4>Binding to Track/Bus controls</h4>
119 A track/bus binding has one of three basic structures
122 <Binding <em>msg specification</em> uri="<em>… control address …</em>"/></br>
123 <Binding <em>msg specification</em> function="<em>… function name …</em>"/></br>
124 <Binding <em>msg specification</em> action="<em>… action name …</em>"/>
127 <h4>Message specifications</h4>
129 You can create a binding for either 3 types of channel messages, or for a
130 system exclusive ("sysex") message. A channel message specification looks
134 <Binding channel="1" ctl="13" …
137 This defines a binding for a MIDI Continuous Controller message involving
138 controller 13, arriving on channel 1. There are 16 MIDI channels, numbered
139 1 to 16. Where the example above says <code>ctl</code>, you can alternatively
140 use <code>note</code> (to create binding for a Note On message) or
141 <code>pgm</code> (to create a binding for a Program Change message).
144 Continous Controlers (CCs) have coninued to evolve for different controlers.
145 The use of Encoders, RPN, NRPN, and controller buttons that give a 0 value
146 when released instead of toggling are now supported. These all have their
147 own type. The whole list of CC types are:
151 <li>ctl - sets a CC to the value sent (works the same as
152 <code>note</code> with the <code>momentary</code> parameter set)</li>
153 <li>ctl-toggle - for CC controls that send a 127 for button press
154 and 0 for button release. The release is ignored and the value is
155 toggled with each press. (works the same as <code>note</code>)</li>
156 <li>ctl-dial - passes the CC value to the controlled object</li>
157 <li>rpn - The CC value may be a 14 bit value</li>
158 <li>nrpn - The CC number and the value may both be 14 bit values</li>
159 <li>rpn-delta - The value is expected to be a signed 14bit value
160 that is added to the current value. For use with encoders</li>
161 <li>nrpn-delta - The value is expected to be a signed 14bit value
162 that is added to the current value. For use with encoders</li>
163 <li>enc-r, enc-l, enc-2 and enc-b - For 7 bit encoders.
164 <a href="@@generic-midi-and-encoders"> Learn more about working
165 with encoders </a></li>
170 Ardour 5.12 has a bug with the encoder detection where the first
171 encoder message resets the control to 0. Setting "Enable Feedback"
172 on allows encoders to work as expected.
175 You can also bind sysex messages:
178 <Binding sysex="f0 0 0 e 9 0 5b f7" ….</br>
179 <Binding sysex="f0 7f 0 6 7 f7" ….
182 The string after the <code>sysex=</code> part is the sequence of MIDI bytes,
183 as hexadecimal values, that make up the sysex message.
186 Finally, you can bind a totally arbitrary MIDI message:</p>
188 <Binding msg="f0 0 0 e 9 0 5b f7" ….</br>
189 <Binding msg="80 60 40" ….
192 The string after the <code>msg=</code> part is the sequence of MIDI bytes, as
193 hexadecimal values, that make up the message you want to bind. Using this is
194 slightly less efficient than the other variants shown above, but is useful for
195 some oddly designed control devices.
199 As of Ardour 4.6 it is possible to use multi-event MIDI strings such as
200 two event CC messages, RPN or NRPN.
204 The <code>sysex=</code> and <code>msg=</code> bindings will only work with
205 <code>function=</code> or <code>action=</code> control addresses. They
206 will <em>not</em> work with the <code>uri=</code> control addresses.
207 Controls used with <code>uri=</code> require a <em>Value</em> which is
208 only available in a known place with channel mode MIDI events.
211 <h4>Control address</h4>
213 A <dfn>control address</dfn> defines what the binding will actually control.
214 There are quite a few different things that can be specified here:
217 Enable Feeback applies to these "Control Addresses" only.
220 <tr><th>/route/gain</th>
221 <td>the gain control ("fader") for the track/bus</td></tr>
222 <tr><th>/route/trim</th>
223 <td>the trim control for the track/bus (new in 4.1)</td></tr>
224 <tr><th>/route/solo</th>
225 <td>a toggleable control for solo (and listen) of the track/bus</td></tr>
226 <tr><th>/route/mute</th>
227 <td>a toggleable control to mute/unmute the track/bus</td></tr>
228 <tr><th>/route/recenable</th>
229 <td>a toggleable control to record-enable the track</td></tr>
230 <tr><th>/route/panwidth</th>
231 <td>interpreted by the track/bus panner, should control image "width"</td></tr>
232 <tr><th>/route/pandirection</th>
233 <td>interpreted by the track/bus panner, should control image "direction"</td></tr>
234 <tr><th>/route/plugin/parameter</th>
235 <td>the Mth parameter of the Nth plugin of a track/bus
237 <tr><th>/route/send/gain</th>
238 <td>the gain control ("fader") of the Nth send of a track/bus</td></tr>
240 <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>
242 <tr><th>a number, e.g. "1"
244 <td>identifies a track or bus by its remote control ID
246 <tr><th>B, followed by a number
248 <td>identifies a track or bus by its remote control ID within the current bank (see below for more on banks)
250 <tr><th>S, followed by a number
252 <td>identifies a selected track in order they have been selected, S1 should be the same track as the Editor Mixer
254 <tr><th>one or more words
256 <td>identifies a track or bus by its name
260 For send/insert/plugin controls, the address consists of a track/bus
261 address (as just described) followed by a number identifying the plugin/send
262 (starting from 1). For plugin parameters, there is an additional third
263 component: a number identifying the plugin parameter number (starting from
267 One additional feature: for solo and mute bindings, you can also add
268 <code>momentary="yes"</code> after the control address. This is useful
269 primarily for NoteOn bindings—when Ardour gets the NoteOn it
270 will solo or mute the targetted track or bus, but then when a NoteOff
271 arrives, it will un-solo or un-mute it.
274 <h4>Bindings to Ardour "functions"</h4>
276 There is currently no feedback available for functions.
279 Rather than binding to a specific track/bus/plugin control, it may be useful to
280 have a MIDI controller able to alter some part of Ardour's
281 state. Ardour's Generic MIDI support provides a small number of
282 easily-used "functions" to do the most common operations, using a
283 binding that looks like this:
286 <Binding channel="1" note="13" function="transport-roll"/>
289 In this case, a NoteOn message for note number 13 (on channel 1) will
290 start the transport rolling.
293 Note that a much greater number of operations are possible using
294 actions, described below.
297 The following function names are available:
301 <code>transport-stop</code>
303 <td>stop the transport
306 <code>transport-roll</code>
308 <td>start the transport "rolling"
311 <code>transport-zero</code>
313 <td>move the playhead to the zero position
316 <code>transport-start</code>
318 <td>move the playhead to the start marker
321 <code>transport-end</code>
323 <td>move the playhead to the end marker
326 <code>loop-toggle</code>
328 <td>turn on loop playback
331 <code>rec-enable</code>
333 <td>enable the global record button
336 <code>rec-disable</code>
338 <td>disable the global record button
341 <code>next-bank</code>
343 <td>Move track/bus mapping to the next bank (see Banks below)
346 <code>prev-bank</code>
348 <td>Move track/bus mapping to the previous bank (see Banks below)
352 <h4>Binding to Ardour "actions"</h4>
354 It is not possible to have feedback available for actions because
355 these represent keyboard shortcuts which are input only.
358 You can also bind a sysex or arbitrary message to any of the items
359 that occur in Ardour's main menu (and its submenus). The <a
360 href="@@list-of-menu-actions">
361 list of actions</a> shows all available values of <em>action-name</em>.
363 To create a binding between an arbitrary MIDI message (we'll use a
364 note-off on channel 1 of MIDI note 60 (hex) with release velocity
365 40 (hex)), the binding file would contain:
368 <Binding msg="80 60 40" action="Editor/temporal-zoom-in"/>
371 The general rule, when taken an item from the keybindings file and
372 using it in a MIDI binding is to simply strip the
373 <code><Action></code> prefix of the second field in the
374 keybinding definition.
377 <h3>Banks and Banking</h3>
379 Because many modern control surfaces offer per-track/bus controls
380 for far fewer tracks & busses than many users want to control,
381 Ardour offers the relatively common place concept of <dfn>banks</dfn>. Banks
382 allow you to control any number of tracks and/or busses easily,
383 regardless of how many faders/knobs etc. your control surface has.<br>
384 To use banking, the control addresses must be specified using the
385 <dfn>bank relative</dfn> format mentioned above ("B1" to identify
386 the first track of a bank of tracks, rather than "1" to identify
390 One very important extra piece of information is required to use
391 banking: an extra line near the start of the list of bindings
392 that specifies how many tracks/busses to use per bank. If the
393 device has 8 faders, then 8 would be a sensible value to use for
394 this. The line looks like this:</p>
396 <DeviceInfo bank-size="8"/>
399 In addition, you probably want to ensure that you bind something
400 on the control surface to the <code>next-bank</code> and
401 <code>prev-bank</code> functions, otherwise you and other users
402 will have to use the mouse and the GUI to change banks, which
403 rather defeats the purpose of the bindings.
405 <h3>The Selected Strip</h3>
407 Often times one wants to just deal with the strip currently
408 selected by the GUI (or the control surface). In the same way as with
409 banks above the selected strip can be designated with <em>S1</em>.
411 <h2>A Complete (though muddled) Example</h2>
413 <?xml version="1.0" encoding="UTF-8"?>
414 <ArdourMIDIBindings version="1.0.0" name="pc1600x transport controls">
415 <DeviceInfo bank-size="16"/>
416 <Binding channel="1" ctl="1" uri="/route/gain B1"/>
417 <Binding channel="1" ctl="2" uri="/route/gain B2"/>
418 <Binding channel="1" ctl="3" uri="/route/send/gain B1 1"/>
419 <Binding channel="1" ctl="4" uri="/route/plugin/parameter B1 1 1"/>
420 <Binding channel="1" ctl="6" uri="/bus/gain master"/>
422 <Binding channel="1" note="1" uri="/route/solo B1"/>
423 <Binding channel="1" note="2" uri="/route/solo B2" momentary="yes"/>
425 <Binding channel="1" note="15" uri="/route/mute B1" momentary="yes"/>
426 <Binding channel="1" note="16" uri="/route/mute B2" momentary="yes"/>
428 <Binding channel="1" enc-r="11" uri="/route/pandirection B1"/>
429 <Binding channel="1" enc-r="12" uri="/route/pandirection B2"/>
431 <Binding sysex="f0 0 0 e 9 0 5b f7" function="transport-start"/>
432 <Binding sysex="f0 7f 0 6 7 f7" function="rec-disable"/>
433 <Binding sysex="f0 7f 0 6 6 f7" function="rec-enable"/>
434 <Binding sysex="f0 0 0 e 9 0 53 0 0 f7" function="loop-toggle"/>
436 <Binding channel="1" note="13" function="transport-roll"/>
437 <Binding channel="1" note="14" function="transport-stop"/>
438 <Binding channel="1" note="12" function="transport-start"/>
439 <Binding channel="1" note="11" function="transport-zero"/>
440 <Binding channel="1" note="10" function="transport-end"/>
441 </ArdourMIDIBindings>
444 Please note that channel, controller and note numbers are specified as
445 decimal numbers in the ranges 1-16, 0-127 and 0-127 respectively
446 (the channel range may change at some point).