# SPECTRAL_ENGINE_README.md

## Motor de Análisis Espectral para Samples de Audio

Este documento describe cómo usar el motor espectral (`spectral_engine.py`), cómo regenerar el índice, y cómo interpretar los resultados.

---

## Resumen

El motor espectral analiza samples de audio para extraer características tímbricas que permiten:

- Búsqueda por similitud sonora (no solo por metadatos)
- Clasificación automática por rango de frecuencia
- Detección de "brightness" (brillo espectral)
- Matching de samples compatibles para capas

---

## Uso Básico

### Análisis de un sample individual

```python
from spectral_engine import get_spectral_engine

engine = get_spectral_engine()
profile = engine.analyze("/path/to/sample.wav")

if profile:
    print(f"Centroid: {profile.centroid_mean:.1f} Hz")
    print(f"Brightness: {profile.brightness}")
    print(f"Frequency range: {profile.dominant_frequency_range}")
```

### Búsqueda de samples similares

```python
similar = engine.find_most_similar(
    reference_path="/path/to/reference.wav",
    candidates=["/path/to/a.wav", "/path/to/b.wav", "/path/to/c.wav"],
    top_n=5
)

for path, score in similar:
    print(f"{path}: {score:.2%} similarity")
```

### Agrupamiento por timbre

```python
clusters = engine.cluster_by_role(
    paths=["/path/to/kick1.wav", "/path/to/kick2.wav", ...],
    n_clusters=5
)

for cluster_id, samples in clusters.items():
    print(f"Cluster {cluster_id}: {len(samples)} samples")
```

---

## Regenerar el Índice Espectral

### Usando el script CLI

```bash
cd "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server"

python build_spectral_index.py --dir "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton"
```

### Opciones disponibles

| Opción | Descripción |
|--------|-------------|
| `--dir PATH` | Directorio raíz de samples a indexar |
| `--force` | Forzar reconstrucción completa |
| `--stats` | Mostrar estadísticas del índice actual |
| `--output PATH` | Ruta de salida del índice (default: `spectral_index.json`) |

### Salida esperada

```
============================================================
Building spectral index for: /path/to/samples
============================================================
Found 1500 audio files
Progress: 100/1500 (6.7%)
...
Progress: 1500/1500 (100.0%)
============================================================
Index build complete
  Total files found: 1500
  Successfully indexed: 1485
  Errors: 15
  Time elapsed: 45.2 seconds
  Output: /path/to/spectral_index.json
============================================================
```

---

## Interpretación de Resultados

### SpectralProfile

Cada sample analizado genera un `SpectralProfile` con los siguientes campos:

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `centroid_mean` | float | Centroide espectral promedio (Hz). Indica el "centro de gravedad" del espectro. |
| `centroid_std` | float | Desviación estándar del centroide. Indica variación espectral. |
| `rolloff_85` | float | Frecuencia bajo la cual está el 85% de la energía (Hz). |
| `flux_mean` | float | Promedio del flux espectral. Indica cambio/timbre dinámico. |
| `mfcc` | List[float] | 13 coeficientes MFCC. Representación compacta del timbre. |
| `rms` | float | Energía RMS promedio. Indica volumen/intensidad. |
| `spectral_flatness` | float | Planitud espectral. Valores bajos = tonal, valores altos = ruido. |
| `duration` | float | Duración en segundos. |
| `genre_hints` | List[str] | Pistas de género inferidas del espectro. |

### Clasificación por Brightness

| Valor | Rango de Centroide | Descripción |
|-------|-------------------|-------------|
| `dark` | < 500 Hz | Sonidos graves, sub-bass |
| `warm` | 500-1500 Hz | Cuerpo, calidez |
| `medium` | 1500-3000 Hz | Balanceado |
| `bright` | 3000-5000 Hz | Presencia, ataque |
| `very_bright` | > 5000 Hz | Hi-hats, aire, brillantez |

### Rangos de Frecuencia

| Categoría | Rango (Hz) | Ejemplos |
|-----------|-----------|----------|
| `sub` | 20-60 | Sub-bass, 808s profundos |
| `bass` | 60-250 | Bass lines, kicks |
| `low_mid` | 250-500 | Cuerpo de snares |
| `mid` | 500-2000 | Voces, synths principales |
| `high_mid` | 2000-4000 | Presencia, ataque |
| `high` | 4000-8000 | Hi-hats, percusiones agudas |
| `air` | 8000-20000 | Aire, brillo, reverb tails |

---

## Scores de Similitud

El método `similarity(a, b)` retorna un valor entre 0.0 y 1.0:

| Componente | Peso | Descripción |
|------------|------|-------------|
| Centroid similarity | 35% | Diferencia de centroide normalizada |
| Rolloff similarity | 25% | Diferencia de rolloff normalizada |
| Flux similarity | 15% | Diferencia de flux normalizada |
| MFCC similarity | 25% | Distancia euclidiana de MFCCs |

**Interpretación:**
- `> 0.8`: Muy similar, mismo tipo de sonido
- `0.5-0.8`: Similar, puede servir como alternativa
- `< 0.5`: Diferente, no recomendado como alternativa directa

---

## Dependencias

### Obligatorias
- Python 3.8+
- NumPy

### Opcionales (mejoran precisión)
- librosa (análisis de audio avanzado)
- scipy (FFT optimizado)

### Instalación

```bash
pip install numpy librosa scipy
```

---

## Troubleshooting

### "librosa no disponible"
El motor funciona en modo básico sin librosa, usando análisis heurístico por nombre de archivo.

### "Error analyzing sample"
Verificar que el archivo existe y es un formato soportado (.wav, .aiff, .aif, .flac, .mp3).

### "Index corrupted"
Eliminar `spectral_index.json` y regenerar con `--force`.

---

## Integración con AbletonMCP-AI

El motor espectral se integra con el selector de samples:

```python
# En sample_selector.py
from spectral_engine import get_spectral_engine

engine = get_spectral_engine()
similar = engine.find_most_similar(reference_sample, candidate_samples)
```

---

## Estructura de Archivos

```
MCP_Server/
├── spectral_engine.py      # Motor principal
├── build_spectral_index.py # Script CLI
├── spectral_index.json     # Índice cacheado
└── SPECTRAL_ENGINE_README.md # Este archivo
```

---

## Referencias

- [Spectral Centroid - Wikipedia](https://en.wikipedia.org/wiki/Spectral_centroid)
- [MFCC - Wikipedia](https://en.wikipedia.org/wiki/Mel-frequency_cepstrum)
- [librosa Documentation](https://librosa.org/doc/latest/index.html)