DEPLOY_STEP_BY_STEP.md

# 🚀 Cómo Desplegar tu ASR en Hugging Face Spaces

## ✅ Estado actual

Todo está listo en: `/gpfs/projects/bsc88/speech/TTS/repos/Streaming_Mamba/SimulStreaming/space/`

**Archivos del Space:**
- `app.py` → FastAPI + Gradio UI
- `server_wrapper.py` → Wrapper de SimulWhisper + threading
- `requirements.txt` → Dependencias Python
- `Dockerfile` → Configuración del contenedor
- `.dockerignore` → Archivos a ignorar en Docker
- `space.yaml` → Configuración metadata del Space
- `README.md` → Documentación completa
- `DEPLOYMENT.md` → Guía rápida

---

## 📋 Requisitos previos (⏱️ 5 min)

Antes de empezar, necesitas:

### 1. Cuenta en Hugging Face
- Ve a https://huggingface.co y crea una cuenta (si no la tienes)
- Confirma tu email

### 2. Generar un token de acceso
- Accede a https://huggingface.co/settings/tokens
- Pulsa **"New token"** → Nombre: `simulstreaming-deploy`
- Tipo: **Write** (para poder crear Spaces)
- Crea el token y **cópialo** (no lo pierdes)

### 3. Instalar herramientas en tu máquina local
```bash
# Git (si no lo tienes: https://git-scm.com)
git --version

# Git LFS (para manejar archivos grandes)
git lfs install

# Hugging Face CLI (instala desde pip)
pip install --upgrade huggingface-hub

# Verificar
huggingface-cli --version
```

---

## 🎯 Pasos del despliegue (⏱️ 10 min)

### PASO 1: Login en Hugging Face desde tu máquina

```bash
huggingface-cli login
```

Cuando pida el token, pega el que copiaste arriba.

```
Token: [pega-tu-token-aquí]
```

✅ Verás: `Token is valid. Your credentials have been saved.`

### PASO 2: Crea un nuevo Space en Hugging Face

Abre https://huggingface.co/spaces en tu navegador:

1. Pulsa **"Create new Space"** (arriba a la derecha)
2. Rellena:
   - **Space name**: `simulstreaming-asr` (o tu nombre favorito)
   - **License**: MIT (cualquiera está bien)
   - **SDK**: **Docker** (importante)
3. Pulsa **"Create Space"**

Espera 5 segundos a que se cree. Se abrirá una página con tu Space vacío.

### PASO 3: Clon el repositorio del Space a tu máquina

Reemplaza `<tu-usuario>` con tu nombre de usuario en HF:

```bash
git clone https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr
cd simulstreaming-asr
```

Ejemplo si tu usuario es `juan123`:
```bash
git clone https://huggingface.co/spaces/juan123/simulstreaming-asr
cd simulstreaming-asr
```

### PASO 4: Copia los archivos del proyecto

Ejecuta desde dentro del directorio del Space:

```bash
# Copiar todos los archivos de la carpeta space
cp /gpfs/projects/bsc88/speech/TTS/repos/Streaming_Mamba/SimulStreaming/space/* .

# Verificar que están todos
ls -la
```

Deberías ver:
```
.dockerignore
.gitattributes
.gitignore
Dockerfile
README.md
DEPLOYMENT.md
app.py
server_wrapper.py
requirements.txt
space.yaml
```

### PASO 5: Versionar en Git

```bash
# Dentro del directorio del Space
git add .
git commit -m "Initial commit: SimulStreaming ASR with Gradio UI"
git push
```

**Importante**: Si durante `git push` pide login, usa:
- Username: tu nombre de usuario en HF
- Password: el token que copiaste (pégalo aquí)

### PASO 6: ¡Esperar a que se despliegue!

Una vez hiciste push, el Space empieza a construirse:

1. Abre https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr en el navegador
2. Verás el estado:
   - 🟡 **Building** → Construyendo Docker (~3 min)
   - 🟡 **Running** → Descargando modelo y inicializando (~5-10 min la primera vez)
   - 🟢 **Running** → ¡Listo! El Space está activo

**Monitorea los logs** si hay errores:
- En la página del Space, busca la sección **"Logs"** o **"Console"**
- Ahí verás qué está pasando

---

## ✨ ¡Prueba tu Space!

Cuando esté verde (**Running**), haz clic en el botón **"Share"** → copia la URL pública, o simplemente accede a:

```
https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr
```

### En la interfaz:

1. **"Start Recording"** → Pulsa para empezar a grabar
2. **Habla cerca del micrófono** (permite acceso al micro en tu navegador)
3. **Verás la transcripción en tiempo real** en el panel de abajo
4. **"Stop Recording"** → Pulsa para terminar

---

## 🔧 Personalización (Opcional)

### Cambiar idioma (p. ej., a Español)

Edita `space/server_wrapper.py` en tu máquina local:

Busca la línea:
```python
'lan': 'en',
```

Cambia a:
```python
'lan': 'es',  # Español
```

Otros idiomas: `'en'` (inglés), `'de'` (alemán), `'fr'` (francés), `'pt'` (portugués), etc.

Luego:
```bash
git add server_wrapper.py
git commit -m "Change language to Spanish"
git push
```

El Space se actualizará automáticamente.

### Usar un modelo más pequeño

Si el Space se queda sin memoria, edita `space/server_wrapper.py`:

```python
model_path='./small.pt',  # En vez de 'large-v3.pt'
```

**Tamaños:**
- `tiny.pt` → ~39 MB (rápido, menos precisión)
- `base.pt` → ~140 MB (buena balance)
- `small.pt` → ~461 MB (mejor)
- `medium.pt` → ~1.5 GB (muy bueno)
- `large-v3.pt` → ~3 GB (mejor, pero pesado)

---

## 🐛 Troubleshooting

| Problema | Solución |
|----------|----------|
| **"ImportError: No module named 'simul_whisper'"** | Asegúrate de que `server_wrapper.py` importa desde la ruta correcta. Si el código está en una carpeta diferente, actualiza el import. |
| **"Model download timeout"** | El modelo es grande (~3GB). Espera más o usa un modelo más pequeño (`small.pt`). |
| **"Out of memory"** | Usa `small.pt` o `tiny.pt` en vez de `large-v3.pt`. |
| **No se captura audio** | 1) Asegúrate HTTPS (HF Spaces usa HTTPS). 2) Permite acceso al micrófono en el navegador. 3) Revisa la consola del navegador (F12 → Console) para ver errores JS. |
| **"Connection refused"** | El Space está construyéndose o hay error en startup. Espera y revisa los Logs. |
| **Transcripción lenta** | Aumenta `min_chunk_size` en `server_wrapper.py` o reduce `audio_max_len`. |

---

## 📚 URLs útiles

- **Tu Space**: https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr
- **Docs de HF Spaces**: https://huggingface.co/docs/hub/spaces-overview
- **Docs de Gradio**: https://www.gradio.app
- **API referencia FastAPI**: https://fastapi.tiangolo.com

---

## 🎓 Próximas mejoras (opcional)

- Mostrar **timestamps** de cada palabra transcrita
- Selector de **idioma** dinámico en la UI
- Historial de transcripciones guardadas
- Exportar a **SRT** o **VTT**
- Soporte para **traducción** (no solo transcripción)

---

## 💬 Soporte

Si tienes problemas:

1. **Revisa los Logs** en la página del Space (sección Logs)
2. **Lee el archivo `README.md`** para más detalles técnicos
3. **Abre un issue** en el repo de `SimulStreaming` o `Whisper Streaming`

---

¡Éxito con tu ASR en Spaces! 🚀