Cesar Mendivil
c22767d3d4
- Updated `srt_to_kokoro.py` to provide a CLI entrypoint with argument parsing. - Enhanced error handling and logging for better user feedback. - Introduced a compatibility layer for legacy scripts. - Added configuration handling via `config.toml` for endpoint and API key. - Improved documentation and comments for clarity. Enhance PipelineOrchestrator with in-process transcriber fallback - Implemented `InProcessTranscriber` to handle transcription using multiple strategies. - Added support for `srt_only` flag to return translated SRT without TTS synthesis. - Improved error handling and logging for transcriber initialization. Add installation and usage documentation - Created `INSTALLATION.md` for detailed setup instructions for CPU and GPU environments. - Added `USAGE.md` with practical examples for common use cases and command-line options. - Included a script for automated installation and environment setup. Implement SRT burning utility - Added `burn_srt.py` to facilitate embedding SRT subtitles into video files using ffmpeg. - Provided command-line options for style and codec customization. Update project configuration management - Introduced `config.py` to centralize configuration loading from `config.toml`. - Ensured that environment variables are not read to avoid implicit overrides. Enhance package management with `pyproject.toml` - Added `pyproject.toml` for modern packaging and dependency management. - Defined optional dependencies for CPU and TTS support. Add smoke test fixture for SRT - Created `smoke_test.srt` as a sample subtitle file for testing purposes. Update requirements and setup configurations - Revised `requirements.txt` and `setup.cfg` for better dependency management and clarity. - Included installation instructions for editable mode and local TTS support.
215 lines
7.8 KiB
Markdown
215 lines
7.8 KiB
Markdown
# Instalación y Quickstart
|
|
|
|
Este documento explica las opciones de instalación y comandos recomendados para entornos CPU-only y entornos con GPU. Incluye instrucciones para Coqui TTS (local) y el uso del `config.toml` para Kokoro.
|
|
|
|
Requisitos mínimos
|
|
- Python 3.11 (recomendado para compatibilidad con Coqui TTS y dependencias).
|
|
- `ffmpeg` y `ffprobe` en PATH.
|
|
|
|
Instalación recomendada (CPU-only)
|
|
|
|
1) Crear virtualenv y activarlo:
|
|
|
|
```bash
|
|
python3.11 -m venv .venv311
|
|
source .venv311/bin/activate
|
|
python -m pip install --upgrade pip
|
|
```
|
|
|
|
2) Instalar PyTorch CPU explícito (recomendado):
|
|
|
|
```bash
|
|
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
|
|
```
|
|
|
|
3) Instalar el resto de dependencias (pinned):
|
|
|
|
```bash
|
|
python -m pip install -r requirements.txt
|
|
```
|
|
|
|
4) (Opcional) instalar dependencias del paquete editables:
|
|
|
|
```bash
|
|
python -m pip install -e .
|
|
```
|
|
|
|
Instalación para GPU
|
|
|
|
- Si dispones de GPU y quieres aprovecharla, instala la rueda de PyTorch adecuada para tu versión de CUDA siguiendo las instrucciones oficiales en https://pytorch.org/ y luego instala el resto de dependencias.
|
|
|
|
Coqui TTS (local)
|
|
|
|
- Coqui TTS permite ejecutar TTS localmente sin depender de un servicio externo.
|
|
- Ten en cuenta:
|
|
- Algunos modelos son pesados (centenas de MB). Hay variantes optimizadas para CPU (p.ej. ~326 MB fp32).
|
|
- La primera ejecución puede descargar modelos; para uso en CI descárgalos y cachea con anticipación.
|
|
|
|
Instalación:
|
|
|
|
```bash
|
|
# dentro del entorno virtual
|
|
python -m pip install -r whisper_project/requirements.txt
|
|
```
|
|
|
|
Uso del `config.toml`
|
|
|
|
- Coloca `config.toml` en la raíz con la sección `[kokoro]`. Usa `config.toml.example` como plantilla.
|
|
- Precedencia por defecto: CLI > `config.toml` > ENV (modo `override-env`).
|
|
|
|
Comandos de ejemplo
|
|
|
|
- Ejecutar pipeline real con traducción local:
|
|
|
|
```bash
|
|
.venv311/bin/python -m whisper_project.main --video output/dailyrutines/dailyrutines.mp4 --translate-method local
|
|
```
|
|
|
|
- Ejecutar smoke test (fixture corto):
|
|
|
|
```bash
|
|
.venv311/bin/python -m whisper_project.main --video tests/fixtures/smoke_fixture.mp4 --translate-method none --dry-run
|
|
```
|
|
|
|
- Forzar instalación CPU-only de PyTorch y dependencies en una sola línea:
|
|
|
|
```bash
|
|
python -m pip install --index-url https://download.pytorch.org/whl/cpu -r requirements.txt
|
|
```
|
|
|
|
Pinning y reproducibilidad
|
|
|
|
- `requirements.txt` (raíz) y `whisper_project/requirements.txt` contienen pins orientados a CPU. Revisa y actualiza si tu entorno requiere otras variantes.
|
|
- Para CI reproducible, genera un lockfile con `pip-compile` o fija versiones a través de `pip freeze` en tu pipeline.
|
|
|
|
Notas y recomendaciones
|
|
|
|
- Para entornos con recursos limitados usa modelos `small` o `base`.
|
|
- Si necesitas ayuda para crear un Dockerfile o un job de CI (GitHub Actions) para pre-cachear modelos, lo puedo generar.
|
|
|
|
## Instalación editable (pip install -e .) usando `pyproject.toml`
|
|
|
|
Este repositorio incluye un `pyproject.toml` para soportar instalaciones en modo editable (`pip install -e .`).
|
|
La instalación editable facilita el desarrollo (cambios en el código se reflejan sin reinstalar).
|
|
|
|
Recomendaciones y ejemplos (CPU-first)
|
|
|
|
1) Activa tu entorno virtual (ejemplo `.venv311`) y actualiza pip:
|
|
|
|
```bash
|
|
source .venv311/bin/activate
|
|
python -m pip install --upgrade pip
|
|
```
|
|
|
|
2) Instala primero la rueda CPU de PyTorch (recomendado):
|
|
|
|
```bash
|
|
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
|
|
```
|
|
|
|
3) Instala el paquete en modo editable con el extra `cpu` (y opcionalmente `tts`):
|
|
|
|
```bash
|
|
python -m pip install -e .[cpu]
|
|
# o para incluir soporte TTS local:
|
|
python -m pip install -e .[cpu,tts]
|
|
```
|
|
|
|
Notas importantes
|
|
- `pip install -e .[cpu]` usará el `pyproject.toml` para leer metadatos y extras definidos allí.
|
|
- Si prefieres instalar PyTorch y otras dependencias con un único comando que fuerce las ruedas CPU, puedes usar:
|
|
|
|
```bash
|
|
python -m pip install --index-url https://download.pytorch.org/whl/cpu -e .[cpu,tts]
|
|
```
|
|
|
|
- Asegúrate de tener `setuptools` y `wheel` actualizados (el `pyproject.toml` ya declara `setuptools` como build-system). Si tienes problemas al instalar en modo editable, ejecuta:
|
|
|
|
```bash
|
|
python -m pip install --upgrade setuptools wheel
|
|
```
|
|
|
|
- El extra `tts` instala dependencias opcionales para Coqui TTS y reproducción (puede descargar modelos a la primera ejecución).
|
|
|
|
- Recuerda no subir `config.toml` con credenciales reales; usa `config.toml.example`.
|
|
|
|
|
|
## Script de instalación automática: `scripts/auto_install.sh`
|
|
|
|
Se incluye un script helper en `scripts/auto_install.sh` para automatizar la creación del virtualenv e instalación de dependencias con opciones CPU/GPU y soporte para TTS local o uso de Kokoro remoto.
|
|
|
|
Propósito
|
|
- Simplificar la puesta en marcha del proyecto en entornos de desarrollo.
|
|
- Permitir elegir instalación CPU-only (recomendado) o GPU, y decidir si instalar dependencias para Coqui TTS local.
|
|
|
|
Ubicación
|
|
- `scripts/auto_install.sh` (hacer ejecutable con `chmod +x scripts/auto_install.sh`).
|
|
|
|
Uso (resumen)
|
|
|
|
```bash
|
|
# instalar en venv por defecto (.venv311), CPU y soporte TTS local:
|
|
./scripts/auto_install.sh --cpu --local-tts
|
|
|
|
# instalar en venv personalizado, GPU y usar Kokoro remoto (no instala TTS extra):
|
|
./scripts/auto_install.sh --venv .venv_gpu --gpu --kokoro
|
|
```
|
|
|
|
Opciones principales
|
|
- `--venv PATH` : ruta del virtualenv a crear/usar (default: `.venv311`).
|
|
- `--cpu` : instalar la build CPU de PyTorch (usa índice CPU de PyTorch).
|
|
- `--gpu` : intentar instalar PyTorch (selección de rueda GPU queda a cargo de pip/usuario si requiere CUDA específica).
|
|
- `--torch-version V` : opción para forzar una versión concreta de `torch`.
|
|
- `--local-tts` : instala extras para Coqui TTS (`tts` extra) y soporte de reproducción.
|
|
- `--kokoro` : indica que usarás Kokoro remoto (no fuerza instalación de TTS local).
|
|
- `--no-editable` : instala dependencias sin modo editable (usa `requirements.txt`).
|
|
|
|
Qué hace internamente
|
|
- Crea (si no existe) y activa el virtualenv.
|
|
- Actualiza `pip`, `setuptools` y `wheel`.
|
|
- Instala `torch` según la opción `--cpu`/`--gpu` y la `--torch-version` si se proporciona.
|
|
- Instala el paquete en modo editable (`pip install -e .`) y añade extras `cpu` y/o `tts` según flags.
|
|
- Si existe `config.toml.example` y no hay `config.toml`, copia el ejemplo a `config.toml` para que lo rellenes con tus credenciales.
|
|
|
|
Ejemplos
|
|
|
|
- Instalación mínima CPU y editable (sin TTS):
|
|
|
|
```bash
|
|
./scripts/auto_install.sh --cpu
|
|
```
|
|
|
|
- Instalación CPU y extras para Coqui TTS local:
|
|
|
|
```bash
|
|
./scripts/auto_install.sh --cpu --local-tts
|
|
```
|
|
|
|
- Instalación editable en un venv personalizado e instalar PyTorch GPU (nota: el script no elige la rueda CUDA exacta por ti):
|
|
|
|
```bash
|
|
./scripts/auto_install.sh --venv .venv_gpu --gpu
|
|
```
|
|
|
|
Notas y recomendaciones
|
|
- Recomendado: para evitar problemas con ruedas de PyTorch, instala primero la rueda CPU/GPU apropiada siguiendo https://pytorch.org/ y luego ejecuta `--cpu`/`--gpu` sin forzar versión en el script.
|
|
- Si necesitas reproducibilidad en CI, considera usar el comando combinado que fuerza el índice CPU para todo:
|
|
|
|
```bash
|
|
python -m pip install --index-url https://download.pytorch.org/whl/cpu -e .[cpu,tts]
|
|
```
|
|
|
|
- Si se detectan errores de compilación de dependencias nativas (p.ej. `av`, `soundfile`), instala las dependencias de sistema necesarias (headers de libav, libsndfile, etc.) antes de repetir la instalación.
|
|
|
|
- El script no elimina ni borra artefactos; solo prepara el entorno. Para ejecutar la pipeline usa la CLI:
|
|
|
|
```bash
|
|
.venv311/bin/python -m whisper_project.main --video path/to/video.mp4 --translate-method local
|
|
```
|
|
|
|
Soporte y troubleshooting
|
|
- Si la instalación falla en una dependencia binaria, pega la salida de error y te indico el paquete del sistema que falta (por ejemplo `libsndfile1-dev`, `libavcodec-dev`, etc.).
|
|
- Si el script no encuentra `python3.11`, intenta `python3` o instala Python 3.11 en el sistema.
|
|
|
|
Fin de la documentación del script.
|