Local speech recognition and synthesis, with language-aware model routing.

Multilingual STT and TTS · CPU inference · OpenAPI · No per-request API fee

SmartVoice

SmartVoice is a local speech-to-text (STT) and text-to-speech (TTS) service. It offers both through one OpenAI-style audio API, with models installed and run on your machine.

Why SmartVoice?

• Private, local processing: Audio and text are processed by models on your machine, without sending inference requests to a third-party speech service. You control where your data, models, and service configuration live.
• One API for speech in both directions: Transcribe audio and synthesize speech through a single OpenAI-style audio API, making it straightforward to connect compatible agents and applications.
• Language-aware model routing: Send requests to smartvoice-auto and SmartVoice selects an installed model for the requested task and language, following your editable priority list.
• Freedom to manage and move models: Install only the models you need, choose explicit model IDs when desired, and export/import model packages to transfer them to another machine.
• Run locally without per-request fees: Supported CPU deployments work on Windows x64, macOS Apple Silicon, and Linux x86_64. After setup, inference can run offline without a cloud account or network connection.

Model installation and updates may download files from their configured sources. SmartVoice binds to 127.0.0.1 by default. If you expose the API on your network, it currently has no authentication, so restrict access with your network configuration and firewall.

Capabilities

For the architecture principles, implementation overview, per-backend OS/architecture/device/build matrix, and the difference between installed models and inference availability, see Architecture Summary and Guidelines.

SmartVoice supports a subset of OpenAI Audio API conventions; this is not a claim of full API compatibility. See the API specification for request and response details.

Smart routing

Smart routing selects an installed model using the request task, language, and an ordered, user-editable JSON table. Use smartvoice-auto for language-aware routing on either audio endpoint, or pass a concrete model ID to call that model directly.

TTS model priority order:

1. Chinese: Qwen3-TTS → Matcha → Kokoro
2. German, French, Spanish, Japanese, Korean: Supertonic → Qwen3-TTS
3. English: Supertonic → Qwen3-TTS → Kokoro
4. Portuguese, Russian, Italian: Supertonic → Qwen3-TTS
5. Other supported languages: Supertonic

For STT, the built-in route table prioritizes SenseVoice for Chinese, English, Cantonese, Japanese, and Korean; Qwen3-ASR covers the remaining configured languages, with Whisper as a fallback for selected languages.

SmartVoice routes by the API endpoint and language:

The built-in route table is copied to <data_dir>/router.json on first startup. Edit it to customize model priorities, then apply changes without restarting:

python -m smartvoice router reload

The first installed and verified candidate is selected. An inference failure does not trigger a retry with the next candidate. See the API specification for request details.

Model catalog

Language availability describes catalog support, not comparative quality. Model and voice licenses may differ from SmartVoice's license.

RTF is the median for warm requests (Chinese where supported; English for Supertonic); lower is faster relative to audio duration. Throughput per CPU core is measured at the highest passing parallel request rate. Both use representative samples and are specific to the test platform: an Apple Silicon Mac running macOS 27.0, with 10 logical CPUs, 16 GiB RAM, Python 3.11.9, and sherpa-onnx 1.13.8. Sherpa tests used two instances, two threads per instance, and a four-request waiting limit; Qwen3-TTS uses one serialized native runtime. Qwen3-TTS's per-core rate is unavailable because its native engine process was not fully included in CPU sampling. See the benchmark reports for details.

Model sizes are approximate unpacked sizes; see catalog/models.json for exact assets and sizes. Qwen3-TTS 0.6B needs at least 6 GiB free during installation. Its Windows runtime requires AVX2 and FMA; Linux builds use the builder's available instruction set. See the platform compatibility notes.

For STT requests with language=auto, SmartVoice uses the optional Whisper Tiny language detector, then routes by the detected language. python -m smartvoice models install all installs it; otherwise SmartVoice uses an installed model that supports automatic detection. Its availability appears in /v1/capabilities.

Quick start

SmartVoice requires Python 3.11 or newer and runs inference on CPU. The service binds to 127.0.0.1 by default.

1. Install SmartVoice

Choose an installation method below. The PyPI option is recommended for normal use; the source option is for development or when you want an editable checkout.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install smartvoice

python3 -m venv .venv
source .venv/bin/activate
python -m pip install smartvoice

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install smartvoice

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

sudo apt-get update
sudo apt-get install -y python3-venv build-essential libopenblas-dev
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

sudo apt-get install -y build-essential libopenblas-dev

SMARTVOICE_QWEN_OUTPUT="$PWD/src/smartvoice/resources/bin" \
  python scripts/build_qwen3_tts_linux.py

pacman -S --needed make gcc diffutils mingw-w64-ucrt-x86_64-openblas

# Omit this if MSYS2 is installed at C:\msys64 or %USERPROFILE%\msys64.
$env:SMARTVOICE_MSYS2_ROOT = "C:\msys64"
$env:SMARTVOICE_QWEN_OUTPUT = "$PWD\src\smartvoice\resources\bin"
.\.venv\Scripts\python.exe .\scripts\build_qwen3_tts_windows.py

Activate .venv before running the model and server commands below. On Windows PowerShell, you can instead keep the environment inactive and replace python with .\.venv\Scripts\python.exe in those commands.

2. Download models

Install a basic STT and TTS model. Model files are downloaded once and stored outside the source checkout, under ~/Library/Application Support/SmartVoice on macOS, ~/.smartvoice on Linux, or %LOCALAPPDATA%\SmartVoice on Windows.

python -m smartvoice models install stt-sensevoice-small-int8
python -m smartvoice models install tts-kokoro-multilingual-v1-1-zh-en
python -m smartvoice models install-language-id

On the macOS Apple Silicon, Windows x64, and Linux x86_64 PyPI wheels, the Qwen3-TTS runtime is bundled. From a source checkout, build the runtime on Windows and Linux as described above; the macOS source build compiles it during installation. Then install Qwen3-TTS to use the configured Chinese and multilingual routes:

python -m smartvoice models install tts-qwen3-0-6b-customvoice

Without the native runtime in a source deployment, Qwen3-TTS is listed as unavailable and other installed TTS models remain usable.

The first model installation requires internet access. After installation, inference runs locally. See Model catalog for supported languages and estimated sizes.

3. Start SmartVoice

By default the HTTP service listens only on 127.0.0.1. To allow other machines to connect, explicitly bind to an external interface, for example:

python -m smartvoice --host 127.0.0.1 --port 8000
# To listen on all IPv4 interfaces:
python -m smartvoice --host 0.0.0.0 --port 8000

External binding is plain HTTP without API authentication. Use it only on a trusted network and configure the machine firewall as needed. HTTPS is not currently supported.

Open the SmartVoice Console to use the speech workspace, review installed models, and verify STT/TTS with your installed models before connecting an application. Open API docs for endpoint details. Sherpa models use a lazy per-model instance pool: parallel inference is enabled by default, one instance is retained, and demand can expand the pool to two independent instances with two native threads each. The per-model waiting limit defaults to four. These settings do not promise a fixed request rate for every model or input. See inference concurrency and the fixed-arrival benchmark protocol. Service settings are stored in <data_dir>/smartvoice.json; routing priorities are stored separately in <data_dir>/router.json and can be reloaded with python -m smartvoice router reload.

4. Connect an agent or application

In your agent or application's settings, choose OpenAI-compatible API and set the SmartVoice API base URL to:

http://127.0.0.1:8000/v1

API

The audio endpoints follow a supported subset of the OpenAI Audio API conventions. For request fields, response formats, and errors, see the API specification.

Transcribe audio with routing

curl.exe -F "file=@sample.wav" -F "model=smartvoice-auto" -F "language=auto" `
  http://127.0.0.1:8000/v1/audio/transcriptions

Supported upload formats include WAV, MP3, M4A, and FLAC. Audio is limited to 25 MiB and 10 minutes by default.

Synthesize speech with routing

curl.exe -X POST http://127.0.0.1:8000/v1/audio/speech `
  -H "Content-Type: application/json" `
  -d '{"model":"smartvoice-auto","input":"Hello from SmartVoice.","language":"auto"}' `
  --output speech.mp3

TTS defaults to mono MP3 (96 kbps); send "response_format":"wav" for WAV. Requests support up to 4,000 characters; generated audio is limited to 180 seconds, with separate 32 MiB canonical WAV and final-response budgets. Supertonic uses bounded text chunks; long STT inputs use silence-aware model-declared windows (25 seconds for Whisper Base; 15 seconds by default) with 1-second overlap and a single language decision across chunks, while retaining the 10-minute input limit. See /docs or the API specification for available parameters, language behavior, and error codes. The local Whisper Chinese decoding repair requires a patched native wheel; see build and validation instructions.

Manage models

The CLI supports models list, refresh, install, uninstall, export, and import. models list groups models by installed state, then by STT, TTS, and SmartVoice native; each model shows its availability, and unavailable models include a reason. Availability checks both model-file integrity and the active inference runtime/device. The running service keeps one process-wide model availability snapshot, initializes it at startup, and updates it after model management operations. If model files are changed outside the running service, refresh that snapshot with python -m smartvoice models refresh or POST /v1/models/refresh. As a fallback, the service checks the snapshot every 10 minutes and refreshes it in the background while continuing to serve the last successful snapshot. A failed TTL refresh is retried after 5, 10, and 15 seconds; after three retries it waits for a manual or model-management refresh to resume scanning. Configure the interval with model_availability_ttl_seconds or SMARTVOICE_MODEL_AVAILABILITY_TTL_SECONDS. Use python -m smartvoice models install all to install every catalog model that is not already installed and the Whisper Tiny language detector. Model downloads run sequentially from their catalog sources; invalid existing model directories are skipped with a repair hint. Installing all models can require several gigabytes of disk space. On Windows x64, Qwen3-TTS is available only when its native runtime has been built; see Build the Qwen3-TTS runtime on Windows. Models can also be installed through API download jobs. Exported model packages can be transferred to offline machines and imported there. An installed model cannot be uninstalled while the service is using it.

Install a model with python -m smartvoice models install <model-id>. By default, SmartVoice uses the model's catalog source. For Hugging Face models, pass --source with a compatible mirror base URL to use another source, such as:

python -m smartvoice models install stt-qwen3-asr-600m-int8 --source https://hf-mirror.com

The base URL is combined with the catalog-pinned repository, revision, and file paths. This option is available only when all required model files are hosted on Hugging Face. Downloaded files are still checked against their catalog SHA-256 values.

python -m smartvoice models list
python -m smartvoice models refresh
python -m smartvoice models export stt-sensevoice-small-int8 ./sensevoice.smartvoice.zip
python -m smartvoice models import ./sensevoice.smartvoice.zip
python -m smartvoice models uninstall stt-sensevoice-small-int8

Architecture

Client / Agent ──► Versioned HTTP API ──► Application services
                         ▲                       │
                         │                       ▼
                    Local CLI              Domain contracts
                                                 │
                               ┌─────────────────┴─────────────────┐
                               ▼                                   ▼
                       Inference port                      Model repository port
                               │                                   │
                               ▼                                   ▼
                    Composite inference provider       Filesystem catalog adapter
                       ┌───────┴────────┐
                       ▼                ▼
                sherpa-onnx       native C INT8 Qwen-TTS
                   adapter            adapter
                       │
                       ▼
              Platform diagnostics adapter

Callers use versioned API and capability endpoints; inference details stay behind provider and repository interfaces. The source deployment supports CPU inference on Windows x64, macOS Apple Silicon, and Linux x86_64. Qwen3-TTS uses the native C INT8 adapter on all three platforms; Linux source deployments build against the system OpenBLAS library as described above. GPU providers, streaming, and Android runtimes are not available in SmartVoice. See Architecture Summary and Guidelines for the detailed matrix and model availability semantics.

Development

python -m pip install -e ".[dev]"
python scripts/test.py ci

python scripts/test.py regression is the default inference regression suite. It includes the existing functional and real-inference tests, short bilingual functional cases for SenseVoice, Qwen3-ASR, and Whisper, audio-window boundary cases, and 75-second segmented inputs. Models not installed on the current runtime are skipped individually. Run python scripts/test.py full for every CI and regression test plus 300- and 590-second bilingual inputs across all three STT models. Full mode requires all three models and the validated patched Whisper runtime; it fails its prerequisite check rather than silently skipping them. Long-input expansion is intentionally excluded from the default regression run. The STT tests check functional success and response metadata, not transcript accuracy. See doc/testing.md and tests/fixtures/stt/README.md for suite details. See doc/releasing.md for versioning, GitHub Releases, and optional PyPI publishing.

Repository layout

catalog/       Model metadata and default router table
src/           API/CLI entry points, application services, domain contracts, ports, and adapters
tests/         Unit, API, and optional real-inference tests
benchmarks/    Benchmark code, configurations, and results
config/        Example service settings
doc/           API specification, testing, release, requirements, and design notes
assets/        Project logo

License

SmartVoice source code is licensed under the Apache License 2.0. Model weights, voices, and other third-party assets may have separate license terms; review them before use or redistribution.