manual/xml/midi_configuration.xml

   1 <?xml version="1.0" standalone="no"?>
   2
   3 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   4
   5 ]>
   6
   7 <section id="sn-midi-configuration">
   8   <title>Midi Configuration</title>
   9   <para>
  10     Although at this time Ardour does not support
  11     <glossterm linkend="gt-midi">MIDI</glossterm> sequencing, it does
  12     support a fairly rich set of interactions via MIDI with other devices.
  13     In particular:
  14   </para>
  15
  16   <itemizedlist>
  17     <listitem>
  18       <para>
  19         Ardour can function as MIDI Time Code (MTC) master or slave
  20       </para>
  21     </listitem>
  22
  23     <listitem>
  24       <para>
  25         Ardour can control or be controlled by other devices using MIDI
  26         Machine Control (MMC)
  27       </para>
  28     </listitem>
  29
  30     <listitem>
  31       <para>
  32         Ardour can bind all gain faders, panners, mute/solo/rec-enable
  33         buttons and all plugin parameters to be controlled by MIDI
  34         Continuous Controller (CC) or Note On/Off messages.
  35       </para>
  36     </listitem>
  37
  38     <listitem>
  39       <para>
  40         Ardour can send MIDI "feedback" whenever gain, pan or plugin state
  41         changes, so that external motorized control surfaces can reflect
  42         parameter changes caused by automation etc.
  43       </para>
  44     </listitem>
  45   </itemizedlist>
  46
  47   <section id="specifying-midi-ports">
  48     <title>Specifying MIDI ports</title>
  49     <para>
  50       Ardour does not attempt to discover what MIDI ports exist on your
  51       system. This is a complex issue, and on systems like Linux and OS X
  52       that permit virtual ports to be created at any time, it is not trivial
  53       to get right (although future versions of Ardour may try).
  54     </para>
  55
  56     <para>
  57       Instead, the MIDI ports that are available for Ardour to use are
  58       defined in your <filename>ardour.rc</filename> file. These port
  59       definitions are not session specific, on the assumption that your
  60       system's MIDI hardware probably doesn't change much from session to
  61       session. The default version of this file contains a single port that
  62       can be used for inter-application MIDI routing as well as MIDI I/O to
  63       whatever physical MIDI ports might be available on your computer. In
  64       many cases, you will not need to change them.
  65     </para>
  66
  67     <para>
  68       When you first use Ardour, the
  69 <!--
  70                         xlink linkend="files_and_environment"
  71                         -->
  72       <filename>ardour.rc</filename> file that you will have contains a
  73       single port definition. It defines a port that is almost guaranteed to
  74       be usable on your system ((Linux/ALSA users may need to ensure that
  75       the <filename>snd-seq</filename> kernel module gets loaded - many
  76       distributions do not do this by default)). This port is a "virtual
  77       port" it isn't actually a hardware MIDI port, but instead is a
  78       software port that can be connected to other software ports or to
  79       whatever hardware MIDI ports you have (see
  80       <xref linkend="midi-making-connections"/>).
  81     </para>
  82   </section>
  83 <!--
  84         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
  85                 href="Some_Subsection.xml" />
  86         -->
  87   <section id="defining-additional-midi-ports">
  88     <title>Defining additional MIDI ports</title>
  89     <para>
  90       To define additional ports, find the line in
  91       <filename>ardour.rc</filename> that looks roughly like this:
  92     </para>
  93 <screen>
  94 &lt;MIDI-port tag="hw:0" device="/dev/snd/midiC1D0" type="alsa/raw" mode="duplex"/&gt;
  95                 </screen>
  96     <para>
  97       On OSX/CoreMIDI it would look more like:
  98     </para>
  99 <screen width="50">
 100 &lt;MIDI-port tag="coremidi" device="ardour" type="coremidi" mode="duplex"/&gt;
 101                 </screen>
 102     <para>
 103       You can then add another line right after it that looks similar but
 104       contains a different port definition.
 105     </para>
 106
 107     <para>
 108       You will see there are 4 pieces of information required to define a
 109       MIDI port for use within Ardour. Your port definition
 110     </para>
 111
 112     <section id="midi-tag">
 113       <title>Tag</title>
 114       <para>
 115         This is just a name of your own choosing. It is how the port will be
 116         referred to within Ardour. You could use a name that describes what
 117         is plugged into the port (e.g. "1600x", "Novation"), or a name that
 118         describes the computer device/system that provides the port (e.g.
 119         "HDSP", "Sequencer"), or a whimsical name of your own choice (e.g.
 120         "bowtie", "merlin").
 121       </para>
 122     </section>
 123
 124     <section id="midi-type">
 125       <title>Type</title>
 126       <para>
 127         This is an operating system specific identifier that defines what
 128         kind of port this is. It can be set to one of three values:
 129       </para>
 130
 131       <itemizedlist>
 132         <listitem>
 133           <para>
 134             <literal>alsa/raw</literal> - the port corresponds to a physical
 135             MIDI port that is accessed directly without involving the ALSA
 136             MIDI routing subsystem.
 137           </para>
 138         </listitem>
 139
 140         <listitem>
 141           <para>
 142             <literal>alsa/sequencer</literal> - the port is a virtual port
 143             that can send and receive MIDI data via the ALSA MIDI routing
 144             subsystem.
 145           </para>
 146         </listitem>
 147
 148         <listitem>
 149           <para>
 150             <literal>coremidi</literal> - the port is a virtual port that
 151             can send and receive MIDI data via the CoreMidi
 152             inter-application MIDI routing subsystem.
 153           </para>
 154         </listitem>
 155       </itemizedlist>
 156     </section>
 157
 158     <section id="midi-device">
 159       <title>Device</title>
 160       <para>
 161         This is an operating specific and MIDI subsystem-specific name that
 162         actually identifies the device to be used for MIDI I/O.
 163       </para>
 164
 165       <itemizedlist>
 166         <listitem>
 167           <para>
 168             for a raw ALSA hardware port, it is the name of the device file
 169             corresponding to the hardware MIDI port. A typical value might
 170             be <filename>/dev/snd/midiC0D0/</filename>.
 171           </para>
 172         </listitem>
 173
 174         <listitem>
 175           <para>
 176             for an ALSA sequencer port, it is an arbitrary name for the port
 177             that will appear as part of the ALSA MIDI routing system
 178           </para>
 179         </listitem>
 180
 181         <listitem>
 182           <para>
 183             for a CoreMIDI port, it is an arbitrary name for the port that
 184             will appear as in any CoreMIDI port selection dialogs.
 185           </para>
 186         </listitem>
 187       </itemizedlist>
 188     </section>
 189
 190     <section id="midi-mode">
 191       <title>Mode</title>
 192       <para>
 193         This specifies whether the port is available for input, output or
 194         both:
 195       </para>
 196
 197       <itemizedlist>
 198         <listitem>
 199           <para>
 200             <literal>read</literal> - the port is available for input only
 201           </para>
 202         </listitem>
 203
 204         <listitem>
 205           <para>
 206             <literal>write</literal> - the port is available for output only
 207           </para>
 208         </listitem>
 209
 210         <listitem>
 211           <para>
 212             <literal>duplex</literal> - the port is available for input and
 213             output
 214           </para>
 215         </listitem>
 216       </itemizedlist>
 217
 218       <para>
 219         You should probably always use <literal>duplex</literal> here. It is
 220         rare to need to open a port for unidirectional communication only.
 221       </para>
 222     </section>
 223   </section>
 224
 225   <section id="midi-removing-ports">
 226     <title>Removing Midi Ports</title>
 227     <para>
 228       To remove a MIDI port, simply delete the line in your
 229       <filename>ardour.rc</filename> file that defines it.
 230     </para>
 231   </section>
 232
 233   <section id="midi-making-connections">
 234     <title>Making Connections</title>
 235     <para>
 236       If you use actual physical hardware MIDI ports, then establishing
 237       connections to other MIDI equipment is simply a matter of connecting
 238       cables correctly. However, if you use "virtual ports" such as those
 239       offered by the ALSA router/sequencer or CoreMIDI, making connections
 240       is slightly more involved.
 241     </para>
 242
 243     <para>
 244       Ardour does not come with any way of establishing MIDI connections
 245       from/to other software MIDI ports. This is a difficult task to get
 246       right, and Ardour may offer something in the future. For now, you need
 247       to use an external tool that is dedicated to this purpose, much the
 248       same way you would use a patchbay (audio/MIDI) with physical
 249       equipment.
 250     </para>
 251
 252     <section id="midi-connections-alsa">
 253       <title>Linux/ALSA</title>
 254       <para>
 255         <application>qjackctl</application> (the same program that is
 256         recommended for controlling JACK) also includes an excellent MIDI
 257         connection manager. You could also use command line tools such as
 258         <application>aconnect</application>.
 259       </para>
 260     </section>
 261
 262     <section id="midi-connection-osx">
 263       <title>OSX/CoreMIDI</title>
 264       <para>
 265         On OSX/CoreMIDI you need to connect the MIDI ports with a patchbay
 266         tool such as the excellent MIDI Patchbay from
 267         <ulink url="http://pete.yandell.com/software/">Pete Yandell</ulink>
 268       </para>
 269     </section>
 270   </section>
 271
 272   <section id="midi-using-midi-ports">
 273     <title>Using MIDI ports</title>
 274     <para>
 275       Each port that is defined in <filename>ardour.rc</filename> can be
 276       used for any of the following functions:
 277     </para>
 278
 279     <itemizedlist>
 280       <listitem>
 281         <para>
 282           MTC input and output
 283         </para>
 284       </listitem>
 285
 286       <listitem>
 287         <para>
 288           MMC input and output
 289         </para>
 290       </listitem>
 291
 292       <listitem>
 293         <para>
 294           MIDI CC/Note input and output
 295         </para>
 296       </listitem>
 297     </itemizedlist>
 298   </section>
 299 </section>