Add diagrams and documentation for the Whisper Pipeline architecture

- Created flowcharts for Infra adapters, artifacts, high-level process, models, and tests in the DOCS/diagrams directory.
- Added a mkdocs.yml configuration file for documentation site setup.

DOCS/architecture.md

@@ -0,0 +1,392 @@
+## 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.
+
+

DOCS/diagrams/adapters.mmd

@@ -0,0 +1,13 @@
+flowchart LR
+  subgraph Infra [Infra adapters]
+    FF[FFmpegAdapter]
+    TR[TranscribeAdapter]
+    KT[KokoroTTSAdapter]
+    TM[TranslatorAdapter]
+  end
+  Video --> FF
+  FF --> TR
+  TR --> TM
+  TM --> KT
+  KT --> Concat[Concat/Normalize WAVs]
+  Concat --> AudioProc[FFmpeg Audio Proc]

DOCS/diagrams/artifacts.mmd

@@ -0,0 +1,15 @@
+flowchart TD
+  A[Workdir /tmp/full_pipeline_*] --> B[extracted.wav]
+  B --> C[segments.json / segments.srt]
+  C --> D[kokoro_chunks/]
+  D --> E[final_audio.wav]
+  E --> F[final_video.mp4]
+  F --> G[output/<basename>/]
+  subgraph Logs [Logs]
+    L1[logs/infra]
+    L2[logs/usecases]
+    L3[logs/cli]
+  end
+  B -.-> L1
+  C -.-> L2
+  E -.-> L1

DOCS/diagrams/high_level.mmd

@@ -0,0 +1,43 @@
+flowchart TD
+  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)"]
+
+  %% Agrupar visualmente (se mantiene la semántica, ahora vertical)
+  subgraph InfraAdapters [Infra adapters]
+    direction TB
+    ExtractAudio
+    Transcribe
+    KokoroTTS
+    AudioProc
+  end
+
+  subgraph Usecase [Usecase / Orchestrator]
+    direction TB
+    Transcribe
+    Translate
+    SRTGen
+    Concat
+  end
+
+  %% servicios auxiliares (con conexiones punteadas)
+  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

DOCS/diagrams/models.mmd

@@ -0,0 +1,6 @@
+flowchart LR
+  Cache["Model cache (~/.cache/transformers)"] --> TF["MarianMT / Transformers"]
+  Cache --> FW["faster-whisper"]
+  TF --> Translate["Translation (local)"]
+  Gemini["Gemini / LLM HTTP API"] --> Translate
+  Translate --> SRTGen["Generate SRT"]

DOCS/diagrams/tests.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+  participant Dev as Developer
+  participant CI as CI
+  participant Stg as Staging
+  Dev->>CI: push + smoke tests (dry-run)
+  CI->>CI: prefetch models
+  CI->>Stg: deploy + integration tests
+  Stg-->>Dev: results & logs

README.md

@@ -1,3 +1,15 @@
+# Whisper Pipeline — Documentación
+
+Bienvenido: esta carpeta contiene la documentación generada para la canalización multimedia (Whisper + Kokoro).
+
+- Ver la arquitectura: `Architecture` (navegación de MkDocs).
+- Para servir las docs localmente:
+
+```bash
+.venv/bin/mkdocs serve --dev-addr=127.0.0.1:8000
+```
+
+Puedes encontrar el diagrama del pipeline en `docs/assets/pipeline_diagram.png`.
 # Whisper dubbing pipeline
 
 Proyecto con utilidades para transcribir, traducir y doblar vídeos por segmentos usando Whisper + TTS (Kokoro). Está pensado para ejecutar dentro de un entorno virtual Python y con `ffmpeg` disponible en PATH.

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Whisper Pipeline Docs
+nav:
+  - Home: README.md
+  - Architecture: DOCS/ARCHITECTURE.md
+theme:
+  name: material
+plugins: []