TingXie

Convert audio recordings to text using faster-whisper with ModelScope model downloads. No HuggingFace needed — models are fetched from ModelScope's China-based CDN.

What It Does

TingXie transcribes .wav, .mp3, .m4a, .flac, .ogg, .wma, .aac, .opus, and .webm files to text. It can process a single file or batch-transcribe an entire directory. Each file gets detected language, per-segment timestamps, and a plain-text transcript.

Models download automatically from ModelScope (iic/speech_whisper_* repos), not HuggingFace. Set TINGXIE_MODEL_DIR to override the cache directory (default: ~/.cache/tingxie/models).

What it does not do: streaming transcription, real-time microphone input, speaker diarization, or translation (transcription only).

Features

• Single file or batch directory transcription
• faster-whisper: 4x faster than openai-whisper, lower memory usage
• ModelScope model downloads (no HuggingFace, no wall issues in China)
• 15+ Whisper model variants: tiny, base, small, medium, large-v3, turbo, distil-*
• CPU and CUDA inference with configurable compute type
• Automatic language detection or manual language hint
• Per-segment timestamps with verbose mode
• JSON output for pipeline integration
• OpenAI function-calling tools schema for agent integration

Requirements

• Python >= 3.9
• faster-whisper (installed automatically)
• modelscope (installed automatically)
• CTranslate2 (installed with faster-whisper)
• FFmpeg (required by faster-whisper — brew install ffmpeg on macOS)

Installation

pip install -e .

For development dependencies:

pip install -e ".[dev]"

Quick Start

Transcribe a single file:

tingxie samples/20260610_125906.wav

Batch transcribe a directory:

tingxie samples/ -m base -l zh

Save transcripts to files:

tingxie samples/ -o output/

Force CPU inference:

tingxie recording.wav --device cpu

CLI Usage

tingxie [-V] [-v] [-q] [--json] [-m MODEL] [-l LANG] [-o PATH]
        [--device {auto,cpu,cuda}] [--compute-type TYPE] PATH

Available Models

tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v1, large-v2, large-v3, large, distil-large-v2, distil-large-v3, distil-medium.en, distil-small.en, turbo

Python API

from tingxie import transcribe, transcribe_dir

# Single file
result = transcribe(audio_path="samples/20260610_125906.wav", model="turbo")
print(result.success)        # True
print(result.data["text"])   # transcribed text
print(result.data["language"])  # detected language

# Force CPU with int8 quantization
result = transcribe(
    audio_path="recording.wav",
    device="cpu",
    compute_type="int8",
)

# Directory batch
result = transcribe_dir(
    directory="samples/",
    model="turbo",
    output="transcripts/",
)
for filename, info in result.data.items():
    print(f"{filename}: {info['text'][:50]}...")

Agent Integration

from tingxie.tools import TOOLS, dispatch

# Use TOOLS in your OpenAI function-calling setup
# Then dispatch results:
result = dispatch("tingxie_transcribe", {
    "audio_path": "recording.wav",
    "model": "turbo",
    "device": "cpu",
})

Model Cache

Models are stored at ~/.cache/tingxie/models/ by default. Override with:

export TINGXIE_MODEL_DIR=/custom/path
tingxie recording.wav

Limitations

• Requires FFmpeg installed on the system
• First run with a model downloads it from ModelScope (~1GB for turbo)
• Not suitable for real-time streaming
• No speaker diarization (cannot distinguish multiple speakers)
• GPU recommended for models larger than small

Development

pip install -e ".[dev]"
ruff format . && ruff check . && mypy . && pytest

License

GPLv3