README.md

metadata

title: Qwen3 Forced Aligner
emoji: 🎯
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.17.3
python_version: '3.11'
app_file: app.py
pinned: false
license: apache-2.0
suggested_hardware: t4-small
short_description: Text-audio forced alignment via Qwen3-ForcedAligner-0.6B

Qwen3 Forced Aligner

A Gradio Space wrapping Qwen/Qwen3-ForcedAligner-0.6B: give it audio + the matching transcript, get back per-unit start_time / end_time alignment. Works both as an interactive web UI and as a plain HTTP/Python API (the whole point — see below).

Supported languages

Chinese, English, Cantonese, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Vietnamese.

Note: the model card lists 11 officially-evaluated languages (all of the above except Vietnamese). Vietnamese is exposed in the UI on request, but alignment quality for it is not guaranteed by the model authors.

Project layout

.
├── app.py              # Gradio Blocks UI; also defines the /align API endpoint
├── aligner.py           # Model loading + align() wrapper (device/dtype auto-detect)
├── pyproject.toml       # Canonical dependency list, for local dev (uv / pip install -e .)
├── requirements.txt     # What the HF Space build actually installs
├── examples/
│   └── client_example.py  # Calls a deployed Space's API via gradio_client
└── README.md             # This file (doubles as the Space's model card / metadata)

Deploying to Hugging Face Spaces

1. Create a new Space at https://huggingface.co/new-space, SDK = Gradio, hardware = a GPU tier (e.g. T4 small) — CPU works but is slow for a ~0.6B model doing repeated inference.
2. Push this repo's contents to the Space's git remote:

   git remote add space https://huggingface.co/spaces/<your-username>/<space-name>
   git push space main
   

   (Or use the Hugging Face web UI's "Add file" / drag-and-drop.)
3. The Space reads requirements.txt to install dependencies and launches app.py automatically. First boot will be slow while it downloads the model weights; subsequent restarts are cached.

Local development

Use Python 3.10 or 3.11 — soynlp (a transitive dependency pulled in by qwen-asr) fails to build on 3.12+.

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .
python app.py

Runs on http://localhost:7860. Without a CUDA GPU, aligner.py falls back to CPU/fp32 (or MPS/fp32 on Apple Silicon) automatically — functional, but much slower than the intended T4/A10G deployment.

Using the Space as an API

Gradio auto-generates an API for every event handler that sets api_name; this app's "Align" button is registered as api_name="align". Once deployed, click "Use via API" at the bottom of the Space page for live, copy-pasteable request docs, or use the gradio_client Python package:

from gradio_client import Client, handle_file

client = Client("<your-username>/<space-name>")

table, raw_json = client.predict(
    audio=handle_file("path/or/url/to/audio.wav"),
    text="甚至出现交易几乎停滞的情况。",
    language="Chinese",
    api_name="/align",
)
print(raw_json)

See examples/client_example.py for a runnable version of this. You can also call the same endpoint from any language over plain HTTP — the "Use via API" page shows the exact POST request format.

Response shape

raw_json is a list of aligned spans:

[
  {"index": 0, "text": "甚", "start_time": 0.16, "end_time": 0.32},
  {"index": 1, "text": "至", "start_time": 0.32, "end_time": 0.48}
]

Configuration

• ALIGNER_MODEL_ID (env var, optional): override the HF model repo id loaded by aligner.py. Defaults to Qwen/Qwen3-ForcedAligner-0.6B.

Credits

Model: Qwen/Qwen3-ForcedAligner-0.6B by the Qwen team, Alibaba Cloud. Library: qwen-asr / QwenLM/Qwen3-ASR.