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