---
name: voxcpm
description: Genera narración/voz en off para Reels y videos usando VoxCPM2 (Text-to-Speech 2B parámetros, 30 idiomas, 48kHz). Puede clonar voces, crear voces nuevas desde descripción, y controlar emoción/ritmo. Usar cuando el usuario pide generar audio, narración, voz en off, o locución para un Reel, video o contenido de audio. Se integra directamente con reel-generator para producir Reels con voz incluida.
---

# VoxCPM — Skill de Generación de Voz para Stepflow

Motor de Text-to-Speech de 2B parámetros. Genera narración profesional para Reels directamente desde el caption del producto.

## Capacidades

| Modo | Descripción | Uso en Stepflow |
|------|-------------|-----------------|
| **Text-to-Speech básico** | Texto → Audio 48kHz | Narrar caption del producto |
| **Voice Design** | Descripción → Voz nueva | Crear voz de marca para el cliente |
| **Voice Cloning** | Audio de referencia → Clonar voz | Usar voz real del dueño del negocio |
| **Controllable Cloning** | Clonar + ajustar emoción/ritmo | Voz entusiasta para promociones |

## Idiomas soportados
30 idiomas incluyendo Español, Inglés, Portugués, Francés, Italiano.

## Instalación

### Requisitos
- Python ≥ 3.10 ✅ (sistema tiene 3.12)
- PyTorch ≥ 2.5.0 con CUDA 12.0+ (para GPU) o CPU (más lento)
- ~8GB disco para el modelo

### Instalar con GPU (NVIDIA CUDA)
```bash
# 1. Instalar PyTorch con CUDA
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 2. Instalar VoxCPM
pip install voxcpm
```

### Instalar solo CPU (sin GPU)
```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install voxcpm
```

## Uso básico

```python
from voxcpm import VoxCPM
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)

# TTS básico
wav = model.generate(text="Nueva colección de carteras artesanales. Calidad y estilo.")
model.save_wav(wav, "narration.wav")
```

## Integración con reel-generator

El script `scripts/generate_narration.py` toma el caption de Notion y genera el audio WAV listo para FFmpeg.

```bash
python skills/voxcpm/scripts/generate_narration.py \
  --text "Las mejores carteras artesanales de Saladillo. Mirá nuestra nueva colección." \
  --output data/clients/amapola/reels/narration.wav \
  --style "warm, professional, Argentinian Spanish"
```

## Pipeline completo con Reel

```bash
# 1. Generar narración
python skills/voxcpm/scripts/generate_narration.py --client amapola --notion-page-id <id>

# 2. Generar Reel con esa narración como audio
python skills/reel-generator/scripts/generate_reel.py \
  --client amapola \
  --audio data/clients/amapola/reels/narration.wav \
  --duration 30
```

## Voice Design para clientes

Crear una voz única para cada cliente usando descripción natural:

```python
# Voz para Amapola (tienda de carteras elegante, Saladillo)
wav = model.generate(
    text="Nueva colección de carteras artesanales.",
    voice_description="A warm, elegant Argentine woman in her 30s, speaking confidently and professionally about luxury leather goods."
)
```

## Notas de performance

| Hardware | RTF (Real-Time Factor) |
|----------|----------------------|
| RTX 4090 | ~0.3x (muy rápido) |
| RTX 3060 | ~0.8x |
| CPU (i7) | ~3-5x (más lento que real-time) |

RTF < 1.0 = más rápido que tiempo real. Para un audio de 15s: GPU genera en ~4s, CPU en ~75s.

## Modelo descargado automáticamente
El modelo se descarga de HuggingFace la primera vez (~4GB). Se cachea en `~/.cache/huggingface/`.