Cesar Mendivil
1264ae8587
- 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.
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
Contenido principal
|
|
- `whisper_project/transcribe.py` - transcribe audio a SRT (faster-whisper backend recomendado).
|
|
- `whisper_project/translate_srt_local.py` - traduce SRT localmente con MarianMT (Helsinki-NLP/opus-mt-en-es).
|
|
- `whisper_project/srt_to_kokoro.py` - sintetiza cada segmento del SRT usando un endpoint TTS compatible (Kokoro), alinea, concatena y opcionalmente mezcla/reemplaza audio en el vídeo.
|
|
- `whisper_project/run_full_pipeline.py` - orquestador "todo en uno" para extraer, transcribir (si hace falta), traducir y sintetizar + quemar subtítulos.
|
|
|
|
Nota de migración (importante)
|
|
--------------------------------
|
|
Este repositorio fue reorganizado para seguir una arquitectura basada en adaptadores y un orquestador central.
|
|
|
|
- El entrypoint canónico para la canalización es ahora `whisper_project/main.py` — úsalo para automatización o integración.
|
|
- Para mantener compatibilidad con scripts históricos, `whisper_project/run_full_pipeline.py` existe como shim y delega a `main.py`.
|
|
- Existen scripts de ejemplo en el directorio `examples/`. Para comodidad se añadieron *shims* en `whisper_project/` que preferirán los adaptadores de `whisper_project/infra/` y, si no están disponibles, harán fallback a los scripts en `examples/`.
|
|
|
|
Recomendación: cuando automatices o enlaces la canalización desde otras herramientas, invoca `whisper_project/main.py` y usa la opción `--dry-run` para verificar los pasos sin ejecutar cambios.
|
|
|
|
Requisitos
|
|
- Python 3.10+ (se recomienda usar el `.venv` del proyecto)
|
|
- ffmpeg y ffprobe en PATH
|
|
- Paquetes Python (instala en el venv):
|
|
- requests, srt, transformers, sentencepiece, torch (si usas MarianMT en CPU), etc.
|
|
|
|
Uso recomendado (ejemplos)
|
|
|
|
1) Ejecutar en dry-run para ver los comandos que se ejecutarán:
|
|
|
|
```bash
|
|
.venv/bin/python whisper_project/run_full_pipeline.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 real (traducción local y reemplazo de la pista de audio):
|
|
|
|
```bash
|
|
.venv/bin/python whisper_project/run_full_pipeline.py \
|
|
--video dailyrutines.mp4 \
|
|
--kokoro-endpoint "https://kokoro.example/api/v1/audio/speech" \
|
|
--kokoro-key "$KOKORO_TOKEN" \
|
|
--voice em_alex \
|
|
--whisper-model base
|
|
```
|
|
|
|
Flags importantes del orquestador (`run_full_pipeline.py`)
|
|
- `--translate-method` : `local` | `gemini` | `none`. Por defecto `local` (MarianMT). Si eliges `gemini` necesitas `--gemini-key`.
|
|
- `--gemini-key` : API key para Gemini (si usas `--translate-method=gemini`).
|
|
- `--mix` : en lugar de reemplazar, mezcla el audio sintetizado con la pista original. Ajusta volumen de fondo con `--mix-background-volume`.
|
|
- `--mix-background-volume` : volumen de la pista original cuando se mezclan (0.0 - 1.0).
|
|
- `--keep-chunks` : conserva los WAV por segmento (útil para debugging).
|
|
- `--keep-temp` : no borra el directorio temporal final (conserva `dub_final.wav` y chunks si `--keep-chunks`).
|
|
- `--dry-run` : sólo muestra los comandos que se ejecutarían.
|
|
|
|
Uso directo de `srt_to_kokoro.py` (si ya tienes un SRT traducido)
|
|
|
|
```bash
|
|
.venv/bin/python 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
|
|
```
|
|
|
|
Notas y troubleshooting
|
|
- Si el endpoint TTS devuelve `400 Bad Request` suele ser por quoting/format del `--payload-template`. `run_full_pipeline.py` ya maneja el quoting para el caso común.
|
|
- Si `ffmpeg` muestra mensajes sobre "Too many bits" o "clamping" al crear el AAC, es una advertencia por bitrate; el MP4 suele generarse correctamente.
|
|
- Si la síntesis remota falla por autenticación, revisa la clave (`--kokoro-key`) o usa `--translate-method local` y prueba con un proveedor de TTS alternativo en `srt_to_kokoro.py`.
|
|
|
|
Siguientes mejoras sugeridas
|
|
- Validar que `--mix` y `--replace-original` no se usen simultáneamente y añadir una opción explícita mutuamente exclusiva.
|
|
- Añadir soporte para más backends de TTS (local TTS, Whisper TTS engines, o Argos local si se desea).
|
|
|
|
Licencia y seguridad
|
|
- Este repositorio contiene scripts de ejemplo. Cuida tus claves API y no las subas a repositorios públicos.
|
|
|
|
Si quieres, añado ejemplos concretos de comandos con `--mix` o con `--keep-temp` y un breve archivo `EXAMPLES.md` con variantes más avanzadas. |