README.md

metadata

title: SimulStreaming ASR
emoji: 🎙️
colorFrom: blue
colorTo: green
sdk: docker
app_file: app.py
pinned: false

SimulStreaming ASR — Hugging Face Space

Interfaz de transcripción en tiempo real (Streaming ASR) basada en SimulWhisper, desplegada como Hugging Face Space.

Características

• Grabación en tiempo real: Captura audio desde el navegador (micrófono).
• Transcripción incremental: Cada fragmento (chunk) se procesa y devuelve texto a medida que hablas.
• Baja latencia: Envío de chunks cada ~1 segundo mediante HTTP POST.
• UI sencilla: Interfaz Gradio con botones Start/Stop.

Estructura de archivos

space/
├── app.py                 # FastAPI + Gradio UI
├── server_wrapper.py      # Wrapper para SimulWhisper + threading safety
├── requirements.txt       # Dependencias
└── README.md              # Este archivo

Requisitos para despliegue en HF Spaces

1. Cuenta en Hugging Face con acceso a Spaces.
2. Git LFS para manejar modelos grandes (el archivo large-v3.pt es ~3GB).
3. Credenciales HF configuradas localmente.

Pasos para desplegar

1. Crear un repositorio nuevo en Hugging Face Spaces

Accede a https://huggingface.co/spaces y crea un nuevo Space:

• Nombre: simulstreaming-asr (o el que prefieras)
• Licencia: Selecciona una (ej. mit)
• Type: Docker o Python (recomendamos Docker para control total)

2. Clonar el repositorio del Space localmente

huggingface-cli repo create simulstreaming-asr --type space --space-sdk docker
git clone https://huggingface.co/spaces/<tu-usuario>/simulstreaming-asr
cd simulstreaming-asr

Reemplaza <tu-usuario> con tu nombre de usuario en HF.

3. Preparar archivos

Copia los archivos del proyecto al repositorio del Space:

# Desde la raíz del repositorio HF Space
cp -r /gpfs/projects/bsc88/speech/TTS/repos/Streaming_Mamba/SimulStreaming/space/* .

# Si usas Docker, copia también estos archivos:
cp Dockerfile .
cp .dockerignore .

4. Descargar y versionar el modelo

El modelo large-v3.pt es muy grande (~3GB). Tienes dos opciones:

Opción A: Descargar el modelo en el Space (recomendado para iteración rápida)

Si el Space está en Docker o Gradio Lite, puedes usar un startup_script:

# Crea un archivo startup_script.sh en la raíz del Space
cat > startup_script.sh << 'EOF'
#!/bin/bash
# Descargar modelo si no existe
if [ ! -f "/app/large-v3.pt" ]; then
    echo "Descargando modelo Whisper large-v3..."
    cd /app
    python -c "
import torch
model = torch.hub.load('openai/whisper', 'large-v3')
# O descargar directamente:
# import urllib.request
# urllib.request.urlretrieve('https://openaipublic.blob.core.windows.net/main/models/gpt-2/python/models/model_117M.json', 'large-v3.pt')
"
fi
echo "Modelo listo."
EOF
chmod +x startup_script.sh

Opción B: Usar un modelo más pequeño

Si large-v3.pt es demasiado grande para el Space, usa medium.pt (1.5GB) o small.pt (461MB). Edita server_wrapper.py:

model_path='./small.pt'  # o 'medium.pt'

5. Git LFS para archivos grandes (si es necesario)

# Instala Git LFS si aún no lo tienes
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

# Dentro del repositorio del Space
git lfs install
git lfs track "*.pt"
echo "*.pt" >> .gitattributes

# Si tienes el modelo localmente
cp /ruta/al/large-v3.pt .
git add large-v3.pt .gitattributes

6. Configuración del Space (si es Docker)

Crea un Dockerfile:

FROM python:3.10-slim

WORKDIR /app

# Instala dependencias del sistema
RUN apt-get update && apt-get install -y \
    libsndfile1 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Copia archivos
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Descarga modelo Whisper (opcional, comentar si está en git-lfs)
# RUN python -c "import torch; torch.hub.load('openai/whisper', 'large-v3')"

EXPOSE 7860

CMD ["python", "app.py"]

Crea un .dockerignore:

.git
.gitignore
__pycache__
*.pyc
.pytest_cache
.env

7. Push al Space

git add .
git commit -m "Initial commit: SimulStreaming ASR with Gradio UI"
git push

HF Spaces compilará el Docker (o instalará dependencias si es Gradio) y desplegará la app.

8. Monitorear el despliegue

• Ve a https://huggingface.co/spaces//simulstreaming-asr
• Verifica que el Space esté en estado "Running" (espera ~5-10 min).
• Si hay errores, revisa los Logs en la UI del Space.

Prueba del Space

1. Una vez que el Space esté corriendo, abre la URL en tu navegador.
2. Pulsa "Start Recording".
3. Habla en el micrófono.
4. Verás la transcripción aparecer en tiempo real.
5. Pulsa "Stop Recording" para finalizar.

Troubleshooting

El modelo tarda mucho en cargar

• Causa: El modelo se descarga / compila la primera vez.
• Solución: Espera. Si es muy lenta, usa un modelo más pequeño (small.pt o medium.pt).

"No se puede acceder al micrófono"

• Causa: HTTPS requerido en navegador.
• Solución: Hugging Face Spaces sirve HTTPS por defecto. Si usas local, accede a https://localhost:7860.

Transcripción lenta o truncada

• Causa: Latencia de red o procesamiento.
• Solución: Aumenta audio_min_len y audio_max_len en server_wrapper.py, o reduce min_chunk_size.

"Model not initialized"

• Causa: La startup no completó.
• Solución: Mira los logs del Space, aumenta el timeout o revisa requirements.txt.

Desarrollo local

Para probar antes de subir a HF Spaces:

cd /gpfs/projects/bsc88/speech/TTS/repos/Streaming_Mamba/SimulStreaming/space

# Instalar dependencias
pip install -r requirements.txt

# Ejecutar app localmente
python app.py

Abre http://localhost:7860 (o https://localhost:7860 si HTTPS).

Configuración personalizada

Edita server_wrapper.py para cambiar:

• model_path: Ruta al modelo Whisper.
• lan: Idioma (e.g., 'es' para español).
• task: 'transcribe' o 'translate'.
• min_chunk_size: Duración mínima del chunk (segundos).

Límites y consideraciones

• GPU: HF Spaces proporciona GPU limitada (si la seleccionas). Verifica espacio en disco.
• Almacenamiento: Modelos grandes requieren >5GB. Asegúrate de usar Git LFS.
• Tiempo de ejecución: HF Spaces tiene límites de tiempo; si el modelo es muy grande, podría timeout.

API HTTP

Si prefieres un cliente diferente (no el JS de Gradio), puedes llamar los endpoints directamente:

# Reset
curl -X POST http://localhost:7860/api/reset

# Enviar chunk (archivo WAV 16kHz)
curl -X POST -F "file=@chunk.wav" http://localhost:7860/api/chunk

# Finalizar transcripción
curl -X POST http://localhost:7860/api/finish

Referencias

• Hugging Face Spaces Docs
• Gradio Docs
• SimulWhisper GitHub
• Whisper Streaming GitHub

---

¿Preguntas? Abre un issue o contacta con el equipo de desarrollo.