458 lines
17 KiB
HTML
458 lines
17 KiB
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 MidiMix (2 layouts)</li>
|
|
<li>AKAI MPD-32</li>
|
|
<li>AKAI MPK61</li>
|
|
<li>AKAI MPKmini</li>
|
|
<li>Alesis QX25</li>
|
|
<li>Arturia KeyLab49</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 (3 layouts)</li>
|
|
<li>Korg nanoKONTROL 2 (2 layouts)</li>
|
|
<li>Korg Taktile</li>
|
|
<li>M-Audio Axiom 25</li>
|
|
<li>M-Audio Axiom 61</li>
|
|
<li>M-Audio Axiom Air 25</li>
|
|
<li>M-Audio Axiom Air Mini 32</li>
|
|
<li>M-Audio Oxygen 8v2</li>
|
|
<li>M-Audio Oxygen 25</li>
|
|
<li>M-Audio Oxygen 49</li>
|
|
<li>M-Audio Oxygen 61v3 (2 layouts)</li>
|
|
<li>Novation Impulse 49</li>
|
|
<li>Novation Impulse 61</li>
|
|
<li>Novation LaunchControl XL</li>
|
|
<li>Novation LaunchKey 25</li>
|
|
<li>Novation LaunchKey 49</li>
|
|
<li>Roland SI-24</li>
|
|
<li>Roland V Studio 20</li>
|
|
<li>WiiMote</li>
|
|
<li>Xboard 61</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
|
|
> Preferences > Control Surfaces > 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>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<ArdourMIDIBindings version="1.0.0" name="The name of this set of
|
|
bindings">
|
|
</ArdourMIDIBindings>
|
|
</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 something that will change
|
|
Ardour's state in some way (the "something" could either be called a
|
|
function or an action, see below).
|
|
</p>
|
|
<h4>Binding to Track/Bus controls</h4>
|
|
<p>
|
|
A track/bus binding has one of three basic structures
|
|
</p>
|
|
<code>
|
|
<Binding <em>msg specification</em> uri="<em>… control address …</em>"/></br>
|
|
<Binding <em>msg specification</em> function="<em>… function name …</em>"/></br>
|
|
<Binding <em>msg specification</em> action="<em>… action name …</em>"/>
|
|
</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>
|
|
<Binding channel="1" ctl="13" …
|
|
</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 a 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 - For 7 bit encoders. 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><Binding channel="1" enc-r="13" …</code></li>
|
|
<li><code><Binding channel="1" enc-l="13" …</code></li>
|
|
<li><code><Binding channel="1" enc-2="13" …</code></li>
|
|
<li><code><Binding channel="1" enc-b="13" …</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>
|
|
<Binding sysex="f0 0 0 e 9 0 5b f7" ….</br>
|
|
<Binding sysex="f0 7f 0 6 7 f7" ….
|
|
</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>
|
|
<Binding msg="f0 0 0 e 9 0 5b f7" ….</br>
|
|
<Binding msg="80 60 40" ….
|
|
</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—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/plugin control, it may be useful to
|
|
have a MIDI controller able to alter some part of Ardour's
|
|
state. Ardour's Generic MIDI support provides a small number of
|
|
easily-used "functions" to do the most common operations, using a
|
|
binding that looks like this:
|
|
</p>
|
|
<code>
|
|
<Binding channel="1" note="13" function="transport-roll"/>
|
|
</code>
|
|
<p>
|
|
In this case, a NoteOn message for note number 13 (on channel 1) will
|
|
start the transport rolling.
|
|
</p>
|
|
<p>
|
|
Note that a much greater number of operations are possible using
|
|
actions, described below.
|
|
</p>
|
|
<p>
|
|
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>
|
|
<Binding msg="80 60 40" action="Editor/temporal-zoom-in"/>
|
|
</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><Action></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 & 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>
|
|
<DeviceInfo bank-size="8"/>
|
|
</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>
|
|
<?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 channel="1" enc-r="11" uri="/route/pandirection B1"/>
|
|
<Binding channel="1" enc-r="12" uri="/route/pandirection B2"/>
|
|
|
|
<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>
|
|
</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>
|
|
|