# 🎛️ AbletonMCP_AI v3.0 - Senior Architecture

[![Gitea](https://img.shields.io/badge/Gitea-renato97%2FAbletonMCP_AI-blue?style=flat-square&logo=gitea)](https://gitea.cbcren.online/renato97/AbletonMCP_AI)
[![Python](https://img.shields.io/badge/Python-3.7%2B-yellow?style=flat-square&logo=python)](https://python.org)
[![Ableton](https://img.shields.io/badge/Ableton%20Live-12%20Suite-black?style=flat-square&logo=ableton)](https://www.ableton.com)
[![Status](https://img.shields.io/badge/Status-Production%20Ready-green?style=flat-square)]()
[![License](https://img.shields.io/badge/License-MIT-orange?style=flat-square)]()

> **MCP-based AI system for professional music production in Ableton Live 12 Suite**
>
> *100% prompt-based music creation. No manual steps required.*

---

## ✨ What is AbletonMCP_AI?

AbletonMCP_AI is an **AI-powered music production system** that lets you create complete professional tracks in Ableton Live using **natural language prompts only**.

**No clicking. No dragging samples. No manual mixing.** Just describe what you want, and the AI does everything:
- 🥁 Creates drum patterns (dembow, trap, perreo)
- 🎹 Generates basslines, chords, and melodies
- 🎚️ Applies professional mixing and mastering
- 📀 Places everything in Arrangement View

---

## 🚀 Quick Example

```
"Reggaeton perreo intenso, 95 BPM, Am, drumloop gata como protagonista, 
1 minuto 30 segundos, bass y chords acompañando"
```

**Result:** Complete 1:38 track with 204 audio clips, 7 tracks, professionally mixed.

---

## 🏗️ Architecture v3.0 (Senior)

```
┌─────────────────────────────────────────────────────────────┐
│  AI Agent (OpenCode / Claude / Kimi)                        │
│  ↓ Natural language prompts                                  │
├─────────────────────────────────────────────────────────────┤
│  MCP Server (FastMCP, stdio)                                 │
│  ↓ JSON commands                                             │
├─────────────────────────────────────────────────────────────┤
│  50+ Production Engines                                      │
│  ├── 🥁 Drum Layer Engine                                    │
│  ├── 🎸 Bass/Chords/Melody Generators                      │
│  ├── 🎛️ Mixing & Mastering (EQ, Compression, Bus)          │
│  ├── 🎯 Coherence Validator                                  │
│  └── 🔥 Intelligent Sample Selector (375+ samples)           │
├─────────────────────────────────────────────────────────────┤
│  LiveBridge (TCP Socket → Ableton Live API)                  │
│  ↓ Real-time clip creation                                   │
├─────────────────────────────────────────────────────────────┤
│  Ableton Live 12 Suite ←── 🎵 Arrangement View               │
└─────────────────────────────────────────────────────────────┘
```

---

## 📦 Key Features

### 🎵 Music Generation
| Feature | Description |
|---------|-------------|
| **Dembow Generator** | Classic reggaeton rhythm with variations |
| **Bass Engine** | Reese bass, sub-bass, melodic patterns |
| **Chord Progressions** | i-v-vi-iv and custom progressions |
| **Melody Engine** | Scale-based with motivic development |
| **Texture Layers** | Pads, ambience, FX |

### 🎚️ Professional Mixing
| Feature | Description |
|---------|-------------|
| **Bus Architecture** | Kick, Snare, Drums, Bass, Synths, FX buses |
| **Parallel Compression** | NY-style compression for punch |
| **EQ Presets** | Extended 15+ presets (kick_sub, bass_glue, etc.) |
| **Auto Gain Staging** | Automatic level balancing |
| **Master Chain** | Professional mastering preset |

### 🔬 Smart Selection
| Feature | Description |
|---------|-------------|
| **Coherence Scoring** | Ensures samples work together (0.90+ threshold) |
| **Metadata Store** | SQLite database of 375+ analyzed samples |
| **Spectral Analysis** | MFCC, RMS, spectral centroid matching |
| **Variation Engine** | Different samples per section |

---

## 🛠️ Installation

### 1. Clone Repository
```bash
git clone https://gitea.cbcren.online/renato97/AbletonMCP_AI.git
cd AbletonMCP_AI
```

### 2. Configure Ableton Live
1. Open **Ableton Live 12 Suite**
2. Go to **Preferences → Link/Tempo/MIDI**
3. Under **Control Surfaces**, add **AbletonMCP_AI**
4. The script auto-starts on TCP port 9877

### 3. Configure OpenCode
Edit `~/.config/opencode/opencode.json`:
```json
{
  "mcp": {
    "ableton-live-mcp": {
      "type": "local",
      "command": ["python", "C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py"],
      "enabled": true,
      "timeout": 300000
    }
  }
}
```

### 4. Sample Library
Place your samples in `libreria/reggaeton/`:
```
libreria/
└── reggaeton/
    ├── kick/
    ├── snare/
    ├── hihat/
    ├── bass/
    ├── chords/
    ├── melody/
    ├── fx/
    └── drumloops/
```

---

## 🎮 Available Tools (96+)

### Project Info
- `get_session_info` - Tempo, tracks, scenes, playback state
- `get_tracks` / `get_scenes` - List all elements
- `get_arrangement_clips` - Timeline content
- `get_master_info` - Master track settings

### Transport & Settings
- `start_playback` / `stop_playback` / `toggle_playback`
- `set_tempo` (20-300 BPM) / `set_time_signature` / `set_metronome`

### Tracks & Mixing
- `create_midi_track` / `create_audio_track`
- `set_track_volume` / `set_track_pan` / `set_track_mute` / `set_track_solo`
- `create_bus_track` / `route_track_to_bus`
- `configure_eq` / `configure_compressor` / `setup_sidechain`

### Clip Creation
- `create_clip` - MIDI clips in Session View
- `add_notes_to_clip` - Add MIDI note data
- `create_arrangement_audio_pattern` - Load audio files to timeline
- `load_sample_to_clip` / `load_sample_to_drum_rack`

### 🎯 **AI Generation (The Good Stuff)**
- `generate_intelligent_track` - One-prompt complete track
- `generate_expansive_track` - 12+ samples per category
- `build_song` - Full arrangement with sections
- `produce_reggaeton` - Complete reggaeton production
- `produce_from_reference` - Match reference audio style

### Advanced
- `create_riser` / `create_downlifter` / `create_impact` - FX generation
- `automate_filter` / `generate_curve_automation` - Parameter automation
- `humanize_track` - Velocity/timing variations
- `apply_professional_mix` - Complete mix chain

---

## 📂 Project Structure

```
AbletonMCP_AI/
├── 📄 __init__.py              # Remote Script entry (~6500 lines)
├── 📄 runtime.py              # TCP server runtime
├── 📁 mcp_server/
│   ├── 📄 server.py           # MCP FastMCP server
│   ├── 📄 integration.py      # Senior Architecture coordinator
│   └── 📁 engines/
│       ├── 📄 sample_selector.py       # Smart sample selection
│       ├── 📄 song_generator.py        # Track generation
│       ├── 📄 arrangement_recorder.py  # Session→Arrangement
│       ├── 📄 live_bridge.py           # Live API execution
│       ├── 📄 mixing_engine.py         # Professional mixing
│       ├── 📄 metadata_store.py        # SQLite sample DB
│       ├── 📄 massive_selector.py      # 330+ sample selection
│       ├── 📄 coherence_system.py      # Compatibility validation
│       └── 📄 ... (50+ more engines)
├── 📁 docs/
│   ├── 📄 skill_produccion_audio.md    # Production skills
│   ├── 📄 skill_reinicio_ableton.md    # Restart procedures
│   ├── 📄 WORKFLOW_REGGAETON.md        # Reggaeton workflow
│   └── 📄 API_REFERENCE_PRO.md         # Complete API docs
├── 📁 examples/
│   └── 📄 professional_production.py   # Usage examples
└── 📁 presets/
    └── 📄 *.json                        # Saved configurations

mcp_wrapper.py               # Launcher script
AGENTS.md                    # Agent instructions
CLAUDE.md / QWEN.md         # Per-agent guides
```

---

## 🧪 Testing

### Compile Check
```powershell
python -m py_compile "AbletonMCP_AI\__init__.py"
python -m py_compile "AbletonMCP_AI\mcp_server\server.py"
```

### Health Check
```python
# Run in OpenCode
ableton-live-mcp_health_check()
```

Expected: Score 5/5 (all systems operational)

---

## 🎵 Production Workflow Example

```python
# 1. Health check
ableton-live-mcp_health_check()

# 2. Generate complete track
ableton-live-mcp_generate_intelligent_track(
    description="reggaeton perreo intenso 95bpm Am drumloop gata",
    structure_type="short",
    variation_level="high",
    coherence_threshold=0.90
)

# 3. Get arrangement status
ableton-live-mcp_get_arrangement_status()

# 4. Apply professional mix
ableton-live-mcp_apply_professional_mix(
    track_assignments='{"21": "drumloop", "22": "bass", "23": "chords"}'
)

# 5. Export
ableton-live-mcp_render_full_mix(output_path="C:\\temp\\track.wav")
```

---

## 🔧 Troubleshooting

| Problem | Solution |
|---------|----------|
| Connection refused | Check Ableton has AbletonMCP_AI loaded in Preferences |
| Port 9877 blocked | Run: `netstat -an \| findstr 9877` |
| Changes not reflecting | Restart Ableton (delete `CrashRecoveryInfo.cfg` first) |
| Sample selection empty | Verify `libreria/reggaeton/` has .wav files |
| Timeout on generation | Check Ableton log for errors |

---

## 📊 Project Statistics

| Metric | Value |
|--------|-------|
| Total Files | 119 |
| Lines of Code | ~90,000 |
| Python Engines | 50+ |
| MCP Tools | 96+ |
| Documentation | 30+ pages |
| Sample Library | 375+ analyzed |
| Presets | 7 saved |

---

## 📝 Changelog

### v3.0 - Senior Architecture (Current)
- ✅ Arrangement-first workflow (no Session View intermediate)
- ✅ SQLite metadata store (no numpy for queries)
- ✅ 50+ production engines
- ✅ Professional mixing chains
- ✅ VST plugin support

### v2.0 - Clean Rewrite
- ✅ Simplified architecture
- ✅ FastMCP stdio transport
- ✅ TCP socket per command

---

## 🤝 Credits

- **Architecture:** Senior v3.0 (Arrangement-first)
- **AI Agents:** Kimi K2 (coding), Qwen (validation)
- **Platform:** Ableton Live 12 Suite
- **Protocol:** Model Context Protocol (MCP)

---

## 📜 License

MIT License - See LICENSE file for details.

---

## 🔗 Links

- **Repository:** https://gitea.cbcren.online/renato97/AbletonMCP_AI
- **Ableton:** https://www.ableton.com
- **MCP Docs:** https://modelcontextprotocol.io

---

<p align="center">
  <strong>🎛️ Produce music with your voice. No limits. 🎵</strong>
</p>