3 title: MIDI Binding Maps
8 <a href="/using-control-surfaces/midi-learn"><dfn>MIDI learning</dfn></a>
9 for more or less any control. This was a nice feature that quite a few other
10 DAWs are providing by now, but it didn't allow Ardour to work "out of the
11 box" with sensible defaults for existing commercial MIDI
12 controllers. In Ardour 3 and later versions, we have augmented the
13 MIDI learn feature with the ability to load a <dfn>MIDI binding map</dfn>
14 for a given controller, which can set up an arbitrary number of physical
15 controls with anything inside Ardour that can be controlled.
18 At this time, these binding maps need to be created with a text editor.
19 Currently, we have presets for:
22 <li>Behringer BCF 2000</li>
23 <li>Korg_nanoKONTROL</li>
24 <li>M-Audio Oxygen 8 v2</li>
26 <li>Behringer DDX3216</li>
27 <li>M-Audio Axiom 25</li>
30 MIDI binding maps are accessible by double-clicking <kbd class="menu">Edit
31 > Preferences > Control Surfaces > Generic MIDI</kbd>. Ardour will
32 retain your selection after you choose one.
35 <h2>Creating new MIDI maps</h2>
36 <h3>The Basic Concept</h3>
38 Since the beginning of time (well, sometime early in the 2.X series),
39 Ardour has had the concept of identifying each track and bus with a
40 <dfn>remote control ID</dfn>. This ID uniquely identifies a track or bus
41 so that when messages arrive from elsewhere via MIDI or OSC , we can determine
42 which track or bus they are intended to control. Ardour has a
44 href="/working-with-tracks/controlling-track-ordering/track-ordering-and-remote-control-ids/">number
45 of ways of assigning remote control IDs</a>, but they don't really matter
46 very much when creating MIDI binding maps, so we won't discuss that here.
47 You just need to know that there is a "first track" and its remote control
50 <h3>Getting Started</h3>
52 MIDI bindings are stored in files with the suffix ".map" attached to their
53 name. The minimal content looks like this:
56 <?xml version="1.0" encoding="UTF-8"?>
57 <ArdourMIDIBindings version="1.0.0" name="The name of this set of
59 </ArdourMIDIBindings>
62 So, to start, create a file with that as the initial contents.
65 On OS X, Ardour loads midi maps from its binary-bundle folder in
66 <code>Ardour-<version>/midi_maps/</code> and checks
67 various other locations as well (defined by the ARDOUR_MIDIMAPS_PATH
68 environment variable). On GNU/Linux the easiest is to save the file to
69 <code>~/.config/ardour3/midi_maps/</code>.
72 <h3>Finding out what your MIDI control surface sends</h3>
74 This is the most complex part of the job, but its still not very hard.
75 You need to connect the control surface to an application that will show
76 you the information that the device sends each time you modify a knob,
77 slider, button etc. There are a variety of such applications (notably
78 <code>gmidimon</code> and <code>kmidimon</code>, but you can actually use
79 Ardour for this if you want. Start Ardour in a terminal window, connect
80 MIDI ports up, and in the Preferences window, enable "Trace Input" on the
81 relevant MIDI port. A full trace of the MIDI data received will show up in
82 the terminal window. (Note: in Ardour3, you get a dedicated, custom dialog
83 for this kind of tracing.)
85 <h3>Types of Bindings</h3>
87 There are two basic kinds of bindings you can make between a MIDI message
88 and something inside Ardour. The first is a binding to a specific parameter
89 of a track or bus. The second is a binding to a function that will change
90 Ardour's state in some way.
92 <h4>Binding to Track/Bus controls</h4>
94 A track/bus binding has one of two basic structures
97 <Binding <em>msg specification</em> uri="<em>... control address ...</em>"/>
98 <Binding <em>msg specification</em> function="<em>... function name ...</em>"/>
101 <h4>Message specifications</h4>
103 You can create a binding for either 3 types of channel messages, or for a
104 system exclusive ("sysex") message. A channel message specification looks
108 <Binding channel="1" ctl="13" ....
111 This defines a binding for a MIDI Continuous Controller message involving
112 controller 13, arriving on channel 1. There are 16 MIDI channels, numbered
113 1 to 16. Where the example above says <code>ctl</code>, you can alternatively
114 use <code>note</code> (to create binding for a Note On message) or
115 <code>pgm</code> (to create a binding for a Program Change message).
118 You can also bind sysex messages:
121 <Binding sysex="f0 0 0 e 9 0 5b f7" ....
122 <Binding sysex="f0 7f 0 6 7 f7" ....
125 The string after the <code>sysex=</code> part is the sequence of MIDI bytes,
126 as hexadecimal values, that make up the sysex message.
129 Finally, you can bind a totally arbitrary MIDI message:</p>
131 <Binding msg="f0 0 0 e 9 0 5b f7" ....
132 <Binding msg="80 60 40" ....
135 The string after the <code>msg=</code> part is the sequence of MIDI bytes, as
136 hexadecimal values, that make up the message you want to bind. Using this is
137 slightly less efficient than the other variants shown above, but is useful for
138 some oddly designed control devices.
142 It is not possible at this time to use multi-event MIDI strings such as
143 two event CC messages, RPN or NRPN.
147 The <code>sysex=</code> and <code>msg=</code> bindings will only work with
148 <code>function=</code> or <code>action=</code> control addresses. They
149 will <em>not</em> work with the <code>uri=</code> control addresses.
152 <h4>Control address</h4>
154 A <dfn>control address</dfn> defines what the binding will actually control.
155 There are quite a few different things that can be specified here:
157 <dl class="wide-table">
159 <dd>the gain control ("fader") for the track/bus</dd>
161 <dd>the trim control for the track/bus (new in 4.1)</dd>
163 <dd>a toggleable control for solo (and listen) of the track/bus</dd>
165 <dd>a toggleable control to mute/unmute the track/bus</dd>
166 <dt>/route/recenable</dt>
167 <dd>a toggleable control to record-enable the track</dd>
168 <dt>/route/panwidth</dt>
169 <dd>interpreted by the track/bus panner, should control image "width"</dd>
170 <dt>/route/pandirection</dt>
171 <dd>interpreted by the track/bus panner, should control image "direction"</dd>
172 <dt>/route/plugin/parameter</dt>
173 <dd>the Mth parameter of the Nth plugin of a track/bus
175 <dt>/route/send/gain</dt>
176 <dd>the gain control ("fader") of the Nth send of a track/bus</dd>
178 <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>
179 <dl class="wide-table">
180 <dt>a number, eg. "1"
182 <dd>identifies a track or bus by its remote control ID
184 <dt>B, followed by a number
186 <dd>identifies a track or bus by its remote control ID within the current bank (see below for more on banks)
188 <dt>one or more words
190 <dd>identifies a track or bus by its name
194 For send/insert/plugin controls, the address consists of a track/bus
195 address (as just described) followed by a number identifying the plugin/send
196 (starting from 1). For plugin parameters, there is an additional third
197 component: a number identifying the plugin parameter number (starting from
201 One additional feature: for solo and mute bindings, you can also add
202 <code>momentary="yes"</code> after the control address. This is useful
203 primarily for NoteOn bindings — when Ardour gets the NoteOn it
204 will solo or mute the targetted track or bus, but then when a NoteOff
205 arrives, it will un-solo or un-mute it.
208 <h4>Bindings to Ardour "functions"</h4>
210 Rather than binding to a specific track/bus control, it may be useful to
211 have a MIDI controller able to alter some part of Ardour's state. A
212 binding definition that does this looks like this:
215 <Binding channel="1" note="13" function="transport-roll"/>
218 In this case, a NoteOn message for note number 13 (on channel 1) will
219 start the transport rolling. The following function names are available:
221 <dl class="narrower-table">
223 <code>transport-stop</code>
225 <dd>stop the transport
228 <code>transport-roll</code>
230 <dd>start the transport "rolling"
233 <code>transport-zero</code>
235 <dd>move the playhead to the zero position
238 <code>transport-start</code>
240 <dd>move the playhead to the start marker
243 <code>transport-end</code>
245 <dd>move the playhead to the end marker
248 <code>loop-toggle</code>
250 <dd>turn on loop playback
253 <code>rec-enable</code>
255 <dd>enable the global record button
258 <code>rec-disable</code>
260 <dd>disable the global record button
263 <code>next-bank</code>
265 <dd>Move track/bus mapping to the next bank (see Banks below)
268 <code>prev-bank</code>
270 <dd>Move track/bus mapping to the previous bank (see Banks below)
274 <h4>Binding to Ardour "actions"</h4>
276 You can also bind a sysex or arbitrary message to any of the items
277 that occur in Ardour's main menu (and its submenus). The best place
278 to look for the (long) list of how to address each item is in your
279 keybindings file, which will contain lines that look like this:
282 (gtk_accel_path "<Actions>/Editor/temporal-zoom-in" "equal")
285 To create a binding between an arbitrary MIDI message (we'll use a
286 note-off on channel 1 of MIDI note 60 (hex) with release velocity
287 40 (hex)), the binding file would contain:
290 <Binding msg="80 60 40" action="Editor/temporal-zoom-in"/>
293 The general rule, when taken an item from the keybindings file and
294 using it in a MIDI binding is to simply strip the
295 <code><Action></code> prefix of the second field in the
296 keybinding definition.
299 <h3>Banks and Banking</h3>
301 Because many modern control surfaces offer per-track/bus controls
302 for far fewer tracks & busses than many users want to control,
303 Ardour offers the relatively common place concept of <dfn>banks</dfn>. Banks
304 allow you to control any number of tracks and/or busses easily,
305 regardless of how many faders/knobs etc. your control surface has.<br />
306 To use banking, the control addresses must be specified using the
307 <dfn>bank relative</dfn> format mentioned above ("B1" to identify
308 the first track of a bank of tracks, rather than "1" to identify
312 One very important extra piece of information is required to use
313 banking: an extra line near the start of the list of bindings
314 that specifies how many tracks/busses to use per bank. If the
315 device has 8 faders, then 8 would be a sensible value to use for
316 this. The line looks like this:</p>
318 <DeviceInfo bank-size="8"/>
321 In addition, you probably want to ensure that you bind something
322 on the control surface to the <code>next-bank</code> and
323 <code>prev-bank</code> functions, otherwise you and other users
324 will have to use the mouse and the GUI to change banks, which
325 rather defeats the purpose of the bindings.
327 <h2>A Complete (though muddled) Example</h2>
329 <?xml version="1.0" encoding="UTF-8"?>
330 <ArdourMIDIBindings version="1.0.0" name="pc1600x transport controls">
331 <DeviceInfo bank-size="16"/>
332 <Binding channel="1" ctl="1" uri="/route/gain B1"/>
333 <Binding channel="1" ctl="2" uri="/route/gain B2"/>
334 <Binding channel="1" ctl="3" uri="/route/send/gain B1 1"/>
335 <Binding channel="1" ctl="4" uri="/route/plugin/parameter B1 1 1"/>
336 <Binding channel="1" ctl="6" uri="/bus/gain master"/>
338 <Binding channel="1" note="1" uri="/route/solo B1"/>
339 <Binding channel="1" note="2" uri="/route/solo B2" momentary="yes"/>
341 <Binding channel="1" note="15" uri="/route/mute B1" momentary="yes"/>
342 <Binding channel="1" note="16" uri="/route/mute B2" momentary="yes"/>
344 <Binding sysex="f0 0 0 e 9 0 5b f7" function="transport-start"/>
345 <Binding sysex="f0 7f 0 6 7 f7" function="rec-disable"/>
346 <Binding sysex="f0 7f 0 6 6 f7" function="rec-enable"/>
347 <Binding sysex="f0 0 0 e 9 0 53 0 0 f7" function="loop-toggle"/>
349 <Binding channel="1" note="13" function="transport-roll"/>
350 <Binding channel="1" note="14" function="transport-stop"/>
351 <Binding channel="1" note="12" function="transport-start"/>
352 <Binding channel="1" note="11" function="transport-zero"/>
353 <Binding channel="1" note="10" function="transport-end"/>
354 </ArdourMIDIBindings>
357 Please note that channel, controller and note numbers are specified as
358 decimal numbers in the ranges 1-16, 0-127 and 0-127 respectively
359 (the channel range may change at some point).