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:

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:

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:

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

@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

@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

# 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

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

pip install librosa soundfile numpy

Sin estas dependencias, el sistema funciona en modo "basic" usando metadatos de los nombres de archivo.