submaster/DOCS/INSTALLATION.md

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:

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

2. Instalar PyTorch CPU explícito (recomendado):

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

3. Instalar el resto de dependencias (pinned):

python -m pip install -r requirements.txt

4. (Opcional) instalar dependencias del paquete editables:

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:

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

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

• Ejecutar smoke test (fixture corto):

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

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:

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

2. Instala primero la rueda CPU de PyTorch (recomendado):

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

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:

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:

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)

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

./scripts/auto_install.sh --cpu

• Instalación CPU y extras para Coqui TTS local:

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

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

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:

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