submaster/DOCS/USAGE.md

## Casos de uso y ejemplos de ejecución

Este documento muestra ejemplos de uso reales del proyecto y variantes de
ejecución para cubrir los flujos más comunes: extraer sólo el SRT traducido,
ejecutar la pipeline completa, modo dry-run, TTS local vs Kokoro, y cómo quemar
el `.srt` en un vídeo por separado.

Prerequisitos
- Tener Python 3.11 y el virtualenv activado (ejemplo: `.venv311`).
- `ffmpeg` disponible en PATH.
- Paquetes instalados en el venv (usar `requirements.txt` o `pip install -e .[cpu,tts]`).

Rutas/convención
- El CLI principal es: `python -m whisper_project.main`.
- El script para quemar SRT es: `python -m whisper_project.burn_srt`.
- En los ejemplos uso `.venv311/bin/python` para indicar el venv; adáptalo a tu
  entorno si usas otro nombre de venv.

1) Extraer y traducir sólo el SRT (modo rápido, sin TTS)

Descripción: ejecuta la transcripción + traducción y deja como salida el
archivo SRT traducido. Útil cuando sólo necesitas subtítulos.

Comando:

```bash
.venv311/bin/python -m whisper_project.main \
  --video output/dailyrutines/dailyrutines.mp4 \
  --translate-method local \
  --srt-only
```

Salida esperada:
- `output/dailyrutines/dailyrutines.translated.srt` (o un SRT en el workdir
  que se moverá a `output/<basename>/`).

Notas:
- No se ejecuta síntesis (TTS) ni se modifica el vídeo.
- Si quieres mantener temporales (chunks) añade `--keep-chunks --keep-temp`.

2) Pipeline completa (SRT -> TTS -> reemplazar audio -> quemar subtítulos)

Descripción: flujo completo por defecto (si no usas `--srt-only`).

Comando:

```bash
.venv311/bin/python -m whisper_project.main \
  --video input.mp4 \
  --translate-method local \
  --kokoro-endpoint https://kokoro.example/api/synthesize \
  --kokoro-key $KOKORO_KEY \
  --voice em_alex
```

Salida esperada:
- `input.replaced_audio.mp4` (vídeo con audio reemplazado)
- `input.replaced_audio.subs.mp4` (vídeo final con subtítulos quemados)
- `output/<basename>/` cuando la CLI mueve artefactos al terminar.

Opciones útiles:
- `--mix` si quieres mezclar la pista sintetizada con la original.
- `--mix-background-volume 0.1` para controlar volumen de fondo.
- `--keep-chunks`/`--keep-temp` para conservar archivos intermedios.

3) Dry-run (simular pasos sin ejecutar)

Descripción: imprimirá los pasos planeados sin hacer trabajo pesado.

Comando:

```bash
.venv311/bin/python -m whisper_project.main --video input.mp4 --dry-run
```

4) Usar TTS local en lugar de Kokoro

Si tienes Coqui TTS instalado y quieres sintetizar localmente:

```bash
.venv311/bin/python -m whisper_project.main \
  --video input.mp4 \
  --translate-method local \
  --local-tts
```

Notas:
- Asegúrate de que en tu `pyproject`/requirements está la dependencia `TTS` y
  que tu Python es 3.11 (Coqui TTS no siempre es compatible con 3.12+).
- Local TTS reduce dependencia de red y suele ser más rápido si el HW es
  suficiente.

5) Traducir con Gemini/Argos (servicios externos)

Ejemplo con Gemini (requiere clave):

```bash
.venv311/bin/python -m whisper_project.main \
  --video input.mp4 \
  --translate-method gemini \
  --gemini-key $GEMINI_KEY
```

Si falla el adaptador local, el orquestador cae a un wrapper que puede lanzar
scripts auxiliares (ver `whisper_project/translate_*`).

6) Quemar un `.srt` en un vídeo por separado

Descripción: si ya tienes un `.srt` (p. ej. generado por `--srt-only`) y
quieres incrustarlo en el vídeo sin ejecutar todo el pipeline.

Comando:

```bash
python -m whisper_project.burn_srt \
  --video input.mp4 \
  --srt translated.srt \
  --out input.subbed.mp4 \
  --style "FontName=Arial,FontSize=24" \
  --codec libx264
```

Notas:
- El filtro `subtitles` de `ffmpeg` normalmente requiere reencodear el vídeo.
- Si tu SRT contiene caracteres especiales, el script hace uso de rutas
  absolutas para evitar problemas.

7) Encadenar extracción SRT y quemado (ejemplo rápido)

Extraer SRT traducido y quemarlo en un solo pipeline usando tuberías de shell
o pasos secuenciales:

```bash
.venv311/bin/python -m whisper_project.main \
  --video input.mp4 --translate-method local --srt-only && \
python -m whisper_project.burn_srt \
  --video input.mp4 --srt output/input/input.translated.srt --out input.subbed.mp4
```

8) Flags de diagnóstico y tiempo de ejecución
- `--verbose` para más logging.
- Revisar `logs/` (si está configurado) para detalles de errores.

Problemas comunes y soluciones rápidas
- Error: "This tokenizer cannot be instantiated — sentencepiece missing" →
  instalar `sentencepiece` en el venv: `.venv311/bin/python -m pip install sentencepiece`.
- Error: problemas con import paths cuando se ejecutan scripts auxiliares →
  usar `python -m whisper_project.main` desde la raíz del repo para garantizar
  que el paquete se importa correctamente.
- Si la síntesis via Kokoro tarda o da timeouts, considera `--local-tts` o
  aumentar timeouts en la configuración del adaptador Kokoro.

¿Qué artefactos debo buscar?
- SRT transcrito: `*.srt` (original y traducido)
- WAV sintetizado: `*.dub.wav` o `dub_final.wav` en workdir
- Vídeos finales: `*.replaced_audio.mp4`, `*.replaced_audio.subs.mp4`

¿Quieres que ejecute alguno de estos ejemplos ahora en tu venv `.venv311` y con
tu fichero `output/dailyrutines/dailyrutines.mp4`? Puedo ejecutar sólo la
extracción SRT traducida (`--srt-only`) y traerte el log + ruta del SRT.