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
This commit is contained in:
Administrator
328
README.md
Normal file
328
README.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# 🎛️ AbletonMCP_AI v3.0 - Senior Architecture
|
||||
|
||||
[](https://gitea.cbcren.online/renato97/AbletonMCP_AI)
|
||||
[](https://python.org)
|
||||
[](https://www.ableton.com)
|
||||
[]()
|
||||
[]()
|
||||
|
||||
> **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
Block a user