0002519: Update manual - MantisBT

ID	Project	Category	View Status	Date Submitted	Last Update

0002519	ardour	documentation	public	2009-01-15 20:11	2017-05-17 07:50

Reporter	tanjeff	Assigned To
Priority	normal	Severity	major	Reproducibility	N/A
Status	closed	Resolution	fixed
Product Version	2.7.1

Summary	0002519: Update manual
Description	The manual is incomplete and out of date. Updates should be provided to get the manual complete.
Additional Information	Here is a patch which updates MIDI stuff, in particular: - Complete rewrite of section "MIDI Configuration". The section has been moved into section 2 - Updated section "Using Control Surfaces" and changed the order and titles of its subsections. - Filled content into section "Using a Generic MIDI control surface" - Slightly updated section "Using the Mackie driver for MCU and BCF2000" - Merged sections "Using a Frontier Design Tranzport" and "Configuring USB device access" and slightly updated them. - Slightly updated section "Behringer DDX3216" - Updated section "Behringer BCF2000/BCR2000" NOTE: The file manual/xml/configuring_usb_device_access.xml is no longer needed since it was merged into manual/xml/frontier_design_tranzport.xml
Tags	No tags attached.

2009-01-15 20:11	ardour2_manual_xml.patch (54,841 bytes) Index: generic_midi_control_surface.xml =================================================================== --- generic_midi_control_surface.xml (revision 4410) +++ generic_midi_control_surface.xml (working copy) @@ -6,11 +6,92 @@ <section id="sn-generic-midi-control-surface"> <title>Using a Generic MIDI control surface</title> - <para> - To be completed. Applies only to Ardour 2. - </para> -<!-- - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="Some_Subsection.xml" /> - --> + + <section id="connecting-control-surface"> + <title>Connecting the MIDI control surface</title> + <para> + In Ardour, all gain faders, panners, mute/solo/rec-enable + buttons and all plugin parameters can be controlled by MIDI + Continuous Controller (CC) (which is called MIDI Parameter Control in + Ardour). Ardour can also send MIDI "feedback" whenever gain, pan or + plugin state + changes, so that external motorized control surfaces can reflect + parameter changes caused by automation etc. In addition, MMC commands are + supported. Generic MIDI control surfaces do not use the MCU protocol. + </para> + + <para> + You need to have a MIDI port set up to deal with MMC and/or MIDI + Parameter control as descibed in <xref linkend="sn-midi-configuration"/>. + Your control surface (e.g. a Behringer BCF2000) has to be connected to + the correct Ardour MIDI port. + </para> + </section> + + <section id="set-up-control-surface"> + <title>Setting up the MIDI control surface</title> + + <para> + To use a generic MIDI control surface in Ardour, choose the "Options" + menu, then choose the "Control Surfaces" submenu, then select "Generic + Midi". + </para> + + <para> + Ardour can send feedback to the control surface, allowing it to reflect + changes caused by automation or by mouse interaction. You can enable + feedback by choosing the "Options" menu, the "Control Surfaces" submenu, + the "Controls" submenu, then selecting "Feedback". + </para> + + <para> + To control e.g. a gain fader, use <mousebutton>Ctrl+Button2</mousebutton> + on the fader. The message "operate controller now" should appear. Move + the desired fader or knob on your control surface. The fader on the + screen should start to move as you move the slider on your control + surface. If you activated MIDI feedback and your control surface supports + it, it should reflect changes you do with the mouse. + </para> + + <para> + You can configure MIDI control for virtually all faders, plugin + parameters and switches by using <mousebutton>Ctrl+Button2</mousebutton> + on it, then moving the desired control on the control surface a bit. + </para> + + <note> + <title>Note</title> + <para> + The assignments of the MIDI controls are saved with the Ardour project. + For each new project, you have to assign every control manually. To + avoud this, you can use a template, see <xref + linkend="sn-templates"/>. + </para> + </note> + </section> + + <section id="used-midi-commands"> + <title>MIDI commands used to control Ardour</title> + + <para> + Controls in Ardour are controlled with Change Control (CC) MIDI commands. + Those commands can be sent on arbitrary MIDI channels. + Faders and other continously moved controls are controlled with CC + commands with a range of 0-127. Buttons (e.g. Mute buttons) are also + controlled with CC commands, where a value of 0-63 switches the button + off and a value of 64-127 switches the button on. + </para> + + <para> + Ardour also receives and sends some MMC commands, such as play, stop, + locate, punch in and punch out. Make sure you configured Ardour to listen + for MMC commands as descibed in <xref linkend="sn-midi-configuration"/>. + </para> + + + </section> + <!-- + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="Some_Subsection.xml" /> + --> </section> Index: control_surfaces.xml =================================================================== --- control_surfaces.xml (revision 4410) +++ control_surfaces.xml (working copy) @@ -7,21 +7,29 @@ <chapter id="ch-control-surfaces"> <title>Using Control Surfaces</title> <para> - You can use a variety of different control surfaces with Ardour. We - anticipate full support for a new class of control surfaces (those using - the Mackie Control protocol) by the mid-summer of 2006, possibly - earlier. + Ardour supports several control surfaces: generic MIDI control surfaces, + MCU surfaces, the Frontier Tranzport device and others. Generic MIDI + control can be used with any MIDI controller capable to send CC (Control + Change) and/or MMC commands, such as the Behringer BCF2000/BCR2000. The + MCU protocol can be used with controllers supporting the Mackie MCU + protocol, but the MCU protocol is not yet fully implemented and configuring + an MCU device is a challenging task. Setting up the Tranzport device is + also tricky. </para> + + <para> + This chapter describes how to use generic MIDI control, MCU and Tranzport + surfaces. Additionally, some short tutorials are included. + Other Surfaces are experimental and are not described in this chapter. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="generic_midi_control_surface.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="mackie.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="frontier_design_tranzport.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="behringer_ddx3216.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bcf2000.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="frontier_design_tranzport.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="generic_midi_control_surface.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="configuring_usb_device_access.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="mackie.xml" /> </chapter> Index: behringer_ddx3216.xml =================================================================== --- behringer_ddx3216.xml (revision 4410) +++ behringer_ddx3216.xml (working copy) @@ -5,7 +5,7 @@ ]> <section id="sn-behringer-ddx3216"> - <title>Behringer DDX3216</title> + <title>Tutorial: Behringer DDX3216</title> <para> The Behringer DDX3216 isn't actually a dedicated control surface, it is a digital mixer. However it does have the capability to control ardour @@ -62,9 +62,10 @@ following steps each time. Load a new session with your desired amount of tracks (I used 16). Go to menu <menuchoice> <guimenu>Windows</guimenu> <guisubmenu>Options Editor</guisubmenu> - </menuchoice> and select the <guilabel>MIDI</guilabel> tab. Select - all the options and make sure the midi port you have connected to in - qjackctl is 'online'. + </menuchoice> and select the <guilabel>MIDI</guilabel> tab. Configure + the port you chose to connect with the DDX3216 to handle all kinds of + MIDI information (see <xref linkend="sn-midi-configuration"/>). Make + sure it is 'online'. </para> </listitem> <listitem> @@ -91,6 +92,7 @@ </para> </listitem> <listitem> + <!-- TODO: This is not up-to date and doesn't match Ardour 2.7.1 --> <para> You can also operate the ardour transport and have ardour transmit MTC back to your DDX3216 (it is only capable of receiving timecode, Index: midi_configuration.xml =================================================================== --- midi_configuration.xml (revision 4410) +++ midi_configuration.xml (working copy) @@ -5,7 +5,7 @@ ]> <section id="sn-midi-configuration"> - <title>Midi Configuration</title> + <title>MIDI Configuration</title> <para> Although at this time Ardour does not support <glossterm linkend="gt-midi">MIDI</glossterm> sequencing, it does @@ -16,36 +16,40 @@ <itemizedlist> <listitem> <para> - Ardour can function as MIDI Time Code (MTC) master or slave + Ardour can function as MIDI Time Code (MTC) master or slave. MTC is + used to transfer the actual time location, so the connected MIDI + devices will stay in sync (even when using fast forward and such). </para> </listitem> <listitem> <para> Ardour can control or be controlled by other devices using MIDI - Machine Control (MMC) + Machine Control (MMC). MMC commands include start, stop, punch in, + punch out and others. </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. + In Ardour, virtually any parameter can be controlled by MIDI + Continuous Controller (CC) messages (which is called MIDI Parameter + Control). In addition, Ardour can send MIDI "feedback" + so that external motorized control surfaces can reflect parameter + changes caused by automation etc. See <xref + linkend="ch-control-surfaces"/> how to configure control surfaces. </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> + If you need MIDI in Ardour, you have to configure it. This is described in + this section. If you don't, skip this section and come back when you need + it. + </para> + + <section id="midi-ports"> + <title>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 @@ -54,180 +58,214 @@ </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. + Instead, some ports are defined which can be connected to any other MIDI + port. 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. 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> + + <section id="configuring-midi-ports"> + <title>Configuring MIDI ports</title> + <para> - To define additional ports, find the line in - <filename>ardour.rc</filename> that looks roughly like this: + When you first use Ardour, three MIDI ports will be available which are + 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). These are "virtual + ports" which are not actually related to any hardware MIDI port. They can + be connected to other software ports or to whatever hardware MIDI ports + you have (see <xref linkend="midi-making-connections"/>). </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 + You can modify existing ports in the "Preferences" Window. Choose + <menuchoice><guimenu> + Edit</guimenu><guisubmenu>Preferences</guisubmenu></menuchoice> to + show that window, then go to the <guilabel>MIDI</guilabel> tab. You + should see at least the ports "control", "mcu" and "seq". For each port + you can configure the following options: </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> + <variablelist> - <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> + <varlistentry> + <term>Online</term> <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. + Setting a port to offline will not cause a port to disappear; + rather Ardour will simple no longer send any data on it, nor + will it process data received on it. Online ports work + normally. </para> </listitem> + </varlistentry> + <varlistentry> + <term>Trace Input</term> + <term>Trace Output</term> <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. + When one of these buttons is checked for a port, the sent (Output) + respective received (Input) MIDI data will be displayed on the + console. Note that you need to run Ardour from a console to see that + output. This can be useful to check your MIDI connections. </para> </listitem> + </varlistentry> + <varlistentry> + <term>MTC</term> + <term>MMC</term> + <term>MIDI Parameter Control</term> <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. + You can choose which port is used for which kind of MIDI + information. For each kind - MTC, MMC and MIDI Parameter Control - + one MIDI port have to be assigned. The same MIDI port can be used + for several kinds of information. </para> </listitem> - </itemizedlist> - </section> + </varlistentry> - <section id="midi-device"> - <title>Device</title> + </variablelist> + + <!-- + <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> - This is an operating specific and MIDI subsystem-specific name that - actually identifies the device to be used for MIDI I/O. + You can easily define additional midi ports. Choose + <menuchoice><guimenu>Edit</guimenu><guisubmenu>Preferences</guisubmenu></menuchoice> + to show the "Preferences" window, then go to the + <guilabel>MIDI</guilabel> tab. Click on the <guibutton>Add new MIDI + port</guibutton> button to add a new port. Provide a name and choose + one of the following options: </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> + <variablelist> - <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> + <varlistentry> + <term>input</term> + <listitem> + <para> + The new port will be an input port. + This is rarely used. + </para> + </listitem> + </varlistentry> - <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> + <varlistentry> + <term>output</term> + <listitem> + <para> + The new port will be an output port. This is rarely used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>duplex</term> + <listitem> + <para> + The new port will be an input and output port. This is what is + normally needed. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + Click on the <guibutton>Add</guibutton> button to create the new port. + </para> + </section> - <section id="midi-mode"> - <title>Mode</title> + <section id="midi-removing-ports"> + <title>Removing MIDI Ports</title> <para> - This specifies whether the port is available for input, output or - both: + To remove a MIDI port, click on the <guibutton>Remove</guibutton> button + right of the port. </para> - <itemizedlist> + <note> + <title>Note</title> + <para> + You can not remove a port if it is configured to transfer MTC, MMC or + MIDI Parameter Control data. That also means that the last port + cannot be removed as it will necessarily be configured to transfer all + kind of MIDI data. + </para> + </note> + + <note> + <title>Note</title> + <para> + If you remove one of the default MIDI ports (control, seq, mcu), it + will automatically be recreated next time you start Ardour. This is + because these default ports are saved in + <filename>/etc/ardour2/ardour_system.rc</filename> where you can't + remove them. Your MIDI configuration is saved in + <filename>$HOME/.ardour2/ardour.rc</filename>. + </para> + </note> + </section> + </section> + + <section id="additional-configuration"> + <title>Additional Configuration</title> + <para> + Ardour allows some more MIDI configuration: + </para> + + <variablelist> + + <varlistentry> + <term>Inbound MMC Device ID</term> <listitem> <para> - <literal>read</literal> - the port is available for input only + Each MMC command includes a device ID. Ardour listens only for MMC + commands with a specific device ID. You can configure for which + device ID Ardour listens. The default of 0 should be safe. </para> </listitem> + </varlistentry> + <varlistentry> + <term>Outbound MMC Device ID</term> <listitem> <para> - <literal>write</literal> - the port is available for output only + Each MMC command includes a device ID. You can configure which + Device ID Ardour uses when it sends MMC commands. The default of + 127 should be safe. </para> </listitem> + </varlistentry> + <varlistentry> + <term>Startup program change</term> <listitem> <para> - <literal>duplex</literal> - the port is available for input and - output + On startup, Ardour sends a Program Change (PC) command. A PC + command includes a program number (a value between 0 and 127). You + can choose which program number is sent by Ardour. A value of -1 + will send 127. The default is 127. </para> + <para> + The PC command is sent on the MIDI port which is configured to handle MIDI + parameter control. It is sent right after you start a session (either a new + one or an existing one). The command is also sent if you choose to load + another session without closing Ardour. + </para> </listitem> - </itemizedlist> + </varlistentry> - <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> + </variablelist> - <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"> @@ -235,9 +273,8 @@ <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. + cables correctly. However, if you use "virtual ports", as Ardour does, + making connections is slightly more involved. </para> <para> @@ -254,46 +291,34 @@ <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 + connection manager. You could also use command line tools such as <application>aconnect</application>. </para> + + <para> + If you use the program <application>qjackctl</application> to + control JACK, there's an easy way to connect Ardour to other MIDI + ports. Run <application>qjackctl</application>, and click on the + <guibutton>Connect</guibutton> button in + the main <application>qjackctl</application> window. This will bring up + the Connection window. Go to the ALSA tab (don't use the MIDI tab!) + and connect the MIDI ports as needed. + </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> + tool such as the excellent <ulink + url="http://www.macmusic.org/software/view.php/lang/en/id/592/">MIDI + Patchbay</ulink> from <!-- (site is currently down) + <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> Index: introduction.xml =================================================================== --- introduction.xml (revision 4410) +++ introduction.xml (working copy) @@ -14,10 +14,8 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="formatting_conventions.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="midi_configuration.xml" /> + href="key_bindings.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="key_bindings.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="user_interface_conventions.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="what_is_different_about_ardour.xml" /> Index: ardour_basics.xml =================================================================== --- ardour_basics.xml (revision 4410) +++ ardour_basics.xml (working copy) @@ -6,11 +6,13 @@ <chapter id="ch-ardour-basics"> <title>Ardour Basics</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="jack.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="midi_configuration.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="sessions.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="sessions.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="jack.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="main_windows.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="editor_window.xml" /> Index: mackie.xml =================================================================== --- mackie.xml (revision 4410) +++ mackie.xml (working copy) @@ -10,9 +10,18 @@ For Ardour 2, this will walk you through the process of configuring and using Mackie MCU, or a BCF2000 in <ulink url="http://www.behringerdownload.de/BCF2000/BCF2000_Emulation_modes.pdf">Logic - Control emulation mode</ulink>. + Control emulation mode</ulink>. </para> + <note> + <title>Note</title> + <para> + MCU support in Ardour is incomplete and setting up an MCU device is + currently a challenging task. + </para> + </note> + + <section id="mackie-connecting-device"> <title>Connecting Device</title> <para> Index: bcf2000.xml =================================================================== --- bcf2000.xml (revision 4410) +++ bcf2000.xml (working copy) @@ -5,251 +5,47 @@ ]> <section id="sn-bcf2000"> - <title>Using a BCF2000</title> + <title>Tutorial: Behringer BCF2000/BCR2000</title> + <para> This will walk you through the process of configuring and using a <ulink url="http://www.behringer.com/BCF2000/index.cfm">Behringer - BCF2000 MIDI control surface</ulink> , or BCF, with Ardour. This should - also work with the + BCF2000 MIDI control surface</ulink> , or BCF, with Ardour. Most of this + should also work with the <ulink url="http://www.behringer.com/BCR2000/index.cfm">BCR2000</ulink>, - but has not been tested. + but has not been tested. The BCF2000 and BCR2000 are able to send/receive + Control Change (CC) MIDI commands, which can be used to control Ardour. MMC + commands are also supported. </para> - <section id="bcf2000-connecting-device"> - <title>Connecting Device</title> - <para> - It's assumed that your USB ports are functional under Linux. The - easiest way to tell if you've got a functional link is to simply - connect the BCF2000 to your computer with a USB cable, connect the - power, and turn it on. You should see the USB MODE light come on in - the upper right corner of the BCF. If that's not on, you'll need to - figure out how to make your <ulink url="http://www.linux-usb.org/">USB - port work under Linux.</ulink> - </para> + <para> + Possibly you want to update the firmware of the BCF2000/BCR2000 first to + eliminate bugs and enable new features. Of course, it should work also + without an update. See <xref linkend="updating-firmware">Firmware + Updating</xref> how to perform an update. + </para> + <section id="setup-bcf2000"> + <title>Setting up the BCF2000/BCR2000</title> <para> - If the USB MODE light is on, doublecheck that Linux knows of the - device. + At first you need to configure a MIDI port in Ardour to handle "MIDI + Parameter Control" and MMC, and you have to connect the BCF2000 to that + port. See <xref linkend="sn-midi-configuration">MIDI Configuration</xref> + how to do that. </para> -<screen> -xtc:~% aconnect -o -client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel] - 0 'M Audio Delta 1010 MIDI' -client 72: 'BCF2000 - Rawmidi 1' [type=kernel] - 0 'BCF2000 MIDI 1 ' -</screen> - </section> - <section id="updating-firmware"> - <title> Firmware Updating (v1.07) </title> <para> - The first thing you're likely to have to do is update the firmware in - the unit. This is a relatively painless process. + Secondly you have to assign controls in Ardour (such as faders and + buttons) to physical controls on the BCF2000. See <xref + linkend="sn-generic-midi-control-surface">Using a Generic MIDI control + surface</xref> how to achieve that. </para> - <orderedlist> - <listitem> - <para> - Download the firmware from Behringers - <ulink url="http://www.behringer.com/05_support/bc_download/bc_downloads.cfm">downloads - page</ulink>. There will be a - <ulink url="http://www.behringer.com/BCF2000/bcf2000_107.zip">zip - file</ulink> available which should be downloaded. (This example - uses version 1.07 of the firmware, the latest available at the - time of this writing. There may be a newer version available now.) - </para> - </listitem> - <listitem> - <para> - Unzip the file you downloaded. You'll typically extract 2 files, a - PDF file with release notes and an SYX file, which is the firmware - update. - </para> - </listitem> - <listitem> - <para> - Find the system device of the BCF - </para> -<screen> -xtc:~% cat /proc/asound/cards -0 [M1010 ]: ICE1712 - M Audio Delta 1010 - M Audio Delta 1010 at 0xdf80, irq -2 [BCF2000 ]: USB-Audio - BCF2000 - BEHRINGER BCF2000 at usb-00:1d.1-2, full speed -</screen> - </listitem> - </orderedlist> - <para> - In this case there are 2 devices. The number at the left indicates the - card number. The BCF is almost certain, then, to use the device - <filename>/dev/snd/midiCnD0</filename> where <emphasis>n</emphasis> is - the card number, in this case, 2. - </para> - <para> - Write the firmware to the BCF with the command - </para> -<screen> -cat bcf2000_1-07.syx > /dev/snd/midiC2D0 -</screen> - <important> - <para> - Make sure you use the actual device you determined in the previous - step - </para> - </important> - - <para> - The BCF display will show a whirling figure-8 animation and count up - to 18. Once the whirling stops, you should turn off the BCF, count to - 5, then turn it on again. You should then see the version number of - the upgraded firmware displayed for a few seconds as the BCF starts. - </para> </section> - <section id="bcf2000-connecting-to-ardour"> - <title> Connecting to Ardour </title> - <para> - After starting Ardour, it's important to connect the MIDI device ports - of Ardour and the BCF together so that they will communicate with each - other. There are a few ways to do this. - </para> - - <section id="bcf2000-connecting-with-qjackctl"> - <title> With qjackctl </title> - <para> - If you use the program <application>qjackctl</application> to - control JACK, there's an easy way to connect Ardour to the BCF. Run - qjackctl, and click on the <guibutton>Connect</guibutton> button in - the main qjackctl window. This will bring up the Connection window. - You should see at least 2 items listed, the BCF and Ardour: - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/con1.jpg"/> - </imageobject> - </mediaobject> - <para> - Connect the BCF output to the Ardour input, and vice versa: - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/con2.jpg"/> - </imageobject> - </mediaobject> - <section id="bcf2000-automating-qjackctl-connection"> - <title> Automating the qjackctl connection </title> - <para> - You can set qjackctl to automatically make the MIDI connections - (and others) by using the Patchbay feature in qjackctl. Start - qjackctl and Ardour, and make the MIDI connections as shown above. - Click on the <guibutton>Patchbay</guibutton> button, then click on - <guibutton>New</guibutton>. Qjackctl will ask if you want to - create a patchbay definition as a snapshot of all actual client - connections. Clicking on <guibutton>Yes</guibutton> will bring in - a set of all ports available. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/qjpatch.jpg"/> - </imageobject> - </mediaobject> - <para> - Make sure you've got both connections as described above, and - click <guibutton>Save...</guibutton> and choose a filename. Once - this is saved, you can close the patchbay. - </para> - - <para> - Next, click on the qjackctl <guibutton>Setup</guibutton> button, - then click on the <guibutton>Options</guibutton> tab. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/qjopts.jpg"/> - </imageobject> - </mediaobject> - <para> - Click on <guibutton>Activate patchbay persistence</guibutton> and - use the filename you used to save the patchbay above. The patchbay - connections will now be made after qjackctl starts up the clients. - </para> - </section> - </section> - - <section id="bcf2000-connecting-from-command-line"> - <title> From the command line </title> - <para> - The command <command>aconnect</command>, which is the ALSA sequencer - connection manager, can do the job of connecting the BCF to Ardour. - First find the numbers of the MIDI device ports for the two: - </para> -<screen> -xtc:~% aconnect -o -client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel] - 0 'M Audio Delta 1010 MIDI' -client 80: 'BCF2000 - Rawmidi 2' [type=kernel] - 0 'BCF2000 MIDI 1 ' -client 129: 'ardour' [type=user] - 0 'seq ' -</screen> - <para> - Here, the BCF is 80, and Ardour is 129. The proper connections can - be made between the two with two commands: - </para> -<screen> -xtc:~% aconnect 80:0 129:0 -xtc:~% aconnect 129:0 80:0 -</screen> - </section> - - <section id="bcf2000-automatic-midi-connection"> - <title> Automating the MIDI connection from the command line </title> - <para> - It's sometimes handy to start Ardour from the command line. I found - it irritating to have Ardour come up, and then have to manually make - the connections for the BCF. This was quickly solved by the - following script, which starts Ardour, finds the proper MIDI device - ports, and connects them: - </para> -<screen> -#!/bin/ksh -# /usr/local/bin/start_ardour.sh -# -# April 17, 2005 - Joe Hartley (jh@brainiac.com) -# A quick script to start Ardour and then make the MIDI connections between -# the BCF2000 and Ardour. - -# start Ardour and give it a little time before setting the MIDI connections -nohup /usr/bin/ardour & -sleep 3 -# Set the IDs - note that they'll both end with a colon -BCF_ID=$(aconnect -o \| grep BCF2000 \| grep client \| awk '{print $2}') -ARD_ID=$(aconnect -o \| grep ardour \| awk '{print $2}') - -aconnect "$BCF_ID"0 "$ARD_ID"0 -aconnect "$ARD_ID"0 "$BCF_ID"0 -</screen> - <para> - As an alternative to the patchbay in qjackctl, you could have it run - this script to start Ardour and make the MIDI connections. Click the - <guibutton>Setup</guibutton> button and choose the - <guibutton>Options</guibutton> tab. Enable the <guibutton>Execute - script after Startup</guibutton> option, and change the line to call - the <filename>start_ardour.sh</filename> script. In this example, I - change directories to the drive I record to so new sessions will - open there by default before I run the script. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/qjopt.jpg"/> - </imageobject> - </mediaobject> - </section> - </section> - - <section id="bcf2000-programming"> - <title> Programming the BCF2000 for effective use </title> + <section id="bcf2000-finetuning"> + <title>Finetuning for BCF2000</title> <para> One problem that I ran into with the BCF2000 was that none of the factory presets really did what I needed to control Ardour. I had a @@ -287,9 +83,16 @@ the mute, solo and rec-enable controls in Ardour to a pushbutton on the BCF. This was because in P2, the buttons sent a Program Change signal, but Ardour expects a Control Change signal. This required - re-programming the BCF a bit. Here's a list of the controls and what I - mapped them to send: + re-programming the BCF a bit. Note that there is a <ulink + url="http://zappa.brainiac.com/preset1.syx">saved + preset file</ulink>, which has the definitions described below. See + <xref linkend="bcf2000-loading-a-preset">Loading a Preset</xref> how to + load it into the BCF2000. </para> + + <para> + Here's a list of the controls and what I mapped them to send: + </para> <itemizedlist> <listitem> @@ -376,8 +179,7 @@ </listitem> <listitem> <para> - Press STORE again to write the settings to an empty preset. If - you want to overwrite an existing preset, press STORE twice. You + Press STORE again to write the settings to an empty preset. You can cancel the store at any time by pressing EXIT. </para> </listitem> @@ -388,113 +190,23 @@ Your BCF2000 is now ready to control Ardour! </para> - <section id="bcf2000-preconfigured-preset-file"> - <title> Preconfigured Preset File </title> - <para> - Here is a <ulink url="http://zappa.brainiac.com/preset1.syx">saved - preset file</ulink>, which has the definitions described above. You - can use <command>amidi</command> to load this into the BCF as - <xref linkend="bcf2000-loading-a-preset"/>. - </para> - </section> </section> - <section id="bcf2000-mapping-ardour-controls"> - <title> Mapping Ardour controls to the BCF2000 </title> - <para> - The final step to control surface Nirvana is to map the controls in - Ardour to the knobs, buttons and faders on the BCF. - </para> + <section id="bcf2000-saving-and-loading-presets"> + <title>Saving and Loading Presets</title> <para> - Before you can map things properly, you'll need to set the MIDI - options within Ardour. In the Editor window of Ardour, choose - <menuchoice> <guimenu>Windows</guimenu> <guisubmenu>Options - Editor</guisubmenu> </menuchoice>. Make sure the seq device is online, - and make sure <guibutton>MTC</guibutton>, <guibutton>MMC</guibutton> - and <guibutton>MIDI Parameter Control</guibutton> is set for the seq - device. Also make sure that the 4 boxes below are checked: + The BCF2000/BCR2000 supports sending the configuration of a Preset to a + MIDI device. Thus, it is possible to store the configuration on a + computer. Of course, it is also possible to load a configuration back + into the BCF2000. There is a <ulink + url="http://zappa.brainiac.com/preset1.syx">saved + preset file</ulink>, which has the definitions described above. See + <xref linkend="bcf2000-loading-a-preset">Loading a Preset</xref> how to + load it into the BCF2000. </para> - <itemizedlist> - <listitem> - <para> - <guibutton>MMC control</guibutton> - </para> - </listitem> - - <listitem> - <para> - <guibutton>MIDI parameter control</guibutton> - </para> - </listitem> - - <listitem> - <para> - <guibutton>Send MMC</guibutton> - </para> - </listitem> - - <listitem> - <para> - <guibutton>Send MIDI parameter feedback</guibutton> - </para> - </listitem> - </itemizedlist> - <mediaobject> - <imageobject> - <imagedata fileref="images/midiopts.jpg"/> - </imageobject> - </mediaobject> <para> - Now you're ready to do the actual mapping. This is a pretty simple - process, all controlled with a <keycombo><keycap>Ctrl</keycap> - <mousebutton>Button2</mousebutton> </keycombo> click. This will pop up - a little window which says <guilabel>operate MIDI controller - now</guilabel>. Simply press the BCF button (or move the slider) that - you want to have control the Ardour function. - </para> - - <section id="bcf2000-example"> - <title>Example</title> - <para> - We want to map the Master fader in Ardour to the first slider on the - BCF. Hold down the <keycap>Ctrl</keycap> key on your keyboard, and - click with <mousebutton>Button2</mousebutton> on the Master fader in - Ardour. You should see the <guilabel>operate MIDI controller - now</guilabel>. Move the first slider on the BCF up or down a bit. - The window should disappear, and you should see the master fader - move up and down as you move the slider on the BCF. If that works, - move the fader in Ardour with your mouse. You should see the slider - on the BCF move up and down in tandem with the Master fader! - </para> - - <para> - If the "operate MIDI controller now" window does not go away, there - is no connection between Ardour and the BCF. Make sure you've - properly connected the two as outlined in the Connecting to Ardour - section. - </para> - </section> - - <section id="bcf2000-transport-controls"> - <title> Transport Controls </title> - <para> - The 4 buttons in the lower right corner are already mapped in Preset - 2 to the MMC transport controls Home (or rewind to the beginning of - the session), Fast Forward, Stop and Play, as shown here. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/transctls.jpg"/> - </imageobject> - </mediaobject> - </section> - </section> - - <section id="bcf2000-saving-and-loading-presets"> - <title> Saving and Loading Presets </title> - <para> After beating my head against a wall trying to get various programs that handle SysEx messages to do what I wanted, I realized that once again, the simplest way for me to do this the first time through is @@ -515,18 +227,18 @@ <para> There's the BCF, at port hw:2 (we can ignore everything after the first number after the colon). We'll tell amidi to use this port with - the -p option + the -p option. </para> <section id="bcf2000-saving-a-preset"> - <title> Saving a Preset </title> + <title>Saving a Preset</title> <para> There's 2 parts to saving a preset: telling the BCF to send the data, and telling the computer to accept it. </para> <section id="bcf2000-recieving-the-data"> - <title> Receiving the Data </title> + <title>Receiving the Data</title> <para> Run <command>amidi</command>, using the <option>-p</option> option to specify the port, and the <option>-r</option> option to receive @@ -544,7 +256,7 @@ </section> <section id="bcf2000-sending-the-data"> - <title> Sending the Data </title> + <title>Sending the Data</title> <para> To send the MIDI data for the current preset to the computer, hold down the Edit key on the BCF and press the Store button. They @@ -552,7 +264,7 @@ <screen> EG </screen> - . This is the Global Edit mode. + This is the Global Edit mode. </para> <para> @@ -566,7 +278,7 @@ <screen> SnGl </screen> - . When ready to send the data, press knob 6. The display on the + When ready to send the data, press knob 6. The display on the BCF will circle around while it's sending data, and return to <screen> EG @@ -591,11 +303,10 @@ </section> <section id="bcf2000-loading-a-preset"> - <title> Loading a Preset </title> + <title>Loading a Preset</title> <para> Loading a .syx file, such as the one saved above, is very simple. - First, select the preset on the BCF to choose the preset to - overwrite. Then call <command>amidi</command> using the + Call <command>amidi</command> using the <option>-s</option> option instead of <option>-r</option> to send a file. </para> @@ -609,8 +320,8 @@ </para> <para> - The preset is now loaded with the settings from the file. They are - only active as long as the preset is not changed. If you go to + The preset is now loaded with the settings from the file, but they are + not yet saved into the preset. If you go to another preset and back to the one you loaded, all the changes will have disappeared. To save the settings, </para> @@ -628,8 +339,7 @@ </listitem> <listitem> <para> - Press STORE again to write the settings to an empty preset. If - you want to overwrite an existing preset, press STORE twice. You + Press STORE again to write the settings to an empty preset. You can cancel the store at any time by pressing EXIT. </para> </listitem> @@ -637,8 +347,10 @@ </section> </section> + <!-- ## Commented out, because I don't know whether it is up-to-date --> + <!-- <section id="bcf2000-bcedit"> - <title> Using BCEdit </title> + <title>Using BCEdit</title> <para> The tool provided by Behringer to manage presets and other things on the BCF is the Java program @@ -664,8 +376,80 @@ be fully usable under Linux yet. </para> </section> -<!-- - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="Some_Subsection.xml" /> - --> + --> + + <section id="updating-firmware"> + <title>Firmware Updating</title> + <para> + Updating the firmware in the unit is a relatively painless process: + </para> + <orderedlist> + <listitem> + <para> + Download the firmware from Behringers + <ulink url="http://www.behringer.com/EN/Support/B-Control-Downloads.aspx">downloads + page</ulink>. There will be a + <ulink url="http://www.behringerdownload.de/B-Control_download/bcf2000_1-10.zip">zip + file</ulink> available for the BCF2000 which should be downloaded. + For the BCR2000, the corresponding file is <ulink + url="http://www.behringerdownload.de/B-Control_download/bcr2000_1-10.zip">here</ulink>. + </para> + <note> + <title>Note</title> + <para> + There may be newer firmware files available than the ones linked + here. + </para> + </note> + + </listitem> + <listitem> + <para> + Unzip the file you downloaded. You'll typically extract 2 files, a + PDF file with release notes and an SYX file, which is the firmware + update. + </para> + </listitem> + <listitem> + <para> + Find the system device of the BCF + </para> +<screen> +xtc:~% cat /proc/asound/cards +0 [M1010 ]: ICE1712 - M Audio Delta 1010 + M Audio Delta 1010 at 0xdf80, irq +2 [BCF2000 ]: USB-Audio - BCF2000 + BEHRINGER BCF2000 at usb-00:1d.1-2, full speed +</screen> + </listitem> + </orderedlist> + <para> + In this case there are 2 devices. The number at the left indicates the + card number. The BCF is almost certain, then, to use the device + <filename>/dev/snd/midiCnD0</filename> where <emphasis>n</emphasis> is + the card number, in this case, 2. + </para> + + <para> + Write the firmware to the BCF with the command + </para> +<screen> +cat bcf2000_1-07.syx > /dev/snd/midiC2D0 +</screen> + <important> + <para> + Make sure you use the actual device you determined in the previous + step. + </para> + </important> + + <para> + The BCF display will show a whirling figure-8 animation and count up + to 18. Once the whirling stops, you should turn off the BCF, count to + 5, then turn it on again. You should then see the version number of + the upgraded firmware displayed for a few seconds as the BCF starts. + </para> + </section> + </section> + Index: frontier_design_tranzport.xml =================================================================== --- frontier_design_tranzport.xml (revision 4410) +++ frontier_design_tranzport.xml (working copy) @@ -11,13 +11,57 @@ <para> Ardour 2.0 can currently use a single Tranzport controller. Ensure that the device is plugged into a functional USB port. On Linux you - will need to <link linkend="sn-configuring-usb-device-access">take - steps</link> to ensure that non-administrative users can access the - device. Note that this feature is <emphasis>not</emphasis> available - in Ardour 0.99.x. + will need to take steps to ensure that non-administrative users can + access the device. Note that this feature is <emphasis>not</emphasis> + available in Ardour 0.99.x. </para> + <!-- TODO: what about MAC? Will it work without further config? --> + <!-- TODO: the following text is out-of-date. These days, one would use + udev, but this must be rewritten by someone who has a tranzport. --> + <important> + <title>Important</title> + <para> + The following instructions are out-of-date and may not work for you. + These days, one would use udev instead of the old-fashion hotplug + system. + </para> + </important> + <para> + First, you need to login as the administrative user ("root"). Then put + the following into a new file called + <filename>/etc/hotplug/usb/tranzport</filename> + </para> +<screen> +#!/bin/sh + +if [ $ACTION = "add" ] && [ -f $DEVICE ] ; then + chmod 0666 $DEVICE +fi +exit 0 +</screen> + <para> + Then make sure that the file is executable by running + </para> +<screen> +chmod +x /etc/hotplug/usb/tranzport +</screen> + <para> + Second, edit the file <filename>/etc/hotplug/usb.usermap</filename> by + adding the following 2 lines to the end of it (make sure that the 2nd + line is not split across multiple lines, even though it is very long): + </para> +<screen> +# Frontier Design Tranzport +tranzport 0x0000 0x165b 0x8101 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +</screen> + <para> + After doing these steps, the next time you plugin your Tranzport it + will be accessible to you as a regular user. + </para> + + <para> In the Options menu, navigate into the Control Surfaces submenu. Click on the "Tranzport" option to enable use of the control surface within Ardour. To disable it, click on this item a second time. ardour2_manual_xml.patch (54,841 bytes)

2009-01-27 22:16	jack.patch (31,150 bytes) Index: jack.xml =================================================================== --- jack.xml (revision 4434) +++ jack.xml (working copy) @@ -10,10 +10,183 @@ Before you can begin to use Ardour, you will need to get the audio input/output capabilities of your system working and properly configured. There are two aspects to this process: getting your audio - interface (soundcard) working, and configuring it to work with the Jack + interface (sound card) working, and configuring it to work with the Jack Audio Connection Kit (<ulink url="http://jackaudio.org/">JACK</ulink>). </para> + <section if="quickstart"> + <title>Quickstart</title> + <para> + To get audio in and out of your Computer, you need to run a piece of + software called JACK, which you can imagine as cables in a real studio. + Fortunately, Ardour can start JACK for you and then communicate with it + to connect to your sound card or to other software. + <orderedlist> + <listitem> + <para> + When starting Ardour, the "Session Control" window is shown and you + are asked to create a session or load an existing one. If JACK is + not running, the tab <guilabel>Audio Setup</guilabel> will appear. + If jack is already running (e.g. if you started it with + <application>qjackctl</application>), the tab will not show up; + skip to point 3 in that case. + </para> + </listitem> + <listitem> + <para> + In the <guilabel>Audio Setup</guilabel> tab you may change the + settings. However, the defaults should be ok. + </para> + </listitem> + <listitem> + <para> + Create a session or open an existing one (as described in <xref + linkend="sn-sessions"/>) and begin using Ardour! If you + encounter problems, e.g. if you are not able to hear something or + to record sound from your sound card, come back to this chapter and + read further. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="getting-audio-working"> + <title>Getting Your Audio Interface Working</title> + <note> + <para> + Although Ardour runs on OS X as well as Linux, this section + describes only a Linux system. The issues faced on OS X tend + to be entirely different. + </para> + </note> + + <para> + Getting your audio interface (sound card) working can be the hardest part + of setting your computer up to run Ardour, or it could be one of the + easiest. The level of difficulty you will face depends on the type of + audio interface ("sound card") you are using, the operating system + version you are using, and your own understanding of how it all works. + </para> + + <para> + In general, your sound card has to be supported by Linux. You can check + the <ulink + url="http://www.alsa-project.org/main/index.php/Matrix:Main">Alsa + soundcard matrix</ulink> for which hardware is supported. Other + hardware may be supported by <ulink + url="http://www.ffado.org/?q=devicesupport/list">FFADO</ulink> which is + a collection of drivers for FireWire connected devices. You can check + whether your sound card works by playing a CD, MP3 or whatever. + Getting the hardware running is not in the scope of the Ardour manual. + </para> + + <section id="selecting-capture-source"> + <title>Selecting Capture Source</title> + <para> + If your soundcard is working, you need to select the correct capture + source. Many audio interfaces, particularly the cheaper varieties that + are often found built into computers, have ways to plug in both + microphones and instruments or other audio equipment to be recorded. + This immediately poses a question: how does Ardour (or any software) + know which signal to record, the one coming into the microphone input, + or the one arriving at the "line in" socket? The same question arises + also for "high-end" audio interfaces, though in different ways. + </para> + + <para> + The short answer is: Ardour doesn’t. Instead, this is a choice you + have to make using a program that understands how to control + the mixing hardware on the audio interface. Linux/ALSA has a number of + such programs: gnome-volume-control, kmix, gamix, aumix and alsamixer + are just a few of them. Each of them offers you a way to select which + of the possible recordable signals will be used for as the "capture + source". They also offer to adjust the level of the capture source + signal. How to select the preferred signal and its level varies from + program to program, so you will have to consult the help documentation + for whichever program you choose to use. + </para> + + <para> + There are also a few programs that offer ways to control just one + particular kind of audio interface. For example, the + <application>hdspmixer</application> program offers control over the + very powerful matrix mixer present on several RME audio interfaces. + <application>envy24ctrl</application> does the same for a number of + interfaces built around the common ice1712/envy24 chipset, found in + devices from M-Audio, Terratec and others. Please note that this is + quite similar to the situation for Windows and MacOS users, where each + audio interface often comes with its own control program that allows + certain critical configuration choices to be made. + </para> + </section> + + <section id="problems-with-input-signal"> + <title>"I don’t get any signal when I record …"</title> + <para> + The most common problem for first-time audio users on Linux is to + try to record something and get no signal at all, or alternatively, + a very low signal. The low signal problem typically arises from one + or more of the following issues: + </para> + + <itemizedlist> + <listitem> + <para> + A microphone is plugged into the "line in" socket of the + interface. The signal levels delivered by microphones are very + small and require amplification before they can be used by most + audio circuitry. In professional recording studios, this is done + using a dedicated box called a "pre-amplifier". If your audio + interface has a "mic input" socket, then it has its own + pre-amplifier built in, although its probably not a very good + one. If you make the mistake of plugging a microphone into the + "line in" socket, you will get either an inaudible or very quiet + signal. + </para> + </listitem> + + <listitem> + <para> + The wrong capture source is selected in the audio interface’s + hardware mixer (see above). + </para> + </listitem> + + <listitem> + <para> + The "capture" gain level in the audio interface’s hardware + mixer is turned down too low. You will need to use a hardware + mixer application (as described above) to increase this. + </para> + </listitem> + </itemizedlist> + + <note> + <para> + Adjusting the faders in Ardour will NOT have any affect on the + hardware mixer. As mentioned above, ardour is dependent on external + mixer settings for a source level. + </para> + </note> + </section> + + <section id="using-multiple-soundcards"> + <title>Can I use multiple sound cards?</title> + <para> + It is no problem with having multiple sound cards built-in into your + computer, but for Ardour (more precisely: for JACK) you have to choose + which one to use. It is not possible to increase the number of hardware + audio channels by combining sound cards, and there are good technical + reasons why this will not be implemented in future. If you need more + channels, save your money for a while and buy yourself a properly + designed multichannel sound card. + </para> + </section> + </section> + + + <section id="sn-jack"> <title>JACK</title> <para> @@ -43,173 +216,319 @@ of sample synchronisation you’d have in a properly configured digital hardware system. This is a problem that has been solved at least a couple of times (ReWire from PropellerHeads and DirectConnect - from Digidesign are the two most common examples), but JACK is a new + from Digidesign are the two most common examples), and JACK is a new design developed as an open source software project, and is thusly - available for anyone to use, learn from, extend, *fix or modify. + available for anyone to use, learn from, extend, fix or modify. </para> + <!-- <para> New users may not initially realize that by using Jack, their computer becomes an extremely flexible and powerful audio tool - especially with Ardour acting as the ’heart’ of the system. </para> - </section> + --> - <section id="getting-audio-working"> - <title>Getting Your Audio Interface Working</title> - <note> - <para> - Although Ardour runs on OS X as well as Linux, this documentation - describes only a Linux (ALSA) system. The issues faced on OS X tend - to be entirely different, and are centered mostly on JACK. There are - also alternative audio device driver families for Linux but they are - also not discussed here. - </para> - </note> - <para> - Getting your audio interface working can be the hardest part of - setting your computer up to run Ardour, or it could be one of the - easiest. The level of difficulty you will face depends on the type of - audio interface ("soundcard") you are using, the operating system - version you are using, and your own understanding of how it all works. + JACK itself does not come with graphical user interface, it runs + entirely in the background and is used by so-called "clients", e.g. by + Ardour. The clients connect to JACK and can then ask which other + clients are present (i.e. connected to JACK) and which inputs and + outputs they have. The clients can then connect to each other, using + JACK. </para> <para> - In an ideal world, your computer already has a working audio - interface, and all you need do is to start up qjackctl and run JACK. - You can determine if you face this ideal situation by doing a few - simple tests on your machine. The most obvious test is whether - you’ve already heard audio coming out of your computer. If you are - in this situation, you can skip ahead to - <xref linkend="selecting-capture-source"/>. + Ardour offers possibilities to connect its inputs and outputs to other + clients (or to its own inputs and outputs) or to the audio hardware, i.e. + your sound card. Another useful software is + <application>qjackctl</application>, which is also a JACK client and + allows to connect other clients to each other, see their actual + connections and even re-connect them automatically next time they are + started. </para> - </section> - <section id="checking-for-an-audio-interface"> - <title>Checking For an Audio Interface</title> <para> - If you’ve never tried to play audio on your computer before, you - should use a basic playback program such as play, aplay or possibly - xmms. Find an audio file on your machine (<command>locate - .wav</command> may help here), and try to play it. There are several - possibilities: + To use JACK it must be started firstly. You can use + <application>qjackctl</application> to start/stop JACK, which is quite + convenient. Another way is using Ardour to start JACK, or you can start + JACK yourself on a console, using the command + <application>jackd</application>, which has no graphical user interface. </para> - <itemizedlist> - <listitem> - <para> - You may get an error from the program - </para> - </listitem> + <section id="control-jack-with-qjackctl"> + <title>Controlling JACK using Qjackctl</title> + <para> + You should be able to start qjackctl from the “application menu” + of your system, typically found on the panel/appbar/dock or whatever + its called that lives at the top/bottom/left/right of your screen. + </para> - <listitem> - <para> - You may hear nothing - </para> - </listitem> + <para> + In the <application>qjackctl</application> window click + <guibutton>Start</guibutton> to start JACK. You can configure the + parameters in the preferences dialog, which you get by clicking + <guibutton>Setup</guibutton>. Most of the settings require restart of + JACK by first clicking <guibutton>Stop</guibutton>, then + <guibutton>Start</guibutton>. + </para> - <listitem> - <para> - You may hear something, but its too quiet - </para> - </listitem> + <para> + You may see and modify the actual connections of the JACK clients in + the "Connections" window. You can show this window by clicking + <guibutton>Connect</guibutton>. Right after starting JACK, no clients + are connected, of course. + </para> - <listitem> + <para> + If you stop JACK, the connections you made in the last session are + lost. The JACK clients may choose to remember them and to reconnect + when JACK is started again. Ardour does not (at least not for all + connections), but you can configure <application>qjackctl</application> + to do so by using the Patchbay feature. + </para> + + <para> + Click on the <guibutton>Patchbay</guibutton> button, then click on + <guibutton>New</guibutton>. Qjackctl will ask if you want to + create a patchbay definition as a snapshot of all actual client + connections. Clicking on <guibutton>Yes</guibutton> will bring in + a set of all ports available. Note that changes which you make here + will not change your actual connections. + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/qjpatch.jpg"/> + </imageobject> + </mediaobject> + + <para> + Make sure you've got the connections you want to be restored in the + future and click <guibutton>Save...</guibutton> and choose a filename. + Once this is saved, you can close the Patchbay. + </para> + + <note> + <title>Note</title> <para> - you may hear something from the wrong loudspeakers. + Changes you make to your connections after saving the Patchbay will + not be in the Patchbay and thus not restored in future. You can + create a new Patchbay file, overwriting the old one. </para> - </listitem> - </itemizedlist> - </section> + </note> - <section id="selecting-capture-source"> - <title>Selecting Capture Source</title> - <para> - Many audio interfaces, particularly the cheaper varieties that are - often found built into computers, have ways to plug in both - microphones and instruments or other audio equipment to be recorded. - This immediately poses a question: how does Ardour (or any software) - know which signal to record, the one coming into the microphone input, - or the one arriving at the "line in" socket? The same question arises - also for "high-end" audio interfaces, though in different ways. - </para> + <para> + Next, click on the qjackctl <guibutton>Setup</guibutton> button, + then click on the <guibutton>Options</guibutton> tab. + </para> - <para> - The short answer is: Ardour doesn’t. Instead, this is a choice you - have to make using a program a program that understands how to control - the mixing hardware on the audio interface. Linux/ALSA has a number of - such programs: alsamixer, gamix, aumix, kmix are just a few of them. - Each of them offers you a way to select which of the possible - recordable signals will be used for as the "capture source". How you - select the preferred signal varies from program to program, so you - will have to consult the help documentation for whichever program you - choose to use. - </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/qjopts.jpg"/> + </imageobject> + </mediaobject> - <para> - There are also a few programs that offer ways to control just one - particular kind of audio interface. For example, the - <application>hdspmixer</application> program offers control over the - very powerful matrix mixer present on several RME audio interface. - <application>envy24ctrl</application> does the same for a number of - interfaces built around the common ice1712/envy24 chipset, found in - devices from M-Audio, Terratec and others. Please note that this quite - similar to the situation for Windows and MacOS users, where each audio - interface often comes with its own control program that allows certain - critical configuration choices to be made. - </para> - - <section id="problems-with-input-signal"> - <title>"I don’t get any signal when I record …"</title> <para> - The most common problem for first-time audio users on Linux is to - try to record something and get no signal at all, or alternatively, - a very low signal. The low signal problem typically arises from one - or more of the following issues: + Click on <guibutton>Activate Patchbay persistence</guibutton> and + use the file name you used to save the Patchbay above. The Patchbay + connections will be loaded when <application>qjackctl</application> + starts the next time. All clients which connect to JACK from then on + (such as Ardour, hydrogen, jamin) will be connected accordingly. </para> - <itemizedlist> - <listitem> - <para> - a microphone input plugged into the "line in" socket of the - interface. The signal levels delivered by microphones are very - small, and require amplification before they can be used by most - audio circuitry. In professional recording studios, this is done - using a dedicated box called a "pre-amplifier". If your audio - interface has a "mic input" socket, then it has its own - pre-amplifier built in, although its probably not a very good - one. If you make the mistake of plugging a microphone into the - "line in" socket, you will get either an inaudible or very quiet - signal. - </para> - </listitem> + </section> - <listitem> - <para> - the wrong capture source selected in the audio interface’s - hardware mixer (see above) - </para> - </listitem> + <section id="start-jack-with-ardour"> + <title>Starting JACK using Ardour</title> + <para> + You can also use Ardour to start JACK. You will get less flexibility + (e.g. no Patchbay), but setup is easier and faster, which is good for + an ad-hoc session. + </para> - <listitem> - <para> - the "capture" gain level in the audio interface’s hardware - mixer is turned down too low. You will need to use a hardware - mixer application (as described above) to increase this. - </para> - </listitem> - </itemizedlist> + <para> + Start Ardour as usual. You will get the "Session Control" window. If + JACK was not started yet, the tab <guilabel>Audio Setup</guilabel> will + be visible. Click on it and make your choices. The defaults should + work for you, but you may choose to change them. Then go to the + <guilabel>New Session</guilabel> or <guilabel>Open Session</guilabel> + tab to begin a session as usual (see <xref linkend="sn-sessions"/> for + details). + </para> <note> + <title>Note</title> <para> - You will notice in the mixer strip for each track in ardour that - you can change the selection of the monitoring source between - input/pre/post. Adjusting the fader while watching the ’input’ - levels will NOT have any affect on the levels. As mentioned above, - ardour is dependent on external mixer settings for a source level. + When Ardour exits, it detects whether other clients (e.g. qjackctl, + jamin) are still connected to JACK and if not, it will stop JACK. + Thus, if you use Ardour as sole JACK client, it will start jack at + the beginning of your session and stop it at the end. </para> </note> + + <para> + The following sections will provide detailed information about the + options found in the <guilabel>Audio Setup</guilabel> tab. + </para> + + <note> + <title>Note</title> + <para> + Not all combination of parameters are meaningful or will even work. + You have to know what you are doing for taking full advantage of all + possibilities. + </para> + </note> + + + <section> + <title>The Device tab</title> + <para> + In the tab <guilabel>Device</guilabel> you may choose the driver and + tweak some basic parameters. + </para> + + + <variablelist> + <varlistentry><term>Driver</term> + <listitem> + <para> + Here you can choose the driver to use. In most cases you will + choose <guilabel>ALSA</guilabel> to connect JACK to your sound + card. If your system uses OSS instead of ALSA, choose + <guilabel>OSS</guilabel>. If you have a FireWire sound card, + try <guilabel>FFADO</guilabel>. The driver + <guilabel>NETJACK</guilabel> connects to a running JACK on + another computer which is reachable by a fast network + connection. This way, it is possible to connect ardour to + applications and sound cards on another computer. The + <guilabel>Dummy</guilabel> driver connects JACK to no hardware, + so only audio data transfer between applications will be + possible. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Interface</term> + <listitem> + <para> + Depending on the chosen driver you can choose the appropriate + Interface here, i.e. which sound card to use. If the field is + not meaningful (e.g. for the Dummy driver) it is disabled. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Sample Rate</term> + <listitem> + <para> + You can choose the appropriate sample rate here. Typical values + are 48000Hz or 441000Hz. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Buffer Size</term> + <listitem> + <para> + This is a technical parameter affecting operation of the sound + card. Smaller values lead to smaller latency, but too small + values lead to bad-sounding artefacts. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Number of buffers</term> + <listitem> + <para> + This is also a technical parameter affecting operation of the + sound card. Smaller values lead to smaller latency, but too + small values lead to bad-sounding artefacts. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Audio Mode</term> + <listitem> + <para> + You can choose whether your sound card can be used to playback + (output sound), record (input sound) or both. If you choose + <guilabel>Playback/Recording on 1 Device</guilabel>, the same + audio device (i.e. sound card "subdevice") is used for both + input and output. If you choose <guilabel>Playback/Recording on + 2 Devices</guilabel>, different audio devices can be used for + input and output. The devices can be chosen in the + <guilabel>Advanced</guilabel> tab, but must be part of the same + interface (sound card). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>The Options tab</title> + <para> + In the tab <guilabel>Options</guilabel> you have additional control + about how JACK runs. These options are specific to JACK and will + therefore not be documented here. For further information see the + manpage of <application>jackd</application> (open a terminal/console + and type <literal>man jackd</literal>, then press enter). + </para> + </section> + + <section> + <title>The Advanced tab</title> + <para> + In the <guilabel>Advanced</guilabel> tab you have advanced control + about your sound card configuration. + </para> + + <variablelist> + <varlistentry><term>Input device</term> + <listitem> + <para> + Here you can choose which device you want to use to get sound + into your computer. The function of this field depends on the + chosen driver and Audio Mode. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Output device</term> + <listitem> + <para> + Here you can choose which device you want to use to get sound out + from your computer. The function of this field depends on the + chosen driver and Audio Mode. + </para> + </listitem> + </varlistentry> + <varlistentry><term>Input channels</term> + <listitem> + <para> + TBD + </para> + </listitem> + </varlistentry> + <varlistentry><term>Output channels</term> + <listitem> + <para> + TBD + </para> + </listitem> + </varlistentry> + <varlistentry><term>Hardware input latency</term> + <listitem> + <para> + TBD + </para> + </listitem> + </varlistentry> + <varlistentry><term>Hardware output latency</term> + <listitem> + <para> + TBD + </para> + </listitem> + </varlistentry> + </variablelist> + </section> </section> </section> @@ -217,11 +536,11 @@ <title>Monitoring Choices</title> <para> Its unfortunate that we have to raise this issue at a point in the - manual where you, the reader, may not even knoiw what "monitoring" + manual where you, the reader, may not even know what "monitoring" means. However, it is such an absolutely critical aspect of using any digital audio workstation that we need to at least cover the basics here. The only people who don’t need to care about monitoring are - those who will never use ardour to record a live performance (even on + those who will never use ardour to record a live performance (even performed using a software synthesizer). </para> @@ -237,7 +556,7 @@ amp+loudspeakers? It can get a lot more complex than that: if you are recording multiple performers at the same time, each performer needs to hear their own playing/singing, but they also probably need to hear - some of their colleagues’ sound as well. You might be overdubbing + some of their colleagues’ sound as well. Or you might be overdubbing yourself - playing a new line on an instrument while listening to tracks you’ve already recorded - how do you hear the new material as well as the existing stuff? @@ -250,41 +569,7 @@ </para> </section> - <section id="using-multiple-soundcards"> - <title>Can I use multiple soundcards</title> - <para> - There are really lots of great reasons why you should not even attempt - to do this. But seriously, save your money for a while and buy - yourself a properly designed multichannel soundcard. - </para> - </section> - <section id="qjackctl"> - <title>Qjackctl</title> - <para> - JACK itself does not come with graphical user interface - to start - JACK and control it you need to have access to a command line and a - basic knowledge of Unix-like operating systems. However, - <ulink url="http://qjackctl.sourceforge.net/">qjackctl</ulink> is a - wonderful application that wraps JACK up with a graphical interface - that is both nice to look at and useful at same time. qjackctl is the - recommended way of using JACK. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/qjackctl.png"/> - </imageobject> - </mediaobject> - <para> - You should be able to start qjackctl from the “application menu” - of your system, typically found on the panel/appbar/dock or whatever - its called that lives at the top/bottom/left/right of your screen. - </para> - - <para> - [ need screenshot of GNOME/KDE/OSX menus here ] - </para> - </section> <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Some_Subsection.xml" /> jack.patch (31,150 bytes)

tanjeff 2009-01-27 22:18 reporter ~0005645	I added yet another patch (jack.patch). This affects the file manual/xml/jack.xml. I reworked the Chapter "Getting Audio In, Out and Around Your Computer". The HTML version of the manual (including all patches attached to this issue) can be seen here: http://www.cccmz.de/~tanjeff/ardour_manual/ch-ardour-basics.html#sn-configuring-jack

seablade 2009-01-27 23:28 manager ~0005646	Thanks for posting the HTML verison, it saves me time with the patching to take a look at it. For the moment I am going to give comments as I come to them, and am starting with your most recent patch first compared to what is currently on Ardour's site... My first comment is that either the manual goes to far or not far enough. This is evidenced by the quickstart section you have in your version. It doesn't quite fit with the rest of the section, setting up Jack, etc. Personally I think a decision needs to be made on how much detail we would like to go into with the manual. If we want to discuss setting up the audio we should do so in its own section, as it is completely unrelated to Ardour itself. We should also discuss the various methods that are known to work as of this time, and give enough detail for the average person to be able to get audio to and from Jack on any OS. This means basics of setting up ALSA, setting up FreeBob/FFADO, or CoreAudio. Another option, and probably the more fitting is going to be discuss setting up Jack, and ignore the various backend options. This means cover proper permissions if needed(aka on Linux) as well as Jack options that are commonly modified(Periods/Buffers/etc.) And the final option is to assume all those are correct and not cover them at all, dealing strictly with Ardour. I think that this decision would need to be made before to much work is done on that section in particular. Seablade

tanjeff 2009-01-28 20:51 reporter ~0005676	I had basically two problems while working on the manual (not only in the Audio Setup section). The first one is that I didn't know the intended audience, the second is where to make the cut between Ardour-related and unrelated stuff. So, who is the target audience? Should we really explain that a microphone needs amplification and will therefore not work on a line-in? I would assume that the reader has already used an analogue mixer and has basic knowledge of (at least analogue) audio routing. Can we expect the Ardour user to use a terminal and figure out which /dev/* file her tranzport device uses? I would assume that the user doesn't normally use terminals, so making MIDI connections in qjackctl is the most we can expect from her to make MIDI data available to Ardour. Secondly, which stuff is Ardour-related? Jack-specific backend options are not. But on the other hand, Ardour provides controls for them, so we should at least explain what they are and give a hint where to find information about them. The part where Ardour interfaces its world is a bit special in that way, because even if something is not in Ardour's scope, it might be necessary to get its features working (e.g. MIDI controls). So I would propose to describe things in a general form, leaving the documentation of details to the corresponding projects. Now to your comments, which are related to my latest patch. Firstly, the Quickstart section ought not to be a lack of detail, but a shortcut to get Ardour running quickly. I introduced it because of the section's size. Secondly, I agree with you that we should include all possible ways to get Ardour running, on all supported platforms. Unfortunately, I have not MacOS so I can't say anything about it, so someone else has to complete the section accordingly. At last, concerning the level of detail, I propose (as described above) that we describe the context in which Ardour is used, in a general form. In particular, we should document that JACK is needed, describing how to start it using Ardour (pointing the user to the JACK project for details about the backend options) and that the user might prefer using qjackctl. We should remove the sections about how starting JACK with qjackctl and how to use qjackctls Patchbay feature. If you like, I can rewrite the section according to my proposals as a preview. Simply let me know.

tanjeff 2009-02-01 12:16 reporter ~0005684	Here is a first shot of how I would write the "Getting Audio In, Out and Around Your Computer" chapter. It contains (nearly) no detailed information about jack or qjackctl, as this is not in the scope of Ardour. http://www.cccmz.de/~tanjeff/ch-ardour-basics.html

Headwar 2017-05-17 07:50 reporter ~0019713	Outdated and unusable as the links are dead. In any case, the manual has changed a lot since, and the patch wouldn't be usable.

Date Modified	Username	Field	Change
2009-01-15 20:11	tanjeff	New Issue
2009-01-15 20:11	tanjeff	File Added: ardour2_manual_xml.patch
2009-01-27 22:16	tanjeff	File Added: jack.patch
2009-01-27 22:18	tanjeff	Note Added: 0005645
2009-01-27 23:28	seablade	Note Added: 0005646
2009-01-28 01:32	seablade	Status	new => acknowledged
2009-01-28 20:51	tanjeff	Note Added: 0005676
2009-02-01 12:16	tanjeff	Note Added: 0005684
2010-05-02 11:59	cth103	Relationship added	related to 0002469
2010-05-02 11:59	cth103	Relationship deleted	related to 0002469
2017-05-17 07:50	Headwar	Note Added: 0019713
2017-05-17 07:50	Headwar	Status	acknowledged => closed
2017-05-17 07:50	Headwar	Resolution	open => fixed