# 📦 SimulStreaming ASR — Space Deployment Package

**Estado**: ✅ LISTO PARA DESPLEGAR

**Ubicación**: `/gpfs/projects/bsc88/speech/TTS/repos/Streaming_Mamba/SimulStreaming/space/`

---

## 📂 Estructura de archivos

```
space/
├── 📄 app.py                      # FastAPI + Gradio UI (interfaz web)
├── 📄 server_wrapper.py           # Wrapper de SimulWhisper (procesamiento)
├── 📄 requirements.txt            # Dependencias Python
├── 📄 Dockerfile                  # Configuración del contenedor Docker
├── 📄 .dockerignore               # Archivos a excluir en Docker
├── 📄 space.yaml                  # Metadatos del Space (HF)
├── 📄 .gitattributes              # Git LFS para modelos grandes
├── 📄 .gitignore                  # Archivos a no versionar en Git
│
├── 📚 README.md                   # Documentación técnica completa
├── 📚 DEPLOYMENT.md               # Guía rápida (5 pasos)
├── 📚 DEPLOY_STEP_BY_STEP.md     # Guía detallada paso-a-paso (RECOMENDADA)
├── 📚 CHECKLIST.md                # Checklist de predeployment
│
└── 🔧 setup.sh                    # Script helper para setup (opcional)
```

---

## 🚀 Inicio rápido

### Para principiantes (RECOMENDADO):
1. Lee: `DEPLOY_STEP_BY_STEP.md` ← START HERE
2. Sigue cada paso en orden
3. ¡Haz push a HF Spaces!

### Para usuarios avanzados:
1. Lee: `DEPLOYMENT.md` (resumen de 5 pasos)
2. Personaliza si es necesario (idioma, modelo, etc.)
3. Deploy

---

## 🎯 ¿Qué hace cada archivo?

| Archivo | Propósito |
|---------|-----------|
| `app.py` | **Aplicación web**: FastAPI backend + Gradio frontend. Expone endpoints `/api/*` y UI para grabar/transcribir. |
| `server_wrapper.py` | **Procesamiento ASR**: Inicializa el modelo SimulWhisper, maneja chunks de audio, thread-safe. |
| `requirements.txt` | **Dependencias**: Gradio, FastAPI, Librosa, Soundfile, Torch, etc. |
| `Dockerfile` | **Containerización**: Especifica cómo construir la imagen Docker para HF Spaces. |
| `.dockerignore` | **Optimización**: Excluye archivos innecesarios de la imagen Docker. |
| `space.yaml` | **Configuración HF**: Metadatos (title, SDK, tags, hardware). |
| `.gitattributes` | **Git LFS**: Configura manejo de archivos grandes (*.pt). |
| `.gitignore` | **Git**: Evita commitear archivos temporales/cachés. |

---

## 🔧 Personalización

### Cambiar idioma
Edita `server_wrapper.py` línea ~40:
```python
'lan': 'es',  # Español (en, de, fr, pt, etc.)
```

### Cambiar modelo
Edita `server_wrapper.py` línea ~34:
```python
model_path='./small.pt',  # tiny, base, small, medium, large-v3
```

### Cambiar puerto
Edita `app.py` línea final:
```python
demo.launch(server_name="0.0.0.0", server_port=7860)
```

---

## 📋 Flujo de despliegue

```
1. Genera token HF (https://huggingface.co/settings/tokens)
   ↓
2. Login: huggingface-cli login
   ↓
3. Crea Space en https://huggingface.co/spaces
   ↓
4. git clone https://huggingface.co/spaces/<user>/<space-name>
   ↓
5. cp space/* . (copiar archivos)
   ↓
6. git add . && git commit && git push
   ↓
7. Espera 5-15 min a que Docker build + modelo cargue
   ↓
8. ✅ ¡Space corriendo! https://huggingface.co/spaces/<user>/<space-name>
```

---

## 🌐 API Reference

Puedes llamar los endpoints directamente (útil para clients personalizados):

```bash
# Reset (nueva sesión)
curl -X POST https://<user>-<space-name>.hf.space/api/reset

# Procesar chunk (enviar audio WAV 16kHz)
curl -X POST -F "file=@chunk.wav" https://<user>-<space-name>.hf.space/api/chunk

# Finalizar (procesar último chunk + retornar resultado final)
curl -X POST https://<user>-<space-name>.hf.space/api/finish
```

---

## ✅ Requisitos comprobados

- ✅ FastAPI corriendo en puerto 7860
- ✅ Gradio montado en `/` con UI interactiva
- ✅ JavaScript para grabar audio + enviar chunks
- ✅ Endpoint `/api/chunk` para procesar chunks incrementales
- ✅ Endpoint `/api/finish` para finalizar sesión
- ✅ Endpoint `/api/reset` para reiniciar
- ✅ SimulWhisper integrado y thread-safe
- ✅ Dockerfile optimizado para HF Spaces
- ✅ Git LFS configurado para modelos grandes
- ✅ Documentación completa en 4 archivos

---

## 🎓 Documentos de referencia

1. **`DEPLOY_STEP_BY_STEP.md`** ← **LEER PRIMERO** (paso-a-paso con explicaciones)
2. **`DEPLOYMENT.md`** (resumen rápido 5 pasos)
3. **`README.md`** (detalles técnicos, troubleshooting)
4. **`CHECKLIST.md`** (verifica antes de hacer push)

---

## 🐛 Soporte rápido

| Problema | Archivo a revisar |
|----------|------------------|
| ¿Cómo hago deploy? | `DEPLOY_STEP_BY_STEP.md` |
| ¿Qué si algo falla? | `README.md` → Sección Troubleshooting |
| ¿Idioma diferente? | `DEPLOYMENT.md` → "Cambios si necesitas otro idioma" |
| ¿Memoria insuficiente? | Edita `server_wrapper.py` use modelo `small.pt` |
| ¿No funciona audio? | `README.md` → "No se puede acceder al micrófono" |

---

## 🎉 Resultado esperado

Después de desplegar exitosamente:

1. Navega a: `https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr`
2. Ves un botón **"Start Recording"**
3. Pulsa → captura audio desde tu micrófono
4. Mientras hablas → transcripción aparece en **tiempo real**
5. Pulsa **"Stop Recording"** → finaliza

**¡Eso es! Tu ASR en streaming está vivo.** 🚀

---

Última actualización: Noviembre 2025