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:

.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:

.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:

.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:

.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):

.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:

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:

.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.