README.md

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

```bash
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:

```bash
# 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`:

```bash
# 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`:

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

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

```bash
# 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`:

```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

```bash
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/<tu-usuario>/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:

```bash
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:

```bash
# 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](https://huggingface.co/docs/hub/spaces-overview)
- [Gradio Docs](https://www.gradio.app)
- [SimulWhisper GitHub](https://github.com/backspacetg/simul_whisper)
- [Whisper Streaming GitHub](https://github.com/ufal/whisper_streaming)

---

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