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

# 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

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:

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

Ejemplo si tu usuario es juan123:

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:

# 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

# 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//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:

'lan': 'en',

Cambia a:

'lan': 'es',  # Español

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

Luego:

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:

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//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! 🚀