onnxvoice

onnxvoice manages, verifies, stores, and executes ONNX voice-model assets through shared catalogs, a content-addressed cache, and a common Python API.

It is a model asset and runtime layer, not a complete text-to-speech frontend. Text normalization, G2P/phonemization, sentence planning, and higher-level voice policy belong to producer packages.

Install

The base package does not install ONNX Runtime. Install the provider extra for the target system:

python -m pip install onnxvoice
python -m pip install "onnxvoice[cpu]"
python -m pip install "onnxvoice[gpu]"
python -m pip install "onnxvoice[directml]"
python -m pip install "onnxvoice[openvino]"

For Pocket's optional Hugging Face voice-state downloads, add the pocket extra. See Pocket download setup.

Voicefolio owns cataloging, discovery, and download of reference WAVs. OnnxVoice's Pocket support is for ONNX bundles and predefined runtime voice states. See Pocket download setup.

Quick start

CLI

onnxvoice list --kind voice --lang en-US
onnxvoice install piper:en_US-lessac-medium
onnxvoice installed
onnxvoice cache info

ONNXVoice provides the shared asset-management CLI for Qwen3-TTS and other supported systems:

onnxvoice list --system qwen3
onnxvoice install qwen3:base-0.6b --quality int4
onnxvoice install qwen3:voice-design-1.7b --quality int4
onnxvoice info qwen3:base-0.6b --quality int4
onnxvoice path qwen3:base-0.6b --quality int4
onnxvoice verify qwen3:base-0.6b --quality int4
onnxvoice installed
onnxvoice cache info

Install progress is written to stderr. Successful install stdout contains only the installed path; use --no-progress to disable progress output. ONNXVOICE_CACHE_DIR selects the shared model and catalog cache root, and the global --cache-dir option overrides it. Ctrl+C prints Cancelled. to stderr and exits with status 130 after cleaning staging data; an existing usable installation is preserved.

Python

from onnxvoice import OnnxVoice

voice = OnnxVoice()
installation = voice.install("piper:en_US-lessac-medium")
runtime = voice.open(installation, provider="cpu")
try:
    # Supply model-ready token IDs from your frontend.
    result = runtime.infer([1, 20, 14, 5, 2])
    print(result.audio.shape, result.sample_rate)
finally:
    runtime.close()

install() acquires catalog assets. open() uses an existing managed installation and does not download assets. open_local() opens explicit files without copying or registering them.

Supported systems

Sopro currently provides bundle management, graph inspection, tokenization, and reference preparation only. End-to-end Python synthesis remains capability-gated pending the real native-runtime and parity gate; see Sopro support. Catalog contents determine which named voices are available. Discovery does not depend on a separate capability list. Adapters execute system-specific model contracts and do not imply text normalization or phonemization support.

Documentation

The full documentation includes task-oriented CLI and Python guides, storage and update behavior, provider setup, local-model workflows, per-system runtime contracts, and the API reference.

See Qwen3-TTS WaveKat for the model-specific API and bundle contract.

Development

python -m pip install -e ".[dev,cpu]"
pytest -q
python docs/make.py html

License

The source code is Apache-2.0. Downloaded models, voices, and model cards retain their own licenses and terms. Installing an asset through onnxvoice does not relicense it.