START_HERE.md

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

'lan': 'es',  # Español (en, de, fr, pt, etc.)

Cambiar modelo

Edita server_wrapper.py línea ~34:

model_path='./small.pt',  # tiny, base, small, medium, large-v3

Cambiar puerto

Edita app.py línea final:

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

# 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