How to Contribute to Supertonic: A Complete Guide for Open-Source Developers

Fork the supertone-inc/supertonic repository, install prerequisites including Git LFS and ONNX Runtime, create a feature branch, and submit a pull request targeting the main branch after running ./test_all.sh to verify your changes.

Supertonic is an open-source, on-device multilingual Text-to-Speech (TTS) system built on ONNX Runtime. The project welcomes contributions ranging from bug fixes and performance improvements to new language support and SDK extensions. This guide walks you through the complete contribution workflow, architectural highlights, and key source files you will encounter when contributing to the repository.

Setting Up Your Development Environment

Before writing code, you need to fork the repository and configure your local machine. The project requires Git LFS for model assets and ONNX Runtime libraries for inference.

First, fork the repository on GitHub, then clone your personal fork:

git clone https://github.com/<your-user>/supertonic.git
cd supertonic

Install the model assets using Git LFS. The repository stores public ONNX checkpoints and preset voice JSONs that are downloaded from Hugging Face:

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

Follow the Prerequisites section in the main README.md to install language-specific toolchains (Python, Node.js, C++, Go, Rust, or Java) and the ONNX Runtime libraries for your platform.

Understanding the Repository Architecture

Supertonic organizes code by programming language, with each SDK containing a minimal example that loads the same ONNX model and invokes the inference pipeline. Understanding this structure helps you target the right files for your contribution.

The repository consists of these core components:

• Model Assets (assets/): Public ONNX checkpoints and voice presets downloaded via Git LFS from Hugging Face
• ONNX Runtime Wrappers: Language-specific bindings that instantiate Ort::Session (C++), onnxruntime::InferenceSession (Python), or equivalents in py/example_onnx.py, cpp/example_onnx.cpp, go/example_onnx.go, and rust/example_onnx.rs
• TTS Core Logic: Text preprocessing and expression-tag parsing (<laugh>, <breath>, etc.) handled in py/helper.py, nodejs/helper.js, and cpp/helper.cpp
• SDK Boilerplate: Build configuration files like rust/Cargo.toml, nodejs/package.json, and java/pom.xml
• Testing Harness: The test_all.sh script builds each language example and runs smoke tests

All SDKs share the same public ONNX interface, meaning new language support can be added by copying an existing example and wiring the appropriate runtime bindings.

Contribution Workflow Step-by-Step

The repository follows a standard GitHub flow. While there is no dedicated CONTRIBUTING.md, these steps align with the project's established practices:

1. Fork and clone: Create your personal fork on GitHub and clone it locally
2. Install prerequisites: Complete the setup in README.md for Git LFS and ONNX Runtime
3. Pick a target area: Choose a language SDK (Python, Node.js, C++, Go, Rust, Java), core model code, documentation, or tests
4. Create a feature branch: Isolate your work with git checkout -b my-feature-branch
5. Implement the change: Edit source files like py/example_onnx.py or cpp/example_onnx.cpp
6. Run the test suite: Execute ./test_all.sh on Linux/macOS or run language-specific tests to verify functionality
7. Commit and push: Use descriptive commit messages and push to origin my-feature-branch
8. Open a Pull Request: Target supertone-inc/supertonic:main from your fork
9. Review and iterate: Respond to maintainer feedback and squash commits if requested
10. Merge: Once approved, maintainers will merge your contribution

Code Examples for Contributors

When adding features or fixing bugs, reference the existing implementations in your target language. Below are minimal examples demonstrating how the TTS pipeline works across different SDKs.

Python Implementation

In py/example_onnx.py, the Python SDK wraps the ONNX Runtime session:

from supertonic import TTS

tts = TTS(auto_download=True)
style = tts.get_voice_style(voice_name="M1")
wav, duration = tts.synthesize(
    text="Supertonic runs on-device with zero network latency.",
    lang="en",
    voice_style=style,
    total_steps=8,
    speed=1.05,
)
tts.save_audio(wav, "output.wav")

Node.js Implementation

The JavaScript binding in nodejs/example_onnx.js uses the helper module:

const { TTS } = require("./helper");
const tts = new TTS({ autoDownload: true });

(async () => {
  const style = await tts.getVoiceStyle("M1");
  const { wav, duration } = await tts.synthesize({
    text: "Supertonic runs on-device with zero network latency.",
    lang: "en",
    voiceStyle: style,
    totalSteps: 8,
    speed: 1.05,
  });
  await tts.saveAudio(wav, "output.wav");
})();

C++ Implementation

The C++ demo in cpp/example_onnx.cpp shows direct use of the ONNX Runtime C++ API:

#include "helper.h"

int main() {
  SupertonicTTS tts;
  tts.LoadModel();
  auto style = tts.GetVoiceStyle("M1");
  auto result = tts.Synthesize(
      "Supertonic runs on-device with zero network latency.",
      "en", style, 8, 1.05);
  tts.SaveWav(result.wav, "output.wav");
}

Key Files and Entry Points

Navigate the codebase using these critical paths:

• README.md: Project overview, quick-start guide, and language support table
• py/example_onnx.py: Reference Python implementation for model loading and inference
• py/helper.py: Shared preprocessing and ONNX wrapper for the Python SDK
• nodejs/example_onnx.js: JavaScript entry point demonstrating the Node.js binding
• nodejs/helper.js: Core utility functions for the Node.js SDK
• cpp/example_onnx.cpp: C++ demo using the ONNX Runtime C++ API directly
• cpp/helper.cpp and cpp/helper.h: Utility layer for the C++ example
• go/example_onnx.go: Go binding example showing ONNX Runtime integration
• rust/example_onnx.rs: Rust demo leveraging the onnxruntime crate
• web/index.html and web/main.js: Browser demo running via WebGPU/ONNX-Runtime-Web
• test_all.sh: Shell script that builds each language example and runs inference checks
• LICENSE: MIT License for the source code

Testing Your Changes

Before submitting a pull request, you must verify that your changes do not break existing functionality. The repository uses test_all.sh as the primary validation tool.

Run the comprehensive test suite from the repository root:

./test_all.sh

This script builds each language example and executes a quick inference check across all supported SDKs. For language-specific testing, navigate to the relevant directory (e.g., cd py && uv run example_onnx.py) and follow the testing instructions in that folder's README.

Summary

• Fork and clone the supertone-inc/supertonic repository, then install Git LFS and download model assets from Hugging Face
• Target specific areas like language SDKs in py/, nodejs/, cpp/, go/, or rust/, or contribute to core logic in the helper files
• Maintain the public ONNX interface to ensure backward compatibility with existing SDKs
• Run ./test_all.sh before submitting your pull request to verify cross-language functionality
• Follow idiomatic style for each language (PEP 8 for Python, clang-format for C++, gofmt for Go) and update documentation to reflect changes

Frequently Asked Questions

Does Supertonic have a CONTRIBUTING.md file?

No, the repository does not contain a dedicated CONTRIBUTING.md file. However, the project follows standard open-source workflows documented in the main README.md. Contribution guidelines are effectively communicated through the repository structure and the test_all.sh validation script.

What prerequisites do I need to install before contributing?

You need Git LFS for downloading model assets and ONNX Runtime libraries for your platform. Additionally, install the language-specific toolchains for whichever SDK you plan to modify (Python, Node.js, C++, Go, Rust, or Java). Model assets are cloned from https://huggingface.co/Supertone/supertonic-3 into the assets/ directory.

How do I add support for a new programming language?

Copy an existing example from py/example_onnx.py, cpp/example_onnx.cpp, or rust/example_onnx.rs and create the appropriate runtime bindings for your target language. Ensure you implement the same public ONNX interface for loading models, preprocessing text, and running inference. Add your new SDK to test_all.sh for automated testing.

What should I do if my pull request fails review?

Respond to maintainer comments promptly and amend your pull request with requested changes. You may need to add unit tests, update documentation, or squash commits. The maintainers prioritize backward compatibility with the ONNX model interface, so ensure your changes do not alter the tensor input/output specifications.

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