# Arquitectura del Locutor Automático IA

## Componentes instalados

| Ruta | Rol |
|---|---|
| `~/.gradio/locutor-venv/` | Entorno virtual Python con el motor XTTS-v2 (torch, coqui-tts, transformers) |
| `~/.gradio/locutor-venv/gr-locutor.sh` | Wrapper: `gr-locutor.sh "texto" [nombre]` → genera un MP3 |
| `~/.gradio/data/locutor-ia/generar.py` | Script real de síntesis (llamado por el wrapper) |
| `~/.gradio/data/locutor-ia/referencia/voz_referencia.wav` | Voz de referencia activa (genérica de GRP o la de la estación) |
| `~/.gradio/data/locutor-ia/salida/` | MP3 generados |
| `~/.gradio/data/locutor-ia/scripts/enriquecer-locucion.py` | Genera el texto: metadata ID3 + Wikipedia + MusicBrainz |
| `~/.gradio/data/locutor-ia/scripts/generar-intro.sh` | Orquesta: texto enriquecido → `gr-locutor.sh` |
| `~/.gradio/data/locutor-ia/scripts/monitor-locuciones.py` | Daemon: mantiene 3 locuciones listas en `playlist4` |
| `~/.gradio/data/locutor-ia/scripts/start-monitor.sh` | start / stop / status del monitor |

## Flujo de una locución

```
monitor-locuciones.py detecta que faltan locuciones en la ventana
  └── generar-intro.sh "/ruta/tema.mp3"
        ├── enriquecer-locucion.py → texto (metadata + Wikipedia + MusicBrainz)
        └── gr-locutor.sh "texto" → generar.py → XTTS-v2 → MP3 en salida/
  └── monitor inserta el MP3 en playlist4 delante de la canción
```

## Coordinación con `playlist-refill`

`playlist-refill` (proceso de GRP) agrega canciones al final de `playlist4` hasta llegar a 14 temas. Si corre a la vez que el monitor inserta locuciones, puede haber una carrera (leer-generar-escribir tarda varios segundos, y mientras tanto el player puede haber consumido temas).

Solución ya implementada: `monitor-locuciones.py` crea `~/.gradio/data/tmp/pause_refill` al iniciar (GRP ya respeta este archivo — es el mismo mecanismo del botón "Automático" de la UI) y lo borra al detenerse. **No hace falta ninguna acción manual** — `start-monitor.sh start/stop` lo maneja solo.

## Bandera de habilitación

`~/.gradio/data/tmp/locutor_auto` (`1`/`0`) — se controla desde el diálogo de Configuración de GRP ("Locutor Automático"). El monitor y el generador no deberían correr si está en `0`.

## Rendimiento medido (texto de referencia ~10s de audio)

| Máquina | Generar | Cargar modelo (1 vez) |
|---|---|---|
| Escritorio con GPU NVIDIA | ~2s | ~10s |
| Escritorio CPU (20 hilos, sin GPU) | ~29s | ~10s |
| RPi5 real (CPU, sin GPU) | ~104s | ~120s |

Todos entran en el margen de una canción de 3-4 minutos. La recomendación es **no correr el generador en la misma máquina que reproduce en vivo** salvo que tenga GPU o de sobra de RAM/CPU — en el RPi5 se midió presión real de memoria (swap) al generar en aislamiento.