qwen-transcribe

Local Mac CLI for transcribing one video file with Qwen3-ASR or selected FunASR backends. A successful run writes a .txt transcript, a timed .srt, and a subtitled review MP4.

Environment

This project uses uv and the project-root .venv.

uv venv .venv
uv sync

Run project commands through uv:

uv run qwen-transcribe --help

Do not use the system python3 command as the project runtime.

Default Models

The default ASR model is:

mlx-community/Qwen3-ASR-1.7B-8bit

SRT output also uses this ForcedAligner model:

Qwen/Qwen3-ForcedAligner-0.6B

The CLI is designed for Apple Silicon Macs with 16GB memory. If the default ASR model is too slow or memory-heavy, pass a different model with --model. The aligner model is internal for now and is prepared by init.

Two FunASR backend aliases are also supported:

funasr:sensevoice
funasr:paraformer-zh

Install the optional FunASR dependencies before using them:

uv sync --extra funasr

funasr:sensevoice uses iic/SenseVoiceSmall with fsmn-vad; it is the better FunASR choice for multilingual audio. SenseVoice does not always return sentence timestamps, so qwen-transcribe falls back to FunASR VAD windows for subtitle timing when needed.

funasr:paraformer-zh uses paraformer-zh with fsmn-vad and ct-punc; it is Chinese-only. For Chinese lecture or course videos, this is the recommended FunASR backend because it provides native sentence timing and generally produces more readable subtitle segmentation.

FunASR subtitles never use the Qwen ForcedAligner. Qwen ForcedAligner is used only by the default MLX/Qwen ASR path.

ffmpeg

ffmpeg must be installed separately. The CLI checks for it during setup and does not install system packages.

brew install ffmpeg

Setup

Prepare the local environment and model cache:

uv run qwen-transcribe init

To validate without preparing missing model files:

uv run qwen-transcribe init --check-only

Transcribe

Transcribe one video. A successful run writes three artifacts next to the source video:

• VIDEO.txt - plain transcript
• VIDEO.srt - playback subtitles generated from the selected backend's timing path
• VIDEO.subtitled.mp4 - a copy of the source video with the subtitles added as a selectable subtitle track

uv run qwen-transcribe transcribe path/to/video.mp4

The source video is never modified. The review MP4 keeps the original video and audio streams and only adds the subtitle track, so you can open it in a local player and toggle the generated subtitles to inspect ASR quality in context.

Use an explicit transcript path. --output names only the .txt; the .srt and review MP4 stay next to the source video:

uv run qwen-transcribe transcribe path/to/video.mp4 --output transcript.txt

Override source language when automatic detection is not desired:

uv run qwen-transcribe transcribe path/to/video.mp4 --language English

Use a FunASR backend:

uv run qwen-transcribe init --model funasr:sensevoice
uv run qwen-transcribe transcribe path/to/video.mp4 --model funasr:sensevoice --overwrite

For Chinese-only Paraformer:

uv run qwen-transcribe init --model funasr:paraformer-zh
uv run qwen-transcribe transcribe path/to/video.mp4 --model funasr:paraformer-zh --language Chinese --overwrite

Replace existing generated artifacts. Without --overwrite the command fails before any work if any of the .txt, .srt, or review MP4 already exists:

uv run qwen-transcribe transcribe path/to/video.mp4 --overwrite

If forced alignment or subtitle formatting fails, the command reports that stage clearly rather than writing guessed subtitles. If MP4 packaging fails after the .txt and .srt are written, those files remain on disk and the command reports a packaging failure.

Limits

For long media, the pipeline cuts the extracted audio into 15-minute ASR windows and merges the resulting transcript and timing offsets before subtitle generation. Local runtime speed and success still depend on the Mac, available memory, model behavior, and source media. SRT generation is slower than .txt because it runs ASR, forced alignment, and subtitle formatting. The first version does not resume from partial ASR or alignment output after failure.