submaster/README.md

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

python3.11 -m venv .venv311
source .venv311/bin/activate
python -m pip install --upgrade pip

2. Instalar PyTorch (CPU wheel) explícitamente:

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu

3. Instalar las demás dependencias pinned:

python -m pip install -r requirements.txt

4. (Opcional) instalar deps internas del paquete editable:

python -m pip install -e .

Nota: con pyproject.toml en la raíz ahora puedes instalar el paquete en modo editable usando:

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

.venv311/bin/python -m whisper_project.main \
  --video output/dailyrutines/dailyrutines.mp4 \
  --translate-method local

Ejemplo sin traducción (solo SRT->TTS):

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

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

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

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

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

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