Official Python Package for Supertonic¶

Supertonic-3: Multilingual synthesis across 31 languages plus a na fallback for text whose language is unknown or outside the supported set.

Quick Start¶

pip install supertonic

Python¶

Every parameter is annotated inline, so the snippet doubles as copy-and-paste documentation for an LLM assistant:

from supertonic import TTS

# Note: first run downloads the model (~400MB) into ~/.cache/supertonic3/
tts = TTS(auto_download=True)       # Initialize TTS engine

style = tts.get_voice_style(voice_name="M1")   # 10 built-in voices: M1–M5, F1–F5

wav, duration = tts.synthesize(
    text="Supertonic is a lightning fast, on-device TTS system.",
    voice_style=style,              # Voice style object
    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8
    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
    max_chunk_length=300,           # Max characters per chunk (auto: 120 for Korean)
    silence_duration=0.3,           # Silence between chunks (seconds)
    lang="en",                      # ISO code; see "Supported Languages" below
    verbose=False,                  # Show detailed progress (default: False)
)
tts.save_audio(wav, "output.wav")

# Multilingual — just swap `lang` and the input text
wav_ko, _ = tts.synthesize("회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.", voice_style=style, lang="ko")
wav_es, _ = tts.synthesize("La reunión comienza pronto y todos se sientan en silencio para escuchar.", voice_style=style, lang="es")

Custom voices (Voice Builder)¶

get_voice_style() loads one of the ten built-in voices (M1–M5, F1–F5). To use a voice created in Voice Builder (zero-shot cloning from a short reference clip), pass its JSON export to get_voice_style_from_path():

# Any voice-style JSON works here:
#   - a Voice Builder export, or
#   - one of the bundled defaults at
#     ~/.cache/supertonic3/voice_styles/{M1..M5,F1..F5}.json
#     (downloaded alongside the model on first run)
style = tts.get_voice_style_from_path("~/voices/my_voice.json")
wav, _ = tts.synthesize("Hello in my own cloned voice.", voice_style=style, lang="en")

CLI¶

# Note: first run will download the model (~400MB) from HuggingFace
supertonic tts 'Supertonic is a lightning fast, on-device TTS system.' -o output.wav

# Pick a built-in voice and bump quality
supertonic tts 'Use a different voice.' -o output.wav --voice F1 --steps 10

# Use a custom voice — Voice Builder export, or a bundled
# ~/.cache/supertonic3/voice_styles/*.json file
supertonic tts 'Hello in my own cloned voice.' -o output.wav \
  --custom-style-path ~/voices/my_voice.json

# Multilingual support — each language with natural text handling
supertonic tts '회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.' -o korean.wav --lang ko
supertonic tts 'La reunión comienza pronto y todos se sientan en silencio para escuchar.' -o spanish.wav --lang es
supertonic tts 'A reunião começa em breve e todos se sentam em silêncio para ouvir.' -o portuguese.wav --lang pt

Local HTTP server¶

Run Supertonic as a thin local HTTP wrapper for n8n, browser extensions, Electron apps, Unity, Home Assistant, or anything that already speaks the OpenAI Audio Speech API:

pip install 'supertonic[serve]'
supertonic serve --host 127.0.0.1 --port 7788

# Native endpoint
curl -X POST http://127.0.0.1:7788/v1/tts \
  -H 'content-type: application/json' \
  -d '{"text":"Supertonic is a lightning fast, on-device TTS system.","voice":"M1","lang":"en"}' \
  -o output.wav

See Local Server for the OpenAI-compatible alias, Voice Builder custom-voice import, and the batch endpoint.

Get Started with the Full Guide

Explore installation options, voice customization, and advanced configuration.

Requirements¶

Supertonic has minimal dependencies - just 4 core libraries:

• onnxruntime - Fast ONNX model inference
• numpy - Numerical operations
• soundfile - Audio file I/O
• huggingface-hub - Model downloads

✨ Highlights¶

⚡ Blazingly Fast — Low-latency, real-time synthesis across desktop, browser, mobile, and edge — fast enough to turn an entire webpage into audio in under a second

🌍 31-Language Multilingual — Synthesize directly from text across 31 languages, or pass lang="na" to let Supertonic process the text language-agnostically when you don't know the input language — no separate language adapters needed

🪶 99M-Parameter Open-Weight Model — A compact, fully open-weight checkpoint — a fraction of the size of 0.7B–2B class open TTS systems — for smaller downloads, faster cold starts, and lower memory footprint

📱 Edge-Device Ready — Runs locally on desktop, mobile, browsers, and resource-constrained hardware like Raspberry Pi or e-readers, with zero network dependency, complete privacy, and no GPU required

🔊 44.1kHz High-Quality Audio — Outputs studio-grade 44.1kHz 16-bit WAV directly, ready for production playback without any external upsampler

🎭 Expression Tags — 10 inline tags (e.g. <laugh>, <breath>, <sigh>) bring natural human nuance into generated speech without prompt engineering or reference audio

🛠️ Multi-Runtime SDKs — Ready-to-use examples through ONNX Runtime across Python, Node.js, Browser (WebGPU), Java, C++, C#, Go, Swift, iOS, Rust, and Flutter

Supported Languages¶

Supertonic-3 supports the following 31 ISO codes, plus a special na fallback for unknown / unsupported languages:

# Pick any supported code, or use 'na' for text whose language is unknown
wav, _ = tts.synthesize("Some uncommon text.", voice_style=style, lang="na")

Performance Benchmarks¶

Characters per Second¶

Notes: API = Cloud-based API services (measured from Seoul) Open = Open-source models Supertonic (M4 pro - CPU) and (M4 pro - WebGPU): Tested with ONNX Supertonic (RTX4090): Tested with PyTorch model Kokoro: Tested on M4 Pro CPU with ONNX NeuTTS Air: Tested on M4 Pro CPU with Q8-GGUF

Real-time Factor¶

Natural Text Handling¶

Supertonic is designed to handle complex, real-world text inputs that contain numbers, currency symbols, abbreviations, dates, and proper nouns.

🎧 View audio samples more easily: Check out our Interactive Demo for a better viewing experience of all audio examples

Overview of Test Cases:

Note: These samples demonstrate how each system handles text normalization and pronunciation of complex expressions without requiring pre-processing or phonetic annotations.

Citation¶

The following papers describe the core technologies used in Supertonic. If you use this system in your research or find these techniques useful, please consider citing the relevant papers:

SupertonicTTS: Main Architecture¶

This paper introduces the overall architecture of SupertonicTTS, including the speech autoencoder, flow-matching based text-to-latent module, and efficient design choices.

@article{kim2025supertonic,
  title={SupertonicTTS: Towards Highly Efficient and Streamlined Text-to-Speech System},
  author={Kim, Hyeongju and Yang, Jinhyeok and Yu, Yechan and Ji, Seunghun and Morton, Jacob and Bous, Frederik and Byun, Joon and Lee, Juheon},
  journal={arXiv preprint arXiv:2503.23108},
  year={2025},
  url={https://arxiv.org/abs/2503.23108}
}

Length-Aware RoPE: Text-Speech Alignment¶

This paper presents Length-Aware Rotary Position Embedding (LARoPE), which improves text-speech alignment in cross-attention mechanisms.

@article{kim2025larope,
  title={Length-Aware Rotary Position Embedding for Text-Speech Alignment},
  author={Kim, Hyeongju and Lee, Juheon and Yang, Jinhyeok and Morton, Jacob},
  journal={arXiv preprint arXiv:2509.11084},
  year={2025},
  url={https://arxiv.org/abs/2509.11084}
}

Self-Purifying Flow Matching: Training with Noisy Labels¶

This paper describes the self-purification technique for training flow matching models robustly with noisy or unreliable labels.

@article{kim2025spfm,
  title={Training Flow Matching Models with Reliable Labels via Self-Purification},
  author={Kim, Hyeongju and Yu, Yechan and Yi, June Young and Lee, Juheon},
  journal={arXiv preprint arXiv:2509.19091},
  year={2025},
  url={https://arxiv.org/abs/2509.19091}
}

Related Projects¶

🏠 Main Repository: github.com/supertone-inc/supertonic

🎧 Try it live: Hugging Face Spaces

🤗 Model Repository: Hugging Face Models

License¶

Code: MIT License

Model: OpenRAIL-M License

Copyright © 2025 Supertone Inc.