smokephil/ardour
1
0
Fork 0
mirror of https://github.com/Ardour/ardour.git synced 2025-12-06 06:44:57 +01:00
Code Issues Projects Releases Wiki Activity

Merge 7d9c3822d3 into 0f3760a8d1

Browse source
This commit is contained in:
Aaron Brewbaker 2025-12-05 13:26:29 +09:00 • committed by GitHub
commit 100c7eb204
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 1672 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

21
.mcp.json Normal file
View file

@ -0,0 +1,21 @@
{
"mcpServers": {
"ardour": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/home/beengud/raibid-labs/ardour-mcp",
"run",
"ardour-mcp"
]
},
"midi-gen": {
"type": "stdio",
"command": "node",
"args": [
"/home/beengud/raibid-labs/ardour-mcp/mcp-servers/midi-mcp-server/build/index.js"
]
}
}
}

290
CLAUDE.md Normal file
View file

@ -0,0 +1,290 @@
# 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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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/`):
```bash
# 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

175
doc/OSC-MCP-README.md Normal file
View file

@ -0,0 +1,175 @@
# Ardour OSC & MCP Quick Start
This directory contains documentation for using Ardour with OSC (Open Sound Control) and MCP (Model Context Protocol) for AI-assisted audio production.
## What's This About?
The ardour-mcp project enables AI assistants (like Claude) to control Ardour through OSC, creating powerful AI-assisted workflows for audio production, mixing, and automation.
## Quick Start (5 Minutes)
```bash
# 1. Build Ardour with OSC support
just setup-mcp
# 2. Run Ardour with OSC debugging
just run-osc-debug
# 3. In Ardour: Edit > Preferences > Control Surfaces
# - Enable "Open Sound Control (OSC)"
# - Set port to 3819
# 4. Test the connection
just test-osc-connection
# 5. Set up and run ardour-mcp server (in sibling directory)
cd ../ardour-mcp
# (follow ardour-mcp setup instructions)
```
## Documentation
- **[ardour-mcp-integration.md](./ardour-mcp-integration.md)** - Complete integration guide
- What is MCP and why use it with Ardour
- Full setup instructions
- Architecture overview
- Troubleshooting guide
- **[osc-examples.md](./osc-examples.md)** - Practical OSC examples
- Quick configuration guide
- OSC command reference
- Python, Node.js, and shell script examples
- Testing and monitoring tools
## Common Commands (Using Just)
```bash
# Get help
just help
# Development workflow
just dev # Configure, build, run (debug mode)
just osc-dev # Build with OSC + run with OSC debug
# Information
just osc-info # Show OSC configuration info
just mcp-info # Show MCP integration info
# Building
just configure-osc # Configure with OSC support
just build # Build with parallel jobs
just rebuild # Clean and rebuild
# Running
just run # Run from build directory
just run-osc-debug # Run with OSC debugging
just run-debug-all # Run with all debug output
# Testing
just check-osc # Verify OSC library was built
just test-osc-connection # Test if OSC port is responding
just watch-logs # Monitor Ardour logs in real-time
```
## Use Cases
- **AI-Assisted Mixing**: Get intelligent suggestions for EQ, compression, and mix balance
- **Automation**: Automate repetitive tasks through natural language commands
- **Session Analysis**: AI analysis of your session structure and routing
- **Learning**: Interactive guidance for learning Ardour features
- **Scripting**: Generate Lua scripts for custom automation
## Example Interactions with Claude
Once set up, you can interact with Ardour through Claude:
```
You: "Show me all the tracks in my current session"
Claude: [Uses MCP to query Ardour via OSC]
"Your session has 12 tracks: Kick, Snare, Toms, OH-L, OH-R,
Bass, Guitar-L, Guitar-R, Keys, Vocal-Lead, Vocal-BG, Master"
You: "Mute all the drum tracks"
Claude: [Sends OSC commands to mute tracks 1-6]
"Muted 6 drum tracks"
You: "Set up a parallel compression bus for the drums"
Claude: [Creates aux track, configures routing, suggests plugin settings]
"Created 'Drums Parallel' bus with routing from tracks 1-6..."
```
## Architecture
```
Claude Code/AI Assistant
↕ MCP Protocol
ardour-mcp Server
↕ OSC Protocol (UDP Port 3819)
Ardour DAW
```
## Requirements
- Ardour 8.x+ (built from source)
- Python 3.8+ or Node.js 14+ (for ardour-mcp)
- Just command runner (optional but recommended)
- ardour-mcp server (sibling project)
## Troubleshooting
### OSC Not Working
```bash
# Check if OSC is enabled
just osc-info
# Verify OSC library exists
just check-osc
# Test connection
just test-osc-connection
# Run with debug output
just run-osc-debug
```
### Need More Help?
1. Check the detailed guides linked above
2. Look at [osc-examples.md](./osc-examples.md) for working code
3. Watch logs: `just watch-logs`
4. Ask in Ardour forums: https://discourse.ardour.org/
## Security Note
OSC has no authentication. Keep port 3819 accessible only from localhost (127.0.0.1). Never expose it to untrusted networks.
## Contributing
Found a useful workflow? Share it!
- Add examples to osc-examples.md
- Contribute to ardour-mcp documentation
- Share templates and scripts
- Report issues and improvements
## Resources
- [Ardour Manual - OSC](https://manual.ardour.org/using-control-surfaces/controlling-ardour-with-osc/)
- [OSC Protocol Specification](https://opensoundcontrol.stanford.edu/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Ardour Development](https://ardour.org/development.html)
## Quick Reference Card
| Task | Command |
|------|---------|
| Complete setup | `just setup-mcp` |
| Build & run with OSC | `just osc-dev` |
| Test OSC | `just test-osc-connection` |
| Show OSC info | `just osc-info` |
| Show MCP info | `just mcp-info` |
| Watch logs | `just watch-logs` |
| Help | `just help` |
---
**Ready to start?** Run `just setup-mcp` and follow the prompts!

446
doc/ardour-mcp-integration.md Normal file
View file

@ -0,0 +1,446 @@
# Ardour-MCP Integration Guide
## Overview
The **ardour-mcp** project provides a Model Context Protocol (MCP) server that enables AI assistants (such as Claude) to control and interact with Ardour through its Open Sound Control (OSC) interface. This creates a powerful workflow where AI can help with audio production tasks, automation, mixing, and session management.
## What is MCP?
Model Context Protocol (MCP) is an open protocol that allows AI assistants to safely interact with external systems through well-defined interfaces. The ardour-mcp server acts as a bridge between Claude (or other MCP-compatible AI assistants) and Ardour's OSC control surface.
## Why Use Ardour with MCP?
### Benefits
1. **AI-Assisted Mixing**: Get AI help with EQ suggestions, compression settings, and mix balance
2. **Automated Workflows**: Automate repetitive tasks like track setup, routing, and plugin configuration
3. **Natural Language Control**: Control Ardour using conversational commands instead of clicking through menus
4. **Session Analysis**: Get insights about your session structure, track counts, routing complexity
5. **Learning Assistant**: Learn Ardour features through interactive guidance
6. **Scripting Help**: Generate Lua scripts for custom automation
7. **Documentation Access**: Quick access to Ardour documentation and best practices
### Use Cases
- **Quick Mix Setup**: "Set up a standard rock band mix with drums, bass, guitars, and vocals"
- **Automation Tasks**: "Create a volume fade out on the master bus from bar 64 to bar 68"
- **Plugin Management**: "Add a compressor to all drum tracks with conservative settings"
- **Session Organization**: "Show me all tracks that have no input connections"
- **Problem Solving**: "Why am I getting feedback in my monitoring setup?"
- **Export Automation**: "Export all tracks as individual stems with specific naming"
## Architecture
```
┌─────────────────┐
│ Claude Code / │
│ AI Assistant │
└────────┬────────┘
│ MCP Protocol
│
┌────────▼────────┐
│ ardour-mcp │
│ MCP Server │
└────────┬────────┘
│ OSC Protocol (UDP)
│ Port 3819
┌────────▼────────┐
│ Ardour │
│ OSC Surface │
└─────────────────┘
```
## Prerequisites
### System Requirements
- Ardour 8.x or later (built from source recommended for development)
- Python 3.8+ (for ardour-mcp server)
- Network connectivity (localhost for typical setup)
- Just command runner (optional, but recommended)
### Installing Dependencies
```bash
# Install just (command runner)
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash
# Or via package manager
# Ubuntu/Debian: cargo install just
# macOS: brew install just
# Arch: pacman -S just
```
## Setup Instructions
### Step 1: Build Ardour with OSC Support
Ardour's OSC support is typically enabled by default, but you can explicitly configure it:
```bash
# Navigate to Ardour source directory
cd /path/to/ardour
# Configure with OSC support
just configure-osc
# Build Ardour
just build
# Verify OSC library was built
just check-osc
```
### Step 2: Enable OSC in Ardour
1. **Start Ardour**:
```bash
just run-osc-debug
```
2. **Enable OSC Control Surface**:
- Go to `Edit > Preferences > Control Surfaces`
- Check the box next to `Open Sound Control (OSC)`
- Click `Show Protocol Settings`
3. **Configure OSC Settings**:
- **Port**: 3819 (default, recommended)
- **Protocol**: UDP
- **Reply Mode**: Enable if you want feedback from Ardour
- **Bank Size**: Set according to your needs (typically 0 for unlimited)
4. **Advanced Settings** (optional):
- **Debug Mode**: Enable for troubleshooting
- **Default Strip Types**: Configure which track types to expose
- **Feedback**: Configure which parameters send updates
5. **Click OK** to save settings
### Step 3: Set Up ardour-mcp Server
```bash
# Navigate to ardour-mcp directory (sibling to ardour)
cd /path/to/ardour-mcp
# Install dependencies (if using Python)
pip install -r requirements.txt
# Or if using Node.js
npm install
# Configure MCP server (check ardour-mcp documentation)
# Typically involves setting OSC host and port
# Start the MCP server
# (refer to ardour-mcp specific instructions)
```
### Step 4: Connect Claude Code to MCP
1. **Configure MCP in Claude Code**:
- Create or edit `~/.config/claude-code/mcp_settings.json`
- Add ardour-mcp server configuration
2. **Example MCP Configuration**:
```json
{
"mcpServers": {
"ardour": {
"command": "python",
"args": ["/path/to/ardour-mcp/server.py"],
"env": {
"ARDOUR_OSC_HOST": "127.0.0.1",
"ARDOUR_OSC_PORT": "3819"
}
}
}
}
```
3. **Restart Claude Code** to load the MCP server
### Step 5: Test the Connection
1. **Verify OSC Port**:
```bash
just test-osc-connection
```
2. **Test from Claude**:
- Open Claude Code
- Try a simple command: "What tracks are in my current Ardour session?"
- Claude should use the MCP server to query Ardour via OSC
## OSC Protocol Reference
### Common OSC Messages
Ardour's OSC implementation supports hundreds of commands. Here are some commonly used ones:
#### Transport Control
```
/transport_play - Start playback
/transport_stop - Stop playback
/rewind - Rewind to start
/ffwd - Fast forward to end
/goto_start - Jump to session start
/goto_end - Jump to session end
```
#### Track/Strip Control
```
/strip/gain <ssid> <value> - Set track gain
/strip/pan_stereo_position <ssid> <pos> - Set pan position
/strip/mute <ssid> <0|1> - Mute/unmute track
/strip/solo <ssid> <0|1> - Solo/unsolo track
/strip/recenable <ssid> <0|1> - Enable/disable recording
```
#### Session Information
```
/session/list - List all tracks
/strip/list - Get strip list with details
/session/frame_rate - Get sample rate
/session/timecode - Get current timecode
```
#### Plugin Control
```
/strip/plugin/parameter <ssid> <plugin> <param> <value>
```
### OSC Query and Feedback
Ardour can send feedback about parameter changes:
```
/strip/gains - Subscribe to gain changes for all strips
/strip/fader/<ssid> - Feedback when fader moves
```
## Development Workflow
### Quick Start Development Cycle
```bash
# Terminal 1: Build and run Ardour with OSC debugging
cd /path/to/ardour
just osc-dev
# Terminal 2: Run ardour-mcp server
cd /path/to/ardour-mcp
# (start your MCP server)
# Terminal 3: Use Claude Code
claude-code
```
### Monitoring OSC Traffic
1. **Enable OSC Debug in Ardour**:
```bash
ARDOUR_DEBUG=OSC just run
```
2. **Watch Ardour Logs**:
```bash
just watch-logs
```
3. **Use OSC Monitor Tools**:
- `oscdump` - Command-line OSC monitor
- `OSCulator` (macOS) - GUI OSC monitor and router
- `protokol` - Cross-platform OSC/MIDI monitor
### Testing OSC Commands Manually
You can test OSC commands using various tools:
```bash
# Using oscsend (from liblo-tools)
oscsend localhost 3819 /transport_play
# Using Python with python-osc
python3 << EOF
from pythonosc import udp_client
client = udp_client.SimpleUDPClient("127.0.0.1", 3819)
client.send_message("/transport_play", [])
EOF
```
## Troubleshooting
### OSC Not Responding
1. **Check OSC is enabled**:
- Edit > Preferences > Control Surfaces
- Verify "Open Sound Control (OSC)" is checked
2. **Verify port is not in use**:
```bash
netstat -an | grep 3819
# or
lsof -i :3819
```
3. **Check firewall settings**:
```bash
# Allow UDP port 3819 on localhost
sudo ufw allow 3819/udp
```
4. **Test with debug output**:
```bash
ARDOUR_DEBUG=OSC just run
```
### MCP Server Connection Issues
1. **Verify MCP server is running**:
```bash
ps aux | grep ardour-mcp
```
2. **Check MCP server logs** (location depends on ardour-mcp implementation)
3. **Verify Claude Code MCP configuration**:
```bash
cat ~/.config/claude-code/mcp_settings.json
```
4. **Test MCP server independently** (without Claude)
### Performance Issues
1. **Reduce OSC feedback**:
- Disable unnecessary feedback in OSC settings
- Use targeted queries instead of broad subscriptions
2. **Adjust OSC update rates** in Ardour preferences
3. **Use local connections only** (127.0.0.1, not 0.0.0.0)
## Security Considerations
### Network Exposure
- **Default configuration**: OSC listens on localhost only (127.0.0.1)
- **Remote access**: Be cautious enabling remote OSC access
- **Firewall**: Keep port 3819 blocked from external networks
- **No authentication**: OSC has no built-in authentication
### Best Practices
1. **Never expose OSC to untrusted networks**
2. **Use SSH tunneling** for remote access if needed
3. **Run ardour-mcp and Ardour on the same machine**
4. **Keep ardour-mcp updated** for security patches
5. **Monitor OSC traffic** in production environments
## Advanced Topics
### Custom OSC Scripts
You can create custom OSC interaction scripts:
```python
# Example: Automated mixing script
from pythonosc import udp_client
client = udp_client.SimpleUDPClient("127.0.0.1", 3819)
# Set consistent levels for drum bus
drum_tracks = [1, 2, 3, 4] # Kick, snare, toms, OH
for track in drum_tracks:
client.send_message(f"/strip/gain", [track, -6.0])
client.send_message(f"/strip/solo", [track, 0])
```
### Integrating with Lua Scripts
Ardour's Lua scripting can complement OSC control:
- Use OSC for external control and monitoring
- Use Lua for complex internal automation
- Combine both for powerful workflows
### Multiple OSC Clients
Ardour can handle multiple OSC clients simultaneously:
- Different control surfaces
- Monitoring tools
- Multiple MCP servers
- Mix and match control paradigms
## Resources
### Documentation
- [Ardour OSC Manual](https://manual.ardour.org/using-control-surfaces/controlling-ardour-with-osc/)
- [OSC Protocol Specification](https://opensoundcontrol.stanford.edu/)
- [Ardour Development Guide](https://ardour.org/development.html)
### Community
- Ardour Forums: https://discourse.ardour.org/
- Ardour IRC: #ardour on libera.chat
- GitHub Issues: https://github.com/Ardour/ardour
### Example Projects
- TouchOSC templates for Ardour
- Open Stage Control layouts
- Ardour OSC Python examples in `share/scripts/`
## Contributing
If you develop useful MCP tools or workflows:
1. Share your OSC command patterns
2. Contribute to ardour-mcp documentation
3. Create example sessions/templates
4. Write tutorials and blog posts
5. Report bugs and enhancement requests
## Appendix: Complete Setup Checklist
- [ ] Ardour built from source with OSC support
- [ ] Just command runner installed
- [ ] Ardour running: `just run-osc-debug`
- [ ] OSC enabled in Ardour preferences
- [ ] OSC port 3819 confirmed open: `just test-osc-connection`
- [ ] ardour-mcp server installed and configured
- [ ] ardour-mcp server running
- [ ] Claude Code MCP settings configured
- [ ] Test connection from Claude successful
- [ ] OSC debug output visible in Ardour logs
- [ ] Ready to use AI-assisted audio production!
## Quick Reference
```bash
# Complete setup in one command
just setup-mcp
# Get OSC information
just osc-info
# Get MCP integration information
just mcp-info
# Run Ardour with OSC debugging
just run-osc-debug
# Test OSC connection
just test-osc-connection
# Watch Ardour logs
just watch-logs
```
---
**Last Updated**: 2025-11-06
**Ardour Version**: 8.x
**OSC Protocol Version**: 1.0

541
doc/osc-examples.md Normal file
View file

@ -0,0 +1,541 @@
# Ardour OSC Configuration Examples
This document provides practical examples for configuring and using Ardour's Open Sound Control (OSC) interface.
## Quick Start
### Enabling OSC in Ardour
1. Launch Ardour: `just run-osc-debug`
2. Navigate to: `Edit > Preferences > Control Surfaces`
3. Enable: `Open Sound Control (OSC)`
4. Click: `Show Protocol Settings`
### Recommended OSC Settings
```
Port: 3819
Reply Port: Auto (or specify if needed)
Bank Size: 0 (unlimited)
Strip Types: All enabled
Feedback: Enable for interactive control
Gainmode: dB
Default Strip: Audio Tracks
Debug Mode: Enable during development
```
## Testing OSC Connection
### Method 1: Using Command Line Tools
```bash
# Test if port is listening
just test-osc-connection
# Or manually with netcat
nc -zv -u 127.0.0.1 3819
```
### Method 2: Send Test OSC Message
Install `liblo-tools`:
```bash
# Ubuntu/Debian
sudo apt-get install liblo-tools
# macOS
brew install liblo
```
Send a test command:
```bash
# Start playback
oscsend localhost 3819 /transport_play
# Stop playback
oscsend localhost 3819 /transport_stop
# Get session info
oscsend localhost 3819 /strip/list
```
### Method 3: Python Script
```python
#!/usr/bin/env python3
# test_osc.py - Test Ardour OSC connection
from pythonosc import udp_client
import time
# Create OSC client
client = udp_client.SimpleUDPClient("127.0.0.1", 3819)
print("Testing Ardour OSC connection...")
# Test transport controls
print("Starting playback...")
client.send_message("/transport_play", [])
time.sleep(2)
print("Stopping playback...")
client.send_message("/transport_stop", [])
time.sleep(1)
print("Rewinding to start...")
client.send_message("/goto_start", [])
print("Test complete!")
```
Install dependencies:
```bash
pip install python-osc
```
Run:
```bash
python3 test_osc.py
```
## Common OSC Commands
### Transport Control
```bash
# Start/Stop
oscsend localhost 3819 /transport_play
oscsend localhost 3819 /transport_stop
# Recording
oscsend localhost 3819 /rec_enable_toggle
oscsend localhost 3819 /rec_enable i 1 # Enable recording
oscsend localhost 3819 /rec_enable i 0 # Disable recording
# Navigation
oscsend localhost 3819 /goto_start
oscsend localhost 3819 /goto_end
oscsend localhost 3819 /rewind
oscsend localhost 3819 /ffwd
# Loop
oscsend localhost 3819 /loop_toggle
oscsend localhost 3819 /set_loop_range # Set loop to current selection
```
### Track/Strip Control
```bash
# Gain control (ssid = strip ID, starts at 1)
oscsend localhost 3819 /strip/gain if 1 0.5 # Set track 1 gain to 50%
oscsend localhost 3819 /strip/gain if 1 1.0 # Set track 1 gain to 100%
oscsend localhost 3819 /strip/gain if 1 0.0 # Set track 1 gain to 0%
# Fader control (in dB)
oscsend localhost 3819 /strip/fader if 1 0.0 # Set track 1 to 0dB
oscsend localhost 3819 /strip/fader if 1 -6.0 # Set track 1 to -6dB
oscsend localhost 3819 /strip/fader if 1 -inf # Set track 1 to -infinity
# Pan control (-1.0 = full left, 0.0 = center, 1.0 = full right)
oscsend localhost 3819 /strip/pan_stereo_position if 1 0.0 # Center
oscsend localhost 3819 /strip/pan_stereo_position if 1 -1.0 # Full left
oscsend localhost 3819 /strip/pan_stereo_position if 1 1.0 # Full right
# Mute/Solo
oscsend localhost 3819 /strip/mute if 1 1 # Mute track 1
oscsend localhost 3819 /strip/mute if 1 0 # Unmute track 1
oscsend localhost 3819 /strip/solo if 1 1 # Solo track 1
oscsend localhost 3819 /strip/solo if 1 0 # Unsolo track 1
# Record enable
oscsend localhost 3819 /strip/recenable if 1 1 # Enable recording on track 1
oscsend localhost 3819 /strip/recenable if 1 0 # Disable recording on track 1
# Monitor
oscsend localhost 3819 /strip/monitor_input if 1 1
oscsend localhost 3819 /strip/monitor_disk if 1 1
```
### Session Information
```bash
# Get track list
oscsend localhost 3819 /strip/list
# Get track name
oscsend localhost 3819 /strip/name if 1
# Get session frame rate
oscsend localhost 3819 /session/frame_rate
# Get current time
oscsend localhost 3819 /session/timecode
```
### Master Bus Control
```bash
# Master gain
oscsend localhost 3819 /master/gain f 1.0
# Master mute
oscsend localhost 3819 /master/mute i 1
# Master fader (dB)
oscsend localhost 3819 /master/fader f 0.0
```
## Python Examples
### Complete Control Script
```python
#!/usr/bin/env python3
# ardour_control.py - Comprehensive Ardour control example
from pythonosc import udp_client
import time
import sys
class ArdourOSC:
def __init__(self, host="127.0.0.1", port=3819):
self.client = udp_client.SimpleUDPClient(host, port)
def transport_play(self):
"""Start playback"""
self.client.send_message("/transport_play", [])
def transport_stop(self):
"""Stop playback"""
self.client.send_message("/transport_stop", [])
def goto_start(self):
"""Jump to session start"""
self.client.send_message("/goto_start", [])
def set_track_gain(self, track_id, gain):
"""Set track gain (0.0 to 1.0)"""
self.client.send_message("/strip/gain", [track_id, gain])
def set_track_fader(self, track_id, db):
"""Set track fader in dB"""
self.client.send_message("/strip/fader", [track_id, db])
def mute_track(self, track_id, mute=True):
"""Mute or unmute a track"""
self.client.send_message("/strip/mute", [track_id, 1 if mute else 0])
def solo_track(self, track_id, solo=True):
"""Solo or unsolo a track"""
self.client.send_message("/strip/solo", [track_id, 1 if solo else 0])
def set_pan(self, track_id, position):
"""Set pan position (-1.0 to 1.0)"""
self.client.send_message("/strip/pan_stereo_position", [track_id, position])
def rec_enable_track(self, track_id, enable=True):
"""Enable/disable recording on a track"""
self.client.send_message("/strip/recenable", [track_id, 1 if enable else 0])
def main():
# Create controller
ardour = ArdourOSC()
print("Ardour OSC Control Demo")
print("-" * 40)
# Example workflow
print("1. Going to start...")
ardour.goto_start()
time.sleep(1)
print("2. Setting up track 1...")
ardour.set_track_fader(1, -6.0) # Set to -6dB
ardour.set_pan(1, 0.0) # Center pan
ardour.mute_track(1, False) # Ensure unmuted
time.sleep(1)
print("3. Starting playback...")
ardour.transport_play()
time.sleep(5)
print("4. Stopping playback...")
ardour.transport_stop()
print("\nDemo complete!")
if __name__ == "__main__":
main()
```
### Batch Track Setup
```python
#!/usr/bin/env python3
# setup_mix.py - Batch configure multiple tracks
from pythonosc import udp_client
def setup_standard_mix():
"""Set up a standard rock band mix"""
client = udp_client.SimpleUDPClient("127.0.0.1", 3819)
# Define mix template
# Format: (track_id, gain_db, pan, name)
mix_template = [
(1, -6.0, 0.0, "Kick"), # Center, moderate level
(2, -8.0, 0.0, "Snare"), # Center, slightly lower
(3, -10.0, -0.3, "Tom 1"), # Left of center
(4, -10.0, 0.3, "Tom 2"), # Right of center
(5, -6.0, -0.8, "OH Left"), # Hard left
(6, -6.0, 0.8, "OH Right"), # Hard right
(7, -4.0, 0.0, "Bass"), # Center, loud
(8, -6.0, -0.5, "Guitar L"), # Left
(9, -6.0, 0.5, "Guitar R"), # Right
(10, -3.0, 0.0, "Vocal"), # Center, loudest
]
print("Setting up standard rock mix...")
for track_id, gain_db, pan, name in mix_template:
print(f" Configuring {name} (Track {track_id})")
client.send_message("/strip/fader", [track_id, gain_db])
client.send_message("/strip/pan_stereo_position", [track_id, pan])
print("Mix setup complete!")
if __name__ == "__main__":
setup_standard_mix()
```
### OSC Monitor
```python
#!/usr/bin/env python3
# osc_monitor.py - Monitor OSC messages from Ardour
from pythonosc import dispatcher
from pythonosc import osc_server
import argparse
def print_handler(unused_addr, *args):
"""Print all received OSC messages"""
print(f"[OSC] {unused_addr}: {args}")
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--ip", default="127.0.0.1", help="Listen IP")
parser.add_argument("--port", type=int, default=3820, help="Listen port")
args = parser.parse_args()
# Set up dispatcher to catch all messages
disp = dispatcher.Dispatcher()
disp.set_default_handler(print_handler)
# Create server
server = osc_server.ThreadingOSCUDPServer((args.ip, args.port), disp)
print(f"OSC Monitor listening on {args.ip}:{args.port}")
print("Configure Ardour to send feedback to this port")
print("Press Ctrl+C to exit\n")
try:
server.serve_forever()
except KeyboardInterrupt:
print("\nShutting down...")
if __name__ == "__main__":
main()
```
## Node.js Examples
### Basic OSC Client
```javascript
// ardour-osc.js - Node.js OSC client for Ardour
const osc = require('node-osc');
class ArdourOSC {
constructor(host = '127.0.0.1', port = 3819) {
this.client = new osc.Client(host, port);
}
send(address, ...args) {
this.client.send(address, ...args);
}
play() {
this.send('/transport_play');
}
stop() {
this.send('/transport_stop');
}
setTrackGain(trackId, gain) {
this.send('/strip/gain', trackId, gain);
}
setTrackFader(trackId, db) {
this.send('/strip/fader', trackId, db);
}
muteTrack(trackId, mute = true) {
this.send('/strip/mute', trackId, mute ? 1 : 0);
}
}
// Example usage
const ardour = new ArdourOSC();
console.log('Testing Ardour connection...');
ardour.play();
setTimeout(() => ardour.stop(), 3000);
```
Install dependencies:
```bash
npm install node-osc
```
## Shell Script Examples
### Quick Control Script
```bash
#!/bin/bash
# ardour-ctl.sh - Shell script for Ardour control
OSC_HOST="localhost"
OSC_PORT="3819"
osc_send() {
oscsend "$OSC_HOST" "$OSC_PORT" "$@"
}
case "$1" in
play)
echo "Starting playback..."
osc_send /transport_play
;;
stop)
echo "Stopping playback..."
osc_send /transport_stop
;;
start)
echo "Jumping to start..."
osc_send /goto_start
;;
mute)
if [ -z "$2" ]; then
echo "Usage: $0 mute <track_id>"
exit 1
fi
echo "Muting track $2..."
osc_send /strip/mute if "$2" 1
;;
unmute)
if [ -z "$2" ]; then
echo "Usage: $0 unmute <track_id>"
exit 1
fi
echo "Unmuting track $2..."
osc_send /strip/mute if "$2" 0
;;
*)
echo "Usage: $0 {play|stop|start|mute|unmute} [args]"
exit 1
;;
esac
```
Make executable:
```bash
chmod +x ardour-ctl.sh
```
Usage:
```bash
./ardour-ctl.sh play
./ardour-ctl.sh mute 1
./ardour-ctl.sh stop
```
## OSC Message Reference
### Path Format
```
/strip/<command> [ssid] [arguments]
```
Where:
- `ssid` = Strip/track ID (starts at 1)
- Arguments vary by command
### Complete Command List
See the [Ardour OSC documentation](https://manual.ardour.org/using-control-surfaces/controlling-ardour-with-osc/osc-control/) for the complete list of supported messages.
Common patterns:
```
/strip/[parameter] if [ssid] [value]
/[global_command]
/master/[parameter] [value]
```
## Troubleshooting
### No Response from Ardour
1. Verify OSC is enabled in preferences
2. Check port number (default: 3819)
3. Ensure Ardour is running
4. Test with debug output: `ARDOUR_DEBUG=OSC just run`
### Messages Not Received
1. Check firewall settings
2. Verify correct IP address (use 127.0.0.1 for local)
3. Ensure UDP protocol (not TCP)
4. Test with `oscdump` to monitor traffic
### Permission Issues
```bash
# Check port permissions
sudo lsof -i :3819
# Allow local OSC traffic
sudo ufw allow from 127.0.0.1 to any port 3819
```
## Best Practices
1. **Always use localhost (127.0.0.1)** for development
2. **Add error handling** in scripts
3. **Add delays** between rapid commands (10-50ms)
4. **Test commands individually** before batch operations
5. **Enable debug mode** during development
6. **Document your OSC workflows** for team members
7. **Use strip names** instead of IDs when possible (via feedback)
## Next Steps
1. Read the complete guide: `doc/ardour-mcp-integration.md`
2. Set up ardour-mcp server
3. Try the examples above
4. Create your own control scripts
5. Share your workflows with the community
## Resources
- OSC Specification: http://opensoundcontrol.org/
- python-osc: https://pypi.org/project/python-osc/
- node-osc: https://www.npmjs.com/package/node-osc
- Ardour Manual: https://manual.ardour.org/
---
**Last Updated**: 2025-11-06

199
justfile Normal file
View file

@ -0,0 +1,199 @@
# Ardour Build and Development Helper
# Uses just (https://github.com/casey/just)
# Default recipe - show available commands
default:
@just --list
# Configure build with default options
configure:
python3 ./waf configure
# Configure with debugging symbols (useful for development)
configure-debug:
python3 ./waf configure --debug-symbols
# Configure with optimizations (for production builds)
configure-optimized:
python3 ./waf configure --optimize
# Configure with tests enabled
configure-test:
python3 ./waf configure --test --run-tests
# Configure with OSC surface support explicitly enabled
configure-osc:
python3 ./waf configure --surfaces
# Build Ardour (parallel build with 4 jobs)
build jobs="4":
python3 ./waf build -j{{jobs}}
# Build and show verbose output
build-verbose:
python3 ./waf build -v
# Clean build artifacts (keeps configuration)
clean:
python3 ./waf clean
# Complete clean (removes configuration too)
distclean:
python3 ./waf distclean
# Install Ardour to system
install:
python3 ./waf install
# Run Ardour from build directory (development mode)
run:
./gtk2_ardour/ardev
# Run Ardour with OSC debug output enabled
run-osc-debug:
ARDOUR_DEBUG=OSC ./gtk2_ardour/ardev
# Run Ardour with all debug output enabled
run-debug-all:
ARDOUR_DEBUG=all ./gtk2_ardour/ardev
# Run Ardour with specific debug flags (e.g., just --set debug="AudioEngine,Processor")
run-debug debug="OSC":
ARDOUR_DEBUG={{debug}} ./gtk2_ardour/ardev
# Full rebuild (clean, configure, build)
rebuild: clean configure build
# Full fresh build (distclean, configure, build)
fresh: distclean configure build
# Quick build workflow for development
dev: configure-debug build run
# Build with OSC support and run with OSC debugging
osc-dev: configure-osc build run-osc-debug
# Run tests (requires configure-test first)
test:
cd libs/evoral && ./run-tests.sh
# Setup test environment variables
test-env:
#!/usr/bin/env bash
export EVORAL_TEST_PATH="libs/evoral/test/testdata"
export LD_LIBRARY_PATH="build/libs/evoral:build/libs/pbd:$LD_LIBRARY_PATH"
echo "Test environment configured"
# Check OSC surface library was built
check-osc:
@ls -lh build/libs/surfaces/osc/osc.so 2>/dev/null || echo "OSC surface not built. Run: just configure-osc build"
# Display OSC configuration info
osc-info:
@echo "OSC Surface Information:"
@echo "------------------------"
@echo "Default OSC Port: 3819"
@echo "Protocol: UDP"
@echo "Documentation: https://manual.ardour.org/using-control-surfaces/controlling-ardour-with-osc/"
@echo ""
@echo "To enable OSC in Ardour:"
@echo "1. Start Ardour: just run"
@echo "2. Go to: Edit > Preferences > Control Surfaces"
@echo "3. Enable 'Open Sound Control (OSC)'"
@echo "4. Click 'Show Protocol Settings' to configure port and options"
@echo ""
@echo "For ardour-mcp integration, see: doc/ardour-mcp-integration.md"
# Show MCP integration information
mcp-info:
@echo "Ardour-MCP Integration:"
@echo "----------------------"
@echo "The ardour-mcp project provides a Model Context Protocol server"
@echo "that allows AI assistants (like Claude) to control Ardour via OSC."
@echo ""
@echo "Setup steps:"
@echo "1. Build and run Ardour: just osc-dev"
@echo "2. Enable OSC in Ardour (port 3819)"
@echo "3. Run ardour-mcp server in the sibling directory"
@echo "4. Connect Claude Code to the MCP server"
@echo ""
@echo "See doc/ardour-mcp-integration.md for detailed instructions"
# Test OSC connection (requires netcat)
test-osc-connection port="3819":
@echo "Testing OSC connection on port {{port}}..."
@nc -zv -u 127.0.0.1 {{port}} 2>&1 || echo "Port {{port}} not responding. Is Ardour running with OSC enabled?"
# Show build info
info:
@echo "Ardour Build Information:"
@echo "------------------------"
@python3 ./waf --version
@echo ""
@git describe --tags --always 2>/dev/null || echo "Version: unknown (not a git repo)"
@echo ""
@echo "Build directory: $(pwd)/build"
@echo "Main executable: build/gtk2_ardour/ardour-*"
# Show current build configuration
config-info:
@cat build/c4che/_cache.py 2>/dev/null | grep -E "(PREFIX|ARDOUR|SURFACES)" || echo "Not configured. Run: just configure"
# Create OSC configuration template
create-osc-config:
@mkdir -p ~/.config/ardour8
@echo "Creating OSC configuration template..."
@echo "Manual configuration required in Ardour UI"
@echo "Config location: ~/.config/ardour8/"
# Show log files location
logs:
@echo "Ardour log files are typically in:"
@echo "~/.config/ardour8/ardour.log"
@ls -lh ~/.config/ardour*/ardour.log 2>/dev/null || echo "No logs found yet"
# Watch Ardour logs in real-time
watch-logs:
tail -f ~/.config/ardour*/ardour.log
# Complete setup for MCP development
setup-mcp: configure-osc build osc-info mcp-info
@echo ""
@echo "Setup complete! Next steps:"
@echo "1. Run: just run-osc-debug"
@echo "2. Enable OSC in Ardour (Edit > Preferences > Control Surfaces)"
@echo "3. Start ardour-mcp server"
# Quick reference card
help:
@echo "Ardour Development Quick Reference"
@echo "==================================="
@echo ""
@echo "Common Workflows:"
@echo " just dev - Configure, build, and run (debug mode)"
@echo " just osc-dev - Build with OSC support and run with OSC debug"
@echo " just setup-mcp - Complete setup for MCP integration"
@echo ""
@echo "Building:"
@echo " just configure - Configure build"
@echo " just build - Build with 4 parallel jobs"
@echo " just rebuild - Clean and rebuild"
@echo " just fresh - Complete fresh build"
@echo ""
@echo "Running:"
@echo " just run - Run Ardour from build directory"
@echo " just run-osc-debug - Run with OSC debugging enabled"
@echo " just run-debug-all - Run with all debug output"
@echo ""
@echo "OSC & MCP:"
@echo " just osc-info - Show OSC configuration info"
@echo " just mcp-info - Show MCP integration info"
@echo " just check-osc - Verify OSC library was built"
@echo " just test-osc-connection - Test OSC port connectivity"
@echo ""
@echo "Maintenance:"
@echo " just clean - Clean build artifacts"
@echo " just distclean - Complete clean"
@echo " just info - Show build information"
@echo ""
@echo "For full command list: just --list"