diff options
Diffstat (limited to 'manual/xml/midi_configuration.xml')
-rw-r--r-- | manual/xml/midi_configuration.xml | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/manual/xml/midi_configuration.xml b/manual/xml/midi_configuration.xml new file mode 100644 index 0000000000..32eb2c71d1 --- /dev/null +++ b/manual/xml/midi_configuration.xml @@ -0,0 +1,299 @@ +<?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> +<MIDI-port tag="hw:0" device="/dev/snd/midiC1D0" type="alsa/raw" mode="duplex"/> + </screen> + <para> + On OSX/CoreMIDI it would look more like: + </para> +<screen width="50"> +<MIDI-port tag="coremidi" device="ardour" type="coremidi" mode="duplex"/> + </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> |