README.md

---
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](https://huggingface.co/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:
   ```bash
   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+.

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

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

```json
[
  {"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](https://huggingface.co/Qwen/Qwen3-ForcedAligner-0.6B)
by the Qwen team, Alibaba Cloud. Library: [qwen-asr](https://pypi.org/project/qwen-asr/)
/ [QwenLM/Qwen3-ASR](https://github.com/QwenLM/Qwen3-ASR).