qwen-transcribe 0.1.2

Local Mac CLI for single-video Qwen3-ASR transcription.

qwen-transcribe

Local Mac CLI for transcribing one video file with Qwen3-ASR. A successful run writes a .txt transcript, a ForcedAligner-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.

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 ASR text and ForcedAligner token timing
• 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

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.