Metadata-Version: 2.3
Name: qwen-transcribe
Version: 0.1.3
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-Python: >=3.11
Description-Content-Type: text/markdown

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

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

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

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.
