# How to Load and Use Voice Styles in Supertonic TTS: A Complete Guide

> Learn to load and use voice styles in Supertonic TTS. This guide shows how to utilize style tensors via language helpers for speaker-specific synthesis.

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

---

**Voice styles in Supertonic TTS are JSON files containing pre-computed `style_ttl` and `style_dp` tensors that you load via language-specific helpers like `loadVoiceStyle` in Swift or `loadStyleFromJSON` in JavaScript, then pass to the `TextToSpeech.call` method for speaker-specific synthesis.**

Supertonic, the open-source text-to-speech engine by Supertone, separates acoustic modeling from speaker identity through modular voice styles. This guide shows you how to load these styles from JSON files and integrate them into your TTS pipeline using the official C++ core and language bindings.

## What Is a Voice Style in Supertonic TTS?

In the Supertonic architecture, a **voice style** is a self-contained JSON file that stores speaker-specific embeddings as two pre-computed tensors. According to the `supertone-inc/supertonic` source code, each file contains:

- **`style_ttl`**: Tensor for the text-to-latent model component with shape `[1, dim1, dim2]`
- **`style_dp`**: Tensor for the duration-predictor component with shape `[1, dim1, dim2]`

These tensors are serialized as nested arrays of Float values. At runtime, the language bindings flatten these arrays and wrap them in ONNX Runtime `ORTValue` objects, which the acoustic model consumes during inference.

## How to Load Voice Styles in Supertonic TTS

The repository provides language-specific helpers to handle JSON parsing, tensor flattening, and ONNX tensor creation. All implementations support batch loading of multiple styles for multi-speaker synthesis.

### Swift (iOS) Implementation

In [`swift/Sources/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Sources/Helper.swift), the `loadVoiceStyle` function (lines 741-806) provides the primary loading mechanism:

```swift
func loadVoiceStyle(_ voiceStylePaths: [String], verbose: Bool) throws -> Style {
    // Reads JSON files, flattens TTL & DP tensors, creates ORTValues
    // Returns Style struct wrapping the ONNX tensors
    return Style(ttl: ortValueTTL, dp: ortValueDP)
}

```

To load a single voice style:

```swift
let stylePath = Bundle.main.path(forResource: "M1", ofType: "json",
                                 inDirectory: "assets/voice_styles")!
let style = try loadVoiceStyle([stylePath], verbose: true)

```

### Web (JavaScript) Implementation

For browser applications, [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) exposes the `loadStyleFromJSON` wrapper (lines 60-66) that calls the core `loadVoiceStyle` utility:

```javascript
async function loadStyleFromJSON(stylePath) {
    const style = await loadVoiceStyle([stylePath], true);
    return style;
}

```

The underlying tensor flattening logic resides in [`web/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/web/helper.js), which converts the nested JSON arrays into flat Float32 buffers required by ONNX Runtime Web.

### Python and Command-Line Usage

All language bindings support the `--voice-style` flag for CLI usage. As shown in [`test_all.sh`](https://github.com/supertone-inc/supertonic/blob/main/test_all.sh) and the Python examples, you can load styles from the `assets/voice_styles/` directory:

```bash
uv run example_onnx.py \
  --voice-style assets/voice_styles/M1.json \
  --text "Hello world" \
  --lang en

```

For batch processing with multiple speakers, pass comma-separated paths:

```bash
uv run example_onnx.py \
  --batch \
  --voice-style assets/voice_styles/M1.json,assets/voice_styles/F1.json \
  --text "Good morning" "How are you?" \
  --lang en en

```

## Using Voice Styles for Speech Synthesis

Once loaded, the **Style** object wraps the ONNX tensors and feeds directly into the synthesis pipeline via the `TextToSpeech.call` or `TextToSpeech.batch` methods.

### Single Speaker Inference

In Swift, pass the style to the `call` method as implemented in [`swift/Sources/ExampleONNX.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Sources/ExampleONNX.swift) (lines 108-121):

```swift
let tts = try loadTextToSpeech(onnxDir, false, env)
let style = try loadVoiceStyle([stylePath], verbose: true)
let (wav, duration) = try tts.call("Welcome to Supertonic.", "en", style, 100)

```

In JavaScript web applications:

```javascript
const style = await loadStyleFromJSON("assets/voice_styles/F2.json");
const audioBuffer = await synthesizeText("Welcome to Supertonic", "en", style);

```

### Batch Processing with Multiple Styles

Supertonic supports loading multiple voice styles simultaneously for parallel inference. In Swift, pass an array of paths to `loadVoiceStyle`:

```swift
let styles = try loadVoiceStyle([
    "path/to/M1.json",
    "path/to/F1.json"
], verbose: true)
let (wavs, durations) = try tts.batch(texts, langs, styles, totalSteps)

```

This creates a batched Style tensor where the first dimension equals the number of voice styles, enabling the ONNX Runtime to synthesize different speakers in a single session.

## Voice Style File Locations and Format

Pre-extracted voice styles ship with the repository under **`assets/voice_styles/`**. The SDK includes ten default speakers:

- [`M1.json`](https://github.com/supertone-inc/supertonic/blob/main/M1.json) through [`M5.json`](https://github.com/supertone-inc/supertonic/blob/main/M5.json) (Male voices 1-5)
- [`F1.json`](https://github.com/supertone-inc/supertonic/blob/main/F1.json) through [`F5.json`](https://github.com/supertone-inc/supertonic/blob/main/F5.json) (Female voices 1-5)

Native SDKs reference these via relative paths (`../assets/voice_styles/`), while web builds access them from the repository root or CDN deployment. Each JSON file follows the schema:

```json
{
  "style_ttl": [[[0.01, 0.02, ...]]],
  "style_dp": [[[0.03, 0.04, ...]]]
}

```

The nested array structure represents the `[1, dim1, dim2]` tensor shape expected by the acoustic model.

## Summary

- Voice styles in Supertonic TTS are JSON files containing `style_ttl` and `style_dp` tensors that define speaker characteristics separate from the acoustic model
- Load styles using `loadVoiceStyle` in Swift ([`swift/Sources/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Sources/Helper.swift) lines 741-806) or `loadStyleFromJSON` in JavaScript ([`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) lines 60-66)
- Pass the resulting Style object to `TextToSpeech.call` for inference; supply multiple paths for batch multi-speaker synthesis
- Use the `--voice-style` flag in Python, Node.js, Go, Rust, C#, Java, and C++ CLI examples to specify JSON file paths
- Pre-trained styles reside in `assets/voice_styles/` and include M1-M5 and F1-F5 variants

## Frequently Asked Questions

### Where are the voice style files located in the Supertonic repository?

Pre-extracted voice styles are stored in the `assets/voice_styles/` directory at the repository root. This location contains JSON files for ten default speakers (M1-M5 and F1-F5), which are referenced by native SDKs using relative paths (`../assets/voice_styles/`) and by web implementations from the root or deployed CDN.

### Can I load multiple voice styles at once for batch processing?

Yes. The `loadVoiceStyle` function accepts an array of file paths and creates batched tensors where the first dimension equals the number of styles provided. This enables synthesizing speech for multiple speakers in a single inference call, as demonstrated in the CLI examples using comma-separated `--voice-style` arguments across Python, JavaScript, and Swift implementations.

### What is the internal structure of voice style JSON files?

Each JSON file contains two top-level fields: `style_ttl` (text-to-latent tensor) and `style_dp` (duration-predictor tensor). Both store data as nested arrays of Float values with shape `[1, dim1, dim2]`. The language bindings flatten these arrays and wrap them in ONNX Runtime `ORTValue` objects before the inference session begins.

### How do I switch voice styles in the Supertonic web demo?

In the browser interface defined in [`web/index.html`](https://github.com/supertone-inc/supertonic/blob/main/web/index.html), select your desired style from the dropdown menu. This triggers the `loadStyleFromJSON` function in [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js), which asynchronously loads the JSON from `assets/voice_styles/`, flattens the tensors using utilities in [`web/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/web/helper.js), and returns a Style object ready for the synthesis pipeline.