diff options
Diffstat (limited to 'manual/xml/midi_configuration.xml')
| -rw-r--r-- | manual/xml/midi_configuration.xml | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/manual/xml/midi_configuration.xml b/manual/xml/midi_configuration.xml new file mode 100644 index 0000000000..13dc039273 --- /dev/null +++ b/manual/xml/midi_configuration.xml @@ -0,0 +1,282 @@ +<?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> |