supertonic Documentation

Technical Documentation: supertone-inc/supertonic

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

This repository is archived. Development and support have ended.

The code remains available for reference under the terms of the LICENSE. No updates, bug fixes, security patches, or support will be provided, and issues and pull requests are no longer monitored. The software is provided "AS IS" as set forth in the license, without any warranty or ongoing responsibility of the original authors.

Archive locations Copy Chapter

The source code is preserved under the supertone-oss-archive GitHub organization.
Model downloads now use the supertone-oss-archive Hugging Face namespace:

• Source code
• Supertonic 3 weights
• Supertonic 2 weights
• Supertonic 1 weights

See Quick Start to download the archived models and run locally.
Code and model weights retain their respective licenses.
This archive does not include hosted demos or Voice Builder services.

Supertonic — Lightning Fast, On-Device, Accurate TTS

Supertonic is a lightning-fast, on-device multilingual text-to-speech system designed for local inference with minimal overhead. Powered by ONNX Runtime, it runs entirely on your device—no cloud, no API calls, no privacy concerns.

✨ Highlights Copy Section

• ⚡ 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>, ``, <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 (31) Copy Section

Arabic (ar), Bulgarian (bg), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Finnish (fi), French (fr), German (de), Greek (el), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Latvian (lv), Lithuanian (lt), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Slovak (sk), Slovenian (sl), Spanish (es), Swedish (sv), Turkish (tr), Ukrainian (uk), Vietnamese (vi)

Not sure which language your text is in? Pass lang="na" and Supertonic will handle the input in a language-agnostic way — no explicit language tag required.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

• 2026.05.20 - Supertonic 3 is now officially supported in Supertone Play and the Supertone API. Visit Play or the API if you want a managed content creation workflow with diverse preset voices and zero-shot voice cloning.
• 2026.05.18 - Python SDK v1.3.1 adds supertonic serve, a local HTTP server with native /v1/tts and OpenAI-compatible /v1/audio/speech endpoints. See the serve documentation.
• 2026.05.18 - Voice Builder now supports Supertonic 3. Create a permanent custom voice profile for Supertonic and download version-specific JSON files for both Supertonic 2 and Supertonic 3. If you already created a Supertonic 2 voice, the matching Supertonic 3 JSON is now available from My Page.
• 2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, fewer repeat/skip failures, and v2-compatible public ONNX assets. Demo | Models
• 2026.01.22 - Voice Builder is now live! Turn your voice into a deployable, edge-native TTS with permanent ownership.
• 2026.01.06 - 🎉 Supertonic 2 released with 5-language support. The v2 code path is preserved on the release/supertonic-2 branch.
• 2025.12.10 - Added supertonic PyPI package! Install via pip install supertonic. For details, visit supertonic-py documentation
• 2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details
• 2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models
• 2025.11.24 - Added Flutter SDK support with macOS compatibility

Quick Start Copy Chapter

Use the examples in this repository with model files downloaded explicitly from
the archive. No Hugging Face login, hosted demo, or original Supertone service is
required. These instructions use Supertonic 3.

1. Clone the source and install the download tool Copy Section

Use Python 3.11 in a virtual environment:

git clone https://github.com/supertone-oss-archive/supertonic.git
cd supertonic
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install huggingface_hub

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell.

2. Download the archived model Copy Section

hf download supertone-oss-archive/supertonic-3 \
  --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 \
  --local-dir assets

This downloads the ONNX models, configuration, and preset voice styles to assets/.
The revision pins the archived snapshot. Git LFS is not needed for this download method.
See Models & Versions for the archived Supertonic 1 and 2 weights.

3. Generate speech locally Copy Section

python -m pip install -r py/requirements.txt
cd py
python example_onnx.py --n-test 1 --text "This speech was generated locally with the archived Supertonic model." --lang en

The generated WAV file is saved in py/results/. After dependencies and models
have been downloaded, this example performs inference locally without a network connection.
See Python examples for voice selection, batch synthesis, and other options.

Optional Python SDK Copy Section

Older releases of the supertonic Python package may still use the original
Supertone Hugging Face namespace for automatic downloads. Download assets/
as above and pass model_dir with auto_download=False instead.

To use the preserved SDK source with Supertonic 3 support, run these commands
from the repository root in the same virtual environment:

python -m pip install "git+https://github.com/supertone-oss-archive/supertonic-py.git@df0f9686dac7fbbde391b759e2ee5286a3737622"
python py/example_pypi.py

The SDK example uses the local assets/ directory and does not download models.
The archived local server guide
is available for reference; the ONNX example above is the default archive setup.

Getting Started in Other Runtimes Copy Chapter

Download the same assets/ directory from the repository root before running
the examples below. The language examples read these local files.

Some language examples need native runtimes:

• Go: install the ONNX Runtime C library. On macOS, brew install onnxruntime.
• Java: use a JDK, not just a JRE. On macOS, brew install openjdk@17.
• C#: targets .NET 9 and allows major-version roll-forward.

Other Runtime Examples Copy Section

Run Supertonic in other languages and platforms

Node.js Example (Details)

cd nodejs
npm install
npm start

Browser Example (Details)

cd web
npm install
npm run dev

Java Example (Details)

cd java
mvn clean install
mvn exec:java

C++ Example (Details)

cd cpp
mkdir build && cd build
cmake .. && cmake --build . --config Release
./example_onnx

C# Example (Details)

cd csharp
dotnet restore
dotnet run

Go Example (Details)

cd go
go mod download
go run example_onnx.go helper.go

Swift Example (Details)

cd swift
swift build -c release
.build/release/example_onnx

Rust Example (Details)

cd rust
cargo build --release
./target/release/example_onnx

iOS Example (Details)

cd ios/ExampleiOSApp
xcodegen generate
open ExampleiOSApp.xcodeproj

In Xcode: Targets → ExampleiOSApp → Signing: select your Team, then choose your iPhone as run destination and build.

Technical Details Copy Section

• Runtime: ONNX Runtime for cross-platform inference
• Browser Support: onnxruntime-web for client-side inference
• Batch Processing: Supports batch inference for improved throughput
• Audio Output: Outputs 44.1kHz 16-bit WAV files

Performance Highlights Copy Chapter

Supertonic 3 is designed for practical on-device inference: compact enough to run locally, while staying competitive with much larger open TTS systems.

Reading Accuracy Copy Section

Evaluated on the Minimax-MLS-test benchmark, Supertonic 3 stays within a competitive WER/CER range against much larger open TTS models such as VoxCPM2, while preserving a lightweight on-device deployment path. Asterisked languages (*) use CER; the others use WER.

📊 Detailed per-language results (WER / CER)*

Lower is better. * indicates CER (character error rate); all other rows use WER (word error rate). Dashes (—) indicate the model does not officially support the language or no result is available.

Supertonic 2 to Supertonic 3 Copy Section

Compared with Supertonic 2, Supertonic 3 reduces repeat and skip failures, improves speaker similarity across the shared-language set, and expands language coverage from 5 to 31 languages. It keeps the v2-compatible public ONNX interface, so existing integrations can move to v3 with the same inference contract.

Runtime Footprint Copy Section

Supertonic 3 runs fast on CPU, even compared with larger baselines measured on A100 GPU, and uses substantially less memory. The open-weight fixed-voice setting does not require a GPU, which makes local, browser, and edge deployment much easier.

Model Size Copy Section

At about 99M parameters across the public ONNX assets, Supertonic 3 is much smaller than 0.7B to 2B class open TTS systems. The smaller model size is a practical advantage for download size, startup time, and on-device inference.

Voice Cloning Copy Chapter

This open-weight repository focuses on fixed-voice, local TTS and does not include an official voice-cloning pipeline. If you want to bring your own voice to local Supertonic deployment, Voice Builder turns a short reference recording into version-specific JSON files for Supertonic 2 and Supertonic 3, so the same custom voice can move with you across supported Supertonic versions.

For a managed creation workflow, Supertonic 3 is now officially available in Supertone Play and the Supertone API. Use them when you want hosted content creation tools, diverse commercially usable preset voices, zero-shot voice cloning, or API-based integration without managing local model files. You can also listen to Supertonic 3 zero-shot samples on the official showcase.

Demo Copy Chapter

Run locally: Follow Quick Start with the archived weights.

Raspberry Pi Copy Section

Watch Supertonic running on a Raspberry Pi, demonstrating on-device, real-time text-to-speech synthesis:

https://github.com/user-attachments/assets/ea66f6d6-7bc5-4308-8a88-1ce3e07400d2

E-Reader Copy Section

Experience Supertonic on an Onyx Boox Go 6 e-reader in airplane mode, achieving an average RTF of 0.3× with zero network dependency:

https://github.com/user-attachments/assets/64980e58-ad91-423a-9623-78c2ffc13680

Chrome Extension Copy Section

Turns any webpage into audio in under one second, delivering lightning-fast, on-device text-to-speech with zero network dependency—free, private, and effortless:

https://github.com/user-attachments/assets/cc8a45fc-5c3e-4b2c-8439-a14c3d00d91c

Programming Language Support Copy Chapter

We provide ready-to-use TTS inference examples across multiple ecosystems:

For detailed usage instructions, please refer to the README.md in each language directory.

Natural Text Handling Copy Chapter

Supertonic is designed to handle complex, real-world text inputs that contain natural prose, punctuation, abbreviations, and proper nouns.

These historical audio samples are hosted externally and are not maintained as part of this archive.

Overview of Test Cases:

Example 1: Financial Expression

Text:

"The startup secured $5.2M in venture capital, a huge leap from their initial $450K seed round."

Challenges:

• Decimal point in currency ($5.2M should be read as "five point two million")
• Abbreviated magnitude units (M for million, K for thousand)
• Currency symbol ($) that needs to be properly pronounced as "dollars"

Audio Samples:

Example 2: Phone Number

Text:

"You can reach the hotel front desk at (212) 555-0142 ext. 402 anytime."

Challenges:

• Area code in parentheses that should be read as separate digits
• Phone number with hyphen separator (555-0142)
• Abbreviated extension notation (ext.)
• Extension number (402)

Audio Samples:

Example 3: Technical Unit

Text:

"Our drone battery lasts 2.3h when flying at 30kph with full camera payload."

Challenges:

• Decimal time duration with abbreviation (2.3h = two point three hours)
• Speed unit with abbreviation (30kph = thirty kilometers per hour)
• Technical abbreviations (h for hours, kph for kilometers per hour)
• Technical/engineering context requiring proper pronunciation

Audio Samples:

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

Built with Supertonic Copy Chapter

Models & Versions Copy Chapter

Version-specific branches and tags preserve historical code. Their old download
instructions may reference the original organization; use the model archives below.
The Quick Start above uses Supertonic 3 and its matching code on main.

Previous service notice — July 23, 2026

The following announcement is preserved as a historical record. Its service links
may no longer be available; use the archive links above for code and models.

[!CAUTION]

⚠️ Service and Repository Notice (July 23, 2026) Copy Chapter

This repository will be archived, and there will be no further development or official support for the open-source Supertonic models.

Voice Builder will no longer be accessible after August 31, 2026.

For details about the service changes, timeline, and information for existing Voice Builder users, please see the official announcement.

Thank you to everyone who has used, contributed to, and supported Supertonic.

Citation Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Section

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

RobustSpeechFlow: Learning Robust Text-to-Speech Trajectories via Augmentation-based Contrastive Flow Matching Copy Section

This paper describes the RobustSpeechFlow technique for improving the robustness and quality of text-to-speech generation by optimizing flow-matching trajectories against data variability

@misc{yang2026robustspeechflowlearningrobusttexttospeech,
      title={RobustSpeechFlow: Learning Robust Text-to-Speech Trajectories via Augmentation-based Contrastive Flow Matching}, 
      author={Jinhyeok Yang and Hyeongju Kim and Yechan Yu and Joon Byun and Frederik Bous and Juheon Lee},
      year={2026},
      eprint={2605.22083},
      archivePrefix={arXiv},
      primaryClass={cs.SD},
      url={https://arxiv.org/abs/2605.22083}, 
}

License Copy Chapter

This project's sample code is released under the MIT License. - see the LICENSE for details.

The accompanying model is released under the OpenRAIL-M License. - see the LICENSE file for details.

This model was trained using PyTorch, which is licensed under the BSD 3-Clause License but is not redistributed with this project. - see the LICENSE for details.

Copyright (c) 2026 Supertone Inc.

Overview (`cpp/README.md`) Copy Section

Supertonic C++ Implementation

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

High-performance text-to-speech inference using ONNX Runtime.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Requirements Copy Chapter

• C++17 compiler, CMake 3.15+
• Libraries: ONNX Runtime, nlohmann/json

Installation Copy Chapter

Ubuntu/Debian:

⚠️ Note: Installation instructions not yet verified.

sudo apt-get install -y cmake g++ nlohmann-json3-dev
wget https://github.com/microsoft/onnxruntime/releases/download/v1.16.3/onnxruntime-linux-x64-1.16.3.tgz
tar -xzf onnxruntime-linux-x64-1.16.3.tgz
sudo cp -r onnxruntime-linux-x64-1.16.3/include/* /usr/local/include/
sudo cp -r onnxruntime-linux-x64-1.16.3/lib/* /usr/local/lib/
sudo ldconfig

macOS:

brew install cmake nlohmann-json onnxruntime

Windows (vcpkg):

⚠️ Note: Installation instructions not yet verified.

vcpkg install nlohmann-json:x64-windows onnxruntime:x64-windows
vcpkg integrate install

Building Copy Chapter

cd cpp
mkdir -p build && cd build
cmake ..
cmake --build . --config Release
./example_onnx

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

./example_onnx

This will use:

• Voice style: ../../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

./example_onnx \
  --voice-style ../../assets/voice_styles/M1.json,../../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 좋아서 한참을 멈춰 서서 들었어요." \
  --lang en,ko \
  --batch

This will:

• Use --batch flag to enable batch processing mode
• Generate speech for 2 different voice-text pairs
• Use male voice style (M1.json) for the first English text
• Use female voice style (F1.json) for the second Korean text
• Process both samples in a single batch (automatic text chunking disabled)

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

./example_onnx \
  --total-step 10 \
  --voice-style ../../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

For long texts, the system automatically chunks the text into manageable segments and generates a single audio file:

./example_onnx \
  --voice-style ../../assets/voice_styles/M1.json \
  --text "Once upon a time, in a small village nestled between rolling hills, there lived a young artist named Clara. Every morning, she would wake up before dawn to capture the first light of day. The golden rays streaming through her window inspired countless paintings. Her work was known throughout the region for its vibrant colors and emotional depth. People from far and wide came to see her gallery, and many said her paintings could tell stories that words never could."

This will:

• Automatically split the long text into smaller chunks (max 300 characters by default)
• Process each chunk separately while maintaining natural speech flow
• Insert brief silences (0.3 seconds) between chunks for natural pacing
• Combine all chunks into a single output audio file

Note: When using batch mode (--batch), automatic text chunking is disabled. Use non-batch mode for long-form text synthesis.

Available Arguments Copy Chapter

Notes Copy Chapter

• Batch Processing: The number of --voice-style files must match the number of --text entries
• Multilingual Support: Use --lang to specify language(s). Available: 31 languages; see the main README for the full list
• Long-Form Inference: Without --batch flag, long texts are automatically chunked and combined into a single audio file with natural pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer

Overview (`csharp/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using ExampleONNX.cs.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

Prerequisites Copy Section

• .NET 9.0 SDK/runtime, or a newer .NET runtime with major-version roll-forward
• Download .NET SDK

The project targets net9.0 and sets RollForward=Major, so systems with only a newer runtime such as .NET 10 can still run the example.

Install dependencies Copy Section

dotnet restore

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

dotnet run

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

dotnet run -- \
  --voice-style ../assets/voice_styles/M1.json,../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 좋아서 한참을 멈춰 서서 들었어요." \
  --lang en,ko \
  --batch

This will:

• Use --batch flag to enable batch processing mode
• Generate speech for 2 different voice-text pairs
• Use male voice style (M1.json) for the first English text
• Use female voice style (F1.json) for the second Korean text
• Process both samples in a single batch (automatic text chunking disabled)

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

dotnet run -- \
  --total-step 10 \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

For long texts, the system automatically chunks the text into manageable segments and generates a single audio file:

dotnet run -- \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Once upon a time, in a small village nestled between rolling hills, there lived a young artist named Clara. Every morning, she would wake up before dawn to capture the first light of day. The golden rays streaming through her window inspired countless paintings. Her work was known throughout the region for its vibrant colors and emotional depth. People from far and wide came to see her gallery, and many said her paintings could tell stories that words never could."

This will:

• Automatically split the long text into smaller chunks (max 300 characters by default)
• Process each chunk separately while maintaining natural speech flow
• Insert brief silences (0.3 seconds) between chunks for natural pacing
• Combine all chunks into a single output audio file

Note: When using batch mode (--batch), automatic text chunking is disabled. Use non-batch mode for long-form text synthesis.

Available Arguments Copy Chapter

Notes Copy Chapter

• Batch Processing: The number of --voice-style files must match the number of --text entries
• Multilingual Support: Use --lang to specify language(s). Available: 31 languages; see the main README for the full list
• Long-Form Inference: Without --batch flag, long texts are automatically chunked and combined into a single audio file with natural pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet

Building the Project Copy Chapter

Build for Release Copy Section

dotnet build -c Release

Run the compiled executable Copy Section

./bin/Release/net9.0/Supertonic

Project Structure Copy Chapter

csharp/
├── ExampleONNX.cs        # Main inference script
├── Helper.cs             # Helper functions and classes
├── Supertonic.csproj     # Project configuration
├── README.md             # This file
└── results/              # Output directory (created automatically)

Overview (`flutter/README.md`) Copy Section

Supertonic Flutter Example

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This example demonstrates how to use Supertonic 3 in a Flutter application using ONNX Runtime.

Note: This project uses the flutter_onnxruntime package (https://pub.dev/packages/flutter_onnxruntime). At the moment, only the macOS platform has been tested. Although the flutter_onnxruntime package supports several other platforms, they have not been tested in this project yet and may require additional verification.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Added and tested macos support.

Multilingual Support Copy Chapter

Supertonic 3 supports 31 languages. Select the appropriate language from the dropdown; see the main README for the full code list.

Requirements Copy Chapter

• Flutter SDK version ^3.5.0

Running the Demo Copy Chapter

flutter clean
flutter pub get
flutter run -d macos

Overview (`go/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using example_onnx.go.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

This project uses Go modules for dependency management.

Prerequisites Copy Section

1. Install Go 1.21 or later from https://golang.org/dl/
2. Install ONNX Runtime C library:

macOS (via Homebrew):

brew install onnxruntime

The Go example auto-detects Homebrew ONNX Runtime paths on both Apple Silicon and Intel Macs.

Linux:

# Download ONNX Runtime from GitHub releases
wget https://github.com/microsoft/onnxruntime/releases/download/v1.16.0/onnxruntime-linux-x64-1.16.0.tgz
tar -xzf onnxruntime-linux-x64-1.16.0.tgz
sudo cp onnxruntime-linux-x64-1.16.0/lib/* /usr/local/lib/
sudo cp -r onnxruntime-linux-x64-1.16.0/include/* /usr/local/include/
sudo ldconfig

Install Go dependencies Copy Section

go mod download

Configure ONNX Runtime Library Path (Optional) Copy Section

If the ONNX Runtime library is not in a standard or Homebrew location, set the environment variable:

Automatic Detection (Recommended):

# macOS
export ONNXRUNTIME_LIB_PATH=$(brew --prefix onnxruntime 2>/dev/null)/lib/libonnxruntime.dylib

# Linux
export ONNXRUNTIME_LIB_PATH=$(find /usr/local/lib /usr/lib -name "libonnxruntime.so*" 2>/dev/null | head -n 1)

Manual Configuration:

export ONNXRUNTIME_LIB_PATH=/path/to/libonnxruntime.so  # Linux
# or
export ONNXRUNTIME_LIB_PATH=/path/to/libonnxruntime.dylib  # macOS

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

go run example_onnx.go helper.go

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

go run example_onnx.go helper.go \
  --batch \
  -voice-style "../assets/voice_styles/M1.json,../assets/voice_styles/F1.json" \
  -text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 기분 좋았어요." \
  -lang "en,ko"

This will:

• Generate speech for 2 different voice-text-language pairs
• Use male voice (M1.json) for the first text in English
• Use female voice (F1.json) for the second text in Korean
• Process both samples in a single batch

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

go run example_onnx.go helper.go \
  -total-step 10 \
  -voice-style "../assets/voice_styles/M1.json" \
  -text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

The system automatically chunks long texts into manageable segments, synthesizes each segment separately, and concatenates them with natural pauses (0.3 seconds by default) into a single audio file. This happens by default when you don't use the --batch flag:

go run example_onnx.go helper.go \
  -voice-style "../assets/voice_styles/M1.json" \
  -text "This is a very long text that will be automatically split into multiple chunks. The system will process each chunk separately and then concatenate them together with natural pauses between segments. This ensures that even very long texts can be processed efficiently while maintaining natural speech flow and avoiding memory issues."

This will:

• Automatically split the text into chunks based on paragraph and sentence boundaries
• Synthesize each chunk separately
• Add 0.3 seconds of silence between chunks for natural pauses
• Concatenate all chunks into a single audio file

Note: Automatic text chunking is disabled when using --batch mode. In batch mode, each text is processed as-is without chunking.

Available Arguments Copy Chapter

Notes Copy Chapter

• Multilingual Support: Use -lang to specify the language for each text. Available: 31 languages; see the main README for the full list
• Batch Processing: When using --batch, the number of -voice-style, -text, and -lang entries must match
• Automatic Chunking: Without --batch, long texts are automatically split and concatenated with 0.3s pauses
• Quality vs Speed: Higher -total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet

Building a Binary Copy Chapter

To build a standalone executable:

go build -o tts_example example_onnx.go helper.go

Then run it:

./tts_example -voice-style "../assets/voice_styles/M1.json" -text "Hello world"

Overview (`ios/README.md`) Copy Section

Supertonic iOS Example App

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

A minimal iOS demo that runs Supertonic 3 (ONNX Runtime) on-device. The app shows:

• Multiline text input
• NFE (denoising steps) slider
• Voice toggle (M/F)
• Language selector for 31 supported languages
• Generate & Play buttons
• RTF display (Elapsed / Audio seconds)

All ONNX models/configs are reused from Supertonic/assets/onnx, and voice style JSON files from Supertonic/assets/voice_styles.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

Prerequisites Copy Chapter

• macOS 13+, Xcode 15+
• Swift 5.9+
• iOS 15+ device (recommended)
• Homebrew, XcodeGen

Install tools (if needed):

brew install xcodegen

Quick Start (zero-click in Xcode) Copy Chapter

0. Prepare assets next to the iOS target (one-time)

cd ios/ExampleiOSApp
mkdir -p onnx voice_styles
rsync -a ../../assets/onnx/ onnx/
rsync -a ../../assets/voice_styles/ voice_styles/

1. Generate the Xcode project with XcodeGen

xcodegen generate
open ExampleiOSApp.xcodeproj

2. Open in Xcode and select your iPhone as the run destination

• Targets → ExampleiOSApp → Signing & Capabilities: Select your Team
• iOS Deployment Target: 15.0+

3. Build & Run on device

• Type text → adjust NFE/Voice → Tap Generate → Audio plays automatically
• An RTF line shows like: RTF 0.30x · 3.04s / 10.11s

What's included (generated project) Copy Chapter

• SwiftUI app files: App.swift, ContentView.swift, TTSViewModel.swift, AudioPlayer.swift
• Runtime wrapper: TTSService.swift (includes TTS inference logic)
• Resources (local, vendored in ios/ExampleiOSApp/onnx and ios/ExampleiOSApp/voice_styles after step 0)

These references are defined in project.yml and added to the app bundle by XcodeGen.

App Controls Copy Chapter

• Text: Multiline TextEditor
• NFE: Denoising steps (default 8)
• Voice: M/F voice style selector
• Language: Language selector for 31 supported languages
• Generate: Runs end-to-end synthesis
• Play/Stop: Controls playback of the last output
• RTF: Shows Elapsed / Audio seconds for quick performance intuition

Multilingual Support Copy Chapter

Supertonic 3 supports 31 languages. Select the appropriate language for your input text; see the main README for the full code list.

Overview (`java/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using ExampleONNX.java.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

This project uses Maven for dependency management.

Prerequisites Copy Section

• Java Development Kit (JDK) 11 or higher, not just a JRE
• Maven 3.6 or higher

On macOS with Homebrew:

brew install openjdk@17 maven
export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
export PATH="$(brew --prefix openjdk@17)/bin:$PATH"

Install dependencies Copy Section

mvn clean install

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

mvn exec:java

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

mvn exec:java -Dexec.args="--batch --voice-style ../assets/voice_styles/M1.json,../assets/voice_styles/F1.json --text 'The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 기분 좋았어요.' --lang en,ko"

This will:

• Generate speech for 2 different voice-text-language pairs
• Use male voice (M1.json) for the first text in English
• Use female voice (F1.json) for the second text in Korean
• Process both samples in a single batch

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

mvn exec:java -Dexec.args="--total-step 10 --voice-style ../assets/voice_styles/M1.json --text 'Increasing the number of denoising steps improves the output fidelity and overall quality.'"

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

The system automatically chunks long texts into manageable segments, synthesizes each segment separately, and concatenates them with natural pauses (0.3 seconds by default) into a single audio file. This happens by default when you don't use the --batch flag:

mvn exec:java -Dexec.args="--voice-style ../assets/voice_styles/M1.json --text 'This is a very long text that will be automatically split into multiple chunks. The system will process each chunk separately and then concatenate them together with natural pauses between segments. This ensures that even very long texts can be processed efficiently while maintaining natural speech flow and avoiding memory issues.'"

This will:

• Automatically split the text into chunks based on paragraph and sentence boundaries
• Synthesize each chunk separately
• Add 0.3 seconds of silence between chunks for natural pauses
• Concatenate all chunks into a single audio file

Note: Automatic text chunking is disabled when using --batch mode. In batch mode, each text is processed as-is without chunking.

Tip: If your text contains apostrophes, use escaping or run the JAR directly:

java -jar target/tts-example.jar --total-step 10 --text "Text with apostrophe's here"

Building a Fat JAR Copy Chapter

To create a standalone JAR with all dependencies:

mvn clean package

Then run it directly:

java -jar target/tts-example.jar

Or with arguments:

java -jar target/tts-example.jar --total-step 10 --text "Your custom text here"

Available Arguments Copy Chapter

Notes Copy Chapter

• Multilingual Support: Use --lang to specify the language for each text. Available: 31 languages; see the main README for the full list
• Batch Processing: When using --batch, the number of --voice-style, --text, and --lang entries must match
• Automatic Chunking: Without --batch, long texts are automatically split and concatenated with 0.3s pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet
• Voice Styles: Uses pre-extracted voice style JSON files for fast inference

Overview (`nodejs/README.md`) Copy Section

TTS ONNX Node.js Implementation

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

Node.js implementation for TTS inference. Uses ONNX Runtime to generate speech from text.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Requirements Copy Chapter

• Node.js v16 or higher
• npm or yarn

Installation Copy Chapter

cd nodejs
npm install

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

node example_onnx.js

Or:

node example_onnx.js

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

node example_onnx.js \
  --voice-style "../assets/voice_styles/M1.json,../assets/voice_styles/F1.json" \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 좋아서 한참을 멈춰 서서 들었어요." \
  --lang "en,ko" \
  --batch

This will:

• Use --batch flag to enable batch processing mode
• Generate speech for 2 different voice-text pairs
• Use male voice style (M1.json) for the first English text
• Use female voice style (F1.json) for the second Korean text
• Process both samples in a single batch (automatic text chunking disabled)

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

node example_onnx.js \
  --total-step 10 \
  --voice-style "../assets/voice_styles/M1.json" \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

For long texts, the system automatically chunks the text into manageable segments and generates a single audio file:

node example_onnx.js \
  --voice-style "../assets/voice_styles/M1.json" \
  --text "Once upon a time, in a small village nestled between rolling hills, there lived a young artist named Clara. Every morning, she would wake up before dawn to capture the first light of day. The golden rays streaming through her window inspired countless paintings. Her work was known throughout the region for its vibrant colors and emotional depth. People from far and wide came to see her gallery, and many said her paintings could tell stories that words never could."

This will:

• Automatically split the long text into smaller chunks (max 300 characters by default)
• Process each chunk separately while maintaining natural speech flow
• Insert brief silences (0.3 seconds) between chunks for natural pacing
• Combine all chunks into a single output audio file

Note: When using batch mode (--batch), automatic text chunking is disabled. Use non-batch mode for long-form text synthesis.

Available Arguments Copy Chapter

Notes Copy Chapter

• Batch Processing: The number of voice style files must match the number of texts. Use commas to separate files and pipes to separate texts
• Multilingual Support: Use --lang to specify language(s). Available: 31 languages; see the main README for the full list
• Long-Form Inference: Without --batch flag, long texts are automatically chunked and combined into a single audio file with natural pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet

Architecture Copy Chapter

• helper.js: Node.js port of Python's helper.py

  • Preprocessor: Audio preprocessing (STFT, Mel Spectrogram)
  • UnicodeProcessor: Text preprocessing
  • Utility functions (mask generation, tensor conversion, etc.)

• example_onnx.js: Main inference script

  • ONNX model loading
  • TTS inference pipeline execution
  • WAV file saving

• package.json: Node.js project configuration and dependencies

Implementation Notes Copy Chapter

1. Pure Node.js WAV Processing: Writes WAV files without external native libraries. Outputs 16-bit PCM format.

2. Memory Efficiency: Note that Node.js may consume significant memory when processing large arrays.

3. Performance: The mel spectrogram extraction (Step 1-1) is currently slower than Python's Librosa, which uses highly optimized C extensions. This bottleneck could be further improved with additional optimizations such as WASM-based FFT libraries or native addons.

Overview (`py/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using example_onnx.py.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added supertonic PyPI package! Install via pip install supertonic for a streamlined experience. This is a separate usage method from the ONNX examples in this directory. For more details, visit supertonic-py documentation and see example_pypi.py for usage.

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed. Adjust the speed factor to make speech faster or slower while maintaining natural quality.

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

This project uses uv for fast package management.

Install uv (if not already installed) Copy Section

curl -LsSf https://astral.sh/uv/install.sh | sh

Install dependencies Copy Section

uv sync

Or if you prefer using traditional pip with requirements.txt:

pip install -r requirements.txt

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

uv run example_onnx.py

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

uv run example_onnx.py \
  --voice-style ../assets/voice_styles/M1.json ../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange." "오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 좋아서 한참을 멈춰 서서 들었어요." \
  --lang en ko \
  --batch

This will:

• Use --batch flag to enable batch processing mode
• Generate speech for 2 different voice-text pairs
• Use male voice style (M1.json) for the first English text
• Use female voice style (F1.json) for the second Korean text
• Process both samples in a single batch (automatic text chunking disabled)

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

uv run example_onnx.py \
  --total-step 10 \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

For long texts, the system automatically chunks the text into manageable segments and generates a single audio file:

uv run example_onnx.py \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Once upon a time, in a small village nestled between rolling hills, there lived a young artist named Clara. Every morning, she would wake up before dawn to capture the first light of day. The golden rays streaming through her window inspired countless paintings. Her work was known throughout the region for its vibrant colors and emotional depth. People from far and wide came to see her gallery, and many said her paintings could tell stories that words never could."

This will:

• Automatically split the long text into smaller chunks (max 300 characters by default)
• Process each chunk separately while maintaining natural speech flow
• Insert brief silences (0.3 seconds) between chunks for natural pacing
• Combine all chunks into a single output audio file

Note: When using batch mode (--batch), automatic text chunking is disabled. Use non-batch mode for long-form text synthesis.

Example 5: Adjusting Speech Speed Copy Section

Control the speed of speech synthesis:

# Faster speech (speed > 1.0)
uv run example_onnx.py \
  --voice-style ../assets/voice_styles/F2.json \
  --text "This text will be synthesized at a faster pace." \
  --speed 1.2

# Slower speech (speed < 1.0)
uv run example_onnx.py \
  --voice-style ../assets/voice_styles/M2.json \
  --text "This text will be synthesized at a slower, more deliberate pace." \
  --speed 0.9

This will:

• Use --speed 1.2 to generate faster speech
• Use --speed 0.9 to generate slower speech
• Default speed is 1.05 if not specified
• Recommended speed range is between 0.9 and 1.5 for natural-sounding results

Available Arguments Copy Chapter

Notes Copy Chapter

• Batch Processing: The number of --voice-style files must match the number of --text entries
• Multilingual Support: Use --lang to specify language(s). Available: 31 languages; see the main README for the full list
• Long-Form Inference: Without --batch flag, long texts are automatically chunked and combined into a single audio file with natural pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet

Overview (`rust/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using Rust.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

This project uses Cargo for package management.

Install Rust (if not already installed) Copy Section

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build the project Copy Section

cargo build --release

Basic Usage Copy Chapter

You can run the inference in two ways:

1. Using cargo run (builds if needed, then runs)
2. Direct binary execution (faster if already built)

Example 1: Default Inference Copy Section

Run inference with default settings:

# Using cargo run
cargo run --release --bin example_onnx

# Or directly execute the built binary (faster)
./target/release/example_onnx

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

# Using cargo run
cargo run --release --bin example_onnx -- \
  --batch \
  --voice-style ../assets/voice_styles/M1.json,../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 기분 좋았어요." \
  --lang en,ko

# Or using the binary directly
./target/release/example_onnx \
  --batch \
  --voice-style ../assets/voice_styles/M1.json,../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 기분 좋았어요." \
  --lang en,ko

This will:

• Generate speech for 2 different voice-text-language pairs
• Use male voice (M1.json) for the first text in English
• Use female voice (F1.json) for the second text in Korean
• Process both samples in a single batch

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

# Using cargo run
cargo run --release --bin example_onnx -- \
  --total-step 10 \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

# Or using the binary directly
./target/release/example_onnx \
  --total-step 10 \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

The system automatically chunks long texts into manageable segments, synthesizes each segment separately, and concatenates them with natural pauses (0.3 seconds by default) into a single audio file. This happens by default when you don't use the --batch flag:

# Using cargo run
cargo run --release --bin example_onnx -- \
  --voice-style ../assets/voice_styles/M1.json \
  --text "This is a very long text that will be automatically split into multiple chunks. The system will process each chunk separately and then concatenate them together with natural pauses between segments. This ensures that even very long texts can be processed efficiently while maintaining natural speech flow and avoiding memory issues."

# Or using the binary directly
./target/release/example_onnx \
  --voice-style ../assets/voice_styles/M1.json \
  --text "This is a very long text that will be automatically split into multiple chunks. The system will process each chunk separately and then concatenate them together with natural pauses between segments. This ensures that even very long texts can be processed efficiently while maintaining natural speech flow and avoiding memory issues."

This will:

• Automatically split the text into chunks based on paragraph and sentence boundaries
• Synthesize each chunk separately
• Add 0.3 seconds of silence between chunks for natural pauses
• Concatenate all chunks into a single audio file

Note: Automatic text chunking is disabled when using --batch mode. In batch mode, each text is processed as-is without chunking.

Available Arguments Copy Chapter

Notes Copy Chapter

• Multilingual Support: Use --lang to specify the language for each text. Available: 31 languages; see the main README for the full list
• Batch Processing: When using --batch, the number of --voice-style, --text, and --lang entries must match
• Automatic Chunking: Without --batch, long texts are automatically split and concatenated with 0.3s pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet
• Known Issues: On some platforms (especially macOS), there might be a mutex cleanup warning during exit. This is a known ONNX Runtime issue and doesn't affect functionality. The implementation uses libc::_exit() and mem::forget() to bypass this issue.

Overview (`swift/README.md`) Copy Section

TTS ONNX Inference Examples

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This guide provides examples for running TTS inference using example_onnx.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added --speed parameter to control speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Installation Copy Chapter

This project uses Swift Package Manager (SPM) for dependency management.

Prerequisites Copy Section

• Swift 5.9 or later
• macOS 13.0 or later

Build the project Copy Section

swift build -c release

Basic Usage Copy Chapter

Example 1: Default Inference Copy Section

Run inference with default settings:

.build/release/example_onnx

This will use:

• Voice style: ../assets/voice_styles/M1.json
• Text: "This morning, I took a walk in the park, and the sound of the birds and the breeze was so pleasant that I stopped for a long time just to listen."
• Output directory: results/
• Total steps: 8
• Number of generations: 4

Example 2: Batch Inference Copy Section

Process multiple voice styles and texts at once:

.build/release/example_onnx \
  --batch \
  --voice-style ../assets/voice_styles/M1.json,../assets/voice_styles/F1.json \
  --text "The sun sets behind the mountains, painting the sky in shades of pink and orange.|오늘 아침에 공원을 산책했는데, 새소리와 바람 소리가 너무 기분 좋았어요." \
  --lang en,ko

This will:

• Generate speech for 2 different voice-text-language triplets
• Use male voice (M1.json) for the first English text
• Use female voice (F1.json) for the second Korean text
• Process both samples in a single batch

Example 3: High Quality Inference Copy Section

Increase denoising steps for better quality:

.build/release/example_onnx \
  --total-step 10 \
  --voice-style ../assets/voice_styles/M1.json \
  --text "Increasing the number of denoising steps improves the output's fidelity and overall quality."

This will:

• Use 10 denoising steps instead of the default 8
• Produce higher quality output at the cost of slower inference

Example 4: Long-Form Inference Copy Section

The system automatically chunks long texts into manageable segments, synthesizes each segment separately, and concatenates them with natural pauses (0.3 seconds by default) into a single audio file. This happens by default when you don't use the --batch flag:

.build/release/example_onnx \
  --voice-style ../assets/voice_styles/M1.json \
  --text "This is a very long text that will be automatically split into multiple chunks. The system will process each chunk separately and then concatenate them together with natural pauses between segments. This ensures that even very long texts can be processed efficiently while maintaining natural speech flow and avoiding memory issues."

This will:

• Automatically split the text into chunks based on paragraph and sentence boundaries
• Synthesize each chunk separately
• Add 0.3 seconds of silence between chunks for natural pauses
• Concatenate all chunks into a single audio file

Note: Automatic text chunking is disabled when using --batch mode. In batch mode, each text is processed as-is without chunking.

Available Arguments Copy Chapter

Multilingual Support Copy Chapter

Supertonic 3 supports 31 languages. Use the --lang argument to specify the language; see the main README for the full code list.

Notes Copy Chapter

• Batch Processing: When using --batch, the number of --voice-style, --text, and --lang entries must match
• Automatic Chunking: Without --batch, long texts are automatically split and concatenated with 0.3s pauses
• Quality vs Speed: Higher --total-step values produce better quality but take longer
• GPU Support: GPU mode is not supported yet

Overview (`web/README.md`) Copy Section

Supertonic Web Example

Archived model download: From the repository root, run
hf download supertone-oss-archive/supertonic-3 --revision aafc6e32416a594460b32413efc49d7fe4ce6d46 --local-dir assets
before using this example. See the archive setup guide
for installation. Hosted demos mentioned in historical release notes are not part of this archive.

This example demonstrates how to use Supertonic in a web browser using ONNX Runtime Web.

Historical release notes

These entries describe past releases. Hosted services and support offers mentioned
here are no longer provided by this archive. Follow the archive setup guide.

2026.04.29 - 🎉 Supertonic 3 released with 31-language support, improved reading accuracy, and v2-compatible public ONNX assets. Demo | Models

2025.12.10 - Added 6 new voice styles (M3, M4, M5, F3, F4, F5). See Voices for details

2025.12.08 - Optimized ONNX models via OnnxSlim now available on Hugging Face Models

2025.11.23 - Enhanced text preprocessing with comprehensive normalization, emoji removal, symbol replacement, and punctuation handling for improved synthesis quality.

2025.11.19 - Added speed control slider to adjust speech synthesis speed (default: 1.05, recommended range: 0.9-1.5).

2025.11.19 - Added automatic text chunking for long-form inference. Long texts are split into chunks and synthesized with natural pauses.

Features Copy Chapter

• 🌐 Runs entirely in the browser (no server required for inference)
• 🚀 WebGPU support with automatic fallback to WebAssembly
• 🌍 Multilingual support: 31 languages
• ⚡ Pre-extracted voice styles for instant generation
• 🎨 Modern, responsive UI
• 🎭 Multiple voice style presets (5 Male, 5 Female)
• 💾 Download generated audio as WAV files
• 📊 Detailed generation statistics (audio length, generation time)
• ⏱️ Real-time progress tracking

Requirements Copy Chapter

• Node.js (for development server)
• Modern web browser (Chrome, Edge, Firefox, Safari)

Installation Copy Chapter

1. Install dependencies:

npm install

Running the Demo Copy Chapter

Start the development server:

npm run dev

This will start a local development server (usually at http://localhost:3000) and open the demo in your browser.

Usage Copy Chapter

1. Wait for Models to Load: The app will automatically load models and the default voice style (M1)
2. Select Voice Style: Choose from available voice presets
   • Male 1-5 (M1-M5): Male voice styles
   • Female 1-5 (F1-F5): Female voice styles
3. Select Language: Choose the language that matches your input text
   • Supertonic 3 supports 31 language codes; see the main README for the full list.
4. Enter Text: Type or paste the text you want to convert to speech
5. Adjust Settings (optional):
   • Total Steps: More steps = better quality but slower (default: 8)
6. Generate Speech: Click the "Generate Speech" button
7. View Results:
   • See the full input text
   • View audio length and generation time statistics
   • Play the generated audio in the browser
   • Download as WAV file

Multilingual Support Copy Chapter

Supertonic 3 supports 31 languages. Make sure to select the correct language for your input text to get the best results. The model will automatically handle text preprocessing and pronunciation for the selected language.

Technical Details Copy Chapter

Browser Compatibility Copy Section

This demo uses:

• ONNX Runtime Web: For running models in the browser
• Web Audio API: For playing generated audio
• Vite: For development and bundling

Notes Copy Chapter

• The ONNX models must be accessible at assets/onnx/ relative to the web root
• Voice style JSON files must be accessible at assets/voice_styles/ relative to the web root
• Pre-extracted voice styles enable instant generation without audio processing
• Ten voice style presets are provided (M1-M5, F1-F5)

Troubleshooting Copy Chapter

Models not loading Copy Section

• Check browser console for errors
• Ensure assets/onnx/ path is correct and models are accessible
• Check CORS settings if serving from a different domain

WebGPU not available Copy Section

• WebGPU is only available in recent Chrome/Edge browsers (version 113+)
• The app will automatically fall back to WebAssembly if WebGPU is not available
• Check the backend badge to see which execution provider is being used

Out of memory errors Copy Section

• Try shorter text inputs
• Reduce denoising steps
• Use a browser with more available memory
• Close other tabs to free up memory

Audio quality issues Copy Section

• Try different voice style presets
• Increase denoising steps for better quality

Slow generation Copy Section

• If using WebAssembly, try a browser that supports WebGPU
• Ensure no other heavy processes are running
• Consider using fewer denoising steps for faster (but lower quality) results

--- METRICS ---

• Files Extracted: 12
• Estimated Token Budget: ~24278 tokens
• Canonical Reference: https://codewiki.google/github.com/supertone-inc/supertonic