DOCSEARCHbyAlgolia
Submit Docs

Qwen3 ASR (Automatic Speech Recognition)

repository·main·Indexed 42 days ago

https://github.com/second-state/qwen3_asr_rs

A pure Rust implementation of Qwen3 ASR with libtorch and MLX backends. It provides high-performance voice transcription via a CLI tool and an OpenAI-compatible HTTP API server (asr-server) for the Qwen3-ASR-0.6B model. Supports various audio formats via FFmpeg and symphonia, including MP3, FLAC, AAC, WAV, and OGG.

Tokens
8.7K
Snippets
32
Records
42
Agent score
53%

What's inside Qwen3 ASR

  1. Run the `asr-server` OpenAI-compatible API

    main

    The asr-server binary provides an OpenAI-compatible HTTP API for audio transcription. This is ideal for agentic skills and bots as it keeps the model loaded in memory, reducing latency compared to the CLI.

    Start the Server

    asr-server --model-dir ./Qwen3-ASR-0.6B

    Server Options

    OptionDescription
    --model-dir <PATH>Path to the Qwen3-ASR model directory (required)
    --host <ADDR>Host address to bind to (default: 0.0.0.0)
    --port <PORT>Port to listen on (default: 8080)
    --language <LANG>Default language for transcription (e.g., chinese, english)
    -v, -vvVerbose output (debug, trace)

  2. Use the `asr` CLI for transcription

    main

    The asr binary generates text from an input audio file. It supports most codecs and file formats via FFmpeg. By default, it attempts to auto-detect the language.

    Basic Usage

    asr ./Qwen3-ASR-0.6B input.wav

    Force a specific language

    To improve accuracy or when auto-detection fails, provide a language hint (e.g., chinese, english):

    asr ./Qwen3-ASR-0.6B input.wav chinese

    Enable debug logging

    Use the RUST_LOG environment variable to enable debug output:

    RUST_LOG=debug asr ./Qwen3-ASR-0.6B input.wav

    Output Format

    The CLI outputs the detected language and the transcribed text:

    Language: English
Text: Thank you for your contribution...
    # Basic transcription (auto-detect language)
asr ./Qwen3-ASR-0.6B input.wav

# Force language
asr ./Qwen3-ASR-0.6B input.wav chinese

# Enable debug logging
RUST_LOG=debug asr ./Qwen3-ASR-0.6B input.wav

  3. Manually install Qwen3 ASR components

    main

    If the automatic bootstrap fails, you can manually install the components:

    1. Download the release: Visit GitHub Releases and download the zip file matching your platform:

      • asr-linux-x86_64.zip (Linux x86_64 CPU)
      • asr-linux-x86_64-cuda.zip (Linux x86_64 CUDA)
      • asr-linux-aarch64.zip (Linux ARM64 CPU)
      • asr-linux-aarch64-cuda.zip (Linux ARM64 CUDA / Jetson)
      • asr-macos-aarch64.zip (macOS Apple Silicon)

    2. Extract and copy:

      SCRIPTS=~/.openclaw/skills/audio_asr/scripts
mkdir -p "$SCRIPTS"
unzip asr-<platform>.zip
cp -r asr-<platform>/* "$SCRIPTS/"
chmod +x "$SCRIPTS/asr"

    3. Download the model:

      huggingface-cli download Qwen/Qwen3-ASR-0.6B --local-dir ~/.openclaw/skills/audio_asr/scripts/models/Qwen3-ASR-0.6B

    4. Generate tokenizer.json: Run the following Python command to generate the required tokenizer file in the model directory:

      python3 -c "
from transformers import AutoTokenizer
import os
path = os.path.expanduser('~/.openclaw/skills/audio_asr/scripts/models/Qwen3-ASR-0.6B')
tok = AutoTokenizer.from_pretrained(path, trust_remote_code=True)
tok.backend_tokenizer.save(f'{path}/tokenizer.json')
print(f'Saved {path}/tokenizer.json')
"

  4. Install the Qwen3 ASR skill via Quick Install

    main

    The recommended way to install the Qwen3 ASR skill is to clone the repository and run the provided bootstrap script. This will set up the skill directory and download the necessary platform-specific releases and models.

    Prerequisites:

    • curl
    • unzip
    • bash
    • pip with huggingface_hub and transformers installed.
    SKILL_DIR="${HOME}/.openclaw/skills/audio_asr"
mkdir -p "$SKILL_DIR"

# Clone the repo
git clone --depth 1 https://github.com/second-state/qwen3_asr_rs.git /tmp/qwen3-asr-repo
cp -r /tmp/qwen3-asr-repo/skills/* "$SKILL_DIR"
rm -rf /tmp/qwen3-asr-repo

# Download platform-specific release and model
"${SKILL_DIR}/bootstrap.sh"

  5. Transcribe audio using the asr binary

    main

    Use the asr binary to perform speech-to-text transcription. The command requires the path to a model directory and the path to the audio file. The transcribed text is printed directly to standard output (stdout).

    {baseDir}/scripts/asr \
  {baseDir}/scripts/models/Qwen3-ASR-0.6B \
  recording.wav

  6. Quick Start with Qwen3 ASR

    main

    You can install Qwen3 ASR using a provided shell script that detects your platform (macOS/Linux, CPU/CUDA GPU), downloads the correct release binary, model weights, and a sample audio file. During installation, you will be prompted to choose a model size (0.6B is recommended) and, on Linux with an NVIDIA GPU, whether to use CUDA or CPU.

    To install and run your first transcription:

    1. Run the installer:
    curl -sSf https://raw.githubusercontent.com/second-state/qwen3_asr_rs/main/install.sh | bash
    1. Navigate to the directory and run the asr tool:
    cd qwen3_asr_rs
./asr ./Qwen3-ASR-0.6B sample.wav
    curl -sSf https://raw.githubusercontent.com/second-state/qwen3_asr_rs/main/install.sh | bash

cd qwen3_asr_rs
./asr ./Qwen3-ASR-0.6B sample.wav

  7. Troubleshoot Qwen3 ASR installation

    main

    Download Failed

    If the download fails, verify your network connectivity by checking the GitHub releases endpoint:

    curl -I "https://github.com/second-state/qwen3_asr_rs/releases/latest"

    Unsupported Platform

    Qwen3 ASR supports the following platforms:

    • Linux: x86_64 and aarch64
    • macOS: Apple Silicon (arm64)

    You can check your current system architecture with:

    echo "OS: $(uname -s), Arch: $(uname -m)"

  8. Verify Qwen3 ASR installation

    main

    After installation, verify that the ASR tool is working by running the asr script against an audio file. The command requires the path to the model directory and the path to the audio file.

    ~/.openclaw/skills/audio_asr/scripts/asr \
  ~/.openclaw/skills/audio_asr/scripts/models/Qwen3-ASR-0.6B \
  /path/to/audio.wav

  9. Use the `POST /v1/audio/transcriptions` endpoint

    main

    This is an OpenAI-compatible endpoint that accepts multipart form data for transcription.

    Request Parameters

    FieldTypeRequiredDescription
    filebinaryYesAudio file (any format supported by FFmpeg)
    languagestringNoLanguage hint (e.g., english, chinese)
    response_formatstringNojson (default), text, or verbose_json
    modelstringNoAccepted for compatibility, ignored
    temperaturefloatNoAccepted for compatibility, ignored
    promptstringNoAccepted for compatibility, ignored

    Examples

    JSON response (default):

    curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F file=@recording.wav

    Plain text response:

    curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F file=@recording.wav \
  -F response_format=text

    Verbose JSON (includes language and duration):

    curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F file=@recording.wav \
  -F response_format=verbose_json

    Force language:

    curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F file=@recording.wav \
  -F language=chinese
    # JSON response (default)
curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F file=@recording.wav

  10. Configure backend features for qwen3-asr-rs

    main

    When building or using qwen3-asr-rs, you must select exactly one backend via Cargo features. The library supports two mutually exclusive backends:

    1. tch-backend: For LibTorch-based execution.
    2. mlx: For Apple MLX-based execution.

    If you attempt to enable both features, or if you enable neither, the compilation will fail with a compile error.

    # Example: Enabling the MLX backend in Cargo.toml
[dependencies]
qwen3-asr-rs = { version = "0.2.0", features = ["mlx"] }

# Example: Enabling the LibTorch backend in Cargo.toml
qwen3-asr-rs = { version = "0.2.0", features = ["tch-backend"] }

  11. Check API server health and models

    main

    The asr-server provides utility endpoints for monitoring and discovery.

    List available models

    GET /v1/models returns a list of available models in an OpenAI-compatible format.

    curl http://localhost:8080/v1/models
# {

  12. asr CLI parameters and requirements

    main

    The asr binary accepts the following positional parameters:

    ParameterRequiredDescription
    model_pathYesPath to the model directory (e.g., Qwen3-ASR-0.6B or Qwen3-ASR-1.7B)
    audio_fileYesPath to the audio file

    Supported Audio Formats: Any format supported by FFmpeg is acceptable (e.g., WAV, MP3, M4A, FLAC, OGG). The tool automatically resamples audio to 16 kHz mono internally.