Metadata-Version: 2.4
Name: tingxie
Version: 0.2.1
Summary: Convert audio recordings to text using faster-whisper with ModelScope
Author: cycleuser
License: GPLv3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: modelscope>=1.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# 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](https://github.com/SYSTRAN/faster-whisper) (installed automatically)
- [modelscope](https://github.com/modelscope/modelscope) (installed automatically)
- CTranslate2 (installed with faster-whisper)
- FFmpeg (required by faster-whisper — `brew install ffmpeg` on macOS)

## Installation

```bash
pip install -e .
```

For development dependencies:

```bash
pip install -e ".[dev]"
```

## Quick Start

Transcribe a single file:

```bash
tingxie samples/20260610_125906.wav
```

Batch transcribe a directory:

```bash
tingxie samples/ -m base -l zh
```

Save transcripts to files:

```bash
tingxie samples/ -o output/
```

Force CPU inference:

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

| Flag | Meaning |
|------|---------|
| `-V`, `--version` | Print version and exit |
| `-v`, `--verbose` | Show per-segment timestamps |
| `-q`, `--quiet` | Suppress non-essential output |
| `--json` | Output as JSON |
| `-m`, `--model` | Whisper model (default: `turbo`) |
| `-l`, `--language` | Language hint, e.g. `zh`, `en` |
| `-o`, `--output` | Output file or directory |
| `--device` | Inference device: `auto`, `cpu`, `cuda` |
| `--compute-type` | Quantization: `default`, `int8`, `float16`, `float32` |

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

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

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

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

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

## License

GPLv3
