Overview and Source Tree Layout

Welcome to the in-code documentation for Ardour.

The main components of Ardour are as follows:

• A GTK2 front-end, in gtk2_ardour.
• libardour, the audio-processing back-end, in libs/ardour.

The source tree is laid out as follows:

Front Ends

• gtk2_ardour/

  The main Ardour GUI – This is where most of the complexity is. It is cleanly separated from the backend and processing engine.

• headless/

  hardour – headless Ardour, mostly demo-code how to use Ardour without a GUI.

• session_utils/

  command-line tools using libardour (e.g. export)

• luasession/

  arlua – fully fledged commandline interface to libardour

Libraries

A collection of libraries and utility functions. Most are shared libraries, and almost all are exclusive to Ardour. A few specific libraries are compiled statically (e.g. fluidsynth for use in plugins).

Ardour specific libs

• libs/pbd/

  Generic utility classes. This is used the basis for all Ardour specific libraries. It provides basic concepts and OS abstractions.

  The name comes from "Paul Barton-Davis", Paul's full name at the time he started working on working on audio software.

• libs/evoral/

  Evoral is Ardour's event Library, used for control events, control lists, automation evaluation, parameter interpolation, parameter descriptions, incl. MIDI event abstraction.

  • libs/evoral/libsmf/ (contains several non-upstreamed fixes)

    Handling Standard MIDI File (Evoral::SMF) format. Abstracted to C++ in SMF.{cc,h}

• libs/backends/

  Interaction with Operating System's Audio/MIDI API: ALSA, CoreAudio, JACK, PortAudio/ASIO, PulseAudio

  see ARDOUR::AudioBackend

• libs/surfaces/

  Control Surfaces, dynamically loaded by libardour on runtime, to remote-control ardour (midi bindings, network etc).

  see ARDOUR::ControlProtocol

• libs/midi++2/

  MIDI parsing, MIDNAM handling, Port abstraction for I/O

• libs/temporal/

  Various utility code for dealing with different kinds of time, including Timecode, and musical time conversions (Temporal::Beats, Temporal::BBT_Time).

  This library also provides the fundamental time types, and the TempoMap. See https://ardour.org/representing-time.html for more information.

• libs/panners/

  Pan plugins (stereo-balance, VBAP, etc) are dynamically loaded at runtime.

  see ARDOUR::Panner

• libs/audiographer/

  Mini Ardour inside Ardour to export audio-files from sessions.

  It is a combination of AudioGrapher::Source and AudioGrapher::Sink classes that are chained together by ARDOUR::ExportGraphBuilder as shown in the ASCII art Export Graph.

• libs/ardour/

  This is it. libardour runs Ardour sessions.

  All realtime processing happens here, plugins are managed etc.

  Some starting points are ARDOUR::Route ARDOUR::Session ARDOUR::Processor

UI related libs

• libs/gtkmm2ext/

  Utility Library to extend GDK, GTK, and basic abstraction for UIs and event-loops. This library is not limited to the GUI, but also used for other graphical interfaces (e.g. Push2, NI Maschine control surfaces).

• libs/canvas/

  Cairo Canvas, provides a slate for scalable drawing and basic layout/packing This is used by Ardour's main editor.

  See ArdourCanvas::GtkCanvas and ArdourCanvas::Item

• libs/widgets/

  Ardour GUI widgets (buttons, fader, knobs, etc). They are basically all CairoWidgets

• libs/waveview/

  Threaded waveform rendering and waveform image cache.

• libs/tk/

  A localized version of GTK+2, renamed as YTK. See Gtk namespace for relevant documentation.

  • libs/tk/ydk libs/tk/ytk

    gdk, gtk based on upstream gtk+ 2.24.23

  • libs/tk/ydk-pixbuf

    stripped down version of gdk-pixbuf 2.31.1

  • libs/tk/ydkmm , libs/tk/ytkmm

    gdkmm, gtkmm based on upstream gtkmm 2.45.3

  • libs/tk/ztk

    atk 2.14.0

  • libs/tk/ztkmm

    atkmm 2.22.7

  • libs/tk/suil

    A local copy of https://github.com/lv2/suil/ (based on 0.10.8). Since GTK2 is in our source tree, we also need to provide various plugin UI wrappers (x11_in_gtk2, win_in_gtk2, suil_cocoa_in_gtk2).

Plugin Scan Tools

By default plugins are scanned by a dedicated external process. If that crashes the main application is not affected, and the plugin that causes the scanner to crash can be blacklisted.

For practical and historical reasons the actual scanner code lives inside libardour.

• libs/auscan/

  Apple Audio Unit Plugin Scan commandline tool.

• libs/fst/

  VST2/3 plugin scan commandline tools.

• libs/vfork/

  A exec-wrapper which redirects file-descriptors to be used with vfork(2). It is used to launch external applications, without impacting real-time constraints of the calling process.

Ardour Community Effect (ACE) Plugins

• libs/plugins/

  A bread and butter set of LV2 Plugins included with Ardour.

  Many of them are custom version of existing plugins (zamaudio, x42), that have been customized to be bundled with Ardour on all platforms that ardour runs on.

Independent, standalone libs

These are 3rd party libs that have been copied into Ardour's source-tree.

• libs/aaf/

  Unmodified https://github.com/agfline/LibAAF for importing AAF sessions.

  Use tools/update_libaaf.sh to update from upstream.

• libs/appleutility/

  Utility classes, abstraction for CoreAudio and AudioUnits (OSX, macOS)

• libs/ardouralsautil/

  Utility class for device-listing (used by the JACK and ALSA backends). Device-reservation commandline tool (linked against libdbus), which is also available from https://github.com/x42/alsa_request_device

• libs/clearlooks-newer/

  GTK theme engine (used by gtk2_ardour)

• libs/fluidsynth/

  Stripped down (library only) and slightly customized version of fluidsynth.

  Use tools/update_fluidsynth.sh to update from upstream.

• libs/hidapi/

  Unmodified https://github.com/signal11/hidapi for interaction with some control surfaces (Push2, NI Maschine)

• libs/libltc/

  Unmodified https://github.com/x42/libltc/ for Linear Timecode en/decoding. see LTCFrame.

• libs/lua/

  Lua Script interpreter and C++ class abstraction

  • libs/lua/lua-5.3.5 is unmodified upstream Lua-5.3.5
  • libs/lua/LuaBridge is a highly customized version of https://github.com/vinniefalco/LuaBridge (C++ bindings)

• libs/ptformat/

  Unmodified https://github.com/zamaudio/ptformat for loading ProTools sessions.

• libs/qm-dsp/

  Stripped down version of https://github.com/c4dm/qm-dsp The Queen Mary DSP library is used by VAMP Plugins.

• vamp-plugins

  VAMP plugins for audio analysis and offline processing (uses qm-dsp)

• libs/vamp-pyin/

  VAMP plugins for pitch and note-tracking (uses qm-dsp), offline analysis

• libs/vst3/

  Stripped down version of Steinberg's VST3 SDK https://github.com/steinbergmedia/vst3sdk/ use tools/update_vst3.sh to update from upstream

• libs/zita-convolver/

  A convolution kernel, so far only available to Lua scripts.

• libs/zita-resampler/

  Efficient resampler with variable rate, useful for adaptive resampling. Mainly used for vari-speed playback. This has been customized for multiple mono channel processing (ArdourZita::VMResampler), and optimized to skip processing for a ratio of 1:1.

Resource Files

These are platform independent files, and bundled as-is.

• share/export/

  Export Format and Presets (see https://manual.ardour.org/exporting/edit-export-format-profile/)

• share/mcp/

  Mackie control surface device files (see https://manual.ardour.org/using-control-surfaces/devices-using-mackielogic-control-protocol/)

• share/midi_maps/

  Generic MIDI control surface presets

• share/osc/

  TouchOSC layouts for use with Ardour's OSC control surface.

• share/patchfiles/

  MIDNAM files, MIDI synth descriptions (note-names, CC, PGM names)

• share/scripts/

  Lua scripts (files with a leading underscore are not bundled). see share/scripts/README for file name convention.

• share/templates/

  Session templates (currently none)

Miscellaneous

• doc/

  Misc developer oriented documentation files and Doxygen

• patches/

  Some .diff files for the build-stack.

• tools/

  Various developer tools, most notably packaging scripts