ardour Documentation

Mirror of Ardour Source Code

5,350 stars C++ C++ 1 file · ~3,330 tokens #audio#c-plus-plus#daw#jack#lv2#midi#vst
RAW Doc

Technical Documentation: Ardour/ardour

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

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/

    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

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

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

  1. callgrind_control -i on

[do operations in Ardour that should be profiled]

  1. callgrind_control -i off

  2. quit ardour

  3. run kcachegrind calgringd.out.

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

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

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#audio Browse audio catalog → #c-plus-plus Browse c-plus-plus catalog → #daw Browse daw catalog → #jack Browse jack catalog → #lv2 Browse lv2 catalog → #midi Browse midi catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →