# How to Migrate from Supertonic v2 to v3 While Maintaining ONNX Interface Compatibility

> Migrate Supertonic v2 to v3 seamlessly. Maintain ONNX interface compatibility by swapping model and config files. Learn how to upgrade without inference code changes.

- Repository: [Supertone Inc./supertonic](https://github.com/supertone-inc/supertonic)
- Tags: migration-guide
- Published: 2026-06-15

---

**You can migrate from Supertonic v2 to v3 without changing any inference code by simply replacing the four ONNX model files and the [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json) configuration file, because v3 preserves the exact same ONNX input/output signatures as v2.**

Supertonic v3 expands support to 31 languages and improves inference speed, yet deliberately maintains the public ONNX inference contract established in v2. This guide walks you through the exact steps to upgrade the `supertone-inc/supertonic` assets while keeping your existing integration code intact.

## Understanding the ONNX-Based Architecture

Supertonic uses a pipeline of four ONNX models that remain structurally identical between v2 and v3. The `load_onnx_all` function in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) (lines 82-97) initializes these models, and the `TextToSpeech` class orchestrates inference.

The four model files are:

- **`duration_predictor.onnx`** – Predicts speech duration per input token (loaded as `dp_ort`)
- **`text_encoder.onnx`** – Converts token IDs and style embeddings into text latents (loaded as `text_enc_ort`)
- **`vector_estimator.onnx`** – Refines latents through flow-matching steps (loaded as `vector_est_ort`)
- **`vocoder.onnx`** – Generates the final 44.1 kHz waveform (loaded as `vocoder_ort`)

The inference pipeline in `TextToSpeech._infer` feeds the same tensor names to each model regardless of version. These inputs include `text_ids`, `style_ttl`, `style_dp`, `text_mask`, and `latent`, ensuring that as long as the model files are compatible, your calling code requires no modifications.

## Downloading the v3 ONNX Assets

The v3 models are hosted on Hugging Face and use the same filenames as v2, allowing for a simple file swap.

1. **Clone the v3 repository** using Git LFS:

```bash
git lfs install
git clone https://huggingface.co/Supertone/supertonic-3 assets

```

2. **Replace your existing assets** by overwriting the contents of your current `assets` directory with the new files:
   - `duration_predictor.onnx`
   - `text_encoder.onnx`
   - `vector_estimator.onnx`
   - `vocoder.onnx`
   - [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json)

Because the filenames are identical, the `load_onnx_all` helper automatically picks up the v3 versions when your application restarts.

## Verifying Compatibility with Existing Code

You can verify the migration using the provided [`example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/example_onnx.py) script without any source changes:

```python
from supertonic import TTS

# Initialize with local assets

tts = TTS(auto_download=False)

# Load voice style from JSON

style = tts.get_voice_style(voice_name="M1")

# Synthesize audio using the same API as v2

wav, dur = tts.synthesize(
    text="Supertonic v3 maintains full ONNX backward compatibility.",
    lang="en",
    voice_style=style,
    total_steps=8,
    speed=1.05,
)

tts.save_audio(wav, "v3_output.wav")

```

Running this script should produce audio output immediately. If you encounter no shape mismatches or input errors, your migration is complete.

## Expanding to New Languages (Optional)

While not required for migration, v3 adds significant language coverage. The `AVAILABLE_LANGS` constant in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) (lines 13-14) now supports 31 languages compared to v2's smaller set.

You can now pass new ISO-639-1 codes such as `vi` (Vietnamese), `uk` (Ukrainian), or `tr` (Turkish) to `tts.synthesize` without changing your inference logic.

## Cross-Language Migration Checklist

All official SDKs follow the same pattern: they load the four ONNX files from a directory you specify. To migrate from Supertonic v2 to v3 across different languages, simply replace the assets folder:

- **Python**: Update the path used by [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) and run [`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py)
- **Node.js**: Replace assets referenced in [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) and verify with [`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js)
- **Go**: Update the assets path in [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) and test with [`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go)
- **Java**: Replace files loaded by [`java/Helper.java`](https://github.com/supertone-inc/supertonic/blob/main/java/Helper.java) and run [`java/ExampleONNX.java`](https://github.com/supertone-inc/supertonic/blob/main/java/ExampleONNX.java)
- **C++**: Update the directory in [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp) and verify with [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp)
- **C#**: Replace assets used by [`csharp/Helper.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/Helper.cs) and test with [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs)
- **Swift**: Update resources accessed by [`swift/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Helper.swift) and verify with [`swift/ExampleONNX.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/ExampleONNX.swift)
- **Flutter**: Replace assets loaded in `flutter/lib/helper.dart` and test with `flutter/lib/main.dart`
- **iOS**: Update bundle resources used by [`ios/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/ios/Helper.swift) in the example app

## Verifying On-Device Performance

After migration, run your existing benchmark scripts to confirm improvements. The v3 models offer faster real-time factors and reduced memory usage compared to v2, though the ONNX input/output interfaces remain identical. You can use the [`test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/test_all.sh) script to validate performance across all supported language bindings.

## Summary

- **Supertonic v3 preserves the exact ONNX signatures** (`text_ids`, `style_ttl`, `style_dp`, `text_mask`, etc.) used in v2, ensuring zero-code-change migration.
- **Replace five files** (`duration_predictor.onnx`, `text_encoder.onnx`, `vector_estimator.onnx`, `vocoder.onnx`, and [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json)) from the Hugging Face repository to upgrade.
- **`load_onnx_all` in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py)** and its equivalents in other SDKs handle the new assets automatically.
- **31 languages** are now available using the same synthesis API.
- **All language SDKs** (Python, Node.js, Go, Java, C++, C#, Swift, Flutter, iOS) follow the same migration pattern: swap assets, keep code.

## Frequently Asked Questions

### Do I need to modify my Python inference code when upgrading from v2 to v3?

No. According to the Supertonic source code, the `TextToSpeech` class and `load_onnx_all` function accept the same input tensors and model filenames. Simply replace the ONNX files and [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json) in your assets directory; your existing `tts.synthesize()` calls will work unchanged.

### Where can I download the official v3 ONNX model files?

The official v3 assets are hosted at `https://huggingface.co/Supertone/supertonic-3`. You must use Git LFS to clone the repository, which contains the four `.onnx` files and the configuration JSON required for inference.

### Will my v2 integrations break if I accidentally mix v2 and v3 model files?

Yes, you must replace all four ONNX files (`duration_predictor.onnx`, `text_encoder.onnx`, `vector_estimator.onnx`, `vocoder.onnx`) simultaneously with their v3 counterparts. The [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json) file should also be updated to match the v3 release. Mixing versions across the pipeline will cause inference errors or garbled output.

### Does v3 support the same voice styles and model configurations as v2?

Yes, the voice style JSON files and the [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json) configuration schema remain compatible. However, v3 adds support for 31 languages (expanded from v2's set) and improves accuracy, so you may benefit from re-exporting styles if you need the new linguistic capabilities.