renato97/AbletonMCP_AI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c7b312acb2e90559ee044d56414bcf45d265e76
AbletonMCP_AI/README.md
Administrator 186458d971 docs: Add beautiful README with badges and full documentation 
- Professional layout with shields.io badges
- Complete feature matrix (Music, Mixing, Smart Selection)
- Installation guide step-by-step
- Available tools reference (96+ commands)
- Project structure visualization
- Production workflow example
- Troubleshooting table
- Statistics and changelog
2026-04-12 22:16:51 -03:00

329 lines
11 KiB
Markdown
Raw Blame History

# 🎛️ 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>
Reference in New Issue View Git Blame Copy Permalink