path: root/manual/xml/midi_configuration.xml

<?xml version="1.0" standalone="no"?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

]>

<section id="sn-midi-configuration">
  <title>Midi Configuration</title>
  <para>
    Although at this time Ardour does not support
    <glossterm linkend="gt-midi">MIDI</glossterm> sequencing, it does
    support a fairly rich set of interactions via MIDI with other devices.
    In particular:
  </para>

  <itemizedlist>
    <listitem>
      <para>
        Ardour can function as MIDI Time Code (MTC) master or slave
      </para>
    </listitem>

    <listitem>
      <para>
        Ardour can control or be controlled by other devices using MIDI
        Machine Control (MMC)
      </para>
    </listitem>

    <listitem>
      <para>
        Ardour can bind all gain faders, panners, mute/solo/rec-enable
        buttons and all plugin parameters to be controlled by MIDI
        Continuous Controller (CC) or Note On/Off messages.
      </para>
    </listitem>

    <listitem>
      <para>
        Ardour can send MIDI "feedback" whenever gain, pan or plugin state
        changes, so that external motorized control surfaces can reflect
        parameter changes caused by automation etc.
      </para>
    </listitem>
  </itemizedlist>

  <section id="specifying-midi-ports">
    <title>Specifying MIDI ports</title>
    <para>
      Ardour does not attempt to discover what MIDI ports exist on your
      system. This is a complex issue, and on systems like Linux and OS X
      that permit virtual ports to be created at any time, it is not trivial
      to get right (although future versions of Ardour may try).
    </para>

    <para>
      Instead, the MIDI ports that are available for Ardour to use are
      defined in your <filename>ardour.rc</filename> file. These port
      definitions are not session specific, on the assumption that your
      system's MIDI hardware probably doesn't change much from session to
      session. The default version of this file contains a single port that
      can be used for inter-application MIDI routing as well as MIDI I/O to
      whatever physical MIDI ports might be available on your computer. In
      many cases, you will not need to change them.
    </para>

    <para>
      When you first use Ardour, the
<!--
			xlink linkend="files_and_environment"
			-->
      <filename>ardour.rc</filename> file that you will have contains a
      single port definition. It defines a port that is almost guaranteed to
      be usable on your system ((Linux/ALSA users may need to ensure that
      the <filename>snd-seq</filename> kernel module gets loaded - many
      distributions do not do this by default)). This port is a "virtual
      port" it isn't actually a hardware MIDI port, but instead is a
      software port that can be connected to other software ports or to
      whatever hardware MIDI ports you have (see
      <xref linkend="midi-making-connections"/>).
    </para>
  </section>
<!--
	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
		href="Some_Subsection.xml" />
	-->
  <section id="defining-additional-midi-ports">
    <title>Defining additional MIDI ports</title>
    <para>
      To define additional ports, find the line in
      <filename>ardour.rc</filename> that looks roughly like this:
    </para>
<screen>
&lt;MIDI-port tag="hw:0" device="/dev/snd/midiC1D0" type="alsa/raw" mode="duplex"/&gt;
		</screen>
    <para>
      On OSX/CoreMIDI it would look more like:
    </para>
<screen width="50">
&lt;MIDI-port tag="coremidi" device="ardour" type="coremidi" mode="duplex"/&gt;
		</screen>
    <para>
      You can then add another line right after it that looks similar but
      contains a different port definition.
    </para>

    <para>
      You will see there are 4 pieces of information required to define a
      MIDI port for use within Ardour. Your port definition
    </para>

    <section id="midi-tag">
      <title>Tag</title>
      <para>
        This is just a name of your own choosing. It is how the port will be
        referred to within Ardour. You could use a name that describes what
        is plugged into the port (e.g. "1600x", "Novation"), or a name that
        describes the computer device/system that provides the port (e.g.
        "HDSP", "Sequencer"), or a whimsical name of your own choice (e.g.
        "bowtie", "merlin").
      </para>
    </section>

    <section id="midi-type">
      <title>Type</title>
      <para>
        This is an operating system specific identifier that defines what
        kind of port this is. It can be set to one of three values:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            <literal>alsa/raw</literal> - the port corresponds to a physical
            MIDI port that is accessed directly without involving the ALSA
            MIDI routing subsystem.
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>alsa/sequencer</literal> - the port is a virtual port
            that can send and receive MIDI data via the ALSA MIDI routing
            subsystem.
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>coremidi</literal> - the port is a virtual port that
            can send and receive MIDI data via the CoreMidi
            inter-application MIDI routing subsystem.
          </para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="midi-device">
      <title>Device</title>
      <para>
        This is an operating specific and MIDI subsystem-specific name that
        actually identifies the device to be used for MIDI I/O.
      </para>

      <itemizedlist>
        <listitem>
          <para>
            for a raw ALSA hardware port, it is the name of the device file
            corresponding to the hardware MIDI port. A typical value might
            be <filename>/dev/snd/midiC0D0/</filename>.
          </para>
        </listitem>

        <listitem>
          <para>
            for an ALSA sequencer port, it is an arbitrary name for the port
            that will appear as part of the ALSA MIDI routing system
          </para>
        </listitem>

        <listitem>
          <para>
            for a CoreMIDI port, it is an arbitrary name for the port that
            will appear as in any CoreMIDI port selection dialogs.
          </para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="midi-mode">
      <title>Mode</title>
      <para>
        This specifies whether the port is available for input, output or
        both:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            <literal>read</literal> - the port is available for input only
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>write</literal> - the port is available for output only
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>duplex</literal> - the port is available for input and
            output
          </para>
        </listitem>
      </itemizedlist>

      <para>
        You should probably always use <literal>duplex</literal> here. It is
        rare to need to open a port for unidirectional communication only.
      </para>
    </section>
  </section>

  <section id="midi-removing-ports">
    <title>Removing Midi Ports</title>
    <para>
      To remove a MIDI port, simply delete the line in your
      <filename>ardour.rc</filename> file that defines it.
    </para>
  </section>

  <section id="midi-making-connections">
    <title>Making Connections</title>
    <para>
      If you use actual physical hardware MIDI ports, then establishing
      connections to other MIDI equipment is simply a matter of connecting
      cables correctly. However, if you use "virtual ports" such as those
      offered by the ALSA router/sequencer or CoreMIDI, making connections
      is slightly more involved.
    </para>

    <para>
      Ardour does not come with any way of establishing MIDI connections
      from/to other software MIDI ports. This is a difficult task to get
      right, and Ardour may offer something in the future. For now, you need
      to use an external tool that is dedicated to this purpose, much the
      same way you would use a patchbay (audio/MIDI) with physical
      equipment.
    </para>

    <section id="midi-connections-alsa">
      <title>Linux/ALSA</title>
      <para>
        <application>qjackctl</application> (the same program that is
        recommended for controlling JACK) also includes an excellent MIDI
        connection manager. You could also use command line tools such as
        <application>aconnect</application>.
      </para>
    </section>

    <section id="midi-connection-osx">
      <title>OSX/CoreMIDI</title>
      <para>
        On OSX/CoreMIDI you need to connect the MIDI ports with a patchbay
        tool such as the excellent MIDI Patchbay from
        <ulink url="http://pete.yandell.com/software/">Pete Yandell</ulink>
      </para>
    </section>
  </section>

  <section id="midi-using-midi-ports">
    <title>Using MIDI ports</title>
    <para>
      Each port that is defined in <filename>ardour.rc</filename> can be
      used for any of the following functions:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          MTC input and output
        </para>
      </listitem>

      <listitem>
        <para>
          MMC input and output
        </para>
      </listitem>

      <listitem>
        <para>
          MIDI CC/Note input and output
        </para>
      </listitem>
    </itemizedlist>
  </section>
</section>