# Technical Documentation: Ardour/ardour

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Ardour/ardour)

### Doc Mainpage (`doc/mainpage.md`)

# 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/`</dt>

  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](https://github.com/Ardour/ardour/blob/56647acc25aa91ccf920e5ac21452bccf35b78e7/libs/ardour/export_graph_builder.cc#L73-L154).

* `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 CairoWidget%s

* `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](https://hexler.net/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

---

### Doc Region Ops (`doc/region_ops.txt`)

How to choose what regions to perform operations on
---------------------------------------------------

Divide region actions into 3 groups:

1. Actions that operate on the selection, and for which the edit point type and location is irrelevant.
e.g. remove-region, rename-region, boost-region-gain

2. Actions that are not related to the selection, but for which the edit point location is important
e.g. insert-region-from-region-list

3. Actions that operate on the selection, and for which the edit point location is important
e.g. set-region-sync-position, place-transient


For group 1, Editor::get_regions_from_selection_and_entered() is used to decide which regions to operate
on.  This method returns the selected regions, unless there are none, in which case it returns the last
region that the mouse entered.

For group 3, Editor::get_regions_from_selection_and_edit_point() is used to decide which regions to operate
on.

If the edit point is `mouse':
     if the mouse is over a selected region, or no region, this method returns all selected regions.
     if the mouse is over an unselected region, just that region is returned.

For other edit points the method returns the selected regions. If no regions are selected, it returns 
the regions under the edit position on the selected tracks.

The action handlers call the appropriate method to decide which regions to operate on.

In addition, Editor::sensitize_the_right_region_actions() is called when a Region menu is about to be displayed,
and it sensitizes the actions that are appropriate given the current situation.  When selecting things from
a menu, group 3 operations are disabled if the edit point is `mouse', as the mouse will be positioned over
the menu and its position is hence meaningless.

---

### Doc Unit Tests (`doc/unit_tests.txt`)

Running unit tests
------------------

This is slightly neater if you have doc/waft on your path.

1.  Pass --test to waf configure
2.  cd libs/ardour
3.  waft --targets=libardour-tests && ./run-tests.sh

The "--targets=libardour-tests" is optional, but it avoids a
rebuild of the whole gtk2_ardour (which isn't necessary for
running the tests).

---

### Doc Updating Waf (`doc/updating_waf.txt`)

# Download waf (https://waf.io/)
#
# autowaf.py and misc.py are present in the tools directory of the Ardour source code.
# - waf-str.patch is needed for py2/py3 compatible install_dir:
#  * in py2 paths are byte-arrays and would need to be converted using .encode("utf-8")
#    (otherwise waf expands them /t/o/p/a/t/h/s/l/i/k/e/t/h/i/s)
#  * however py3 cannot handled encoded arrays:
#    (TypeError: cannot use a string pattern on a bytes-like object)
#
# Current waf is build as follows:

ARDOURSRC=`pwd`
cd /tmp
curl https://waf.io/waf-2.0.26.tar.bz2 | tar xj
cd waf-2.0.26

patch -p1 < $ARDOURSRC/tools/patches/waf-str.patch

./waf-light -v --make-waf --tools=misc,doxygen,clang_compilation_database,$ARDOURSRC/tools/autowaf.py,$ARDOURSRC/tools/misc.py --prelude=''
cp ./waf $ARDOURSRC/waf

---

### Doc Using Callgrind (`doc/using_callgrind.txt`)

Profiling Ardour with Callgrind
===============================

Prerequisites
-------------

*  valgrind version 3.7.0 or later (current 3.9.0)
*  kcachegrind 0.6 or later (current: 0.7.4)


Basic Profiling
---------------

1.  Compile ardour with debug symbols [1].
2.  `cd gtk2_ardour`
3.  start ardour using `./arcall`

Load a session, ideally use the 'Dummy' (non realtime) backend.

The `arcall` script does not start profiling immediately,
to start profiling, in a second terminal run

4. `callgrind_control -i on`

[do operations in Ardour that should be profiled]

5. `callgrind_control -i off`

6. quit ardour

7. run  `kcachegrind calgringd.out.<PID>`

NB. There will be multiple files calgringd.out.<PID>-<Thread-ID> for every run,
only load the main file without the dash into

8. clean-up: `rm calgringd.out.*`


Advanced Usage
--------------

Edit gtk2_ardour/arcall, add/remove options as needed.
see http://valgrind.org/docs/manual/cl-manual.html for further information.

---

[1] ideally an optimized built with debug-symbols (-g) is used for profiling,
however the ardour wscript does not yet offer that configuration option.
However, a default (non optimized build) does contain debug-symbols.

---

--- METRICS ---
- Files Extracted: 5
- Estimated Token Budget: ~3253 tokens
- Canonical Reference: https://codewiki.google/github.com/Ardour/ardour