Initial commit: AbletonMCP-AI complete system
- MCP Server with audio fallback, sample management - Song generator with bus routing - Reference listener and audio resampler - Vector-based sample search - Master chain with limiter and calibration - Fix: Audio fallback now works without M4L - Fix: Full song detection in sample loader Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renato97
203
AbletonMCP_AI/MCP_Server/SAMPLE_SYSTEM_README.md
Normal file
203
AbletonMCP_AI/MCP_Server/SAMPLE_SYSTEM_README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# Sistema de Gestión de Samples - AbletonMCP-AI
|
||||
|
||||
Sistema completo de indexación, clasificación y selección inteligente de samples musicales.
|
||||
|
||||
## Componentes
|
||||
|
||||
### 1. `audio_analyzer.py` - Análisis de Audio
|
||||
|
||||
Detecta automáticamente características de archivos de audio:
|
||||
- **BPM**: Detección de tempo mediante análisis de onset
|
||||
- **Key**: Detección de tonalidad mediante cromagrama
|
||||
- **Tipo**: Clasificación en kick, snare, bass, synth, etc.
|
||||
- **Características espectrales**: Centroide, rolloff, RMS
|
||||
|
||||
**Uso básico:**
|
||||
```python
|
||||
from audio_analyzer import analyze_sample
|
||||
|
||||
result = analyze_sample("path/to/sample.wav")
|
||||
print(f"BPM: {result['bpm']}, Key: {result['key']}")
|
||||
print(f"Tipo: {result['sample_type']}")
|
||||
```
|
||||
|
||||
**Backends:**
|
||||
- `librosa`: Análisis completo (requiere instalación)
|
||||
- `basic`: Análisis por nombre de archivo (sin dependencias)
|
||||
|
||||
### 2. `sample_manager.py` - Gestión de Librería
|
||||
|
||||
Gestor completo de la librería de samples:
|
||||
- Indexación recursiva de directorios
|
||||
- Clasificación automática por categorías
|
||||
- Metadatos extensibles (tags, rating, géneros)
|
||||
- Búsqueda avanzada con múltiples filtros
|
||||
- Persistencia en JSON
|
||||
|
||||
**Categorías principales:**
|
||||
- `drums`: kick, snare, clap, hat, perc, shaker, tom, cymbal
|
||||
- `bass`: sub, bassline, acid
|
||||
- `synths`: lead, pad, pluck, chord, fx
|
||||
- `vocals`: vocal, speech, chant
|
||||
- `loops`: drum_loop, bass_loop, synth_loop, full_loop
|
||||
- `one_shots`: hit, noise
|
||||
|
||||
**Uso básico:**
|
||||
```python
|
||||
from sample_manager import SampleManager
|
||||
|
||||
# Inicializar
|
||||
manager = SampleManager(r"C:\Users\ren\embeddings\all_tracks")
|
||||
|
||||
# Escanear
|
||||
stats = manager.scan_directory(analyze_audio=True)
|
||||
|
||||
# Buscar
|
||||
kicks = manager.search(sample_type="kick", key="Am", bpm=128)
|
||||
house_samples = manager.search(genres=["house"], limit=10)
|
||||
|
||||
# Obtener pack completo
|
||||
pack = manager.get_pack_for_genre("techno", key="F#m", bpm=130)
|
||||
```
|
||||
|
||||
### 3. `sample_selector.py` - Selección Inteligente
|
||||
|
||||
Selección contextual basada en género, key y BPM:
|
||||
- Perfiles de género predefinidos
|
||||
- Matching armónico entre samples
|
||||
- Generación de kits de batería coherentes
|
||||
- Mapeo MIDI automático
|
||||
|
||||
**Géneros soportados:**
|
||||
- Techno (industrial, minimal, acid)
|
||||
- House (deep, classic, progressive)
|
||||
- Tech-House
|
||||
- Trance (progressive, psy)
|
||||
- Drum & Bass (liquid, neuro)
|
||||
- Ambient
|
||||
|
||||
**Uso básico:**
|
||||
```python
|
||||
from sample_selector import SampleSelector
|
||||
|
||||
selector = SampleSelector()
|
||||
|
||||
# Seleccionar para un género
|
||||
group = selector.select_for_genre("techno", key="F#m", bpm=130)
|
||||
|
||||
# Acceder a elementos
|
||||
group.drums.kick # Sample de kick
|
||||
group.bass # Lista de bass samples
|
||||
group.synths # Lista de synths
|
||||
|
||||
# Mapeo MIDI
|
||||
mapping = selector.get_midi_mapping_for_kit(group.drums)
|
||||
|
||||
# Cambio de key armónico
|
||||
new_key = selector.suggest_key_change("Am", "fifth_up") # Em
|
||||
```
|
||||
|
||||
## Integración con MCP Server
|
||||
|
||||
El servidor MCP expone las siguientes herramientas:
|
||||
|
||||
### Gestión de Librería
|
||||
- `scan_sample_library` - Escanear directorio de samples
|
||||
- `get_sample_library_stats` - Estadísticas de la librería
|
||||
|
||||
### Búsqueda y Selección
|
||||
- `advanced_search_samples` - Búsqueda con filtros múltiples
|
||||
- `select_samples_for_genre` - Selección automática por género
|
||||
- `get_drum_kit_mapping` - Kit de batería con mapeo MIDI
|
||||
- `get_sample_pack_for_project` - Pack completo para proyecto
|
||||
|
||||
### Análisis y Compatibilidad
|
||||
- `analyze_audio_file` - Analizar archivo de audio
|
||||
- `find_compatible_samples` - Encontrar samples compatibles
|
||||
- `suggest_key_change` - Sugerir cambios de tonalidad
|
||||
|
||||
## Estructura de Datos
|
||||
|
||||
### Sample
|
||||
```python
|
||||
@dataclass
|
||||
class Sample:
|
||||
id: str # ID único
|
||||
name: str # Nombre del archivo
|
||||
path: str # Ruta completa
|
||||
category: str # Categoría principal
|
||||
subcategory: str # Subcategoría
|
||||
sample_type: str # Tipo específico
|
||||
key: Optional[str] # Tonalidad (Am, F#m, C)
|
||||
bpm: Optional[float] # BPM
|
||||
duration: float # Duración en segundos
|
||||
genres: List[str] # Géneros asociados
|
||||
tags: List[str] # Tags
|
||||
rating: int # Rating 0-5
|
||||
```
|
||||
|
||||
### DrumKit
|
||||
```python
|
||||
@dataclass
|
||||
class DrumKit:
|
||||
name: str
|
||||
kick: Optional[Sample]
|
||||
snare: Optional[Sample]
|
||||
clap: Optional[Sample]
|
||||
hat_closed: Optional[Sample]
|
||||
hat_open: Optional[Sample]
|
||||
perc1: Optional[Sample]
|
||||
perc2: Optional[Sample]
|
||||
```
|
||||
|
||||
## Mapeo MIDI
|
||||
|
||||
Notas estándar para drums:
|
||||
- `36` (C1): Kick
|
||||
- `38` (D1): Snare
|
||||
- `39` (D#1): Clap
|
||||
- `42` (F#1): Closed Hat
|
||||
- `46` (A#1): Open Hat
|
||||
- `41` (F1): Tom Low
|
||||
- `49` (C#2): Crash
|
||||
|
||||
## Ejemplos de Uso
|
||||
|
||||
### Crear un track completo
|
||||
```python
|
||||
# Seleccionar samples para techno
|
||||
selector = get_selector()
|
||||
group = selector.select_for_genre("techno", key="F#m", bpm=130)
|
||||
|
||||
# Usar con Ableton
|
||||
ableton = get_ableton_connection()
|
||||
|
||||
# Crear tracks y cargar samples
|
||||
for i, sample in enumerate([group.drums.kick, group.drums.snare]):
|
||||
if sample:
|
||||
print(f"Cargar {sample.name} en track {i}")
|
||||
```
|
||||
|
||||
### Buscar samples compatibles
|
||||
```python
|
||||
# Encontrar samples que combinen con un kick
|
||||
kick = manager.get_by_path("path/to/kick.wav")
|
||||
compatible = selector.find_compatible_samples(kick, max_results=5)
|
||||
|
||||
for sample, score in compatible:
|
||||
print(f"{sample.name}: {score:.1%} compatible")
|
||||
```
|
||||
|
||||
## Archivos Generados
|
||||
|
||||
- `.sample_cache/sample_library.json` - Índice de la librería
|
||||
- `.sample_cache/library_stats.json` - Estadísticas
|
||||
|
||||
## Dependencias Opcionales
|
||||
|
||||
Para análisis de audio completo:
|
||||
```bash
|
||||
pip install librosa soundfile numpy
|
||||
```
|
||||
|
||||
Sin estas dependencias, el sistema funciona en modo "basic" usando metadatos de los nombres de archivo.
|
||||
Reference in New Issue
Block a user