ableton-mcp-ai/AbletonMCP_AI/MCP_Server/SAMPLE_SYSTEM_README.md

# 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.