Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
225
docs/SPECTRAL_ENGINE_README.md
Normal file
225
docs/SPECTRAL_ENGINE_README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user