How to Build Supertonic from Source Using CMake

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 searches for ONNX Runtime as a shared library and nlohmann-json for JSON parsing.

Ubuntu and Debian

Install the required packages and ONNX Runtime:

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:

brew install cmake nlohmann-json onnxruntime

Windows with vcpkg

Install dependencies via vcpkg:

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:

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:

cd cpp
mkdir -p build && cd build

Configure with CMake

Run CMake to configure the project. The script in 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.

cmake ..

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

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).

Compile the Code

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

cmake --build . --config Release

Run the Example

Execute the binary to verify the build:

./example_onnx

By default, this uses the voice style assets/voice_styles/M1.json from the repository root and outputs WAV files to results/.

Build Configuration Options

The 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:

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 to generate WAV outputs.

Frequently Asked Questions

Where does the CMake build find ONNX Runtime?

The CMake script in 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 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). 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, F1.json) that define voice characteristics. These are loaded by the TextToSpeech class in cpp/helper.cpp to configure the ONNX Runtime inference session for specific voices.

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