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

> Learn how to contribute to Supertonic. Follow our guide to fork the repository, set up prerequisites, and submit your pull request for open-source collaboration.

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

---

**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`](https://github.com/supertone-inc/supertonic/blob/main/./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:

```bash
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:

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

```

Follow the **Prerequisites** section in the main [`README.md`](https://github.com/supertone-inc/supertonic/blob/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`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py), [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp), [`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go), and [`rust/example_onnx.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/example_onnx.rs)
- **TTS Core Logic**: Text preprocessing and expression-tag parsing (`<laugh>`, `<breath>`, etc.) handled in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py), [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js), and [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)
- **SDK Boilerplate**: Build configuration files like [`rust/Cargo.toml`](https://github.com/supertone-inc/supertonic/blob/main/rust/Cargo.toml), [`nodejs/package.json`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/package.json), and [`java/pom.xml`](https://github.com/supertone-inc/supertonic/blob/main/java/pom.xml)
- **Testing Harness**: The [`test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py) or [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp)
6. **Run the test suite**: Execute [`./test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/./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`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py), the Python SDK wraps the ONNX Runtime session:

```python
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`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js) uses the helper module:

```javascript
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`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp) shows direct use of the ONNX Runtime C++ API:

```cpp
#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`](https://github.com/supertone-inc/supertonic/blob/main/README.md)**: Project overview, quick-start guide, and language support table
- **[`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py)**: Reference Python implementation for model loading and inference
- **[`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py)**: Shared preprocessing and ONNX wrapper for the Python SDK
- **[`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js)**: JavaScript entry point demonstrating the Node.js binding
- **[`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js)**: Core utility functions for the Node.js SDK
- **[`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp)**: C++ demo using the ONNX Runtime C++ API directly
- **[`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)** and **[`cpp/helper.h`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.h)**: Utility layer for the C++ example
- **[`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go)**: Go binding example showing ONNX Runtime integration
- **[`rust/example_onnx.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/example_onnx.rs)**: Rust demo leveraging the `onnxruntime` crate
- **[`web/index.html`](https://github.com/supertone-inc/supertonic/blob/main/web/index.html)** and **[`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js)**: Browser demo running via WebGPU/ONNX-Runtime-Web
- **[`test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/test_all.sh) as the primary validation tool.

Run the comprehensive test suite from the repository root:

```bash
./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`](https://github.com/supertone-inc/supertonic/blob/main/./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`](https://github.com/supertone-inc/supertonic/blob/main/CONTRIBUTING.md) file. However, the project follows standard open-source workflows documented in the main [`README.md`](https://github.com/supertone-inc/supertonic/blob/main/README.md). Contribution guidelines are effectively communicated through the repository structure and the [`test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py), [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp), or [`rust/example_onnx.rs`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/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.