How supertone-inc/supertonic works
1. What this repo is
- This repository is not a single application; it is a multi-runtime example and packaging repo for the Supertonic on-device TTS model.
- The actual inference product is the shared ONNX model assets; the code here shows how to wire that model into different languages and platforms.
2. Main boundary: model assets vs. sample code
- Each runtime folder has an assets/ directory expected to contain the downloaded Supertonic checkpoint and preset voice data.
- The README makes clear that the first run can fetch these assets from Hugging Face, and all examples stay local after that.
- This creates the key architectural boundary: text input and voice settings in the app/runtime → ONNX Runtime inference → WAV audio output.
3. Shared execution pattern across all runtimes
- The examples all follow the same high-level flow:
- normalize/load model assets from local assets/
- prepare text, language code, voice/style inputs
- run ONNX inference
- emit 44.1 kHz WAV audio or playback it directly
- The repo is therefore organized around portable inference adapters, not around a central service or backend.
4. Python as the reference implementation
- py/ is the most complete reference path and includes:
- example_onnx.py for direct local inference
- example_pypi.py for package-style usage
- helper.py for shared loading/synthesis utilities
- Its tooling (pyproject.toml, requirements.txt, uv.lock) indicates it is the primary “getting started” environment and likely the clearest canonical API shape.
5. C/C++-style native runtime layer
- cpp/ is a CMake-based native sample using example_onnx.cpp, helper.cpp, and helper.h.
- This is the lowest-level integration path in the repo and likely mirrors how other non-managed runtimes invoke ONNX Runtime directly.
- Because it is native, this folder represents the boundary where model execution is closest to the host OS and filesystem.
6. Managed desktop/runtime bindings
- csharp/, java/, go/, rust/, and swift/ each implement the same inference idea in their ecosystem’s idiomatic packaging:
- C# uses a .csproj
- Java uses Maven
- Go uses modules
- Rust uses Cargo
- Swift uses Swift Package Manager
- These folders are separate integration surfaces, but architecturally they are all wrappers around the same local ONNX model execution.
7. Node.js and browser paths
- nodejs/ is the server-side JavaScript example, while web/ is the browser example.
- The browser stack is materially different because it uses client-side inference via onnxruntime-web, with index.html, main.js, helper.js, style.css, and Vite config supporting a static dev/build workflow.
- This is the only path in the repo that is explicitly browser-native and does not depend on a desktop runtime.
8. Mobile and app-shell integrations
- ios/ExampleiOSApp is a full SwiftUI iOS sample, with dedicated files for:
- TTSService for synthesis orchestration
- TTSViewModel for app state
- AudioPlayer for playback
- ContentView for the UI
- flutter/ is the cross-platform app wrapper, and its macos/ subtree shows it is configured as a desktop-capable Flutter app rather than a generic library.
- These platforms are important because they show how the same model can be embedded inside a UI app with playback and state management.
9. Support code inside each example
- Many runtimes include a Helper.* file alongside the entry example file.
- These helpers are the local abstraction layer for repetitive tasks such as loading assets, configuring the model session, and writing audio output.
- In architectural terms, they are the runtime-specific glue between the app entrypoint and the shared model assets.
10. Tooling and build boundaries
- Build systems are deliberately per-language, not centralized:
- C++: CMake
- Java: Maven
- Rust: Cargo
- Go: module tooling
- Node/web: npm + Vite
- Swift: Swift Package Manager
- iOS: Xcodegen-generated Xcode project
- Python: uv/pyproject-based environment
- C#: .NET project file
- This reinforces that the repo is a polyglot SDK/demo collection, not a single cross-language framework.
11. Test and orchestration
- test_all.sh suggests a repo-level smoke-test or validation script that likely exercises multiple example paths.
- The existence of this script is a clue that the examples are intended to stay behaviorally aligned across runtimes.
12. Infrastructure and external dependency
- The only material external infrastructure is Hugging Face Hub for model download/storage.
- There is no cloud inference service in this repo; the architecture is explicitly offline/local-first, with optional first-run asset download.
13. How to draw the diagram
- A good architecture diagram would show:
- a shared Supertonic model assets block
- multiple runtime adapters around it (Python, native, JVM, .NET, Go, Rust, Swift, Node, browser, iOS, Flutter)
- a common data flow from text + language + voice/style inputs to ONNX Runtime / onnxruntime-web to audio output
- optional initial dependency arrow from Hugging Face to the local assets/ folder
- The main architectural point is that all examples are parallel front doors into the same local TTS model, not separate products.
Main entry points: example_onnx.py Python sample · example_onnx.cpp C++ sample · main.js Web app · test_all.sh Smoke tests
Components 20
Core model
Shared local assets and inference boundary
- Hugging Face · Optional first-run model download source
- Model assets · Downloaded Supertonic checkpoint and voice data under each runtime's assets folder
- Text + voice · Text, language, voice, and style settings
- ONNX Runtime · Local model execution for desktop, mobile, and native runtimes
- WAV output · 44.1 kHz synthesized audio or direct playback
Python
Reference implementation and package-style usage
- Python sample · Primary Python path for direct inference and package-style usage
py/example_onnx.py - Python helper · Shared loading and synthesis utilities
py/helper.py
Native
Lowest-level C/C++ integration
- C++ sample · CMake-based direct ONNX Runtime integration
cpp/example_onnx.cpp - C++ helper · Native asset loading and synthesis support
cpp/helper.cpp
Managed runtimes
Language-specific wrappers around local ONNX inference
- C# sample · .NET example for local inference
csharp/ExampleONNX.cs - Java sample · Maven-based JVM example
java/ExampleONNX.java - Go sample · Go module example for local inference
go/example_onnx.go - Rust sample · Cargo-based example using local assets
rust/src/example_onnx.rs - Swift sample · Swift Package Manager example
swift/Sources/ExampleONNX.swift
JavaScript
Node.js and browser paths
- ORT Web · Client-side ONNX inference in the browser
- Node sample · Server-side JavaScript example
nodejs/example_onnx.js - Web app · Static browser example with Vite and onnxruntime-web
web/main.js
Mobile apps
iOS and Flutter app shells
- iOS app · SwiftUI sample with service, view model, and audio playback
ios/ExampleiOSApp/TTSService.swift - Flutter app · Flutter wrapper with macOS-capable app shell
flutter/lib/main.dart
Tooling
Repo-level validation and smoke testing
- Smoke tests · Repo-level script to exercise multiple example paths
test_all.sh
Connections 41
- Hugging Face → Model assets: download · Fetch model checkpoint and voice data on first run
- Model assets → Python sample: load · Python example reads local assets
- Model assets → C++ sample: load · Native sample reads local assets
- Model assets → C# sample: load · Managed runtime reads local assets
- Model assets → Java sample: load · Managed runtime reads local assets
- Model assets → Go sample: load · Managed runtime reads local assets
- Model assets → Rust sample: load · Managed runtime reads local assets
- Model assets → Swift sample: load · Managed runtime reads local assets
- Model assets → Node sample: load · Node.js example reads local assets
- Model assets → Web app: load · Browser example loads bundled local assets
- Model assets → iOS app: load · iOS sample reads local assets
- Model assets → Flutter app: load · Flutter sample reads local assets
- Python sample → Python helper: uses · Shared Python synthesis utilities
- C++ sample → C++ helper: uses · Native helper utilities
- Text + voice → Python sample: feeds · Text, language, and voice settings
- Text + voice → C++ sample: feeds · Text, language, and voice settings
- Text + voice → C# sample: feeds · Text, language, and voice settings
- Text + voice → Java sample: feeds · Text, language, and voice settings
- Text + voice → Go sample: feeds · Text, language, and voice settings
- Text + voice → Rust sample: feeds · Text, language, and voice settings
- Text + voice → Swift sample: feeds · Text, language, and voice settings
- Text + voice → Node sample: feeds · Text, language, and voice settings
- Text + voice → Web app: feeds · Text, language, and voice settings
- Text + voice → iOS app: feeds · Text, language, and voice settings
- Text + voice → Flutter app: feeds · Text, language, and voice settings
- Python sample → ONNX Runtime: runs on · Python invokes local ONNX inference
- C++ sample → ONNX Runtime: runs on · C++ invokes local ONNX inference
- C# sample → ONNX Runtime: runs on · C# invokes local ONNX inference
- Java sample → ONNX Runtime: runs on · Java invokes local ONNX inference
- Go sample → ONNX Runtime: runs on · Go invokes local ONNX inference
- Rust sample → ONNX Runtime: runs on · Rust invokes local ONNX inference
- Swift sample → ONNX Runtime: runs on · Swift invokes local ONNX inference
- Node sample → ONNX Runtime: runs on · Node.js invokes local ONNX inference
- Web app → ORT Web: runs on · Browser uses onnxruntime-web
- iOS app → ONNX Runtime: runs on · iOS sample invokes local ONNX inference
- Flutter app → ONNX Runtime: runs on · Flutter sample invokes local ONNX inference
- ONNX Runtime → WAV output: emits · Synthesized WAV or playable audio
- ORT Web → WAV output: emits · Browser playback output
- Smoke tests → Python sample: checks · Smoke test across example paths
- Smoke tests → C++ sample: checks · Smoke test across example paths
- Smoke tests → Web app: checks · Smoke test across example paths