fix potential crash-causing coding errors when removing regionviews from the selection

[ardour.git] / DOCUMENTATION / FAQ

The Ardour FAQ
January 23, 2004

--Problems--
1.1.  Why can't I get configure to run when ...
1.2.  I'm getting syntax errors during build.
1.3.  I get the warning: "Gtk-WARNING **: Unable to locate image file in 
1.4.  What's an xrun?
1.5.  The region area overlaps the buttons in the editor.
1.6.  Ardour keeps freezing.  Here's the strace...
1.7.  What is "ardev" and why is it a shell script?
1.8.  How do I debug this thing?
1.9.  I want Ardour to run faster.

--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.  How do I pan stereo outputs?
3.2.  Where's the patch bay?
3.3.  How do I do stuff?

--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 ...
4.6.  Why not another frontend to libardour?  Why not QT?

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

--Problems--
1.1.  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.2.  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 in the BUILD file, 
update your library.  If it is higher than what is listed in the BUILD file, 
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.3.  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 BUILD file.

1.4.  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 .

Jan Depner's HOWTO is loaded with latency tuning tips for Ardour:
http://myweb.cableone.net/eviltwin69/ALSA_JACK_ARDOUR.html

1.5.  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.6.  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.8.

1.7.  What is "ardev" and why is it a shell script?

This is only applicable if configure was run with --enable-development-build.

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.8 for more on this.

1.8.  How do I debug this thing?

+-------------------------------------------------------------------------+
| NOTE: Newer versions of gdb and/or glibc and/or the kernel have broken
| gdb in a critical way that make it impossible to run ardour. The gdb
| development group claim to have fixed this, but on many
| distributions, the version that is provided is still broken.
|
| Under such circumstances, you will have to get a core dump from
| ardour, and then use gdb to analyse the core dump, rather than 
| using gdb as a "live tool". 
|
| Many distributions set the default core dump size to 0, to prevent
| core dumps completely. So the first step is to do enter this
| at your shell prompt (in a terminal window):
| 
|    ulimit -c 9999999999
|
| Then run ardour in whatever way causes a crash. after the crash
| you should find a file called "core" in your working directory.
| then run:
|
|    gdb ardour core
| 
| When the gdb> prompt appears, type
|
|    backtrace
|
| Collect the output, and file it as an attachment to a Mantis
| bug report at http://ardour.org/mantis
|
| Thanks for helping to improve Ardour.
+------------------------------------------------------------------------+

A) How to start gdb ....

A1) IF YOU DID NOT USE --enable-development-build

You can use gdb the usual way:

    % cd /where/you/built/ardour
    % gdb ardour


A2) IF YOU USE --enable-development-build

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.

A3) ABOUT LADSPA PLUGINS AND GDB

Moving all your LADSPA plugins out of the way will make gdb very much
quicker to start. For example, if you normally keep them in
/usr/local/lib/ladspa, you could do something like:

     mkdir /usr/local/lib/LADSPA
     mv /usr/local/lib/ladpsa/* /usr/local/lib/LADSPA
     
gdb doesn't do very well when forced to handle dozens of dynamically
loaded objects, as typically happens with LADSPA plugins.

It might be easier to redefine LADSPA_PATH to a dummy path.

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
        
collect the output from this, and then go to 

        http://ardour.org/mantis 

and file a new bug report with the output attached.  This will allow
us to get the most out of your misfortune. 

If you compiled ardour from source and want to be even more helpful,
recompile it after running

         ./configure --disable-optimize

at the top level. This will make the debugging output more useful.

1.9.  I want Ardour to run faster.

The --enable-optimize flag is enabled by default which turns
on compiler features that can make Ardour run up to 50% faster.  
If you downloaded Ardour as a binary package, it should have been
compiled with that flag already.  

--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

   Many people have asked about VST support within Ardour. Work has been
   done on this, but there are both license issues and technical
   ones. The licensing issues seem relatively easy to resolve.

   On the technical front, given that the goal is to not require VST
   developers to build new native Linux versions of their plugins, the
   most promising approach involves using Wine to support native
   Windows VST plugins. It is already possible to run most VST plugins as
   JACK clients and thus use them as inserts with Ardour, but the process
   of doing so is not what most users would term "convenient".  

   However, Wine cannot currently be used within a complex
   multithreaded application. The Wine development team are working on
   this, and as a rough guess, I'd expect progress within about 6 months
   (i.e end of 2003). At that time, it will be possible to use most VST
   plugins that have their own GUI ("editor") from within Ardour.

   However, initially, this functionality will be available only as
   part of a for-cost distribution of Ardour. 

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.  Jack
has (as of this writing) support for Linux, Solaris, and MacOSX.  There
have not been any reports of running Ardour on any platforms besides Linux
though.

In addition, 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.  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.mega-nerd.com/libsndfile/#Features

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 colons (:).
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.  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.2.  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.

3.3.  How do I do stuff?

Region Dragging (object mode)
-----------------------------

   click-drag => moves region
   shift-click-drag => moves region with time position held constant
                          (i.e. across tracks)
   ctl-click-drag => moves a copy of the region
   ctl-shift-click-drag => time-constrained movement of a copy of the
                            region
   snapmod-click-drag  => ignores current snap setting

Region Alignment (clicks without motion)
----------------

 [ all alignment uses:
       
       1) current region selection, if it exists
       2) else the edit cursor
 ]

   ctl-click => aligns start of region 
   ctl-shift-click => aligns end of region
   ctl-alt-click => aligns sync point of region

Marks
-----

        click in tempo track to create a new tempo mark         
        click in meter track to create a new meter mark
        click in marker track to create a new marker
        regular edit op for tempo/meter allows editing
        regular delete op for all markers (except initial
           tempo/meter markers)
        snapmod-click-drag to move a marker while ignoring
           current snap mode       

Editing
-------
 
 default is ctl-button3 click
 

Deletion
--------

 default is shift-button3 click

Context Menu
------------
 
 button3 click

Snap Modifier
-------------

  default is mod3 (typically meta/windows/start key). using
  ctl or shift or alt will cause problems. you can also
  use combinations, but again, combinations using ctl and shift
  will cause problems. mod3 or mod4 are probably your best
  choices.

Selection (RANGE MODE required)
---------

   click on a region => make a region selection
   shift-click on a region => add region to region selection
   click-drag => make a range selection
   shift-click-drag => add to range selection
   ctrl-click-drag => move selection

Separation 
----------
  
   in range mode:

      a) make a single range selection

   then, to split existing region apart

      b) right click => Selection => Separate region

    OR, to creates a new region without splitting original

      b) switch to object mode
      c) click on selection and drag


solo/mute/rec-enable
--------------------

    to toggle solo/mute/RE for EVERYTHING:
     
          ctl-shift-click on a solo/mute/RE button

    to solo/mute/RE mix group (when group is not active)
    
          ctl-click on solo/mute button

    to toggle solo-safe status (which appears to not work
         correctly right now)

         shift-click on solo button
   
    to momentarily engage solo while pressing a mouse button

         use button2 instead of button1


gain sliders
------------

    shift-click to reset to 0dB
    ctl-click-drag for finer scale
    ctl-alt-click-drag for even finer scale
    
panners
-------

    (stereo): shift-click to reset to center

--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.

These languages have translations:

gtk-ardour:
French, German, Italian, Portuguese, Brazilian Portuguese, and Russian

libardour:
Italian

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.org/

There is also the IRC #ardour channel on the FreeNode network.

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.djcj.org/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 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.

4.6.  Why not another frontend to libardour?  Why not QT?

The GTK+ frontend to libardour is almost 7 times the size of libardour.  GUIs
for these sort of programs are very large and detail orientated.  It would be
a waste of time to try to reimplement Ardour with another widget set.  This is 
also why there won't be a native port of Ardour to MacOS X.