ardour/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Ardour is a professional digital audio workstation (DAW) for Linux, macOS, and Windows. It supports multi-track audio and MIDI recording, editing, mixing, and mastering with support for various plugin formats (LV2, VST2, VST3, AU).

Official website: https://ardour.org/ Development guide: https://ardour.org/development.html

Build System

Ardour uses Waf (Python-based build system). All build commands use python3 ./waf.

Essential Build Commands

# Set PKG_CONFIG_PATH for Homebrew/custom library paths (if needed)
export PKG_CONFIG_PATH="/home/linuxbrew/.linuxbrew/lib/pkgconfig:/home/linuxbrew/.linuxbrew/share/pkgconfig:/usr/lib/pkgconfig"

# Configure the build
python3 ./waf configure

# Build with parallel jobs
python3 ./waf build -j4

# Install (optional)
python3 ./waf install

# Clean build
python3 ./waf clean

# Complete clean (removes configuration)
python3 ./waf distclean

Build Options

# Configure with optimizations
python3 ./waf configure --optimize

# Build with debugging symbols
python3 ./waf configure --debug-symbols

# Build with tests
python3 ./waf configure --test

# Run tests after build
python3 ./waf configure --run-tests

# Build specific backends (JACK, ALSA, PulseAudio, etc.)
python3 ./waf configure --with-backends=jack,alsa,dummy

# Build without VST support
python3 ./waf configure --no-lxvst --no-vst3

# Force C++17 mode
python3 ./waf configure --cxx17

Build Outputs

• Main executable: build/gtk2_ardour/ardour-<VERSION>
• Libraries: build/libs/*/
• Built-in LV2 plugins: build/libs/plugins/*/

Running Tests

Individual library tests can be found in libs/*/test/ directories:

# Build tests
python3 ./waf configure --test
python3 ./waf build

# Run evoral tests (example)
cd libs/evoral
./run-tests.sh

# Set up environment for test data
export EVORAL_TEST_PATH="libs/evoral/test/testdata"
export LD_LIBRARY_PATH="build/libs/evoral:build/libs/pbd:$LD_LIBRARY_PATH"

Architecture Overview

Core Architecture Layers

Ardour is structured as a layered system with clear separation between the audio engine, session management, and UI:

1. Audio Engine Layer (libs/ardour/)

   • Session management (libs/ardour/ardour/session.h)
   • Audio/MIDI routing and processing
   • Real-time audio graph execution
   • Plugin hosting (LV2, VST2, VST3, AU)
   • Export/import functionality

2. Low-Level Libraries

   • libs/pbd/ - Portable Build Dependencies (threading, signals, file utilities)
   • libs/temporal/ - Time and tempo handling (beats, bars, superclock)
   • libs/evoral/ - Event-based MIDI sequencing and control automation
   • libs/audiographer/ - Audio processing graph for export/analysis

3. Backend Layer (libs/backends/)

   • Audio backend abstractions: JACK, ALSA, PulseAudio, CoreAudio, PortAudio, Dummy
   • Each backend implements the AudioBackend interface

4. UI Layer (gtk2_ardour/)

   • GTK2-based UI (despite the name, uses GTK3+ in modern versions)
   • Canvas rendering system (libs/canvas/)
   • Custom widgets (libs/widgets/, libs/gtkmm2ext/)
   • Waveform rendering (libs/waveview/)

5. Control Surfaces (libs/surfaces/)

   • Hardware controller support: Mackie Control, Faderport, Push2, OSC, etc.
   • Generic MIDI control
   • WebSocket interface for remote control

6. Plugin System

   • Built-in plugins in libs/plugins/ (a-comp, a-delay, a-eq, etc.)
   • Plugin discovery and scanning (libs/auscan/ for AU)
   • VST support (libs/fst/, libs/vst3/)

Key Concepts

• Session: The top-level container for a project. Manages routes, sources, regions, playlists, and the processing graph.
• Route: Abstract base for tracks and busses. Handles signal flow, processors, and automation.
• Region: A section of audio or MIDI data with position and length.
• Processor: Audio/MIDI processing element (plugins, sends, inserts).
• Temporal: Ardour uses multiple time domains (audio samples, musical beats, wall-clock time). The libs/temporal/ library handles conversions.

Signal Flow

AudioBackend → AudioEngine → Session → Routes → Processors → BufferSet

Audio flows through:

1. Backend captures audio from hardware
2. AudioEngine distributes to session
3. Session routes through the processing graph
4. Each Route processes through its processor chain
5. Output buffers are sent back to the backend

Thread Model

• Process thread: Real-time audio processing (JACK process callback or equivalent)
• Butler thread: Disk I/O operations (reading/writing audio files)
• GUI thread: User interface updates (GTK main loop)
• Background threads: File scanning, analysis, exports

Communication between threads uses lock-free structures and message queues to maintain real-time safety.

Lua Scripting

Ardour has extensive Lua scripting support for automation and extending functionality.

• Scripts location: share/scripts/
• Documentation: https://manual.ardour.org/lua-scripting/
• Interactive scripting console: Window > Scripting in the UI

Script naming conventions:

• _*.lua - Example scripts (not installed)
• __*.lua - Excluded from unit tests
• s_*.lua - Code snippets for interactive use
• _-*.lua - Ignored by git (local dev scripts)

Development Environment

Running from Build Directory

Use the ardev wrapper scripts to run Ardour from the build directory without installing:

# Linux
./gtk2_ardour/ardev

# Set up environment variables manually (if needed)
source gtk2_ardour/ardev_common.sh

The ardev script sets up:

• ARDOUR_SURFACES_PATH - Control surface modules
• ARDOUR_BACKEND_PATH - Audio backend modules
• ARDOUR_DATA_PATH - UI themes, icons, templates
• ARDOUR_MIDI_PATCH_PATH - MIDI instrument definitions

Debugging

# Build with debug symbols
python3 ./waf configure --debug-symbols

# Run with gdb
gdb --args ./build/gtk2_ardour/ardour-<VERSION>

# Enable Ardour debug flags (set before running)
export ARDOUR_DEBUG="all"  # or specific flags like "AudioEngine,Processor"

Session Utilities

Command-line tools for batch processing sessions (in session_utils/):

# Example utilities
./build/session_utils/new_session       # Create new session from command line
./build/session_utils/copy-mixer        # Copy mixer settings
./build/session_utils/export            # Batch export

Important Files and Directories

• wscript - Main build configuration
• libs/ardour/ - Core audio engine
• gtk2_ardour/ - Main UI implementation
• libs/backends/ - Audio backend implementations
• libs/surfaces/ - Control surface support
• libs/plugins/ - Built-in audio plugins (LV2 format)
• share/ - Runtime data (templates, scripts, themes)
• tools/ - Development and packaging utilities

Coding Patterns

Memory Management

• Modern C++ with extensive use of std::shared_ptr and smart pointers
• RCU (Read-Copy-Update) pattern for lock-free data structures (pbd/rcu.h)
• Real-time safe allocators for audio thread (pbd/reallocpool.h or pbd/tlsf.h)

Signal/Slot System

Uses pbd/signals.h (not Boost.Signals) for decoupled communication between components.

State Management

Most objects inherit from PBD::Stateful for serialization to XML. Session state is saved in .ardour XML files.

Common Development Workflows

Adding a New Built-in Plugin

1. Create plugin directory in libs/plugins/
2. Implement LV2 plugin interface
3. Add to libs/plugins/wscript
4. Rebuild: python3 ./waf build

Modifying the UI

1. UI code is in gtk2_ardour/
2. Canvas rendering uses libs/canvas/
3. Custom widgets in libs/widgets/
4. Themes are in gtk2_ardour/themes/

Working with Sessions

1. Session code in libs/ardour/session*.cc
2. Session state format defined by XML serialization
3. Use session_utils/ tools for batch operations

Platform-Specific Notes

Linux

• Primary development platform
• Requires JACK, ALSA, or PulseAudio
• Package dependencies: see https://ardour.org/development.html

macOS

• Requires macOS 10.13+
• Uses CoreAudio backend
• AU (Audio Units) plugin support

Windows

• MinGW cross-compilation or MSVC
• ASIO support via PortAudio backend

Git Workflow

• Main branch: master
• Requires full git clone (uses git describe for versioning)
• GitHub release tarballs are NOT supported - clone the repository

Important Notes

• Ardour version is maintained via git tags
• The build depends on git describe output for version information
• Pre-commit hooks may modify files (auto-formatting, version updates)
• When committing, always check for hook-modified files before finalizing