The Ardour FAQ
December 5, 2002

--Problems--
1.1.  I downloaded the binary and...
1.2.  Why no tarballs?
1.3.  Why can't I get configure to run when ...
1.4.  I'm getting syntax errors during build.
1.5.  I get segfaults running Ardour on Redhat 7.0.
1.6.  I get the warning: "Gtk-WARNING **: Unable to locate image file in 
1.7.  What's an xrun?
1.8.  The region area overlaps the buttons in the editor.
1.9.  Ardour keeps freezing.  Here's the strace...
1.10  Why is "ardour" a shell script?
1.11  How do I debug this thing?

--Features--
2.1.  Are plugins supported?
2.2.  Are VST plugins supported?
2.3.  Does Ardour run on non-Linux systems?
2.4.  Ardour needs to have this feature now.
2.5.  Why doesn't Ardour support MP3s?
2.6.  Does Ardour support MIDI?
2.7.  What soundfile formats are supported?
2.8.  Can I use multiple cards?
2.9.  How do I save captures across partitions?

--Usability--
3.1.  What do the selection colors mean?
3.2.  How do I use select mode?
3.3.  How do I use move mode?
3.4.  How do I split a region?
3.5.  What are those blue and red lines in the editor?
3.6.  How do I add a soundfile?
3.7.  How do a pan stereo outputs?
3.8.  How do I set up a loop?
3.9.  How does zoom mouse mode work?
3.10. How do I punch in?
3.11. How do I use auto punch?
3.12. Where's the patch bay?

--Misc--
4.1.  What's the deal with JACK, LAAGA, and Audioengine?
4.2.  Is Ardour internationalized?
4.3.  How do I get support?
4.4.  Well, where's the manual?
4.5.  Why are all these libraries included? I already have ...

--------------------------------------------------------------------------------

--Problems--
1.1.  I downloaded the binary and...

Stop.  There are no binaries.  The only releases are source releases.  Some
people have made RPMs and DEBs of Ardour, and this was nice of them.  But,
at this point in Ardour's development, anything older than the latest source
release is pointless.

1.2   Why no tarballs?

a) Because at this point in its development, I don't want to deal with
   bug reports from a version that's more than 3 hours old.  I am not
   going to build and upload tarballs every 3 hours.  Ardour sometimes
   changes dramatically internally several times in a day.  CVS lets
   people easily, quickly, cheaply get the latest changes and build a
   completely up-to-date version.

b) To try to discourage people without sufficient programming skill from
   trying to compile it.  I don't have the time to provide hand holding
   for the build process.  Compiling Ardour can be very difficult,
   although it's getting better all the time.  When I feel it's likely that
   most people will be able to compile the source without much
   difficulty, I'll start releasing tarballs again.

1.3.  Why can't I get configure to run when ...

You can only run configure at the top level of the Ardour source
tree.  You don't want to know why this is true.  Don't try to work
around it.

1.4.  I'm getting syntax errors during build.

This probably means that you are using an out of date library.  Or you
might be using a very new library that has changed its API.  Check the
version number.  If it is lower than what is listed on the README, update
your library.  If it is higher than what is listed on the README, email
the mailing list.  Note that you have to be a member of the mailing list
to send mail to it, which is done to prevent the list from receiving
much spam.

1.5.  I get segfaults running Ardour on Redhat 7.0.

Redhat has seen fit to release a preview version of the gcc C++ compiler
with their distribution - gcc-2.96.x.  This version is widely known to
cause problems for the C++ language which is more sensitive to compiler
changes than the C language.  Paul recommends gcc-2.95.2 which is
absolutely known to compile Ardour. Other people are working on support
for gcc-3.x but not all the dependencies (eg. gtk++) support this version 
yet. 

Another related problem is the use of "packages" where the compiler
used to build the "package" (where "compiler" includes command line
arguments given the actual compiler) differ from the one used to build
Ardour.  It is a good idea to compile each library Ardour depends on
from source, if only to be sure that this is not the source of any
problems you run into.

1.6. I get the warning: "Gtk-WARNING **: Unable to locate image file in 
	pixmap_path: "set-next-button.xpm"

The most common cause of this error is simply that you have not set 
the pixmap pathname correctly.  It can be specified in the Ardour 
config file. See the README file.

1.7. What's an xrun?

It's a generic term used to describe a situation where the software
did not keep up with the hardware, either by feeding it data, or by
collecting data from it.  It generally means that you're having
trouble with latency.  This can be caused by several factors.  You
could have a misconfigured system, you might be trying to do to much,
or both.

If you're haven't read http://www.linuxdj.com/audio/lad/resourceslatency.php3,
then your system is probably misconfigured.

If you are running many many tracks, with multiple LADSPA plugins, then it
is possible that your system just can't keep up with what you want to do.
Either simplify your music, or upgrade your machine.  A dual processor does
wonders.

You can test your setup with the latencytest tool, available at
http://www.linuxdj.com .

1.8.  The region area overlaps the buttons in the editor.

Make sure that you are using the appropriate font size for your monitor's
resolution.  If you are running at 1024x768 or below, you should use the
75dpi package, not the 100dpi.  This is usually set in /etc/X11/XF86Config.

1.9.  Ardour keeps freezing.  Here's the strace...

The results from strace aren't very useful.  To provide helpful information 
to the developers, run Ardour under gdb. If you don't know how to use
gdb, this isn't the time to learn. If you do know how to use gdb, read
section 1.11.

1.10  Why is "ardour" a shell script?

To speed up the process of developing Ardour, we do not statically
link Ardour and its library, libardour. Instead, we use dynamic
linking, which allows the developers to avoid the (very) long
relinking step when they make certain kinds of changes to libardour. 

This means that the executable image for Ardour relies on the system
being able to find libardour whenever you start it. Rather than leave
this to chance and/or the whims of your system adminstrator (probably
yourself), we instead use a short shell script to make sure that the
connection between the two of them can be established. 

This has almost zero impact on any aspect of Ardour's operation. The
only noticeable effect is that it makes debugging slightly more
difficult. See 1.11 for more on this.

1.11  How do I debug this thing?

A) How to start gdb ....

The first and most basic thing you need to know is how to invoke
gdb. Because of the dynamic linking between Ardour and its library you
can't just invoke Ardour and get it to work. Besides, "ardour" itself
is a shell script (see 1.10 for more on this). So, what you need to do
is to invoke gdb with LD_LIBRARY_PATH set to point to the place where
libardour is installed, and use the name of actual executable image.

If you installed in the default location, this command will invoke gdb
correctly: 

  env LD_LIBRARY_PATH=/usr/local/lib/ardour gdb /usr/local/lib/ardour/ardourx

If you used a --prefix argument during the build process so that
Ardour would be installed somewhere other than under /usr/local, then 
replace /usr/local in the command above with whatever "prefix" you
used.

You could easily make the above a shell alias or a 1 line shell script
if you think you'll be debugging Ardour with gdb a lot.

B) What to do with gdb

When Ardour has crashed or is "stuck", issue the following command 
to gdb (you will need to use Ctrl-C if its "stuck" to get back to the
gdb command prompt):

   thread apply all bt
        
then send the entire output to ardour-dev, and we'll be
able to get the most out of your misfortune.

--Features--
2.1.  Are plugins supported?

LADSPA plugins are supported.  To use them, click the middle mouse
button in the top box at the top of the mixerstrip you wish to have a
plugin for.  This opens up a window which lists all the plugins.  Double
click on the one you wish to use.  In the mixer window, click on the
plugin to toggle it on and off, option-click to edit its values, or
shift-click to remove it.

2.2.  Are VST plugins supported?

There are several issues here:

1) Generic VST support

   This is possible, but is also tricky.  Steinberg does not allow
   redistribution of their header files, and the header files that
   they distribute will not work under Linux.  It would therefore be
   impossible to compile Ardour with VST support unless you got
   modified files from (say) me, and that would violate the license
   agreement Steinberg has for VST.  They have indicated that they are
   not opposed to Linux support, but that's the end of the story right
   now.
 
   If we end up distributing binary copies of Ardour, this could
   be dealt with (I compile it, and so you don't need the modified
   header files).  But that's not happening yet.

2) Specific plugins

   a) executable format issues

   Plugins are pieces of executable code.  The format used for
   the files that store this code is different under windows
   and macos than it is for linux.  Some people have managed
   to find workarounds for this --- there are reports of people
   running windows-derived buzz plugins under linux, but nobody
   has looked into trying it with vst plugins.

   Linux also runs on a lot more hardware than windows or MacOS.  
   We assume that when you say linux, you mean "linux on an intel
   compatible processor", but keep in mind that to most of us, 
   linux means more than that --- it includes the PPC, Sparc, Alpha,
   ARM, MIPS and many other chip architectures.  Of that list,
   only PPC has any VST plugin support at all.

   This problem would go away if a VST plugin was available as source
   code, but to my knowledge, only 1 is (freeverb).

   b) OS dependency issues

   Most VST plugin writers do not follow Steinberg's design advice,
   and write plugins that have operating system dependencies.  As
   a result, even if you could find a way to actually use, say, 
   a windows-format VST plugin on Linux on an Intel machine, the
   plugin would contain calls to operating system services that
   don't exist (in the same way) under Linux.

So, the basic answer is "no".  I am an active member of the VST-plugins
mailing list, and I try to encourage people who write free plugins to
make their source code available so that we can use it under Linux, as
well as reminding people to try to avoid operating system dependencies
in their plugins.  I think this mostly falls on deaf ears.

2.3.  Does Ardour run on non-Linux systems?

Ardour depends on the JACK system to access the sound hardware.  I do
not believe that JACK has been ported to non-linux systems.  If it
was, Ardour should be able to run on that platform.  Also, Ardour has
abstracted the JACK dependency, so it can be ported to use another
sound library.  But at the time, it only uses the JACK library, which
only runs on Linux.  The JACK website is http://jackit.sf.net/.

2.4.  Ardour needs to have this feature now.

Paul accepts donations through his paypal account.  The feature will 
(probably) be added more quickly if you pay him.  Contact him first.  

2.5.  Why doesn't Ardour support MP3s?

Ardour is meant for serious audio work.  MP3 is a lossy format
unsuitable for this.  Ardour does export sessions to wav format, which
is trivial to convert to MP3.

2.6.  Does Ardour support MIDI?

Ardour currently supports MIDI in the sense of:

 * functioning as a MIDI Timecode master (it generates MTC)
 * functioning as a MIDI Timecode slave (experimental; send reports!)
 * understanding MIDI Machine Control
 * allowing the user to bind GUI controls (sliders, etc.) to
     MIDI Continuous Controller and NoteOn/NoteOff messages

It does not offer any facilities for editing or arranging or recording
or playing MIDI data.  There has been talk of integrating Midi
Mountain, an excellent midi editor.  There hasn't been any progress in
this direction lately, mostly due to other areas that need to be fixed
up.  It's not a trivial affair if the integration is going to proceed
in a way leaves the result feeling "natural".

2.7.  What soundfile formats are supported?

It depends on what version of libsndfile is installed.  This link lists the
latest formats: http://www.zip.com.au/~erikd/libsndfile/#Capabilities

Please note that Ardour requires the 1.x series of libsndfile.

2.8.  Can I use multiple cards?

In a word: maybe.

The sync issues that arise even between the same make and model of a card 
aren't worth the effort of fixing.  If you want to have more than two 
channels, buy a professional card.

On the other hand, if you already have two professional cards with word-sync,
you might be able to get them to work.  This is several layers removed from
Ardour; the proper place to ask for help is at http://www.alsa-project.org .

There is more information at http://www.linuxdj.com/audio/quality/#multi

2.9.  How do I save captures across partitions?

Ardour lets you specify multiple directories to save captured audio in.  In
the options editor, in the session path box, specify the full paths of the
directories you wish to use, seperated by commas.  These can be on different
partitions or even different disks.  Using this "software RAID"-like setup
can greatly increase your disk bandwidth.

--Usability--
3.1.  What do the selection colors mean?

This is relevant for the region list, mixerstrips, plugins, and
groups.  Blue is on and orange is off.  But you can change the colors
in the Ardour UI RC file, named in the Ardour config file.  It's a
standard GTK+ RC file, and the file should be fairly self-documenting
if you know anything about GTK+ (and perhaps even if you don't, though
you need to understand colors as RGB values).

3.2.  How do I use select mode?

      - dbl-click positions edit cursor
      - click selects a region (view)  <==== MAY CHANGE
      - click-drag defines selection
      - ctrl-click click aligns region start to edit cursor
      - ctrl-meta click aligns region end to edit cursor
      - clrl-shift click aligns region sync point to edit cursor

Note that the key bindings can be remapped so that a different key
than meta can be used instead.

3.3.  How do I use move mode?

      - dbl-click positions playhead cursor
      - click selects a region (view)
      - click-drag moves a region
      - shift-click drags a region with fixed time position
      - alt-click copies and drags a region
      - alt-shift-click copies and drags a region with fixed time position
      - ctrl-click click aligns region start to selected region start
      - ctrl-meta  click aligns region end to selected region start
      - clrl-shift click aligns region sync point to selected region

Note that the key bindings can be remapped so that different keys can
be used.  This is helpful if your keyboard does not have a meta or alt key.

3.4.  How do I split a region?

 1) Either: 
   a) Click on the edit cursor button in the toolbar, then
      Click on the arranger where you want to do the split
  *or*
   b) Drag the (blue) edit cursor to the desired split location

 2) Either:
   a) Use button 3 to click on the region to split.  A context-sensitive
      menu will appear.  Select "Split Region"
   *or*
   b) Use control-s (temporary binding, I suspect)

Some combination of the above methods might work as well.

3.5.  What are those blue and red lines in the editor?

The red line represents the playhead.
The blue line is the edit point.

3.6.  How do I add a soundfile?

In the track that you want to add the file to, do a right button click.
Then go to the edit menu, then to the "insert external sndfile".  From
there you'll get a box that wants a pathname.  Write that, then click add
directory.  You'll get a listing of all the sndfiles in that directory.
Aiff files should be included.  If it isn't, then try converting it to a
wav file with sox.

3.7.  How do I pan stereo outputs?

Panning works over JACK ports.  So even if you have two outputs
connected to one port, Ardour doesn't consider this to be stereo.  You
need to make sure that you have two ports, and then add one (or more)
destination to each port.

You need to think of the ports as if they were physical sockets to
which you can connect as many plugs as you want. A single port means
mono, even though you can send the signal to many different
places. Two ports means stereo, even though the right and left signals
can each go to any number of different places.

3.8.  How do I set up a loop?

Looping uses "locations" to define the loop points. Some quick
instructions:

1) Click on Windows->Locations. The locations window pops up.
2) Click on the SET NEXT button in the locations window
     (then click on the new listed location; this is a bug workaround
      and won't be necessary in the future)
3) go to the start of the session (Home, or the transport button)
4) Click on the "Start set" button in the locations window
5) go the end of the session (End, or the transport button)
6) Click on the "End set" button in the locations window
7) Click in the "Loop" column 
8) Click on the loop button in the transport controls
9) Go back the start, or anywhere inside the loop, and start rolling

(optional)
10)  to adjust the length of the loop:

       a) Use the fwd/backward buttons in the Locations window 
       b) drag the location marker points in the markers strip above
            the editor

     You can change the loop length in real time while its playing,
     but if you ever allow the cursor to go "out" of the loop,
     the looping will stop. For example, if you shift the end point
     back towards the start as the playhead crosses it, the looping
     will stop.

     Click, Shift-Click, Ctrl-Click and Shift-Ctrl-Click give
     progressively finer steps on the fwd/backward buttons, all the
     way down to a single frame.

3.9.  How does zoom mouse mode work?

      button1 click: zoom in
      button2 click: zoom out
      ctrl-button2: zoom to display entire session (subject
                     to current power-of-2 zoom restriction)
 
      button click+drag: select area, then zoom to display it,
                          also subject to current power-of-2
                          zoom restriction.     

3.10. How do I punch in?

Engage the dynamic punch button in the transport controls.  Rec-enable
the transport.  Press play (or do whatever you do to start the
transport rolling.  Click on the rec-enable button of the relevant
diskstream in the recorder window to punch in, and again to punch out.

3.11. How do I use auto punch?

Create a location.  The simplest way to do this is to put the mouse
into select mode, select the desired section, then right-click in the
track display, and in the "Select" submenu, choose "Create location
from selection".

Popup the location window (Alt-l or the "Windows" menu).  Click in the
"punch" column.  You have just chosen this location to be used for
autopunch.  You can adjust the start/end either from this window, or by
dragging the markers that appear in the editor's ruler area.

Engage the autopunch button on the transport controls.  Engage
rec-enable on the desired diskstreams.  Rec-enable the transport.  Start
rolling.  Ardour should now punch in and out at the start and end of
the location on all rec-enabled tracks.

3.12.  Where's the patch bay?

There is no separate dedicated patch bay. Patch bay functionality
is integral to the mixer. The mixer can have any number of inputs,
any number of busses, etc. In other words, it *is* the patchbay.

--Misc--
4.1.  What's the deal with JACK?

JACK is the Jack Audio Connection Kit.  There is a basic problem with
audio+MIDI apps on Linux at this time: they are not able to exchange
data with each other in situations where low latency is a system goal.
There are systems (aRts, MidiShare, parts of alsa-lib) that allow data
sharing, but not when the latencies get down below 20ms.

JACK is an API that solves this problem.  Also, and quite importantly,
JACK drastically simplifies the programming of audio applications.
Applications that use JACK do not need to know anything about audio
hardware.  They do not interact with it directly in any way
whatsoever.  All they do is provide a few callbacks to the server they
connect with; the primary callback is responsible for producing and/or
consuming a specified amount of data whenever it is called.  This is a
'callback' model, and is extremely different from ALSA, OSS, and
several other audio APIs.  It is, however, very similar to Apple's
CoreAudio, Steinberg's ASIO, the PortAudio library, and most plugin
APIs. See http://jackit.sf.net/

4.2.  Is Ardour internationalized?

Parts of Ardour are.  Work is ongoing to fully internationlize Ardour.  If
you speak a language besides English, feel free to volunteer to help
translate.

4.3.  How do I get support?

Ardour is a volunteer project.  There is no one devoted to providing
support.  However, there is a members only mailing list where someone
might answer your question.  You can join at Ardour's website: 

		  http://ardour.sf.net/

Alternatively, you can pay Paul for specific support.  Check with him
for hourly rates.

4.4.  Well, where's the manual?

Currently, the existing documentation is sparse.  You might want to check out
the Protools reference; Ardour is rather similar to it.  Also, Paul wants
users to be able to complete the Mackie HDR tutorial using Ardour; so that
is another manual to check out.  Both are available online from
<a href=http://digidesign.com/support/documents.html>DigiDesign</a> and <a
href=http://mackie.com>Mackie</a>.

There is the begining of a manual in Ardour's manual directory.  Feel
free to create your own HOWTOs, tips and tricks sheets, tutorials, or
whatever you feel like adding.

A couple people have written some documentation to get people started with
Ardour.  It is available at http://www.boosthardware.com/LAU/ardour/

4.5.  Why are all these libraries included? I already have ...

Yes, we know that it's quite likely that you already have gtkmm or
sigc++ installed on your machine, let alone libxml2 and others.  There
are 2 problems. 

Ardour requires either the latest version of these libraries or even a
version with a patch that has not yet been incorporated into a release
of the library.  Rather than require you to get the library source,
patch it, recompile and install it, Ardour keeps its own copy, builds
a static, private version of the library and links against it.  That
way, we don't have to worry about crashes caused by you having the
wrong version of the library. 

The second problem is more general.  C++ does not yet have a unified
"Application Binary Interface", even on a single process
architecture+OS combination.  This is unlikely to ever change (it was
encouraged by the inventor of C++).  This means that libraries compiled
with one compiler are not always compatible with applications compiled
with another compiler.  By "another compiler", we can mean something as
subtle as a different version of g++.  Worse, because many C++
libraries feature inlined code, we even need to be sure you compile
against exactly the same version of the library as other parts of
Ardour will use.  Even worse, there are compile time flags you or
someone else could give to a C++ compiler that would make the library
incompatible in subtle ways with code compiled with different flags.

After a year of trying to address these problems "the normal way", the
Ardour team gave up and decided to include every necessary library
that is written in C++ and/or has patches required.  You may not like
this very much, but trust us, you would like the alternative even
less.

