# How to Run Supertonic on Windows Using C# or C++

> Easily run Supertonic on Windows using C# or C++. Build the C# sample with dotnet CLI or compile the C++ sample with CMake to generate WAV audio files.

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

---

**You can run Supertonic on Windows by building the C# sample with the `dotnet` CLI (which P/Invokes the native `helper.dll`) or compiling the C++ sample with CMake and Visual Studio 2022, both interfacing with the same core synthesis engine to generate WAV audio files.**

Supertonic is a cross-platform speech synthesis engine developed by supertone-inc that provides native Windows support through both managed .NET and native C++ implementations. This guide explains how to run Supertonic on Windows using C# or C++ by referencing the exact source files—such as [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs) and [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp)—to ensure technical accuracy and reproducible builds.

## Prerequisites for Windows Development

Before building Supertonic, install the toolchain specific to your chosen language. Both approaches require the native `helper` library, but differ in their build orchestration.

### C# Requirements

- **.NET 6 SDK** (or newer) with the `dotnet` CLI on your `PATH`
- Verify installation: `dotnet --version` (must return ≥ 6.0)

### C++ Requirements

- **CMake 3.15+** and **Visual Studio 2022** (Desktop Development with C++ workload)
- Verify installation: `cmake --version` and ensure `cl.exe` is available

## Repository Structure and Key Files

Understanding the codebase layout helps clarify how the C# and C++ implementations share the same runtime core while using different binding strategies.

### C# Implementation Files

- [`csharp/Helper.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/Helper.cs) – P/Invoke wrappers that import functions from the native `helper.dll`
- [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs) – Console application entry point that parses arguments and calls the synthesis pipeline
- `csharp/Supertonic.csproj` – MSBuild project file configured with `RuntimeIdentifier` set to `win-x64`

### C++ Implementation Files

- [`cpp/helper.h`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.h) – Public C++ API header exposing the `Supertonic::Helper` class
- [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp) – Core synthesis engine implementation handling ONNX runtime inference
- [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp) – Sample executable demonstrating command-line usage
- [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) – Build configuration generating Visual Studio solutions

## Building and Running the C# Sample

The C# approach uses P/Invoke to marshal data between managed code and the native Windows DLL, providing a simpler build process for .NET developers.

### Step 1: Restore and Build

Navigate to the `csharp` directory and restore NuGet packages:

```powershell
cd supertonic\csharp
dotnet restore

```

Build the project for 64-bit Windows, which automatically copies the native `helper.dll` to the output directory:

```powershell
dotnet build -c Release -r win-x64

```

### Step 2: Execute the Synthesis

Run the example by specifying the voice style directory, input text, and language code:

```powershell
dotnet run -c Release --no-build -- \
    --voice-style ..\..\voice_style/default \
    --text "Hello, Supertonic on Windows!" \
    --lang en

```

This invokes the `Main` method in [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs), which instantiates the `SupertonicHelper` class (defined in [`csharp/Helper.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/Helper.cs)) to call the native `synthesize` function. The application writes the resulting audio to `output.wav` in the current directory.

## Building and Running the C++ Sample

The C++ implementation provides direct access to the native API without marshalling overhead, using CMake to handle the ONNX Runtime dependency linkage.

### Step 1: Generate the Visual Studio Solution

Open a Developer Command Prompt for Visual Studio 2022 and create a build directory:

```powershell
cd supertonic\cpp
mkdir build
cd build
cmake -G "Visual Studio 17 2022" -A x64 ..

```

This generates `Supertonic.sln` and project files linking against `onnxruntime.dll` (bundled in the repository).

### Step 2: Compile the Executable

Build the Release configuration:

```powershell
cmake --build . --config Release

```

The compiler produces `example_onnx.exe` in the `Release\` directory, statically linking the helper implementation while dynamically linking the ONNX Runtime.

### Step 3: Run the Native Application

Execute the program with the required arguments:

```powershell
.\Release\example_onnx.exe ^
    --voice-style "..\..\voice_style\default" ^
    --text "Hello from Supertonic C++ on Windows!" ^
    --lang en

```

The `main` function in [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp) parses these arguments, initializes the `Supertonic::Helper` object (declared in [`cpp/helper.h`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.h) and implemented in [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)), and writes the synthesized audio to `output.wav`.

## Troubleshooting Common Issues

When running Supertonic on Windows, specific errors indicate configuration or path problems that have straightforward solutions.

### DllNotFoundException in C#

If you encounter `System.DllNotFoundException: Unable to load DLL 'helper'`, the native library is missing or built for the wrong architecture. Re-run `dotnet build -r win-x64` to ensure the x64 version of `helper.dll` is copied to the output folder.

### Missing onnxruntime.dll

When the C++ executable fails to start citing `onnxruntime.dll not found`, verify that the DLL exists next to `example_onnx.exe`. The CMake script should copy this automatically, but manual verification ensures the dynamic linker can resolve the dependency.

### Garbled Audio or No Output

Silent or corrupted output typically indicates an incorrect `--voice-style` path. Confirm the directory contains [`metadata.json`](https://github.com/supertone-inc/supertonic/blob/main/metadata.json) and the `.onnx` model file, and ensure the `--lang` parameter matches a supported code listed in the voice style's configuration.

## Summary

- **C# approach**: Use `dotnet build -r win-x64` to compile [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs), which P/Invokes the native `helper.dll` through [`csharp/Helper.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/Helper.cs) wrappers.

- **C++ approach**: Use CMake with Visual Studio 2022 to build [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp), directly linking the core synthesis engine from [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp).
- Both methods accept `--voice-style`, `--text`, and `--lang` arguments, producing identical `output.wav` files via the shared native runtime.
- The repository bundles `onnxruntime.dll` for Windows, eliminating external dependency installation for the C++ build.

## Frequently Asked Questions

### Can I use a newer .NET version like .NET 8 or .NET 9?

Yes. The `csharp/Supertonic.csproj` file targets .NET 6 as a minimum, but you can build and run the project using the .NET 8 or .NET 9 SDK without modifying the source code. The `dotnet` CLI automatically handles backward compatibility for this console application.

### Why does the C# sample require building the C++ helper library?

The C# implementation relies on P/Invoke to call functions from the native `helper.dll`, which is itself built from the C++ source ([`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)). When you run `dotnet build -r win-x64`, the MSBuild process compiles this native DLL and copies it to the output directory, enabling the managed code to access the underlying ONNX runtime inference engine.

### Is it possible to run the C++ sample without Visual Studio installed?

No, you need the Visual Studio 2022 C++ toolchain (or Build Tools for Visual Studio 2022) because the CMake configuration generates a Visual Studio-specific solution file using the generator `"Visual Studio 17 2022"`. While you could theoretically use a different generator like Ninja with the MSVC compiler, the official [`cpp/CMakeLists.txt`](https://github.com/supertone-inc/supertonic/blob/main/cpp/CMakeLists.txt) is optimized for the Visual Studio IDE workflow on Windows.

### How do I synthesize long-form content over 30 seconds?

Both the C# and C++ samples support the `--long-form` flag. In the C# implementation, add `--long-form` to the `dotnet run` command arguments. In the C++ implementation, append `--long-form` when calling `example_onnx.exe`. This enables the internal streaming decoder in [`helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/helper.cpp) to process extended text sequences without memory constraints.