Prerequisites for Supertonic: Complete Setup Guide for Multi-Language TTS

To run Supertonic, you must install Git LFS to download the ONNX model assets and satisfy language-specific runtime requirements such as Python 3.9+, .NET 9, Node.js 18+, or Go with ONNX Runtime.

Supertonic is an open-source, multi-language text-to-speech (TTS) system developed by supertone-inc/supertonic that runs entirely on-device across Python, Node.js, WebGPU, Java, Go, C#, Swift, Rust, and other runtimes. Before synthesizing speech, you need to configure system-level dependencies and download the pre-trained model files. This guide covers the exact prerequisites for Supertonic based on the repository's source code and documentation.

Universal Prerequisites (All Languages)

Every Supertonic implementation requires the same core asset setup regardless of your target language.

Git LFS and Model Assets

Supertonic stores large ONNX model files using Git LFS (Large File Storage). Without this, the assets folder will contain only pointer files instead of actual model weights.

Install Git LFS using your package manager:

# macOS

brew install git-lfs && git lfs install

# Other platforms: follow instructions at https://git-lfs.com

Once Git LFS is initialized, download the voice models and style JSON files into an assets directory:

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

As documented in the repository's main README.md (lines 109-126), these assets contain the ONNX inference graphs and voice configuration files required at runtime.

Language-Specific Requirements

After installing the universal assets, configure your development environment according to your implementation language.

Python Prerequisites

Supertonic requires Python 3.9 or newer. The repository recommends using uv for fast dependency management:

# Install uv

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

# Sync dependencies (in py/ directory)

uv sync

Alternatively, use standard pip: pip install -r requirements.txt. See py/README.md (lines 23-33) for detailed Python setup instructions.

Go Prerequisites

Go bindings require the ONNX Runtime C library installed on your system:

# macOS installation

brew install onnxruntime

Linux and Windows users should install ONNX Runtime from the official release page. The Go examples in go/example_onnx.go and go/helper.go link against this native library.

Java Prerequisites

Java implementations require a full JDK (not just JRE). Version 17 is explicitly mentioned in the documentation:

brew install openjdk@17

Build and execution use Maven, configured via java/pom.xml with entry points in java/Helper.java and java/ExampleONNX.java.

C# / .NET Prerequisites

The C# examples require .NET 9 or newer, with roll-forward to newer major versions allowed:

dotnet --list-sdks  # Verify version >= 9

Source files csharp/Helper.cs and csharp/ExampleONNX.cs demonstrate the .NET integration.

Node.js and WebGPU Prerequisites

For server-side JavaScript, install Node.js 18 or newer. For browser-based WebGPU inference, use Chrome 112+, Edge 112+, or Firefox Nightly with WebGPU enabled.

cd nodejs
npm install

# For web examples

cd web
npm install
npm run dev  # Launches Vite dev server on http://localhost:5173

The web configuration is defined in web/package.json and web/vite.config.js.

Swift and iOS Prerequisites

iOS development requires Xcode 15 or newer (includes Swift 5.9) and XcodeGen for project generation:

brew install xcodegen

Install Xcode from the App Store before building the Swift examples.

Rust Prerequisites

Rust examples require Rust 1.70 or newer and Cargo:

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

C++ Prerequisites

C++ implementations need CMake 3.24 or newer and a C++17-compatible compiler:

brew install cmake

Flutter Prerequisites

Flutter support requires Flutter 3.13 or newer and the Dart SDK. Follow the official Flutter installation guide at flutter.dev.

Quick Start Commands by Language

Below are the minimal terminal commands to verify your prerequisites for Supertonic and run the first example.

Python (Fastest Setup)

# Install uv and dependencies

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

# Run ONNX inference (downloads assets automatically on first run)

uv run example_onnx.py

Source: py/README.md lines 21-33

Go

brew install onnxruntime
cd go
go mod download
go run example_onnx.go helper.go

Source: README.md lines 22-24

Java

brew install openjdk@17
cd java
mvn clean install
mvn exec:java

Source: README.md lines 24-25

C#

# Verify .NET 9+ is installed

dotnet --list-sdks

cd csharp
dotnet run

Source: README.md lines 25-26

Key Files and Directories

Understanding these files helps troubleshoot prerequisite issues:

• README.md (root): Central hub documenting high-level prerequisites and model download instructions (lines 109-126)

• py/README.md: Python-specific setup using uv or pip

• go/example_onnx.go and go/helper.go: Demonstrate Go bindings to ONNX Runtime

• java/Helper.java and java/ExampleONNX.java: Java entry points with Maven configuration

• csharp/Helper.cs and csharp/ExampleONNX.cs: C# runtime integration examples

• web/package.json: Browser WebGPU build configuration

• assets/: Runtime directory containing ONNX models and voice-style JSONs from HuggingFace

Summary

• Install Git LFS first to properly download the large ONNX model files from https://huggingface.co/Supertone/supertonic-3
• Universal requirement: All languages need the assets directory populated with model weights and JSON configuration files
• Python: Use Python 3.9+ with uv (recommended) or pip
• Compiled languages: Install system dependencies like ONNX Runtime C library (Go), JDK 17 (Java), .NET 9 (C#), or CMake 3.24+ (C++)
• Web: Requires Node.js 18+ and a WebGPU-capable browser (Chrome/Edge 112+)
• Mobile: Xcode 15+ for iOS/Swift, Flutter 3.13+ for cross-platform mobile

Frequently Asked Questions

Do I need a GPU to run Supertonic?

No. Supertonic is designed for on-device CPU inference using ONNX Runtime. While WebGPU examples can utilize GPU acceleration in browsers, the Python, Go, Java, and other native implementations run efficiently on CPU. The repository's examples in py/example_onnx.py and go/example_onnx.go default to CPU execution.

Can I run Supertonic without Git LFS?

No. The pre-trained voice models are stored as large binary files in Git LFS. Without installing Git LFS and running git lfs install, the assets folder will contain only LFS pointer files rather than the actual ONNX graphs required for inference. See the main README.md lines 112-115 for installation instructions.

What Python version is required for Supertonic?

Supertonic requires Python 3.9 or newer. The py/README.md explicitly recommends using the uv package manager for faster dependency resolution, though standard pip install -r requirements.txt is also supported. The examples use modern Python features compatible with 3.9+.

Is an Internet connection required after initial setup?

No. Once you have downloaded the model assets using git clone https://huggingface.co/Supertone/supertonic-3 assets and installed the language-specific dependencies, Supertonic operates entirely offline. The TTS synthesis happens on-device without API calls or cloud services, as implemented in the local ONNX Runtime examples across all supported languages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}