---
title: ASR Annotation Progress
emoji: 📊
colorFrom: yellow
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# ASR Annotation — Team Progress Dashboard

A small FastAPI service that collects **counts-only** progress reports from the ASR
labeling webapp and shows per-annotator and aggregate stats on a live dashboard.

Reports are persisted as one file per annotator (`reports/<slug>.json`) inside a
**private HF Dataset repo**, so progress survives Space restarts/rebuilds (the Space
filesystem itself is ephemeral). **No transcripts or audio are ever sent** — only tallies.

## Endpoints

| Method | Path          | Purpose                                              |
| ------ | ------------- | ---------------------------------------------------- |
| `GET`  | `/`           | Live HTML dashboard (auto-refreshes every 15s).      |
| `GET`  | `/api/stats`  | JSON: all reports + aggregate.                       |
| `POST` | `/report`     | Submit a report. Requires `X-Report-Token` header.   |

### `POST /report` body

```json
{
  "annotator": "Asha",
  "folder": "Folder_19",
  "total": 500,
  "counts": { "pending": 120, "delete": 30, "correct": 300, "to_correct": 25, "edited": 25 },
  "updatedAt": 1719300000000
}
```

## One-time setup

1. **Create a private Dataset** to hold the reports, e.g. `shaanilmo/asr-annotation-progress`
   (the Space also auto-creates it on first boot if your `HF_TOKEN` has write access).
2. **Create this Space** with **SDK = Docker** and push these files (`app.py`,
   `requirements.txt`, `Dockerfile`, this `README.md`).
3. Add the following **Space Secrets** (Settings → Variables and secrets):
   - `HF_TOKEN` — a **write** access token for the account owning the Dataset.
   - `DATASET_REPO` — e.g. `shaanilmo/asr-annotation-progress`.
   - `REPORT_TOKEN` — any shared string; the webapp must send the same value.
4. In the webapp (`webapp/app.js`), set `PROGRESS_ENDPOINT` to
   `https://<your-space-subdomain>.hf.space/report` and `REPORT_TOKEN` to the same value.

## Run locally

```bash
cd hf_space
pip install -r requirements.txt
export HF_TOKEN=hf_xxx
export DATASET_REPO=shaanilmo/asr-annotation-progress
export REPORT_TOKEN=some-shared-string
uvicorn app:app --port 7860
# dashboard: http://localhost:7860/
```