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

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 and 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 – P/Invoke wrappers that import functions from the native helper.dll
• 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 – Public C++ API header exposing the Supertonic::Helper class
• cpp/helper.cpp – Core synthesis engine implementation handling ONNX runtime inference
• cpp/example_onnx.cpp – Sample executable demonstrating command-line usage
• 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:

cd supertonic\csharp
dotnet restore

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

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:

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, which instantiates the SupertonicHelper class (defined in 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:

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:

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:

.\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 parses these arguments, initializes the Supertonic::Helper object (declared in cpp/helper.h and implemented in 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 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, which P/Invokes the native helper.dll through csharp/Helper.cs wrappers.

• C++ approach: Use CMake with Visual Studio 2022 to build cpp/example_onnx.cpp, directly linking the core synthesis engine from 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). 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 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 to process extended text sequences without memory constraints.

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