Add new continuous controller types

[ardour-manual] / include / generic-midi-binding-maps.html

<p>
  Ardour 2.X supported
  <a href="@@generic-midi-learn"><dfn>MIDI learning</dfn></a>
  for more or less any control. This was a nice feature that quite a few other
  DAWs are providing by now, 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 <dfn>MIDI binding map</dfn>
  for a given controller, which can set up an arbitrary number of physical
  controls with anything inside Ardour that can be controlled.
</p>
<p>
  Currently (August 2016), we have presets for the following devices/modes:
</p>
<ul>
  <li>AKAI MPD-32</li>
  <li>AKAI MPK61</li>
  <li>AKAI MPKmini</li>
  <li>Behringer BCF2000</li>
  <li>Behringer BCF2000 (Mackie Emulation mode; better to use
    Ardour's actual Mackie Control Protocol support)</li>
  <li>Behringer DDX3216</li>
  <li>Korg nanoKONTROL (2 layouts)</li>
  <li>Korg nanoKONTROL 2 (2 layouts)</li>
  <li>Korg Taktile</li>
  <li>M-Audio Axiom 25 (2 layouts)</li>
  <li>M-Audio Axiom 61</li>
  <li>M-Audio Oxygen 49</li>
  <li>M-Audio Oxygen 61v3</li>
  <li>M-Audio Oxygen 25</li>
  <li>M-Audio Oxygen 8v2</li>
  <li>Novation Impulse 49</li>
  <li>Novation Impulse 61</li>
  <li>Novation LaunchControl XL</li>
  <li>Novation LaunchKey 25</li>
  <li>Roland SI-24</li>
  <li>Roland V Studio 20</li>
  <li>Yamaha KX25</li>
</ul>
  At this time, new binding maps need to be created with a text editor.
<p>
  MIDI binding maps are accessible by double-clicking <kbd class="menu">Edit
  &gt; Preferences &gt; Control Surfaces &gt; Generic MIDI</kbd>. Ardour will
  retain your selection after you choose one.
</p>

<h2>Creating new MIDI maps</h2>
<h3>The Basic Concept</h3>
<p>
  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
  <dfn>remote control ID</dfn>. This ID uniquely identifies a track or bus
  so that when messages arrive from elsewhere via MIDI or OSC , we can determine
   which track or bus they are intended to control. See
   <a href="@@controlling-track-ordering">
   remote control IDs</a> for more information.
   You just need to know that there is a "first track" and its remote control
   ID is 1, and so on.
</p>
<h3>Getting Started</h3>
<p>
  MIDI bindings are stored in files with the suffix ".map" attached to their
  name. The minimal content looks like this:
</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ArdourMIDIBindings version="1.0.0" name="The name of this set of
bindings"&gt;
&lt;/ArdourMIDIBindings&gt;
</pre>
<p>
  So, to start, create a file with that as the initial contents.
</p>
<p>
        The file should be located in the midi_maps sub directory located in
        the <a href="@@files-and-directories-ardour-knows-about">Ardour configuration directory</a>
</p>

<h3>Finding out what your MIDI control surface sends</h3>
<p>
  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
  <code>gmidimon</code> and <code>kmidimon</code>, 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.)
</p>
<h3>Types of Bindings</h3>
<p>
  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.
</p>
<h4>Binding to Track/Bus controls</h4>
<p>
  A track/bus binding has one of two basic structures
</p>
<code>
  &lt;Binding <em>msg specification</em>  uri="<em>&hellip; control address &hellip;</em>"/&gt;
  &lt;Binding <em>msg specification</em>  function="<em>&hellip; function name &hellip;</em>"/&gt;
</code>

<h4>Message specifications</h4>
<p>
  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:
</p>
<code>
   &lt;Binding channel="1" ctl="13" &hellip;
</code>
<p>
  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 <code>ctl</code>, you can alternatively
  use <code>note</code> (to create binding for a Note On message) or
  <code>pgm</code>  (to create a binding for a Program Change message).
</p>
<p>
        Continous Controlers (CCs) have coninued to evolve for different controlers.
        The use of Encoders, RPN, NRPN, and controller buttons that give a 0 value
        when released instead of toggling are now supported. These all have their
        own type. The whole list of CC types are:
</p>
<p>
        <ul>
                <li>ctl - sets as CC to the value sent (works the same as
                <code>note</code> with the <code>momentary</code>parameter set)</li>
                <li>ctl-toggle - for CC controls that send a 127 for button press
                and 0 for button release. The release is ignored and the value is
                toggled with each press. (works the same as <code>note</code>)</li>
                <li>ctl-dial - passes the CC value to the controlled object</li>
                <li>rpn - The CC value may be a 14 bit value</li>
                <li>nrpn - The CC number and the value may both be 14 bit values</li>
                <li>rpn-delta - The value is expected to be a signed 14bit value
                that is added to the current value. For use with encoders</li>
                <li>nrpn-delta - The value is expected to be a signed 14bit value
                that is added to the current value. For use with encoders</li>
                <li>enc-r, enc-l, enc-2 and enc-b - See below</li>
        </ul>
</p>
<p>
  As of Ardour 4.2, <code>enc-r</code>, <code>enc-l</code>, <code>enc-2</code> and
  <code>enc-b</code> may be used for surfaces that have encoders that send
  offsets rather than values. These accept Continuous Controller messages
  but treat them as offsets. These are good for banked controls as they are
  always at the right spot to start adjusting. (
   <a href="@@generic-midi-and-encoders">
   Learn more about working with encoders
   </a>)
</p>
<p>
        <ul>
                <li><code>&lt;Binding channel="1" enc-r="13" &hellip;</code></li>
                <li><code>&lt;Binding channel="1" enc-l="13" &hellip;</code></li>
                <li><code>&lt;Binding channel="1" enc-2="13" &hellip;</code></li>
                <li><code>&lt;Binding channel="1" enc-b="13" &hellip;</code></li>
        </ul>
        The <code>enc-*</code> value is the CC number used by the encoder.
        Encoders only work with CC messages.
</p>
<p class="note">
        Ardour 5.12 has a bug with the encoder detection where the first
        encoder message resets the control to 0. Setting "Enable Feedback"
        on allows encoders to work as expected.
</p>
<p>
  You can also bind sysex messages:
</p>
<code>
  &lt;Binding sysex="f0 0 0 e 9 0 5b f7" &hellip;.
  &lt;Binding sysex="f0 7f 0 6 7 f7" &hellip;.
</code>
<p>
  The string after the <code>sysex=</code> part is the sequence of MIDI bytes,
  as hexadecimal values, that make up the sysex message.
</p>
<p>
  Finally, you can bind a totally arbitrary MIDI message:</p>
<code>
  &lt;Binding msg="f0 0 0 e 9 0 5b f7" &hellip;.
  &lt;Binding msg="80 60 40" &hellip;.
</code>
<p>
  The string after the <code>msg=</code> 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.
</p>

<p class="note">
  As of Ardour 4.6 it is possible to use multi-event MIDI strings such as
  two event CC messages, RPN or NRPN.
</p>

<p class="note">
  The <code>sysex=</code> and <code>msg=</code> bindings will only work with
  <code>function=</code> or <code>action=</code> control addresses. They
  will <em>not</em> work with the <code>uri=</code> control addresses.
  Controls used with <code>uri=</code> require a <em>Value</em> which is
  only available in a known place with channel mode MIDI events.
</p>

<h4>Control address</h4>
<p>
  A <dfn>control address</dfn> defines what the binding will actually control.
  There are quite a few different things that can be specified here:
</p>
<p class="note">
        Enable Feeback applies to these "Control Addresses" only.
</p>
<table class="dl">
<tr><th>/route/gain</th>
<td>the gain control ("fader") for the track/bus</td></tr>
<tr><th>/route/trim</th>
<td>the trim control for the track/bus (new in 4.1)</td></tr>
<tr><th>/route/solo</th>
<td>a toggleable control for solo (and listen) of the track/bus</td></tr>
<tr><th>/route/mute</th>
<td>a toggleable control to mute/unmute the track/bus</td></tr>
<tr><th>/route/recenable</th>
<td>a toggleable control to record-enable the track</td></tr>
<tr><th>/route/panwidth</th>
<td>interpreted by the track/bus panner, should control image "width"</td></tr>
<tr><th>/route/pandirection</th>
<td>interpreted by the track/bus panner, should control image "direction"</td></tr>
<tr><th>/route/plugin/parameter</th>
<td>the Mth parameter of the Nth plugin of a track/bus
</td></tr>
<tr><th>/route/send/gain</th>
<td>the gain control ("fader") of the Nth send of a track/bus</td></tr>
</table>
<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>
<table class="dl">
<tr><th>a number, e.g. "1"
</th>
<td>identifies a track or bus by its remote control ID
</td></tr>
<tr><th>B, followed by a number
</th>
<td>identifies a track or bus by its remote control ID within the current bank (see below for more on banks)
</td></tr>
<tr><th>S, followed by a number
</th>
<td>identifies a selected track in order they have been selected, S1 should be the same track as the Editor Mixer
</td></tr>
<tr><th>one or more words
</th>
<td>identifies a track or bus by its name
</td></tr>
</table>
<p>
  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).
</p>
<p>
  One additional feature: for solo and mute bindings, you can also add
  <code>momentary="yes"</code> after the control address. This is useful
  primarily for NoteOn bindings&mdash;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.
</p>

<h4>Bindings to Ardour "functions"</h4>
<p class="note">
        There is currently no feedback available for functions.
</p>
<p>
  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:
</p>
<code>
  &lt;Binding channel="1" note="13" function="transport-roll"/&gt;
</code>
<p>
  In this case, a NoteOn message for note number 13 (on channel 1) will
  start the transport rolling. The following function names are available:
</p>
<table class="dl">
<tr><th>
<code>transport-stop</code>
</th>
<td>stop the transport
</td></tr>
<tr><th>
<code>transport-roll</code>
</th>
<td>start the transport "rolling"
</td></tr>
<tr><th>
<code>transport-zero</code>
</th>
<td>move the playhead to the zero position
</td></tr>
<tr><th>
<code>transport-start</code>
</th>
<td>move the playhead to the start marker
</td></tr>
<tr><th>
<code>transport-end</code>
</th>
<td>move the playhead to the end marker
</td></tr>
<tr><th>
<code>loop-toggle</code>
</th>
<td>turn on loop playback
</td></tr>
<tr><th>
<code>rec-enable</code>
</th>
<td>enable the global record button
</td></tr>
<tr><th>
<code>rec-disable</code>
</th>
<td>disable the global record button
</td></tr>
<tr><th>
<code>next-bank</code>
</th>
<td>Move track/bus mapping to the next bank (see Banks below)
</td></tr>
<tr><th>
<code>prev-bank</code>
</th>
<td>Move track/bus mapping to the previous bank (see Banks below)
</td></tr>
</table>

<h4>Binding to Ardour "actions"</h4>
<p class="note">
        It is not possible to have feedback available for actions because
        these represent keyboard shortcuts which are input only.
</p>
<p>
  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 <a
  href="@@list-of-menu-actions">
  list of actions</a> shows all available values of <em>action-name</em>.
<p>
  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:
</p>
<code>
   &lt;Binding msg="80 60 40" action="Editor/temporal-zoom-in"/&gt;
</code>
<p>
  The general rule, when taken an item from the keybindings file and
  using it in a MIDI binding is to simply strip the
  <code>&lt;Action&gt;</code> prefix of the second field in the
  keybinding definition.
</p>

<h3>Banks and Banking</h3>
<p>
  Because many modern control surfaces offer per-track/bus controls
  for far fewer tracks &amp; busses than many users want to control,
  Ardour offers the relatively common place concept of <dfn>banks</dfn>. Banks
  allow you to control any number of tracks and/or busses easily,
  regardless of how many faders/knobs etc. your control surface has.<br>
  To use banking, the control addresses must be specified using the
  <dfn>bank relative</dfn> format mentioned above ("B1" to identify
  the first track of a bank of tracks, rather than "1" to identify
  the first track).
</p>
<p>
  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:</p>
<code>
   &lt;DeviceInfo bank-size="8"/&gt;
</code>
<p>
  In addition, you probably want to ensure that you bind something
  on the control surface to the <code>next-bank</code> and
  <code>prev-bank</code> 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.
</p>
<h3>The Selected Strip</h3>
<p>
  Often times one wants to just deal with the strip currently
  selected by the GUI (or the control surface). In the same way as with
  banks above the selected strip can be designated with <em>S1</em>.
</p>
<h2>A Complete (though muddled) Example</h2>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ArdourMIDIBindings version="1.0.0" name="pc1600x transport controls"&gt;
  &lt;DeviceInfo bank-size="16"/&gt;
  &lt;Binding channel="1" ctl="1"   uri="/route/gain B1"/&gt;
  &lt;Binding channel="1" ctl="2"   uri="/route/gain B2"/&gt;
  &lt;Binding channel="1" ctl="3"   uri="/route/send/gain B1 1"/&gt;
  &lt;Binding channel="1" ctl="4"   uri="/route/plugin/parameter B1 1 1"/&gt;
  &lt;Binding channel="1" ctl="6"   uri="/bus/gain master"/&gt;

  &lt;Binding channel="1" note="1"  uri="/route/solo B1"/&gt;
  &lt;Binding channel="1" note="2"  uri="/route/solo B2" momentary="yes"/&gt;

  &lt;Binding channel="1" note="15"  uri="/route/mute B1" momentary="yes"/&gt;
  &lt;Binding channel="1" note="16"  uri="/route/mute B2" momentary="yes"/&gt;

  &lt;Binding channel="1" enc-r="11"   uri="/route/pandirection B1"/&gt;
  &lt;Binding channel="1" enc-r="12"   uri="/route/pandirection B2"/&gt;

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

  &lt;Binding channel="1" note="13" function="transport-roll"/&gt;
  &lt;Binding channel="1" note="14" function="transport-stop"/&gt;
  &lt;Binding channel="1" note="12" function="transport-start"/&gt;
  &lt;Binding channel="1" note="11" function="transport-zero"/&gt;
  &lt;Binding channel="1" note="10" function="transport-end"/&gt;
&lt;/ArdourMIDIBindings&gt;
</pre>
<p>
  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).
</p>