Metadata-Version: 2.3
Name: qwen-transcribe
Version: 0.1.5
Summary: Local Mac CLI for single-video Qwen3-ASR transcription.
Requires-Dist: huggingface-hub>=0.36.0
Requires-Dist: mlx-audio>=0.3.1
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.20.0
Requires-Dist: funasr>=1.3.14 ; extra == 'funasr'
Requires-Dist: numba>=0.66.0 ; extra == 'funasr'
Requires-Dist: torch>=2.0.0 ; extra == 'funasr'
Requires-Dist: torchaudio>=2.0.0 ; extra == 'funasr'
Requires-Python: >=3.11
Provides-Extra: funasr
Description-Content-Type: text/markdown

# 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`.

```bash
uv venv .venv
uv sync
```

Run project commands through `uv`:

```bash
uv run qwen-transcribe --help
```

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

## Default Models

The default ASR model is:

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

SRT output also uses this ForcedAligner model:

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

```text
funasr:sensevoice
funasr:paraformer-zh
```

Install the optional FunASR dependencies before using them:

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

```bash
brew install ffmpeg
```

## Setup

Prepare the local environment and model cache:

```bash
uv run qwen-transcribe init
```

To validate without preparing missing model files:

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

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

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

Override source language when automatic detection is not desired:

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

Use a FunASR backend:

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

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

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