submaster/DOCS/architecture.md

## Arquitectura técnica — Canalización Multimedia (Whisper + Kokoro)

Esta página es la versión unificada de la documentación de arquitectura para MkDocs. Describe la estructura por capas, el flujo orquestado por `whisper_project/main.py` y las recomendaciones prácticas.

## Resumen rápido


## Diagrama sencillo (texto)

```
 [Video] --> [Extract audio (ffmpeg)] --> [Transcribe (whisper)]
     --> [Translate (local/gemini)] --> [Generate SRT]
     --> [Kokoro TTS per-segment] --> [Concat WAVs] --> [Replace/Mix audio]
     --> [Burn subtitles] --> [output/<basename>/]
```

## Diagrama Mermaid (alto nivel)

```mermaid
flowchart LR
  VInput["Video input"] --> ExtractAudio["Extract audio\n(ffmpeg)"]
  ExtractAudio --> Transcribe["Transcription\n(faster-whisper / openai-whisper)"]
  Transcribe --> Segments["Segments\n(start/end/text)"]
  Segments --> Translate["Translation decision\n(usecase)"]
  Translate -->|local| LocalTranslate["Local MarianMT\n(Helsinki-NLP)"]
  Translate -->|remote| GeminiAPI["Gemini / LLM HTTP API"]
  LocalTranslate --> SRTGen["Generate SRT\n(translated) "]
  GeminiAPI --> SRTGen
  SRTGen --> KokoroTTS["Kokoro TTS\n(per-segment synth)"]
  KokoroTTS --> ChunkAdjust["Align / Pad / Trim\n(per segment)"]
  ChunkAdjust --> Concat["Concat / Normalize WAVs"]
  Concat --> AudioProc["FFmpeg Audio Proc\n(replace or mix)"]
  AudioProc --> BurnSubs["Burn subtitles (ffmpeg)"]
  BurnSubs --> Output["output/<basename>/\n(final artifacts)"]

  subgraph InfraAdapters [Infra adapters]
    ExtractAudio
    Transcribe
    KokoroTTS
    AudioProc
  end

  subgraph Usecase [Usecase / Orchestrator]
    Transcribe
    Translate
    SRTGen
    Concat
  end

  %% auxiliary services
  Logs["Logging (logs/infra, logs/usecases, logs/cli)"]
  Cache["Model cache (~/.cache/transformers)"]
  Logs -.-> Transcribe
  Logs -.-> KokoroTTS
  Cache -.-> Transcribe
  Cache -.-> LocalTranslate

  classDef infra fill:#f8f9fa,stroke:#0366d6,color:#000
  class InfraAdapters infra
```
Fuente del diagrama: `DOCS/diagrams/adapters.mmd`
Fuente del diagrama: `DOCS/diagrams/artifacts.mmd`
Fuente del diagrama: `DOCS/diagrams/models.mmd`
Fuente del diagrama: `DOCS/diagrams/tests.mmd`

## Imagen del diagrama

Si prefieres una imagen estática, está incluida en `DOCS/assets/pipeline_diagram.png` y se referencia aquí de forma relativa:

![Pipeline diagram](assets/pipeline_diagram.png)

<p align="center">
  <img src="assets/pipeline_diagram.png" alt="Pipeline diagram" style="max-width:100%; height:auto;" />
</p>

> Nota: este archivo vive en `DOCS/architecture.md` y usa la carpeta `DOCS/assets/` para los recursos embebidos.

## Diagramas detallados

A continuación se incluyen las versiones estáticas (PNG) de los diagramas generados a partir de los ficheros Mermaid en `DOCS/diagrams/`. Estas imágenes se incluyen para que MkDocs pueda servirlas rápidamente sin depender del render en tiempo real.

### Diagrama general (alto nivel)

![High level pipeline](assets/high_level.png)

_Fuente: `DOCS/diagrams/high_level.mmd`_

### Adaptadores (infra)

![Infra adapters](assets/adapters.png)

_Fuente: `DOCS/diagrams/adapters.mmd`_

### Artefactos y logging

![Artifacts and logging](assets/artifacts.png)

_Fuente: `DOCS/diagrams/artifacts.mmd`_

### Modelos y caché

![Models and cache](assets/models.png)

_Fuente: `DOCS/diagrams/models.mmd`_

### Pruebas y despliegue

![Tests & deploy](assets/tests.png)

_Fuente: `DOCS/diagrams/tests.mmd`_


## Flujo de trabajo (pipeline)

Los pasos principales orquestados por `PipelineOrchestrator` son:

1. Crear directorio temporal de trabajo (workdir) en `/tmp/full_pipeline_<id>`.
2. Extraer audio del vídeo (ffmpeg) -> WAV.
3. Transcribir audio a segmentos (faster-whisper / openai-whisper).
4. Traducir segmentos (opciones: local MarianMT, Gemini remoto, etc.).
5. Generar SRT traducido.
6. Sintetizar cada segmento con Kokoro TTS (por segmentos) y ajustar duración.
7. Concat/normalizar chunks y producir WAV final.
8. Reemplazar o mezclar la pista de audio del vídeo original.
9. Quemar SRT en el vídeo y mover artefactos a `output/<basename>/`.
10. Limpieza: borrar workdir y, por defecto, limpiar `/tmp/full_pipeline_*` salvo `--keep-temp`.

## Adaptadores y shims

Esta capa agrupa los componentes que actúan como "puentes" entre la lógica del orquestador y el mundo exterior (subprocess, HTTP, librerías de ML). Son responsables de encapsular detalles operativos y exponer contratos simples y estables al orquestador.

Objetivos y responsabilidades
- Encapsular llamadas a herramientas externas (ffmpeg), servicios HTTP (Kokoro, Gemini) y librerías locales (faster-whisper, transformers).
- Normalizar entradas/salidas: devolver estructuras de datos (por ejemplo, objetos Segment) en vez de rutas o strings sueltos.
- Manejar retries, timeouts y errores transitorios; transformar errores externos en excepciones del dominio que entiende el orquestador.
- Registrar eventos relevantes y métricas (latencias, tamaños de payload, códigos HTTP).
- Ser conservadores con efectos secundarios: no deben cambiar directorios globales ni variables de entorno; trabajan dentro del `workdir` proporcionado.

Estructura recomendada (contratos)
- TranscribeAdapter
  - entrada: path a WAV
  - salida: lista de Segment {start, end, text, confidence}
- KokoroTTSAdapter
  - entrada: texto del segmento, voz, modelo
  - salida: path a WAV sintetizado
- FFmpegAdapter
  - métodos: extract_audio(video)->wav, replace_audio(video,audio)->video_out, burn_subtitles(video,srt)->video_out

Buenas prácticas
- Inyectar adaptadores en el orquestador (dependency injection) para facilitar tests.
- Envolver todas las llamadas a 3rd-party en try/except y lanzar excepciones propias (ej. AdapterError, TemporaryAdapterError).
- Exponer parámetros configurables (timeouts, max_retries, backoff).
- Emitir logs estructurados (JSON opcional) si se quiere integrar con sistemas de observabilidad.

Mermaid: vista de Adaptadores

```mermaid file="DOCS/diagrams/adapters.mmd"
```

---

## Logging, artefactos y flags importantes

Esta sección describe cómo se registran eventos, qué artefactos produce la canalización y los flags CLI esenciales.

Logging
- Carpetas recomendadas:
  - `logs/infra/` — logs de adaptadores
  - `logs/usecases/` — logs del orquestador y reglas de negocio
  - `logs/cli/` — logs de la capa de entrada (parsing de flags)
- Configuración típica:
  - Console handler: nivel INFO (DEBUG con `--verbose`)
  - File handler: RotatingFileHandler (5 MB, 5 backups)
  - Formato: `%(asctime)s %(levelname)s %(name)s: %(message)s`

Artefactos producidos
- `workdir` (temporal): `/tmp/full_pipeline_<id>/`
- `extracted.wav` — audio extraído
- `segments.json` / `segments.srt` — segmentos y SRT generado
- `kokoro_chunks/` — WAVs por segmento
- `final_audio.wav` — WAV concatenado y normalizado
- `final_video.mp4` — vídeo con la pista de audio resultante
- `burned_video.mp4` — vídeo con subtítulos quemados (opcional)
- `output/<basename>/` — carpeta final cuando no es `--dry-run`

Flags importantes (resumen)
- `--video PATH` (required): archivo de entrada
- `--srt PATH` (optional): usar SRT existente
- `--kokoro-endpoint` / `--kokoro-key`
- `--voice`, `--kokoro-model`
- `--translate-method` [local|gemini|none]
- `--gemini-key`
- `--dry-run`, `--keep-temp`, `--keep-chunks`
- `--mix`, `--mix-background-volume`
- `--verbose` (DEBUG)
- `--logs-dir` (opcional): personalizar ubicación de logs

Mermaid: artefactos y logging

```mermaid file="DOCS/diagrams/artifacts.mmd"
```

---

## Gestión de modelos

Resumen
- Transcripción: `faster-whisper`, `openai-whisper` (local) o servicios remotos.
- Traducción local: MarianMT (`transformers`).
- Traducción remota / LLM: Gemini u otros endpoints HTTP.

Recomendaciones operativas
- Usar `TRANSFORMERS_CACHE` o un cache compartido en CI para evitar descargas repetidas.
- Preferir modelos `base`/`small` para ejecuciones CPU; `medium`/`large` requieren GPU/VRAM.
- Para `faster-whisper`, usar `compute_type=int8` o q4 para reducir memoria cuando sea posible.
- No almacenar credenciales en el repo; usar variables de entorno (`KOKORO_KEY`, `GEMINI_KEY`) o secret manager.

Mermaid: flujo de modelos y cache

```mermaid file="DOCS/diagrams/models.mmd"
```

---

## Recomendaciones y pruebas

Flujo recomendado para desarrollo y CI
1. `--dry-run` para validar flags y rutas sin escribir `output/`.
2. Smoke test local: ejecutar pipeline contra un fixture corto (10s) con adaptadores fakes o endpoints de staging.
3. Integración: ejecutar en staging con servicios reales y `--keep-temp` activado para debugging.
4. Producción: ejecutar con modelos y recursos adecuados (GPU si procede) y recolección de métricas.

Qué probar en CI
- Unit tests: adaptadores (mocks), orquestador (fakes), validación de argumentos.
- Smoke: pipeline en `--dry-run` para validar el flujo completo sin artefactos pesados.
- Prefetch: job que descarga y cachea modelos antes de la ejecución principal.

Checklist de documentación adicional
- Incluir ejemplos de payloads HTTP para Kokoro (request/response) y plantillas `curl`.
- Añadir snippets de `ffmpeg` para extracción, reemplazo y burn de subtítulos.
- Documentar un ejemplo SRT de entrada y salida.
- Incluir guía de pre-cacheo de modelos y variables de entorno requeridas.

Mermaid: flujo de pruebas y despliegue

```mermaid file="DOCS/diagrams/tests.mmd"
```

---

Si quieres, puedo aplicar este contenido directamente en `DOCS/architecture.md` (reemplazando las secciones vacías) — dime si lo hago ahora. También puedo extraer los bloques Mermaid a archivos separados `DOCS/diagrams/*.mmd` si prefieres tenerlos aislados.


## Arquitectura técnica — Canalización Multimedia (Whisper + Kokoro)

Este documento describe, a nivel técnico, cómo está organizada la iniciativa del proyecto y cómo funciona el flujo orquestado por `run_full_pipeline` / `whisper_project/main.py`.

Contenido breve:
- Entrypoints y ejecución
- Capas arquitectónicas (Usecases / Infra / CLI)
- Flujo de trabajo (pasos del pipeline)
- Adaptadores y shims
- Logging, artefactos y limpieza
- Flags/claves importantes y recomendaciones
- Errores comunes y debugging rápido

1) Entrypoints y ejecución
---------------------------

- Punto canónico: `whisper_project/main.py` — contiene la función `main()` que construye adaptadores por defecto e invoca el usecase orquestador (`PipelineOrchestrator`).
- Compatibilidad histórica: `whisper_project/run_full_pipeline.py` es un "shim" que simplemente delega a `whisper_project.main:main` para preservar la interfaz previa.
- Recomendación de ejecución desde la raíz del repo:

```bash
.venv/bin/python3 -m whisper_project.run_full_pipeline \   # o -m whisper_project.main
  --video /ruta/al/video.mp4 --kokoro-endpoint "https://..." \
  --kokoro-key "$KOKORO_TOKEN" --voice em_alex --whisper-model base
```

Ejecutar el archivo directamente (p. ej. `python whisper_project/run_full_pipeline.py`) puede requerir ajustar `PYTHONPATH=.`, porque Python resuelve paquetes según `sys.path`. Usar `-m` evita ese problema.

2) Capas arquitectónicas
------------------------

El proyecto sigue una aproximación inspirada en Clean Architecture:

- `whisper_project/usecases/` — lógica de orquestación y casos de uso (p. ej. `PipelineOrchestrator`). Aquí residen las reglas de negocio que coordinan los pasos del pipeline.
- `whisper_project/infra/` — adaptadores concretos hacia herramientas y servicios externos (ffmpeg, Kokoro TTS, backends de transcripción/Traducción). Ejemplos:
  - `ffmpeg_adapter.py` — wrappers para extracción, reemplazo y burn de subtítulos.
  - `kokoro_adapter.py` — cliente HTTP hacia el endpoint TTS (sintetiza por segmento y devuelve WAVs).
  - `transcribe_adapter.py` — compatibilidad con backends como faster-whisper o openai-whisper.
- `whisper_project/cli/` y scripts shim — pequeñas interfaces de línea de comandos que exponen utilidades concretas (por compatibilidad y tests).
- `whisper_project/logging_config.py` — configuración centralizada de logging, crea carpetas `logs/infra`, `logs/usecases`, `logs/cli` y handlers rotativos.

3) Flujo de trabajo (pipeline)
-----------------------------

Pasos principales que orquesta `PipelineOrchestrator`:

1. Crear directorio temporal de trabajo (workdir) en `/tmp/full_pipeline_<id>`.
2. Extraer audio del vídeo (ffmpeg) -> WAV.
3. Transcribir audio a segmentos (faster-whisper / openai-whisper) -> segmentos con start/end/text.
4. Traducir segmentos (opciones):
   - local: MarianMT/Marian-based adapters
   - gemini: llamada remota HTTP a API tipo Gemini (con key)
   - argos / otros: adapters alternativos
5. Generar SRT traducido a partir de segmentos.
6. Sintetizar cada segmento con Kokoro TTS (HTTP) según SRT -> chunks WAV, opcionalmente alinear y pad/trim para coincidir con duraciones.
7. Concat/normalizar chunks y producir WAV final.
8. Reemplazar la pista de audio del vídeo original con el WAV generado, o mezclar (mix) según flag.
9. Quemar SRT en el vídeo (subtítulos quemados) y escribir artefactos en `output/<basename>/`.
10. Limpieza: borrar workdir y, por defecto, también `/tmp/full_pipeline_*` residuales salvo que se pase `--keep-temp`.

4) Adaptadores y shims
----------------------

- Diseño: la lógica del orquestador no hace llamadas directas a subprocessos; en su lugar inyecta adaptadores (dependency injection). Esto simplifica testing y permite sustituir implementaciones.
- Shims y scripts en la raíz (`run_full_pipeline.py`, `srt_to_kokoro.py`, `dub_and_burn.py`, `translate_srt_*`) permanecen para compatibilidad con ejemplos y para facilitar pruebas manuales.

5) Logging, artefactos y limpieza
--------------------------------

- Logging centralizado a través de `configure_logging(verbose)`:
  - Crea carpetas `logs/infra`, `logs/usecases`, `logs/cli`.
  - Añade RotatingFileHandler por tipo (rotación configurable) y handler de consola (INFO por defecto, DEBUG con `--verbose`).
- Salidas finales: si la ejecución no es `--dry-run`, el orquestador mueve el vídeo final y artefactos relacionados a `output/<basename>/`.
- Limpieza automática: por defecto se elimina el `workdir` y se buscan y borran residuales `/tmp/full_pipeline_*`. Pasa `--keep-temp` para evitar borrado (útil para debugging).

6) Flags y parámetros importantes
---------------------------------

- `--video` (required): ruta al vídeo fuente.
- `--srt` (opcional): usar SRT ya traducido (salta transcripción/traducción si procede).
- `--kokoro-endpoint`, `--kokoro-key`: URL y token para el servicio TTS.
- `--voice`, `--kokoro-model`: parámetros para la síntesis.
- `--translate-method` (local|gemini|argos|none): seleccionar estrategia de traducción.
- `--gemini-key`: clave para Gemini si se elige `gemini`.
- `--dry-run`: simula los pasos sin ejecutar (útil en CI o la primera ejecución).
- `--keep-chunks`, `--keep-temp`: conservar artefactos intermedios para debugging.
- `--mix`, `--mix-background-volume`: mezclar en lugar de reemplazar la pista de audio.
- `--verbose`: habilita logging DEBUG.

7) Tests y verificación
------------------------

- Proyecto contiene tests ligeros que verifican delegaciones y la API de ciertos adaptadores. Ejecutar:

```bash
python3 -m tests.run_tests
```

- Se recomienda ejecutar `--dry-run` primero y revisar `logs/` antes de una ejecución real con red y servicios externos.

8) Errores comunes y debugging rápido
-----------------------------------

- ModuleNotFoundError al ejecutar el script directamente: ejecutar con `-m` desde la raíz o usar `PYTHONPATH=.`. Mejor: `python -m whisper_project.run_full_pipeline ...`.
- Problemas con `ffmpeg`: comprobar `ffmpeg` y `ffprobe` en PATH y su versión.
- Errores TTS/HTTP: revisar `--kokoro-endpoint` y `--kokoro-key`; inspeccionar logs en `logs/infra` para requests/response y payloads.
- Si la traducción remota falla, el pipeline soporta fallback a `local` si está configurado o si el adaptador lo implementa.

9) Recomendaciones de mejora
---------------------------

- Añadir tests que verifiquen la escritura de ficheros de log y la limpieza de temporales.
- Añadir un flag `--logs-dir` para poder personalizar la ubicación de logs en entornos CI.
- Publicar el paquete en editable mode (`pip install -e .`) para evitar dependencias en `PYTHONPATH` al ejecutar desde entornos automatizados.

----

Archivo generado automáticamente por la documentación del repositorio. Si quieres, lo adapto a formato `docs/` + mkdocs o lo extiendo con diagramas mermaid y ejemplos de payloads para Kokoro.


## Gestión y uso de los modelos (Whisper, Marian, Kokoro, Gemini)

Esta sección explica cómo gestionar y trabajar con los modelos utilizados en los distintos pasos del pipeline.

- Whisper / faster-whisper / openai-whisper
  - Modelos comunes: `tiny`, `base`, `small`, `medium`, `large`.
  - Recomendación: usar `base` o `small` para calidad razonable en CPU; `medium`/`large` requieren GPU y más memoria.
  - faster-whisper: permite cargar modelos quantizados (int8, q4/q8) para reducir memoria. Ejemplo de carga:

```python
from faster_whisper import WhisperModel
## Nota sobre unificación

Este archivo existía como una versión previa de la documentación. El contenido principal ha sido unificado en `DOCS/architecture.md` (archivo canónico). Para evitar ambigüedad, por favor usa `DOCS/architecture.md` como única referencia; ese archivo contiene la versión corregida del diagrama Mermaid y la referencia al recurso `DOCS/assets/pipeline_diagram.png`.

Si quieres que elimine este archivo por completo en una próxima acción, indícamelo y lo borro.
  - Cache y ubicación: los modelos se descargan en el cache de transformers / faster-whisper (por defecto en `~/.cache/huggingface` o `~/.cache/faster-whisper`). Puedes cambiarlo con la variable `TRANSFORMERS_CACHE` o similar.