225 lines
6.3 KiB
Markdown
225 lines
6.3 KiB
Markdown
# 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) |