mirror of
https://github.com/Ardour/ardour.git
synced 2025-12-10 00:34:59 +01:00
docs: Add OSC/MCP integration documentation and justfile
Added comprehensive documentation for integrating Ardour with Model Context Protocol (MCP) and Open Sound Control (OSC). Includes usage examples, integration guides, and a justfile for common development tasks. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Aaron Brewbaker
parent
7b34fc51d9
commit
4a264d68c8
4 changed files with 1361 additions and 0 deletions
175
doc/OSC-MCP-README.md
Normal file
175
doc/OSC-MCP-README.md
Normal 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
446
doc/ardour-mcp-integration.md
Normal 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
541
doc/osc-examples.md
Normal 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
199
justfile
Normal 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"
|
||||
Loading…
Add table
Add a link
Reference in a new issue