## 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)

```bash
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)

```bash
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

```bash
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)

```bash
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)

```bash
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

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