Information for first-time OS X users

Please read EVERYTHING on this page before proceeding to use Ardour. Every single sentence here contains vitally important information. If you skip any part of it, and the actions implied, Ardour may fail to start, may crash after starting, or may fail in other ways.

Clear out old stuff

Even though this page says that it is for new users, you may have used an older version of Ardour (e.g. the X11 version) on your system. If you have ever used Ardour on your system before, you should:

1. Remove the folder named .ardour2 and all its contents from your home folder.
2. If you have installed the LADSPA VST Bridge plugin, remove it. It will cause the Ardour OS X native version to crash on startup.
3. SAE version only If you have used a very new version of JACK (newer than 0.112) since the last startup, you will need to reboot.

System Update

You must have applied all system updates. Apple released a newer version of a software library used by Ardour (libcurl), and without the new one, Ardour will not run. If you want to check, see if you have libcurl1.4 installed. Otherwise, just do the update. Please don't report crashes of Ardour without making sure you've done this step.

Right Click!

Ardour has been written with the assumption that you have (at least) a 2 button mouse available. There is a lot of useful functionality built into context menus that appear when you right-click on most objects.

If you are using an Apple laptop that appears to have only a single button, you should use Apple icon -> System Preferences -> Keyboard & Mouse ->Trackpad to set the touchpad into "two-finger tap = right click" mode. Then you can get access to the context menus and more by just tapping with two fingers instead of one.

Note that you will find Ardour (and other digital audio workstations) even easier to use if you spend a little money on a full 3 button USB mouse with a mousewheel. They are cheap, easy to use and will all work with your MacBook.

Background: lots of people think that ctrl-click is always the way to get right-click operation on OS X. Its not. This is simply a per-application convention that many apps (but not all) have used. ctrl-click does not send the program something that looks like a right-click, it sends it a normal click with the additional information that the ctrl key is pressed. Some apps have used this as the signal to do some of the same things that right-click is associated with. Ardour has its own independent uses for ctrl-click, so we require to you configure your system to send a genuine right-click in order to see context menus and more.

Cmd-Scroll action

On a related note, you may also want to visit the System Preferences dialog, and choose Keyboard/Mouse to disable the default mapping of cmd-Scroll. OS X ships with this bound to "zoom screen", which might be useful for some users, but probably not audio-focused ones. Ardour uses cmd-Scroll for zooming itself, and you may find it very useful to have this available.

Making sure you have a duplex audio device (INTEL USERS ONLY)

Until very recently, every Mac came with an audio interface that was preconfigured to do playback and recording at the same time. With the introduction of Intel-based Macs, and Tiger (OS X 10.4), Apple changed all that, for reasons that remain unclear. The builtin audio device on Macs using Intel processors no longer comes configured to do playback and capture at the same time. This odd decision by Apple has not affected many (or even most) 3rd party audio interfaces - most professional and prosumer devices come ready to be used for both purposes at the same time. However, some cheaper consumer devices have also ended up with playback or capture support, but not both at the same time.

Luckily, you can change this.

You must perform these steps as a user with administrative priviledges. The first thing to do is to open up Applications -> Utilities -> Audio/MIDI Setup. Go to the main menu bar, click on Audio and then select Open aggregate device editor. Follow the simple instructions to add the builtin playback and capture devices to your new aggregate device. You will need a name for the new device: "Builtin" is as good as any, but the choice is not important. You're done, and ready to use JACK.

The rest of this document applies to Intel and PPC systems

You need to know JACK

This section does NOT apply to users of the SAE version, which comes with JACK as part of the package.

Although we do plan to make Ardour available without the need for any additional downloads, this release continues to require that you have JACK (the JACK Audio Connection Kit) installed on your system (you might be wondering just what on earth JACK is). The simplest way to do this is to visit the JackOSX website and install the package from there. Make sure you have version 0.76 of JackOSX or newer. Ardour will start but crash if you have an older version. If you are using JACK without JackOSX, you need at least version 0.109.2, or the same situation will occur.

Note that you are not required to have JACK running when you start Ardour. Later, if you need access to the kinds of control that applications like JackPilot (part of JackOSX) offer, you can choose to have it running before starting Ardour. In general, this only matters if you want to connect other CoreAudio applications to Ardour.

The Basics

You should have been able to download the .zip file, and should have ended up with the striking red Ardour logo on your desktop. Clicking on that icon should start up Ardour, but ...

Slow Startup

The very first time you run Ardour, it will take roughly 2 to 3 times as long to get started on a session as it will subsequently. This is because the user interface code has to build a catalog of the system fonts, something which only happens once. Ardour will post a warning message about this, but we want to warn you ahead of time about this alarming delay.

If you have a lot AU plugins, Ardour will also do a 1-time scan of them to determine some basic information about each one. This can take a while, but will not happen again unless you update a plugin.

Plugins

This release of Ardour includes 117 LADSPA plugins (the SAE version contains a stripped down set of just 8 or so recommended plugins). You will also be able to use the 20 or so default AudioUnit plugins supplied by Apple, along with any other AU plugins that you may have installed.

It doesn't work!

Please see our page on how to report a bug. BUT before you do, please keep the following two extra pieces of information in mind:

• If you are having problems starting Ardour, is a good idea to open the Console (Applications -> Utilities -> Console). That way, error output and other information from startup will be visible.
• Always enable the system Crash Logger. This way you can collect useful information if Ardour is crashing. We will want to see that information in any bug report you might file.

Finally, please do come and talk to us on our IRC channel. You may be used to online forums as a place to get help, but in our world, we prefer to do things in real time rather than go back and forth on a very delayed communication channel. It is harder for us to support our OS X users because they generally do not build Ardour from source, but we can still talk you through many common problems in a few minutes online. This is preferable for us, and we think its probably better for you too.

Known Issues

The full list of bugs is always available, but these are a few that tend to hit new OS X users early and often.

• AU plugin settings are not saved
• MP3 and AAC audio files cannot be imported and will cause a crash if attempted
• Automation with certain AU plugins (particularly Apple's own) tends to cause a lot of clicking/noise.
• Invalid fontconfig cache contents: if you get a crash on startup and the Console window contains information about a missing Pango font, you should remove the directory $HOME/.fontconfig and restart Ardour. The font cache will be rebuilt (slowly!) and things will work again.

Other things you might want

An alternative GUI for JACK

To configure JACK, you can either use Ardour itself, or JackPilot, which comes with the JackOSX package, or QJackCtl. Each has it owns benefits and disadvantages. A recent release of QJackCtl for Intel Leopard (or Tiger) and JackOSX ≥ 0.77 is QJackCtl-0.3.2-intel.dmg. An older Universal release of QJackCtl for Intel and PPC macs with Tiger or Leopard is available here: QJackCtl-0.2.22.dmg. Please read the included README carefully for initial setup instructions, it is very important.