submaster/EXAMPLES.md

Ejemplos rápidos de uso

Este archivo reúne comandos prácticos para probar la canalización y entender las opciones más usadas.

Nota: el entrypoint canónico es whisper_project/main.py. El fichero histórico whisper_project/run_full_pipeline.py existe como shim y delega a main.py.

1. Dry-run (ver qué pasaría sin ejecutar cambios)

PYTHONPATH=. python3 whisper_project/main.py \
  --video dailyrutines.mp4 \
  --kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
  --kokoro-key "$KOKORO_TOKEN" \
  --voice em_alex \
  --whisper-model base \
  --dry-run

2. Ejecutar la canalización completa (traducción local con MarianMT y reemplazo)

PYTHONPATH=. python3 whisper_project/main.py \
  --video dailyrutines.mp4 \
  --kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
  --kokoro-key "$KOKORO_TOKEN" \
  --voice em_alex \
  --whisper-model base \
  --translate-method local

3. Mezclar (mix) en lugar de reemplazar la pista original

PYTHONPATH=. python3 whisper_project/main.py \
  --video dailyrutines.mp4 \
  --kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
  --kokoro-key "$KOKORO_TOKEN" \
  --voice em_alex \
  --whisper-model base \
  --mix \
  --mix-background-volume 0.35

4. Conservar archivos temporales y WAV por segmento (útil para debugging)

PYTHONPATH=. python3 whisper_project/main.py \
  --video dailyrutines.mp4 \
  --kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
  --kokoro-key "$KOKORO_TOKEN" \
  --voice em_alex \
  --whisper-model base \
  --keep-chunks --keep-temp

5. Traducción con Gemini (requiere clave)

PYTHONPATH=. python3 whisper_project/main.py \
  --video dailyrutines.mp4 \
  --translate-method gemini \
  --gemini-key "$GEMINI_KEY" \
  --kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
  --kokoro-key "$KOKORO_TOKEN" \
  --voice em_alex

6. Uso directo de srt_to_kokoro.py si ya tienes un SRT traducido

PYTHONPATH=. python3 whisper_project/srt_to_kokoro.py \
  --srt translated.srt \
  --endpoint "https://kokoro.example/api/v1/audio/speech" \
  --payload-template '{"model":"model","voice":"em_alex","input":"{text}","response_format":"wav"}' \
  --api-key "$KOKORO_TOKEN" \
  --out out.wav \
  --video input.mp4 --align --replace-original

Payload template (Kokoro)

El parámetro --payload-template es útil cuando el endpoint TTS espera un JSON con campos concretos. El ejemplo anterior usa {text} como placeholder para el texto del segmento. Asegúrate de escapar las comillas cuando lo pases en la shell.

Errores frecuentes y debugging rápido

• Si el TTS devuelve 400 Bad Request: revisa el --payload-template y las comillas/escaping.
• Si ffmpeg falla: revisa que ffmpeg y ffprobe estén en PATH y que la versión sea reciente.
• Para problemas de autenticación remota: verifica las variables de entorno con tokens ($KOKORO_TOKEN, $GEMINI_KEY), o prueba --translate-method local si la traducción remota falla.

Recomendaciones

• Automatización/CI: siempre usar --dry-run en la primera ejecución para confirmar pasos.
• Integración: invoca whisper_project/main.py directamente desde procesos automatizados; run_full_pipeline.py sigue disponible como shim por compatibilidad.
• Limpieza: cuando ya no necesites los scripts de examples/, considera moverlos a docs/examples/ o mantenerlos como referencia, y sustituir los shims por llamadas directas a los adaptadores en whisper_project/infra/.

Si quieres, añado ejemplos adicionales (p.ej. variantes para distintos proveedores TTS o payloads avanzados). EXAMPLES - Pipeline Whisper + Kokoro TTS

Ejemplos de uso (desde la raíz del repo, usando el venv .venv):

1. Dry-run (muestra los comandos que se ejecutarían):

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4
--kokoro-endpoint "https://kokoro.bfzqqk.easypanel.host/api/v1/audio/speech"
--kokoro-key "$KOKORO_TOKEN" --voice em_alex
--whisper-model base --dry-run

2. Ejecución completa (reemplaza el audio):

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4
--kokoro-endpoint "https://kokoro.bfzqqk.easypanel.host/api/v1/audio/speech"
--kokoro-key "$KOKORO_TOKEN" --voice em_alex
--whisper-model base

3. Usar un SRT ya generado (evita transcribir):

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4 --srt subs_en.srt
--kokoro-endpoint "https://kokoro..." --kokoro-key "$KOKORO_TOKEN" --voice em_alex

4. Traducir con Gemini (si tienes clave) o usar fallback local:

Usar Gemini (requiere --gemini-key o la variable GEMINI_API_KEY)

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4 --translate-method gemini --gemini-key "$GEMINI_KEY"
--kokoro-endpoint "https://kokoro..." --kokoro-key "$KOKORO_TOKEN" --voice em_alex

Forzar traducción local (MarianMT):

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4 --translate-method local
--kokoro-endpoint "https://kokoro..." --kokoro-key "$KOKORO_TOKEN" --voice em_alex

5. Mezclar (mix) en lugar de reemplazar:

.venv/bin/python whisper_project/run_full_pipeline.py
--video dailyrutines.mp4 --mix --mix-background-volume 0.3
--kokoro-endpoint "https://kokoro..." --kokoro-key "$KOKORO_TOKEN" --voice em_alex

Notas:

• Si algo falla con Gemini, el pipeline soporta fallback a la traducción local.
• Usa --keep-temp y/o --keep-chunks para inspeccionar los WAV intermedios.
• Ajusta --whisper-model a "base", "small", "medium" según recursos.