Metadata-Version: 2.3
Name: qwen-asr-cli
Version: 0.1.2
Summary: CLI wrapper for Qwen3-ASR single-file transcription
Keywords: asr,speech-to-text,qwen,cli
Author: smoose
Author-email: smoose <kongzhh1101@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: huggingface-hub>=0.36.2
Requires-Dist: modelscope>=1.34.0
Requires-Dist: platformdirs>=4.9.2
Requires-Dist: qwen-asr>=0.0.6
Requires-Dist: torch>=2.10.0
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/smoosex/qwen-asr-cli
Project-URL: Repository, https://github.com/smoosex/qwen-asr-cli
Project-URL: Issues, https://github.com/smoosex/qwen-asr-cli/issues
Description-Content-Type: text/markdown

# qwen-asr CLI

A lightweight CLI wrapper around `qwen-asr` for single-file speech transcription.

## Features

- Local transcription with Qwen3-ASR (transformers backend)
- Default model install: `Qwen/Qwen3-ASR-0.6B`
- Default source: Hugging Face (`--source huggingface`)
- Audio preprocessing with `ffmpeg` to `16kHz mono`
- Device auto-selection: `cuda > mps > cpu`
- Default `max_new_tokens`: `4096`
- Default transcribe output: final text only (backend logs are suppressed)

## Prerequisites

- Python 3.10+
- `uv`
- `ffmpeg` in `PATH`

## Setup

```bash
uv sync --dev
```

## Install

Install from PyPI via uv:

```bash
uv tool install qwen-asr-cli
```

Install from PyPI via pip:

```bash
python -m pip install qwen-asr-cli
```

Install from Homebrew (macOS and Linuxbrew):

```bash
brew tap smoosex/tap
brew install qwen-asr-cli
```

## Quick Start

Install default model:

```bash
qwen-asr install-model
```

Install the larger official model:

```bash
qwen-asr install-model --model Qwen/Qwen3-ASR-1.7B
```

Transcribe an audio file:

```bash
qwen-asr transcribe ./demo.wav
```

Force Chinese/English language:

```bash
qwen-asr transcribe ./demo.wav --language zh
qwen-asr transcribe ./demo.wav --language en
```

Save output text:

```bash
qwen-asr transcribe ./demo.wav --output ./demo.txt
```

Use a custom model path:

```bash
qwen-asr transcribe ./demo.wav --model /path/to/model
```

Check runtime:

```bash
qwen-asr doctor
```

For local development inside this repository, use `uv run qwen-asr ...`.

## Model Resolution Priority

If `--model` is omitted in `transcribe`, the CLI resolves model in this order:

1. `QWEN_ASR_MODEL_DIR`
2. Default model path (`platformdirs` cache + `Qwen3-ASR-0.6B`)
3. Error with hint to run `qwen-asr install-model`

## Official Installable Models

- `Qwen/Qwen3-ASR-0.6B` (default)
- `Qwen/Qwen3-ASR-1.7B`

## Commands

```bash
qwen-asr install-model --help
qwen-asr transcribe --help
qwen-asr doctor --help
```

`--language` mapping:

- `auto` -> auto detect
- `zh` -> `Chinese` (qwen-asr language name)
- `en` -> `English` (qwen-asr language name)

## Test

```bash
uv run pytest
```

## Release

1. Bump version in `pyproject.toml`.
2. Push to `main`.
3. Create and push a version tag, e.g. `v0.1.1`.
4. GitHub Actions will:
   - run tests
   - publish to PyPI via Trusted Publisher
   - update `smoosex/homebrew-tap` formula automatically
