# Whisper Project (pipeline multimedia) Resumen rápido ---------------- Canalización para: extraer audio de vídeo -> transcripción -> (opcional) traducción -> generar SRT -> sintetizar por segmentos (Kokoro o TTS local) -> reemplazar pista de audio -> quemar subtítulos. Este repo prioriza instalaciones CPU-first por defecto. En `requirements.txt` y `whisper_project/requirements.txt` encontrarás pins y recomendaciones para instalaciones CPU-only. Quick start (recomendado para CPU) --------------------------------- 1. Crear y activar virtualenv (Python 3.11 recomendado): ```bash python3.11 -m venv .venv311 source .venv311/bin/activate python -m pip install --upgrade pip ``` 2. Instalar PyTorch (CPU wheel) explícitamente: ```bash python -m pip install torch --index-url https://download.pytorch.org/whl/cpu ``` 3. Instalar las demás dependencias pinned: ```bash python -m pip install -r requirements.txt ``` 4. (Opcional) instalar deps internas del paquete editable: ```bash python -m pip install -e . ``` Nota: con `pyproject.toml` en la raíz ahora puedes instalar el paquete en modo editable usando: ```bash python -m pip install -e . ``` esto usará el `pyproject.toml` (TOML) como fuente de metadatos y extras. Ejecutar la pipeline (ejemplo) ------------------------------ Usando `config.toml` en la raíz (si tienes Kokoro): ```bash .venv311/bin/python -m whisper_project.main \ --video output/dailyrutines/dailyrutines.mp4 \ --translate-method local ``` Ejemplo sin traducción (solo SRT->TTS): ```bash .venv311/bin/python -m whisper_project.main --video input.mp4 --translate-method none ``` Uso de `config.toml` -------------------- Coloca un `config.toml` en la raíz con: ```toml [kokoro] endpoint = "https://kokoro.example/synthesize" api_key = "sk-..." voice = "em_anna" model = "tacotron2" ``` El CLI usa la precedencia: CLI > `config.toml` > ENV (modo `override-env` por defecto). Coqui TTS (local) vs Kokoro (remoto) ----------------------------------- - Kokoro: cliente HTTP que sintetiza por segmento. Bueno si tienes endpoint estable y quieres offload. - Local Coqui `TTS`: útil si no quieres dependencia de red y tienes CPU suficiente; requiere modelos locales y más espacio. Para usar Coqui TTS local, instala `TTS` y dependencias (ya listadas en `whisper_project/requirements.txt`) y ejecuta con la flag `--local-tts`. Recomendaciones y troubleshooting -------------------------------- - Si ves problemas de memoria/tiempo, reduce el modelo de `faster-whisper` a `small` o `base`. - Para problemas con `torch`, instala explicitamente desde el índice CPU (ver arriba). - Si `ffmpeg` falla, revisa que `ffmpeg` y `ffprobe` estén en `PATH`. Más documentación ------------------ Consulta `DOCS/architecture.md` para la documentación técnica completa, diagramas y guías de pruebas. Para instrucciones de instalación y quickstart (CPU/GPU) revisa `DOCS/INSTALLATION.md`. Licencia y contribución ----------------------- Revisa `CONTRIBUTING.md` (si existe) y respeta la política de no subir credenciales en `config.toml` — utiliza `config.toml.example` como plantilla. Fin del README. # 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.