ableton-mcp-ai/docs/sprint_1_libreria_analisis_espectral.md

SPRINT 1 - Análisis Espectral de Librería + Embeddings

Date: 2026-04-11 Assigned: Kimi K2 Reviewed by: Qwen (después de completar) Priority: CRÍTICA - Base para generación inteligente

---

OBJETIVO

Analizar TODOS los samples de libreria/reggaeton/ (509 samples) con técnicas de análisis de audio avanzado para poder:

1. Encontrar samples similares entre sí
2. Comparar contra reggaeton_ejemplo.mp3 como referencia
3. Generar canciones que suenen similar a la biblioteca del usuario

---

ARCHIVOS A CREAR

1. libreria_analyzer.py

Ubicación: C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\libreria_analyzer.py

Funcionalidad:

• Escanea recursivamente libreria/reggaeton/ buscando TODOS los .wav, .mp3, .aif, .flac
• Para CADA sample extraer:
  • BPM (tempo detection via onset detection)
  • Key (key detection via chromagram)
  • RMS (nivel de energía/promedio)
  • Spectral Centroid (brillo del sample)
  • Spectral Rolloff (frecuencia de corte)
  • Zero Crossing Rate (percutivo vs sostenido)
  • MFCCs (13 coeficientes - timbre/fingerprint)
  • Onset Strength (qué tan rítmico/percutivo es)
  • Duration (duración en segundos)
  • Sample Rate
  • Channels (mono/stereo)
• Guardar todo en cache: libreria/reggaeton/.features_cache.json
• Formato del JSON:

{
  "version": "1.0",
  "total_samples": 509,
  "scan_date": "2026-04-11T...",
  "samples": {
    "C:/.../libreria/reggaeton/kick/kick_808.wav": {
      "name": "kick_808.wav",
      "pack": "kick",
      "bpm": 0,
      "key": "",
      "rms": -12.5,
      "spectral_centroid": 2500.0,
      "spectral_rolloff": 8000.0,
      "zero_crossing_rate": 0.15,
      "mfccs": [0.5, -0.3, 0.1, ...],
      "onset_strength": 0.85,
      "duration": 0.5,
      "sample_rate": 44100,
      "channels": 1,
      "role": "kick"
    }
  }
}

2. embedding_engine.py

Ubicación: C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\embedding_engine.py

Funcionalidad:

• Crear embedding vectorial para cada sample (numpy array de ~20 dimensiones)
• El embedding combina: BPM, Key, RMS, Spectral Centroid, Spectral Rolloff, ZCR, MFCCs(13), Onset Strength, Duration
• Normalizar todos los embeddings (min-max scaling) para que sean comparables
• Guardar en: libreria/reggaeton/.embeddings_index.json (como arrays serializados)
• Función find_similar(sample_path, top_n=10) → retorna samples más similares por distancia coseno o euclidiana
• Función find_by_audio_reference(audio_file_path, top_n=20) → analiza un archivo de audio completo y encuentra los samples más similares

3. reference_matcher.py

Ubicación: C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\reference_matcher.py

Funcionalidad:

• Analizar libreria/reggaeton_ejemplo.mp3 como track de referencia
• Extraer su fingerprint espectral completo (BPM, Key, energy curve, timbre promedio)
• Comparar TODA la librería contra esta referencia
• Generar ranking: qué samples son más similares al estilo del usuario
• Crear "perfil de sonido" del usuario:
  • BPM preferido
  • Key preferida
  • Timbre promedio (MFCCs medios)
  • Energy curve
  • Roles de samples más usados (kick, snare, etc.)
• Guardar en: libreria/reggaeton/.user_sound_profile.json

---

DETALLES DE IMPLEMENTACIÓN

Librerías a usar

import numpy as np
import librosa          # Análisis espectral principal
import librosa.feature  # MFCCs, spectral centroid, etc.
import json
import os
from pathlib import Path

Si librosa NO está disponible, usar fallback con:

• scipy.io.wavfile para leer WAVs
• Estimación de BPM por onset detection simple
• Sin MFCCs (usar spectral centroid básico)

Estructura de la librería

libreria/reggaeton/
├── reggaeton_ejemplo.mp3    ← Referencia PRINCIPAL
├── kick/
├── snare/
├── bass/
├── fx/
├── drumloops/
├── hi-hat (para percs normalmente)/
├── oneshots/
├── perc loop/
├── reggaeton 3/
├── SentimientoLatino2025/
├── sounds presets/
├── (extra)/
└── flp/

Detección de rol por carpeta

El rol de cada sample se infiere de la carpeta donde está:

• kick/ → "kick"
• snare/ → "snare"
• bass/ → "bass"
• fx/ → "fx"
• drumloops/ → "drum_loop"
• hi-hat*/ → "hat_closed"
• oneshots/ → "oneshot"
• perc loop/ → "perc_loop"
• reggaeton 3/ → "synth" (default)
• SentimientoLatino2025/ → "multi" (pack completo)

---

ARCHIVOS A MODIFICAR

sample_selector.py

Agregar método select_by_similarity(reference_path, top_n=10) que:

1. Usa embedding_engine.find_similar() para encontrar samples similares
2. Retorna un InstrumentGroup con los samples más parecidos a la referencia

---

ARCHIVOS DE SALIDA GENERADOS

Archivo	Contenido
libreria/reggaeton/.features_cache.json	Features de los 509 samples
libreria/reggaeton/.embeddings_index.json	Embeddings vectoriales normalizados
libreria/reggaeton/.user_sound_profile.json	Perfil de sonido del usuario

---

RESTRICCIONES

1. NO MODIFICAR ningún sample .wav/.mp3 - solo lectura
2. NO ELIMINAR nada de libreria/
3. El análisis puede tardar varios minutos (509 samples) - mostrar progreso
4. Usar caché: si .features_cache.json existe y es reciente, no re-analizar
5. Todos los paths en los JSON deben ser absolutos (Windows)
6. Compilar cada archivo después de crear: python -m py_compile "<path>"

---

VERIFICACIÓN (Qwen hará esto después)

# Compilar
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\libreria_analyzer.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\embedding_engine.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\engines\reference_matcher.py"

# Test rápido
python -c "from engines.libreria_analyzer import LibreriaAnalyzer; a = LibreriaAnalyzer(); print(f'Scanned {len(a.features)} samples')"

---

Cuando termines, avisale a Qwen para que revise, compile y cree el Sprint 2.