MIDI Binding Maps for Ardour 3.0 and later versions

Ardour 2.X supported MIDI learning for more or less any control. This was a nice feature that quite a few other DAWs have now provided, but it didn't allow Ardour to work "out of the box" with sensible defaults for existing commercial MIDI controllers. In Ardour 3 and later versions, we have augmented the MIDI learn feature with the ability to load a MIDI binding map for a given controller, which can set up an arbitrary number of physical controls with anything inside Ardour that can be controlled. At this time, these binding maps need to be created with a text editor, but we currently have presets for

  • Behringer BCF 2000
  • Korg_nanoKONTROL
  • M-Audio Oxygen 8 v2
  • Roland SI-24
  • Behringer DDX3216
  • M-Audio Axiom 25

MIDI binding maps are accessible by double clicking on the "Generic MIDI" line in the Control Surfaces tab of the Ardour preferences dialog. Ardour will retain your chosen map after you choose one.

The information below describes in great detail how to create a new MIDI binding map.

The Basic Concept

Since the beginning of time (well, sometime early in the 2.X series), Ardour has had the concept of identifying each track and bus with a remote control ID. This ID uniquely identifies a track or bus so that when messages arrive from elsewhere (MIDI or OSC), we can determine which track or bus they are intended to control. Ardour has a number of ways of assigning remote control IDs, but they don't really matter very much when creating MIDI binding maps, so we won't discuss that here. You just need to know that there is a "first track" and its remote control ID is 1, and so on.

Getting Started

MIDI bindings are stored in files with the suffix ".map" attached to their name. The minimal content looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<ArdourMIDIBindings version="1.0.0" name="The name of this set of bindings">
</ArdourMIDIBindings>
So, to start, create a file with that as the initial contents.

Finding out what your MIDI control surface sends

This is the most complex part of the job, but its still not very hard. You need to connect the control surface to an application that will show you the information that the device sends each time you modify a knob, slider, button etc. There are a variety of such applications (notably gmidimon and kmidimon, but you can actually use Ardour for this if you want. Start Ardour in a terminal window, connect MIDI ports up, and in the Preferences window, enable "Trace Input" on the relevant MIDI port. A full trace of the MIDI data received will show up in the terminal window. (Note: in Ardour3, you get a dedicated, custom dialog for this kind of tracing)

Types of Bindings

There are two basic kinds of bindings you can make between a MIDI message and something inside Ardour. The first is a binding to a specific parameter of a track or bus. The second is a binding to a function that will change Ardour's state in some way.

Binding to Track/Bus controls

A track/bus binding has one of two basic structures

  <Binding msg specification  uri="... control address ..."/>
  <Binding msg specification  function="... function name ..."/>

Message specifications

You can create a binding for either 3 types of channel messages, or for a system exclusive ("sysex") message. A channel message specification looks like this:

   <Binding channel="1" ctl="13" ....
This defines a binding for a MIDI Continuous Controller message involving controller 13, arriving on channel 1. There are 16 MIDI channels, numbered 1 to 16. Where the example above says ctl, you can alternatively use note (to create binding for a Note On message) or pgm (to create a binding for a Program Change message).

You can also bind sysex messages:

  <Binding sysex="f0 0 0 e 9 0 5b f7" ....
  <Binding sysex="f0 7f 0 6 7 f7" ....
The string after the sysex= part is the sequence of MIDI bytes, as hexadecimal values, that make up the sysex message.

Finally, you can bind a totally arbitrary MIDI message:

  <Binding msg="f0 0 0 e 9 0 5b f7" ....
  <Binding msg="80 60 40" ....
The string after the msg= part is the sequence of MIDI bytes, as hexadecimal values, that make up the message you want to bind. Using this is slightly less efficient than the other variants shown above, but is useful for some oddly designed control devices.

Control address

A control address defines what the binding will actually control. There are quite a few different things that can be specified here:

/route/gain
/route/solo
/route/mute
/route/recenable
/route/send/gain
/route/plugin/parameter
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:
a number, eg. "1"
identifies a track or bus by its remote control ID
B, followed by a number
identifies a track or bus by its remote control ID within the current bank (see below for more on banks)
one or more words
identifies a track or bus by its name
For send/insert/plugin controls, the address consists of a track/bus address (as just described) followed by a number identifying the plugin/send (starting from 1). For plugin parameters, there is an additional third component: a number identifying the plugin parameter number (starting from 1).

One additional feature: for solo and mute bindings, you can also add momentary="yes" after the control address. This is useful primarily for NoteOn bindings - when Ardour gets the NoteOn it will solo or mute the targetted track or bus, but then when a NoteOff arrives, it will un-solo or un-mute it.

Bindings to Ardour "functions"

Rather than binding to a specific track/bus control, it may be useful to have a MIDI controller able to alter some part of Ardour's state. A binding definition that does this looks like this:

  <Binding channel="1" note="13" function="transport-roll"/>
In this case, a NoteOn message for note number 13 (on channel 1) will start the transport rolling. The following function names are available:

transport-stop
stop the transport
transport-roll
start the transport "rolling"
transport-zero
move the playhead to the zero position
transport-start
move the playhead to the start marker
transport-end
move the playhead to the end marker
loop-toggle
turn on loop playback
rec-enable
enable the global record button
rec-disable
disable the global record button
next-bank
Move track/bus mapping to the next bank (see Banks below)
prev-bank
Move track/bus mapping to the previous bank (see Banks below)

Binding to Ardour "actions"

You can also bind a sysex or arbitrary message to any of the items that occur in Ardour's main menu (and its submenus). The best place to look for the (long) list of how to address each item is in your keybindings file, which will contain lines that look like this:

(gtk_accel_path "<Actions>/Editor/temporal-zoom-in" "equal")
To create a binding between an arbitrary MIDI message (we'll use a note-off on channel 1 of MIDI note 60 (hex) with release velocity 40 (hex)), the binding file would contain:
   <Binding msg="80 60 40" action="Editor/temporal-zoom-in"/>
The general rule, when taken an item from the keybindings file and using it in a MIDI binding is to simply strip the <Action> prefix of the second field in the keybinding definition.

Banks and Banking

Because many modern control surfaces offer per-track/bus controls for far fewer tracks & busses than many users want to control, Ardour offers the relatively common place concept of "banks". Banks to allow you to relatively easily control any number of tracks and/or busses regardless of how many faders/knobs etc. your control surface has. To use banking, the control addresses must be specified using the bank relative format mentioned above ("B1" to identify the first track of a bank of tracks, rather than "1" to identify the first track).

One very important extra piece of information is required to use banking: an extra line near the start of the list of bindings that specifies how many tracks/busses to use per bank. If the device has 8 faders, then 8 would be a sensible value to use for this. The line looks like this:

   <DeviceInfo bank-size="8"/>
In addition, you probably want to ensure that you bind something on the control surface to the next-bank and prev-bank functions, otherwise you and other users will have to use the mouse and the GUI to change banks, which rather defeats the purpose of the bindings.

A Complete (though muddled) Example

<?xml version="1.0" encoding="UTF-8"?>
<ArdourMIDIBindings version="1.0.0" name="pc1600x transport controls">
  <DeviceInfo bank-size="16"/>
  <Binding channel="1" ctl="1"   uri="/route/gain B1"/>
  <Binding channel="1" ctl="2"   uri="/route/gain B2"/>
  <Binding channel="1" ctl="3"   uri="/route/send/gain B1 1"/>
  <Binding channel="1" ctl="4"   uri="/route/plugin/parameter B1 1 1"/>
  <Binding channel="1" ctl="6"   uri="/bus/gain master"/>

  <Binding channel="1" note="1"  uri="/route/solo B1"/>
  <Binding channel="1" note="2"  uri="/route/solo B2" momentary="yes"/>

  <Binding channel="1" note="15"  uri="/route/mute B1" momentary="yes"/>
  <Binding channel="1" note="16"  uri="/route/mute B2" momentary="yes"/>

  <Binding sysex="f0 0 0 e 9 0 5b f7" function="transport-start"/>
  <Binding sysex="f0 7f 0 6 7 f7" function="rec-disable"/>
  <Binding sysex="f0 7f 0 6 6 f7" function="rec-enable"/>
  <Binding sysex="f0 0 0 e 9 0 53 0 0 f7" function="loop-toggle"/>

  <Binding channel="1" note="13" function="transport-roll"/>
  <Binding channel="1" note="14" function="transport-stop"/>
  <Binding channel="1" note="12" function="transport-start"/>
  <Binding channel="1" note="11" function="transport-zero"/>
  <Binding channel="1" note="10" function="transport-end"/>
</ArdourMIDIBindings>

Please note that channel, controller and note numbers are specified as decimal numbers in the ranges 1-16, 0-127 and 0-127 respectively (the channel range may change at some point)

@delete it would be good to

@delete
it would be good to bind that to the shuttle speed control

Hi, I own a M-Audio Keystudio

Hi,

I own a M-Audio Keystudio 49, and I would like to help out.

However, I'm having trouble understanding what I should do. I've started up kmidimon, and it seems to be displaying the midi commands. However, I don't really understand what the different types of bindings are. On top of that it seems you need the raw hex of the midi commands, but it seems kmidimon interprets them.

They keyboard itself is really simple: the only controls it has are two wheels, a slider, and two buttons. However, the entire thing is programmable, meaning you can choose the channel it goes out on, and choose the functions of the wheels, sliders, and buttons. I'm not sure but it seems like this might be a problem.

If you want to look at the possible outputs, you can see the user guide here: http://www.m-audio.com/images/global/manuals/070921_KyStuMac_UG_EN01.pdf

If someone could explain how to convert the readings from kmidimon into a mapping, that would be really useful, because right now I'm not sure I understand how ardour handles the midi. To me it seems strange that you would specify the track in a mapping, because that would mean you couldn't change the keyboard to record to different tracks.

Thanks,
Jeremy

@jeremybub: why don't you

@jeremybub: why don't you post a little bit of what kmidimon displays? It sounds as if your keystudio is sending standard commands (such as MMC "Start" or "Stop") which don't need to be bound if you want them just do the "normal" thing.

Alright, here is a very

Alright, here is a very simple log.
I changed the volume, bent the pitch a little bit, moved the modulation wheel a little bit, and pressed and released a note.

0,0.0219,0:0,,ALSA Port subscribed,0:1,128:0
2663,5.5497,0:0,,ALSA Port subscribed,20:0,128:0
7699,16.0432,20:0,1,Control change,7,1
7835,16.3271,20:0,1,Control change,7,2
12192,25.4001,20:0,1,Pitch bend,128,
12203,25.4294,20:0,1,Pitch bend,384,
12216,25.4561,20:0,1,Pitch bend,512,
12226,25.4839,20:0,1,Pitch bend,640,
12245,25.5178,20:0,1,Pitch bend,768,
12282,25.5891,20:0,1,Pitch bend,896,
12339,25.7101,20:0,1,Pitch bend,0,
15127,31.5198,20:0,1,Control change,1,1
15150,31.5801,20:0,1,Control change,1,2
15175,31.6268,20:0,1,Control change,1,3
19447,40.5199,20:0,1,Note on,36,80
19488,40.6028,20:0,1,Note on,36,0

Hey! I recently purchased a

Hey!

I recently purchased a Korg nanoPad and I want to use this sometimes as a transport control. Do you think this is of any use for someone else and I should post the midi binding here? Any other idea of how to use it with Ardour?
I'm iwlling to help :)

Best,
chrisi

It certainly won't hurt to

It certainly won't hurt to post the MIDI maps you create for ANY surface. The idea is to try to have defaults so that out of the box Ardour can directly use some functionality of just about any controller.

Seablade

Howdy! I work for Livid

Howdy! I work for Livid Instruments out of Austin, Tx. I would love to create some mappings for our
Ohm
Block
and Code Controllers

It seems like the information here is pretty complete, thanks!

I was wondering...
Is it possible for me to link an encoder to loop points?
So that I could roll them back and forth one measure at a time?

I am a newb to this forum, for the most part.
Is there a list of supported operations?
Is it possible to Bank plugs in in the way tracks are done...
Say,
CC 56 always controls
parameter 1 of the
1st plug-in on
Track 1

Or even Simpler that
CC 52 always controls the Gverb Plug-in Associated with track one (even if it's not there)

the list of supported

the list of supported operations is described in the original post. there are currently no operations to control the loop range. the binding to the nth-parameter of the nth-plugin on the nth-track is described in the original post. there is no way to refer to plugins by name. thanks for your interest, and we'd love to see binding maps for your controllers, especially since they look so cool :)

Thanks very much! I will get

Thanks very much! I will get to work on this. I'm excited to tinker around with the new Ardour while working on this!

~Justin

I was about to start the

I was about to start the process of building mapping files for some controllers, but wanted to take a look at what is already there. I downloaded Ardour3 from svn, but I do not see any .map files. Have these been dropped, never added, or do I need to grab a different branch or something? I also grabbed A2 from svn, but no files there either.

I have an M-Audio Axiom 25, Korg nanoKontrol, and an old Roland foot controller. I'm going to see if I can borrow equipment from some bandmates to map them as well.

@choocus: they are in ardour3

@choocus: they are in ardour3 svn, in the "midi_maps" folder at the top level of the tree.

It appears that my svn didn't

It appears that my svn didn't get a complete copy. It's getting held up with an "operation not permitted" when attempting to create a symbolic link.

I'll troubleshoot and get it downloaded and compiled to start testing. I went ahead and copied the files from svn on the web.

[edit] I just realized that I was trying to checkout to a removable drive with FAT formatting /headdesk/ Problem solved.

In the meantime, here are my first two (untested) map files:
http://chooch.us/content/Korg_nanoKONTROL.map
http://chooch.us/content/M-Audio_Axiom25.map

I noticed that in svn the last five mappings in the bcf2000.map file use
"function-" rather than "function=". I'm assuming that is incorrect as the example on this post uses equal signs.

@choocus: added to svn,

@choocus: added to svn, thanks! and i'll fix the bcf file too.

for those looking for a GTK

for those looking for a GTK MIDI monitor, check this out:

http://home.gna.org/gmidimonitor/

enjoy

Hi, I've modified the BCF2000

Hi, I've modified the BCF2000 map to use two BCF2000s in a 16 channel configuration with channel 16 set to control the Master bus. I used the same preset on each but set the second to use channels 9-16 for the CCs and 12 for program changes. I modified the map as follows, but it's not displaying as an option in Ardour. Anyone got any ideas? Thanks

https://docs.google.com/document/d/1IOdLxtCEqrMP4HB36APC49U6iChkS5ycpmc7RdZGpVc/edit?hl=en_US

@moogmusic: expand on what

@moogmusic: expand on what you mean by "its not displaying as an option". where did you put the modified map file?

I never noticed this.. For my

I never noticed this.. For my BCF2000 do I need to reset it to factory preset for this map to work??

I've got an Emu Xboard: is

I've got an Emu Xboard: is that a popular keyboard? I'd be glad to do a map file if you think it's worth adding to the list.

@paul I placed it in the

@paul I placed it in the share/midi_maps directory (I think that's the path - I'm not currently on my own computer) which contains all the other maps. By "not displaying as an option" I mean that when double clicking on the General MIDI controllers in the Control Surfaces tab of preferences, it's not showing in the drop down menu of options.

Thanks

@moogmusic: try putting it

@moogmusic: try putting it into ~/.config/ardour3/midi_maps

@mcgruff: this is ardour - we

@mcgruff: this is ardour - we don't care about popularity :) Just do the map already, and I'll add it to the list.

@paul I've not had much time

@paul I've not had much time to look into this, but just popping it in ~/.config/ardour3/midi_maps didn't work.

If I want to add comments to

If I want to add comments to a file would I use:

# a comment

...or:

<.!-- a comment -->

..or just don't add comments at all?

@mcgruff: its XML, so <!--

@mcgruff: its XML, so <!-- ... -->

comments are a good idea.

Nearly finished the Emu

Nearly finished the Emu Xboard map. However, I haven't been able to test it yet. Above article says:

"MIDI binding maps are accessible via a selector on the MIDI tab of the Ardour preferences dialog.

...but I can't see any selector in the midi tab.

ardour 2.8.11 built from revision 8444

That is because this feature

That is because this feature is for Ardour3, not Ardour2.

Seablade

Not there either (Ardour

Not there either (Ardour 3.0alpha10 built from revision 10000).

@mcgruff: sorry, the article

@mcgruff: sorry, the article is wrong. you have to dbl-click on the "Generic MIDI" line of the Control Surfaces tab of the Preferences dialog.

Here's a simple map for Emu

Here's a simple map for Emu Xboard 61. For some reason I can't get the note --> function mappings to work but at least there is 16 channel gain control and master volume on the controller wheel.

http://ccgi.mcgruff.plus.com/~mcgruff/public/ardour/midi-bindings/xboard-61.map

@moogmusic Did you get dual

@moogmusic

Did you get dual bcf2000 to work successfully ? I have two bcf myself and will soon try getting them control my daw of choice.
I fetched your bcf4000 file and hopefully it will do magic..

/Anders