# Micro Stems Approach

Ultima revision: 2026-03-30

## Objetivo

Dejar de tratar la referencia como un bloque largo y pasar a leerla como una secuencia de gestos cortos.

La idea es:

1. partir `ejemplo.mp3` en ventanas chicas
2. inferir que rol cumple cada fragmento
3. comparar cada fragmento contra la libreria local
4. extraer familias y tokens dominantes
5. usar ese resumen para sesgar la seleccion global y dejar de mezclar material "correcto" pero sin identidad

## Lo que ya quedo implementado

Archivo principal:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`

Cambios reales:

- existe `_build_micro_stem_plan(...)`
- existe `_apply_micro_stem_bias(...)`
- `build_arrangement_plan(...)` ahora agrega:
  - `micro_stems`
  - `micro_stem_summary`
- el rerank global de `matches` ahora puede recibir sesgo desde micro-fragmentos antes de elegir palette y layers

## Como funciona hoy

### Segmentacion

- usa el banco de segmentos ya existente de `reference_listener.py`
- trabaja con ventanas de hasta `4.0s`
- calcula importancia por:
  - energia
  - densidad de onsets
  - balance armonico/percusivo
  - tamaño de ventana

### Inferencia de roles

Cada micro-fragmento intenta inferir roles como:

- `kick`
- `snare`
- `hat`
- `bass_loop`
- `perc_loop`
- `top_loop`
- `synth_loop`
- `vocal_loop`
- `vocal_shot`
- `fill_fx`
- `snare_roll`
- `atmos_fx`

La inferencia se apoya en:

- `harmonic_ratio`
- `percussive_ratio`
- `spectral_centroid`
- `rms_mean`
- `onset_mean`
- `section kind`

### Matching

Para cada fragmento:

- toma candidatos top por rol desde `match_assets(...)`
- compara vector del fragmento contra bancos de segmentos de cada candidato
- combina:
  - similitud de segmento
  - tempo
  - key

### Resumen que produce

`micro_stem_summary` expone:

- `dominant_families`
- `dominant_tokens`
- `role_focus`
- cantidad de segmentos considerados y elegidos

## Lo que SI hace

- detecta familias repetidas reales dentro de la libreria
- encuentra mejor DNA ritmico que el scoring global promedio
- evita parte del ruido de "un sample bueno pero fuera de mundo"
- ayuda a que `reference_listener` prefiera material mas coherente con la referencia

## Lo que TODAVIA NO hace

- no reconstruye frase por frase en Arrangement
- no materializa literalmente micro-fragmentos de la referencia
- no usa aun `MIDI` ni presets `.fst` como parte del matching
- no decide instrumentos armonicos reales cuando esos activos existen solo en MIDI/presets

## Limitacion critica actual

La libreria del usuario tiene bastante material armonico importante en:

- `sounds presets`
- `MIDI PACK`
- subcarpetas `MIDI` dentro de sample packs

El matching micro actual es audio-first.

Eso significa:

- si el piano del estilo esta representado solo como `MIDI` o preset y no como loop de audio
- el sistema no lo va a seleccionar como `synth_loop`
- por eso el usuario sigue sintiendo que faltan pianos/keys aunque el analisis audio ya haya mejorado

## Bugs reales corregidos mientras se hacia esto

- `detect_reference_sections()` ya no rompe al convertir `librosa.feature.tempo(...)` a float
- `synth_loop` ya no acepta archivos vocales disfrazados
- `sample_selector.record_section_selection()` ya acepta dicts y no solo objetos con `.name`
- `_extract_pack()` ya no trata carpetas genericas como `20 One Shots` como si fueran un pack dominante

## Evidencia runtime local

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\temp\ejemplo_micro_stems_report.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\temp\ejemplo_arrangement_plan_validation.json`

## Siguiente paso correcto

No es "sumar mas audio loops".

Es esto:

1. indexar `MIDI` y presets del mismo universo familiar
2. mapear familias de audio a siblings armonicos (`Piano`, `Keys`, `Rhode`, `Guitar`, `Pad`, `Pluck`)
3. materializar el remake desde una `phrase plan`, no solo desde loops globales