# How to Build Supertonic from Source Using CMake

> Learn to build Supertonic from source with CMake. Follow our guide to clone the repository, install dependencies, and compile the TTS inference engine for your project.

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

---

**To build Supertonic from source using CMake, clone the repository with Git LFS, install ONNX Runtime and nlohmann-json dependencies, then run `cmake ..` and `cmake --build . --config Release` from the `cpp/build` directory to compile the TTS inference engine.**

Supertonic is a high-performance text-to-speech (TTS) inference engine developed by Supertone Inc. that leverages ONNX Runtime for optimized neural speech synthesis. This guide walks you through the complete process to build Supertonic from source using CMake, targeting the C++17 implementation located in the `cpp/` directory of the repository.

## Prerequisites

Supertonic requires **CMake ≥ 3.15**, a C++17-compatible compiler, and several dependencies. The build system defined in [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) searches for **ONNX Runtime** as a shared library and **nlohmann-json** for JSON parsing.

### Ubuntu and Debian

Install the required packages and ONNX Runtime:

```bash
sudo apt-get install cmake g++ nlohmann-json3-dev

# Download ONNX Runtime manually

wget https://github.com/microsoft/onnxruntime/releases/download/v1.16.3/onnxruntime-linux-x64-1.16.3.tgz
tar -xzf onnxruntime-linux-x64-1.16.3.tgz
sudo cp -r onnxruntime-linux-x64-1.16.3/include/* /usr/local/include/
sudo cp -r onnxruntime-linux-x64-1.16.3/lib/* /usr/local/lib/
sudo ldconfig

```

### macOS

Use Homebrew to install dependencies:

```bash
brew install cmake nlohmann-json onnxruntime

```

### Windows with vcpkg

Install dependencies via vcpkg:

```bash
vcpkg install nlohmann-json:x64-windows onnxruntime:x64-windows

```

## Step-by-Step Build Instructions

### Clone the Repository with Git LFS

The model assets are stored in Git LFS. Clone the repository and pull the large ONNX model files:

```bash
git clone https://github.com/supertone-inc/supertonic.git
cd supertonic
git lfs install
git lfs pull  # Downloads model files into assets/

```

### Create the Build Directory

Navigate to the C++ subdirectory and create a build folder:

```bash
cd cpp
mkdir -p build && cd build

```

### Configure with CMake

Run CMake to configure the project. The script in [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) (lines 8‑14) automatically sets Release flags (`-O3 -DNDEBUG -ffast-math`) and searches for ONNX Runtime using three methods: CMake config, `pkg-config`, or manual search in common locations.

```bash
cmake ..

```

If ONNX Runtime is installed in a non-standard location, specify the root:

```bash
cmake .. -DONNXRUNTIME_ROOT=/path/to/onnxruntime

```

According to the source code, if ONNX Runtime is not found, the script aborts with a clear error message (lines 52‑57 of [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt)).

### Compile the Code

Build the static helper library (`tts_helper`) and the example executable (`example_onnx`):

```bash
cmake --build . --config Release

```

### Run the Example

Execute the binary to verify the build:

```bash
./example_onnx

```

By default, this uses the voice style [`assets/voice_styles/M1.json`](https://github.com/supertone-inc/supertonic/blob/main/assets/voice_styles/M1.json) from the repository root and outputs WAV files to `results/`.

## Build Configuration Options

The [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) provides several configuration flags:

- **`-DCMAKE_BUILD_TYPE=Release`**: Enables `-O3 -DNDEBUG -ffast-math` optimizations (lines 8‑14).
- **`-DOpenMP_CXX_FOUND=ON`**: Links OpenMP for parallel processing (lines 91‑95).
- **`-DONNXRUNTIME_ROOT=/path/to/onnxruntime`**: Overrides auto-discovery for custom ONNX Runtime installations.

## Complete Build Command Example

For a full build and batch inference test on Linux or macOS:

```bash
git clone https://github.com/supertone-inc/supertonic.git && cd supertonic && \
git lfs install && git lfs pull && \
cd cpp && mkdir -p build && cd build && \
cmake .. && cmake --build . --config Release && \
./example_onnx \
  --voice-style ../../assets/voice_styles/M1.json,../../assets/voice_styles/F1.json \
  --text "Hello world|Bonjour le monde" \
  --lang en,fr \
  --batch

```

This command demonstrates **batch mode** (`--batch`), processing two voice-style and text pairs in a single run to produce two WAV files in `results/`.

## Summary

- Supertonic requires **CMake ≥ 3.15**, **C++17**, **ONNX Runtime**, and **nlohmann-json**.
- Clone with **Git LFS** to retrieve model assets from the `assets/` directory.
- Configure in `cpp/build/` with `cmake ..` and build with `cmake --build . --config Release`.
- The build produces `example_onnx` and the `tts_helper` library.
- Run the example with voice style JSONs like [`assets/voice_styles/M1.json`](https://github.com/supertone-inc/supertonic/blob/main/assets/voice_styles/M1.json) to generate WAV outputs.

## Frequently Asked Questions

### Where does the CMake build find ONNX Runtime?

The CMake script in [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) attempts three discovery methods in order: CMake config files, `pkg-config`, or manual search in common system locations. If none succeed, it aborts with an error message (lines 52‑57). Use `-DONNXRUNTIME_ROOT=<path>` to specify a custom installation prefix.

### What is the role of the `tts_helper` library?

`tts_helper` is a static library defined in [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) that wraps ONNX Runtime calls, handles voice-style JSON loading via `loadVoiceStyle`, and manages inference batching. The `example_onnx` executable links against this library to perform end-to-end synthesis.

### How do I enable parallel processing during inference?

Link OpenMP by passing `-DOpenMP_CXX_FOUND=ON` during the CMake configuration step (lines 91‑95 of [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt)). This enables parallel processing optimizations in the inference engine.

### What are the voice style JSON files in the assets directory?

The `assets/voice_styles/` directory contains JSON configuration files (e.g., [`M1.json`](https://github.com/supertone-inc/supertonic/blob/main/M1.json), [`F1.json`](https://github.com/supertone-inc/supertonic/blob/main/F1.json)) that define voice characteristics. These are loaded by the `TextToSpeech` class in [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp) to configure the ONNX Runtime inference session for specific voices.