Files

renato97 6d080d43b3 Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

2026-04-08 17:58:47 -03:00

6.3 KiB

Raw Permalink Blame History

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

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

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

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

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

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:

# 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

6.3 KiB Raw Permalink Blame History