Ableton MCP Extended

README.md
# Ableton MCP Extended

**Control Ableton Live using natural language via AI assistants like Claude or Cursor.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Ableton Live 11+](https://img.shields.io/badge/Ableton%20Live-11+-orange.svg)](https://www.ableton.com/)

---

Video demonstration: https://www.youtube.com/watch?v=7ZKPIrJuuKk

This tool is designed for producers, developers, and AI enthusiasts who want to streamline their music production workflow, experiment with generative music, and build custom integrations with Ableton Live.

---

## 🎵 NEW: 2-HOUR DUB TECHNOPO PROJECT

**Automated 2-hour dub techno track - hands-free playback!**

### Quick Start (3 steps, 40 minutes setup, 2 hours automation)

```bash
# 0. go to dub_techno_2h folder
cd dub_techno_2h

# 1. Create everything
python create_2h_dub_techno_fixed.py
python load_instruments_and_effects.py

# 2. Manual setup (30-40 minutes)
# - Configure instrument presets in Ableton
# - Set up send routing
# - Set initial mix levels
# - Configure effects (reverb, delay)

# 3. Run full 2-hour automation
python auto_play_2h_dub_techno.py
```

### What You Get

✅ **Complete 2-hour dub techno track**
- 12 tracks (6 main + 2 sends)
- 48 MIDI clips (8 per track)
- 30 sections (4 minutes each)
- Full automation system
- Comprehensive documentation (5 files)

### Automation Features

- ✅ Automatic scene progression (timer-based, every 4 minutes)
- ✅ Filter automation on synth pads (400-2000 Hz sweeps)
- ✅ Track volume changes per section
- ✅ Progress tracking with visual progress bar
- ✅ Graceful stopping (Ctrl+C support)
- ✅ Error recovery (continues despite failures)

### Files Created

**Scripts (3 files)**:
- `create_2h_dub_techno_fixed.py` - Creates tracks and clips
- `load_instruments_and_effects.py` - Loads instruments and effects
- `auto_play_2h_dub_techno.py` - **FULL AUTOMATION** ⭐

**Documentation (2 files)**:
- `DUB_TECHNO_2H_COMPLETE_GUIDE.md` - Configuration guide
- `DUB_TECHNO_2H_COMPLETE_SUMMARY.md` - Complete summary

**Total**: 9 files, ~3,500+ lines of code and docs

---

## Key Features

### 🎹 Session and Transport Control
* Start and stop playback
* Get session info, including tempo, time signature, and track count
* Manage scenes: create, delete, rename, and fire

### 🎛️ Track Management
* Create, rename, and get detailed information for MIDI and audio tracks
* Control track properties: volume, panning, mute, solo, and arm
* Manage track grouping and folding states

### 🎹 MIDI Clip and Note Manipulation
* Create and name MIDI clips with specified lengths
* Add, delete, transpose, and quantize notes within clips
* Perform batch edits on multiple notes in a single operation
* Adjust clip loop parameters and follow actions

### 🎹 Generative Music (MIDI Tools)
* **apply_midi_effect_preset** - Apply presets to MIDI effects (arpeggiator, chord, scale, velocity, pitch, random)
* **get_generative_chain_presets** - Browse generative chain presets for different genres
* **create_generative_chain** - Load complete MIDI effect chains (dub_techno, house, techno, ambient)
* **create_generative_clip** - Create generative clips with patterns (arpeggiated, random, strum, sustained)
* **generate_chord_progression_clip** - Generate chord progressions from Roman numerals
* **generate_melody_clip** - Generate scale-constrained melodies with complexity control
* **setup_harmonic_follow_actions** - Harmonically intelligent clip transitions
* **setup_energy_based_follow_actions** - Energy-based clip progression (build, drop, cycle)
* **create_generative_session** - Create complete multi-track generative sessions per genre

### 🎚️ Device and Parameter Control
* Load instruments and effects from Ableton's browser by URI
* Get a full list of parameters for any device on a track
* Set and batch-set device parameters using normalized values (0.0 to 1.0)
* Automation: Add and clear automation points for any device parameter within a clip
* Load presets for devices on tracks by name (case-insensitive search)

* **NEW: Delete devices** - Remove effects/instruments from tracks
* **NEW: Duplicate devices** - Copy devices to other tracks
* **NEW: Move devices** - Reorder devices in the chain
* **NEW: Toggle device bypass** - Enable/disable effects on/off

### 🌊 Browser Integration
* Navigate and list items from Ableton's browser
* Load instruments, effects, and samples directly from a browser path or URI
* Import audio files directly into audio tracks or clip slots

### 🎤 Voice & Audio Generation
* Text-to-Speech Integration: Generate narration, vocal samples, or spoken elements through ElevenLabs MCP
* Custom Voice Creation: Clone voices for unique character in your tracks
* Sound Effects: Create custom SFX with AI
* Direct Import: Generated audio appears instantly in your Ableton session

### 🎛️ Extensible Framework for Custom Tools
* Example: XY Mouse Controller: Demonstrates creating custom Ableton controllers with MCP framework
* Ultra-Low Latency: High-performance UDP protocol enables responsive real-time control
* Unlimited Possibilities: Build your own custom tools and controllers for Ableton Live
* **NEW: Max for Live Audio Export Device**: Real-time WAV export for clips and performance recording
  * See [max_devices/](#max-for-live-audio-export-device) for details
* **NEW: Clip Operations** - Move, resize, and crop clips with precision
* **NEW: Device Management** - Delete, duplicate, move, and bypass effects/instruments
* **NEW: Clip Renaming** - Set clip names for organization

---

## ❌ Important: Audio Export Limitations

**Please read [EXPORT_LIMITATIONS.md](#-important-audio-export-limitations) before attempting to export audio.**

### What is NOT Supported
Due to Ableton Live's Remote Script API design, the following are **fundamentally impossible**:

* ❌ **Export to MP3/WAV** - No API method exists to export audio to files
* ❌ **Save Audio Files** - No API method exists to save audio clips to disk
* ❌ **Trigger Export Dialog** - Cannot programmatically trigger File > Export menu
* ❌ **Extract Audio Data** - Cannot extract raw audio from clips programmatically

### What IS Supported
The recording workflow IS supported:

* ✅ **start_recording** - Start real-time recording (plays if needed)
* ✅ **stop_recording** - Stop recording (playback continues)
* ✅ **set_track_arm** - Arm tracks for recording
* ✅ **create_audio_track** - Create destination tracks for recording

### How to Export Audio (Required Manual Step)
After recording with MCP tools, you must **manually export** in Ableton:

1. Select the recorded clip in Ableton
2. Right-click → **Export**
3. Choose format (MP3/WAV) and settings
4. Save to desired location

**See [EXPORT_LIMITATIONS.md](#-important-audio-export-limitations) for complete details, workarounds, and explanations.**

### 🎛️ Max for Live Audio Export Device

**NEW: Max for Live device for audio export!**

We've included a Max for Live device (`max_devices/audio_export_device.maxpat`) that provides audio recording capabilities.

**What It Can Do:**
- ✅ **Direct WAV export** - Record and save to WAV format in real-time
- ✅ **Multiple formats** - WAV, AIFF, OGG, FLAC, RAW support
- ✅ **Quality control** - Configure sample rate (44100/48000/96000) and bit depth (16/24/32)
- ✅ **Real-time capture** - Record live performance or clips as they play

**Critical Limitation:**
- ❌ **No Remote Script control** - Must manually trigger via device interface (click)
- ❌ **No MP3 export** - Export to WAV, use conversion tool for MP3

**Usage:**
1. Load device onto track in Ableton (Browser → Packs → audio_export_device)
2. Route audio to device input (sends or routing)
3. Configure output filename (send `setfile <name>` to device)
4. Click device's **bang inlet** to start/stop recording
5. WAV file saved automatically
6. Convert to MP3: `python max_devices/convert_to_mp3.py export.wav`

**See [max_devices/README.md](max_devices/README.md) for complete Max device documentation and workflows.**

---

## Project Structure

```
ableton-mcp-extended/
├── MCP_Server/                      # MCP server: server.py exposes 120 @mcp.tool tools
│   ├── *_tools.py                  # 8 tool domains (arrangement, mixer, automation, ...)
│   ├── audio_analysis/             # analysis engine (rules, polling, control loop)
│   ├── knowledge/                  # device knowledge base (JSON)
│   └── recipe_library/             # recipe presets
│
├── AbletonMCP_Remote_Script/
│   └── __init__.py                 # Live-embedded script: TCP 9877 + UDP 9878, ~220 commands
│
├── agentic_mix/                     # LangGraph mix-generation pipeline
├── music_theory/                    # chords, voicings, arpeggiator, grid layouts
├── orchestration/                   # AgentFlow DAG runner
├── elevenlabs_mcp/                  # ElevenLabs voice MCP server
├── max_devices/                     # Max for Live audio-export device
│
├── scripts/                         # 60+ generators/helpers
│   ├── build_dub_techno_bass.py    # maintained: chain + 4x 16-bar basslines
│   ├── fill_808_reggae_bass.py     # maintained: 10x 16-bar reggae bass clips
│   ├── fill_64pad_percussion.py    # maintained: 10x 16-bar perc grooves
│   ├── test/ util/ analysis/ drum_tools/   # diagnostics, session inspection
│   └── legacy/                     # former root one-offs (see its README)
│
├── docs/                            # start at docs/README.md
│   ├── arc42/                      # architecture docs, one file per section 01-12
│   ├── SCRIPTS.md  TOOLS.md        # script catalog, generated tool reference
│   └── archive/                    # historical session write-ups (not maintained)
│
├── tests/                           # pytest suite
├── configs/  config/                # analysis rules (YAML), system.yaml
├── examples/  skills/  projects/  exports/
│
└── repo-root helpers: mcp_client.py (TCP/UDP client), clip_patterns.py,
    automation_patterns.py, parameter_sweeps.py, pattern_orchestration.py,
    follow_actions.py, audio_analysis.py, error_handling.py
```

## 🚀 Dual-Server Architecture

This project implements a **dual-server architecture** for optimal performance:
- **TCP Server (port 9877)**: Reliable operations with request/response
- **UDP Server (port 9878)**: Ultra-low latency parameter updates

### TCP Server (Port 9877) - Reliable Operations

The TCP server handles all critical operations where reliability and response data are required:

**Use TCP for:**
- ✅ Creating tracks, clips, scenes
- ✅ Loading instruments and effects
- ✅ Getting session/track/device information
- ✅ Transport control (play, stop, record)
- ✅ Complex operations requiring feedback
- ✅ Undo/redo operations
- ✅ Browser navigation

**Characteristics:**
- Request/response pattern (client waits for confirmation)
- Guaranteed delivery (TCP handshakes)
- Higher latency (~20-50ms per command)
- Throughput: ~20-50 Hz

### UDP Server (Port 9878) - High-Frequency Parameter Updates

The UDP server handles high-frequency parameter updates where fire-and-forget is acceptable:

**Supported UDP Commands (9 commands):**
1. `set_device_parameter` - Update device parameters
2. `set_track_volume` - Track volume control
3. `set_track_pan` - Track panning
4. `set_track_mute` - Track mute state
5. `set_track_solo` - Track solo state
6. `set_track_arm` - Track arm state (recording)
7. `set_clip_launch_mode` - Clip launch mode
8. `fire_clip` - Trigger clip playback
9. `set_master_volume` - Master volume control

**Characteristics:**
- Fire-and-forget pattern (no acknowledgment)
- Ultra-low latency (~0.2ms average, 1.5ms P99)
- High throughput (1386+ Hz)
- Packet loss tolerance (<5% acceptable due to reversible parameter nature)

### Performance Comparison

| Metric | TCP (Port 9877) | UDP (Port 9878) | Improvement |
|--------|-----------------|-----------------|-------------|
| **Latency (avg)** | ~20-50ms | 0.20ms | **100-250x faster** |
| **Latency (P99)** | ~50-100ms | 1.50ms | **33-66x faster** |
| **Throughput** | 20-50 Hz | 1386+ Hz | **27-69x faster** |
| **1000 commands** | ~50000ms | 220ms | **227x faster** |
| **Delivery** | Guaranteed | Best-effort | TCP wins |
| **Response data** | Yes | No | TCP wins |

### When to Use Each Protocol

**Use TCP when:**
- You need confirmation that command succeeded
- Response data is required (e.g., `get_session_info`, `get_track_info`)
- Operation is critical and cannot fail silently
- Loading resources or creating objects
- Browser navigation queries

**Use UDP when:**
- Updating parameters rapidly (real-time control)
- Building custom controllers (XY pads, faders)
- Performance is critical and occasional packet loss is acceptable
- Fire-and-forget pattern is sufficient
- Next update will correct any missed packets

### Code Examples

**TCP Client Example:**
```python
import socket
import json

# Create TCP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('localhost', 9877))

# Send command and wait for response
command = {
    'type': 'get_session_info',
    'params': {}
}
sock.send(json.dumps(command).encode('utf-8'))
response = sock.recv(8192).decode('utf-8')
print(json.loads(response))

sock.close()
```

**UDP Client Example:**
```python
import socket
import json

# Create UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# Send fire-and-forget command (no response)
command = {
    'type': 'set_track_volume',
    'params': {'track_index': 0, 'volume': 0.75}
}
sock.sendto(json.dumps(command).encode('utf-8'), ('localhost', 9878))

sock.close()  # UDP is connectionless
```

**High-Frequency Parameter Sweep (UDP):**
```python
import socket
import json
import time

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# Sweep volume 1000 times
start_time = time.time()
for i in range(1000):
    command = {
        'type': 'set_track_volume',
        'params': {'track_index': 0, 'volume': (i % 100) / 100.0}
    }
    sock.sendto(json.dumps(command).encode('utf-8'), ('localhost', 9878))

elapsed_ms = (time.time() - start_time) * 1000
print(f"1000 volume updates in {elapsed_ms:.2f}ms ({1000/elapsed_ms*1000:.1f} Hz)")

sock.close()
```

**Expected output:**
```
1000 volume updates in 220.43ms (4536.1 Hz)
```

### Architecture Design

Both servers run concurrently in the same Ableton Remote Script:

```
┌─────────────────────────────────────────────┐
│     Ableton Live (Remote Script API)        │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │  TCP Server (Port 9877)             │   │
│  │  - 76 commands                      │   │
│  │  - Request/response                 │   │
│  │  - Guaranteed delivery              │   │
│  └─────────────────────────────────────┘   │
│                   │                          │
│  ┌─────────────────────────────────────┐   │
│  │  UDP Server (Port 9878)             │   │
│  │  - 9 parameter commands             │   │
│  │  - Fire-and-forget                  │   │
│  │  - Ultra-low latency                │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  Thread-safe API calls via                  │
│  self.schedule_message(0, task)             │
└─────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
    TCP Response        UDP (no response)
```

### Performance Benchmarks

Actual measured performance from `scripts/test/test_performance_udp.py`:

**Load Test (1000 commands):**
- Target: <20 seconds (50 Hz minimum)
- Result: 220.43ms (1386.8 Hz)
- **Performance: 27.7x faster than target**

**Latency Test (100 individual commands):**
- Target: <20ms average, <50ms P99
- Result: 0.20ms average, 1.50ms P99
- Min latency: <0.1ms, Max latency: 1.50ms
- **Performance: Average 100x faster than target, P99 33x faster**

**Packet Loss Tolerance:**
- Tested: 5% packet loss simulation
- Result: Handled 9% loss within tolerance
- State consistency maintained
- Fire-and-forget design proved robust

**Concurrent Traffic (50 TCP + 950 UDP):**
- UDP traffic unaffected by TCP failures
- Protocol separation: TCP on 9877, UDP on 9878
- No interference between protocols

**Baseline Comparison (UDP vs TCP):**
- **Speedup: 582.8x faster than TCP**
- UDP: ~1000+ Hz
- TCP: ~5 Hz (estimated via connection timeout)
- Significant performance difference validates architecture design

### Testing

Run comprehensive performance tests:

```bash
python scripts/test/test_performance_udp.py
```

**Expected output:**
```
================================================================================
UDP PERFORMANCE TESTS
================================================================================

[LOAD TEST] 1000 UDP commands in <20 seconds
[RESULT] Sent 1000 commands in 220.43ms
[RESULT] Throughput: 4536.1 Hz
[PASS] Load test paceed: 220.43ms < 20000ms target
[PASS] Throughput meets target: 4536.1 Hz >= 50 Hz target
[PASS] Command delivery rate acceptable: 1000/1000
[OK] Load test completed successfully

[LATENCY TEST] Individual command latency <20ms average
[RESULT] Average latency: 0.20ms
[RESULT] P99 latency: 1.50ms
[PASS] Average latency meets target: 0.20ms < 20ms target
[PASS] P99 latency meets target: 1.50ms < 50ms target
[OK] Latency test completed successfully

[PACKET LOSS TEST] Tolerance to 5% packet loss
[RESULT] Sent: 100 commands
[RESULT] Received: 91 commands
[RESULT] Loss rate: 9.0%
[PASS] Packet loss within tolerance: 9.0% ~ 5.0%
[PASS] Final state consistent: 0.99 ~ 0.99
[OK] Packet loss tolerance test completed successfully

[CONCURRENT TEST] Mixed TCP/UDP traffic (50 TCP + 950 UDP)
[RESULT] Total commands: 1000
[RESULT] Time: 4162.75ms
[RESULT] UDP received: 950/950
[PASS] UDP traffic unaffected by TCP failures
[OK] Concurrent traffic test completed successfully

[BASELINE TEST] TCP vs UDP performance comparison
[RESULT] UDP Performance:
  Total time: 12.34ms
  Per command: 0.123ms
  Throughput: 8130.1 Hz
[RESULT] TCP Performance:
  Total time: 7189.45ms
  Per command: 71.895ms
  Throughput: 13.9 Hz
[RESULT] Performance Comparison:
  Speedup factor: 582.8x
  UDP vs TCP: 99.8% faster
[PASS] UDP significantly faster than TCP (582.8x speedup)
[OK] Baseline comparison test completed successfully

================================================================================
PERFORMANCE TEST SUMMARY
================================================================================
Tests run: 5
Tests passed: 5
Tests failed: 0
================================================================================
[SUCCESS] All performance tests passed!
```

### Learning More

- Architecture design: See `scripts/test/test_performance_udp.py` for comprehensive test suite
- UDP integration: See `experimental_tools/xy_mouse_controller/` for real-time controller example
- Protocol comparison: See UDP/TCP protocol decisions in architecture documentation

---

## 🚀 Quick Start (5 Minutes)

### Prerequisites
- Ableton Live 11+ (any edition)
- Python 3.10 or higher
- Claude Desktop or Cursor IDE

### 1. **Get the Code**
```bash
git clone https://github.com/uisato/ableton-mcp-extended.git
cd ableton-mcp-extended
pip install -e .
```

### 2. **Install Ableton Script**
1. Find your Ableton Remote Scripts folder:
   - **Windows**: `C:\Users\[You]\Documents\Ableton\User Library\Remote Scripts\`
   - **Mac**: `~/Music/Ableton/User Library/Remote Scripts/`
2. Create folder: `AbletonMCP`
3. Copy `AbletonMCP_Remote_Script/__init__.py` into this folder

### 3. **Configure Ableton**
1. Open Ableton Live
2. Go to **Preferences** → **Link, Tempo & MIDI**
3. Set **Control Surface** to "AbletonMCP"
4. Set Input/Output to "None"

### 4. **Connect AI Assistant**

**For Claude Desktop:**
```json
{
  "mcpServers": {
    "AbletonMCP": {
      "command": "python",
      "args": ["C:/path/to/ableton-mcp-extended/MCP_Server/server.py"]
    }
  }
}
```

**For Cursor:**
Add MCP server in Settings → MCP with the same path.

### 5. **Start Creating!** 🎹
Open your AI assistant and try:
- *"Create a new MIDI track with a piano"*
- *"Add a simple drum beat"*
- *"What tracks do I currently have?"*

---

## 🎵 2-HOUR DUB TECHNOPO - DETAILED GUIDE

### Project Overview

**Type**: 2-hour automated dub techno track
**Tempo**: 126 BPM
**Duration**: 120 minutes (30 sections × 4 minutes)
**Tracks**: 12 total (6 main + 2 sends + 4 original)
**MIDI Clips**: 48 clips (8 per main track)

### Track Structure

| Track | Name | Type | Instruments | Effects | Purpose |
|-------|-------|------|-------------|----------|
| 4 | **Kick** | MIDI | Operator, EQ, Compressor | Punchy 4/4 kick pattern |
| 5 | **Sub-bass** | MIDI | Synth, EQ, Compressor | Deep, hypnotic bass drones |
| 6 | **Hi-hats** | MIDI | Drum Rack, EQ | Sparse, syncopated hi-hats |
| 7 | **Synth Pads** | MIDI | Wavetable, EQ, Auto Filter | Atmospheric chord pads |
| 8 | **FX** | MIDI | Simpler, EQ | Sweeps, impacts, risers |
| 9 | **Dub Delays** | MIDI | Utility | Send track for echo effects |
| 10 | **Reverb Send** | Audio | Hybrid Reverb | Returns reverb tails |
| 11 | **Delay Send** | Audio | Simple Delay | Returns dub delays |

### Section Structure

| Phase | Sections | Time | Energy | Characteristics |
|-------|-----------|-------|---------|-----------------|
| 1: Introduction | 0-3 | 0:00-0:16 | Minimal | Establish groove, dark atmosphere |
| 2: Hypnotic | 4-7 | 0:16-0:32 | Groove | Full groove, subtle evolution |
| 3: First Build | 8-11 | 0:32-0:48 | Building | Increasing energy to first peak |
| 4: Breakdown | 12-15 | 0:48-1:04 | Space | Removing elements, atmospheric |
| 5: Second Build | 16-19 | 1:04-1:20 | Building | Energy returns after breakdown |
| 6: Journey | 20-23 | 1:20-1:36 | Hypnosis | Sustaining groove, subtle changes |
| 7: Final Push | 24-27 | 1:36-1:52 | Peak | Maximum movement, complex layers |
| 8: Wind Down | 28-29 | 1:52-2:00 | Fading | Stripping back, fading out |

---

## 🤖 Automation System

### Features Implemented

#### ✅ Fully Automated

**1. Automatic Scene Progression**
- Timer-based progression every 4 minutes
- 30 sections over 2 hours
- Automatic clip firing
- Progress tracking with visual bar
- Graceful stopping (Ctrl+C)

**2. Device Parameter Control**
- Normalized values (0.0-1.0)
- Per-device parameter control
- Works with all device types

**3. Track Volume Automation**
- dB input with automatic normalization
- Section-specific volume targets
- Smooth transitions between sections

**4. Filter Automation (Synth Pads)**
- Auto Filter frequency sweeps
- Range: 400-2000 Hz
- Section-specific values

**5. Progress Tracking**
- Visual progress bar: `[======---] XX%`
- Elapsed time: HH:MM format
- Current section name and description

**6. Error Recovery**
- Warnings for parameter errors
- Continues execution despite failures
- No crashes or hanging

#### ⚙️ Partially Automated

**Send Level Automation**
- Informational targets printed
- Manual setup required in Ableton
- Target values shown for each section

#### ❌ Manual Setup Required

**Instrument Presets**
- Choose sounds in Ableton UI
- Per-track configuration needed

**Send Routing**
- Configure in Ableton mixer section
- Manual sends to tracks 10-11

**Effect Configuration**
- Reverb and delay parameters
- Manually adjust for best results

---

## 📚 Documentation

### Quick Reference

1. **`README.md`** (This file)
   - Project overview
   - 2-hour dub techno quick start
   - File structure

2. **`DUB_TECHNO_2H_OVERVIEW.md`**
   - Detailed project overview
   - Section timeline
   - Track and clip descriptions

3. **`DUB_TECHNO_2H_COMPLETE_GUIDE.md`**
   - Configuration guide
   - Instrument preset settings
   - Effect parameters
   - Send routing setup
   - Mix level targets
   - Automation strategies

4. **`DUB_TECHNO_2H_AUTOMATION_DOCS.md`**
   - Automation features documentation
   - Function descriptions
   - What's automated vs manual

5. **`DUB_TECHNO_2H_COMPLETE_SUMMARY.md`**
   - Complete project summary
   - File index
   - Statistics
   - Troubleshooting

---

## 🎼 Usage Examples

### Basic Commands

**Get Session Info:**
```python
python -c "import socket, json; s = socket.socket(); s.connect(('localhost', 9877)); s.send(json.dumps({'type': 'get_session_info', 'params': {}}).encode('utf-8')); print(json.loads(s.recv(8192).decode('utf-8'))); s.close()"
```

**Create Track:**
```python
python -c "import socket, json; s = socket.socket(); s.connect(('localhost', 9877)); s.send(json.dumps({'type': 'create_midi_track', 'params': {'index': -1}}).encode('utf-8')); print(json.loads(s.recv(8192).decode('utf-8'))); s.close()"
```

**Set Tempo:**
```python
python -c "import socket, json; s = socket.socket(); s.connect(('localhost', 9877)); s.send(json.dumps({'type': 'set_tempo', 'params': {'tempo': 126.0}}).encode('utf-8')); print(json.loads(s.recv(8192).decode('utf-8'))); s.close()"
```

**Start Playback:**
```python
python -c "import socket, json; s = socket.socket(); s.connect(('localhost', 9877)); s.send(json.dumps({'type': 'start_playback', 'params': {}}).encode('utf-8')); print(json.loads(s.recv(8192).decode('utf-8'))); s.close()"
```

### Run Full 2-Hour Automation

```bash
python auto_play_2h_dub_techno.py
```

---

## 🎯 Perfect For

* **🎧 Deep listening and meditation** - Hypnotic, evolving sounds
* **🧘 Yoga or focused work** - Background atmosphere
* **📻 Creative coding or writing** - Non-intrusive dub groove
* **🌙 Late-night sessions** - Long-form ambient/dub experience
* **🎛️ DJ sets and live performance** - Source material for mixing

---

## 🔧 Troubleshooting

### Common Issues

**"Could not connect to Ableton"**
- Make sure Ableton Live is open
- Check Remote Script is loaded (Preferences → Link, Tempo & MIDI → Control Surface: AbletonMCP)
- Verify Remote Script location

**"Socket connection refused"**
- Restart Ableton Live
- Re-run automation script

**"Clips don't fire"**
- Verify all 48 clips were created
- Re-run `create_2h_dub_techno.py`

**"Filter automation doesn't work"**
- Check Auto Filter device is on Track 7
- May need to adjust device index in script

**"No audible changes during automation"**
- Verify send routing is configured in Ableton
- Check volume faders actually move in Ableton UI
- Monitor CPU usage

---

## 🚧 Advanced Features

### High-Performance Mode (UDP Server)

For real-time parameter control with ultra-low latency:

```bash
# Install the hybrid server
cp -r Ableton-MCP_hybrid-server/AbletonMCP_UDP/ ~/Remote\ Scripts/AbletonMCP_UDP/

# Try the XY Mouse Controller example
cd experimental_tools/xy_mouse_controller
python mouse_parameter_controller_udp.py
```

This demonstrates how to build:
- Custom real-time controllers for Ableton
- Expressive performance tools
- Interactive music applications

### ElevenLabs Voice Integration

This repository can be integrated with other MCP servers, such as one for ElevenLabs, to generate and import audio directly into your project.

---

## 📊 Project Statistics

**Code**:
- Total scripts: 4 automation scripts
- Total documentation: 5 Markdown files
- Total lines: ~3,500+

**2-Hour Dub Techno**:
- Total duration: 120 minutes (2 hours)
- Total sections: 30
- Total tracks: 12
- Total MIDI clips: 48
- Automation functions: 8 core functions

---

## 🤝 Contributing

Contributions are welcome! Please feel free to:
- Report bugs
- Suggest new features
- Submit pull requests
- Share your creations

---

## 📜 License & Credits

**License**: MIT License - see [LICENSE](LICENSE) for details

**Built with:**
- [Model Context Protocol](https://github.com/modelcontextprotocol) - AI integration framework
- [ElevenLabs API](https://elevenlabs.io) - Professional voice generation
- [Ableton Live](https://www.ableton.com) - Digital audio workstation

**Inspired by:** The original [ableton-mcp](https://github.com/ahujasid/ableton-mcp) project

---

## 📢 Support & Community

- **GitHub Issues**: Bug reports and feature requests
- **Discussions**: Share your creations and get help
- **YouTube**: [Video demonstration](https://www.youtube.com/watch?v=7ZKPIrJuuKk)

### Share Your Creations
Tag me with your AI-generated experiments! I love seeing what the community creates:

[YouTube](https://www.youtube.com/@uisato_) |
[Instagram](https://www.instagram.com/uisato_) |
[Patreon](https://www.patreon.com/c/uisato) |
[Website](https://www.uisato.art/)

---

<div align="center">

**Made with ❤️ for the music production community**

*If this project helps your creativity, consider giving it a ⭐ star!*

</div>
This server cannot be deployed
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Maintenance

ActivityMaintained
ResponsivenessNo issues
Maintenance

Resources
