### Install and Run Examples

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Install the Supertonic package and navigate to the examples directory to run the provided scripts.

```bash
pip install supertonic
cd examples
python test1_simple.py
```

--------------------------------

### Install supertonic[serve]

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Install the necessary dependencies for running the supertonic server.

```bash
pip install 'supertonic[serve]'
```

--------------------------------

### Long Text Auto-Chunking Example Setup

Source: https://github.com/supertone-inc/supertonic-py/blob/main/notebook/supertonic_demo.ipynb

Prepares for demonstrating Supertonic's long text processing by setting a voice style. The actual long text synthesis logic would follow.

```python
style = tts.get_voice_style("F1")

# For longer texts, Supertonic automatically splits them into manageable chunks:
# - Respects sentence boundaries and common abbreviations (Mr., Mrs., Dr., etc.)
# - Adds silence between chunks for natural flow
# - Adjustable chunk size and silence duration
```

--------------------------------

### Install and Run Local Server

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Install the supertonic serve package and run the local HTTP server. The server provides native and OpenAI-compatible API endpoints.

```bash
pip install 'supertonic[serve]'                    # adds fastapi + uvicorn
supertonic serve --host 127.0.0.1 --port 7788      # defaults; loopback only
```

--------------------------------

### Install Supertonic Python Package

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/index.md

Install the Supertonic Python package using pip. This is the first step to using the library.

```bash
pip install supertonic
```

--------------------------------

### Run supertonic serve command

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Start the local TTS server. Default bind is 127.0.0.1:7788. Binding to any other interface is opt-in and emits a warning.

```bash
supertonic serve [--host HOST] [--port PORT] [OPTIONS]
```

--------------------------------

### Install Supertonic Python Package

Source: https://github.com/supertone-inc/supertonic-py/blob/main/notebook/supertonic_demo.ipynb

Installs the Supertonic package and its core dependencies: onnxruntime, numpy, soundfile, and huggingface-hub.

```python
# Install Supertonic
%pip install supertonic
```

--------------------------------

### Run Local HTTP Server for Supertonic

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/index.md

Install the serving component and run Supertonic as a local HTTP server. This enables integration with applications that use the OpenAI Audio Speech API.

```bash
pip install 'supertonic[serve]'
```

```bash
supertonic serve --host 127.0.0.1 --port 7788
```

--------------------------------

### Display supertonic model information

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/info.md

Run this command to view details about your supertonic installation, including cache paths and available voices. The `i` alias can also be used.

```bash
supertonic info
```

--------------------------------

### Basic Usage of supertonic say

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/say.md

Play speech directly from text. Ensure `sounddevice` is installed for playback.

```bash
supertonic say 'Hello, welcome to the world!'
```

--------------------------------

### Supertonic Version Command

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Display the currently installed version of the Supertonic CLI.

```bash
supertonic version
```

--------------------------------

### Get Help for Supertonic Subcommand

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Access detailed options and arguments for any specific Supertonic CLI subcommand.

```bash
supertonic <subcommand> --help
```

--------------------------------

### GET /v1/styles

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Lists available built-in voices and any imported custom voices.

```APIDOC
## GET /v1/styles

### Description
List built-in voices + imported custom voices

### Method
GET

### Endpoint
/v1/styles
```

--------------------------------

### GET /v1/health

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Liveness/readiness endpoint. Returns status, model, sample rate, version, and voices loaded.

```APIDOC
## GET /v1/health

### Description
Liveness/readiness, returns `{status, model, sample_rate, version, voices_loaded}`

### Method
GET

### Endpoint
/v1/health
```

--------------------------------

### Basic Text-to-Speech Synthesis

Source: https://github.com/supertone-inc/supertonic-py/blob/main/notebook/supertonic_demo.ipynb

Generates speech from a given text using a specified voice style. Assumes a clean setup and that the TTS instance is already loaded.

```python
# Generate speech with a simple text
text = "The train delay was announced at 4:45 PM on Wed, Apr 3, 2024 due to track maintenance."
style = tts.get_voice_style(voice_name="F3")
wav, duration = tts.synthesize(text, voice_style=style, total_steps=5)

display(Audio(wav.squeeze(), rate=tts.sample_rate))
```

--------------------------------

### Supertonic Serve Command

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Run a local HTTP server that provides a native `/v1/*` namespace and an OpenAI-compatible alias. Requires `fastapi` and `uvicorn`.

```bash
supertonic serve --host 127.0.0.1 --port 7788
```

--------------------------------

### get_model_revision

Source: https://github.com/supertone-inc/supertonic-py/blob/main/llms.txt

Gets the specific revision (commit hash or tag) for a model.

```APIDOC
## get_model_revision

### Description
Gets the specific revision (commit hash or tag) for a model.

### Method
`get_model_revision(model_name)`

### Parameters
- **model_name** (str) - The name of the model.
```

--------------------------------

### TTS Initialization and Synthesis

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/api/index.md

Demonstrates how to initialize the TTS engine and synthesize speech from text. Includes parameters for voice style, quality, speed, and chunking.

```APIDOC
## TTS Initialization and Synthesis

### Description
Initialize the TTS engine and synthesize speech from text. This example shows how to set up the `TTS` object and use the `synthesize` method with various parameters to control the output.

### Method
Python SDK methods

### Initialization
```python
from supertonic import TTS

tts = TTS(auto_download=True)       # Initialize TTS engine
```

### Getting Voice Style
```python
style = tts.get_voice_style(voice_name="M1")   # 10 built-in voices: M1–M5, F1–F5
```

### Synthesizing Speech
```python
wav, duration = tts.synthesize(
    text="Your text here.",         # Text to synthesize
    voice_style=style,              # Voice style object
    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8
    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
    max_chunk_length=300,           # Max characters per chunk (auto: 120 for Korean)
    silence_duration=0.3,           # Silence between chunks (seconds)
    lang=None,                      # Auto: "na" for multilingual, "en" for v1
    verbose=False,                  # Show detailed progress (default: False)
)
```

### Parameters for `synthesize`
#### Text
- **text** (str) - Required - The text content to be synthesized into speech.

#### Voice Style
- **voice_style** (object) - Required - A voice style object obtained from `get_voice_style`.

#### Quality
- **total_steps** (int) - Optional - Controls the quality of the synthesized speech. Range: 5 (low) to 12 (high). Default is 8.

#### Speed
- **speed** (float) - Optional - Controls the speaking rate. Range: 0.7 (slow) to 2.0 (fast). Default is 1.0.

#### Chunking
- **max_chunk_length** (int) - Optional - Maximum number of characters per audio chunk. Default is auto (120 for Korean).

#### Silence
- **silence_duration** (float) - Optional - Duration of silence in seconds to insert between audio chunks. Default is 0.3.

#### Language
- **lang** (str or None) - Optional - Specifies the language for synthesis. If None, it defaults to 'na' for multilingual or 'en' for v1.

#### Verbosity
- **verbose** (bool) - Optional - If True, displays detailed progress information during synthesis. Default is False.

### Return Value
- **wav** (bytes) - The synthesized audio data in WAV format.
- **duration** (float) - The duration of the synthesized audio in seconds.
```

--------------------------------

### get_model_repo

Source: https://github.com/supertone-inc/supertonic-py/blob/main/llms.txt

Gets the Hugging Face repository name for a given model.

```APIDOC
## get_model_repo

### Description
Gets the Hugging Face repository name for a given model.

### Method
`get_model_repo(model_name)`

### Parameters
- **model_name** (str) - The name of the model.
```

--------------------------------

### supertonic serve command

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Run a thin local HTTP server around the same TTS engine. Exposes a native `/v1/*` namespace plus an OpenAI Audio Speech-compatible alias.

```APIDOC
## supertonic serve

### Description
Run a thin local HTTP server around the same TTS engine. Exposes a native `/v1/*` namespace plus an **OpenAI Audio Speech-compatible alias** so any client that already speaks the OpenAI API can swap the base URL.

!!! note "Requires `fastapi` + `uvicorn`"
    Install with: `pip install 'supertonic[serve]'`

### Usage

```bash
supertonic serve [--host HOST] [--port PORT] [OPTIONS]
```

Default bind is `127.0.0.1:7788`. Binding to any other interface is opt-in and emits a one-line stderr warning — put the server behind a reverse proxy when exposing it beyond loopback.
```

--------------------------------

### Error Response Format

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Example of an error response from the server, which follows the OpenAI-shaped envelope for compatibility.

```json
{
  "error": {
    "message": "unsupported response_format 'mp3'; set response_format to one of: wav, flac, ogg",
    "type": "invalid_request_error",
    "code": "unsupported_response_format"
  }
}
```

--------------------------------

### Display Supertonic CLI Help

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

View the main help message for the Supertonic CLI to understand available commands.

```bash
supertonic --help
```

--------------------------------

### Use Custom Voice Styles

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Shows how to apply custom voice styles using JSON files or Python dictionaries.

```bash
python test4_custom_reference.py
```

--------------------------------

### Basic Text-to-Speech using CLI

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech directly from the command line. The first run automatically downloads the model. Supports multilingual synthesis by specifying the language code.

```bash
# Note: First run downloads model automatically (~400MB)
supertonic tts 'Supertonic is a lightning fast, on-device TTS system.' -o output.wav

# Multilingual support
supertonic tts '회의는 2024년 4월 3일 수요일 오후 4시 45분에 시작됩니다.' -o korean.wav --lang ko
```

--------------------------------

### Download Model CLI

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/download.md

Use this command to download a model from HuggingFace Hub. Aliases include 'd'.

```bash
supertonic download
```

--------------------------------

### Basic Text-to-Speech Synthesis in Python

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Initialize the TTS engine, select a voice style, and synthesize speech from text. The first run automatically downloads the model. The `lang` parameter can be used for language-specific handling.

```python
from supertonic import TTS

# Note: First run downloads model automatically (~400MB)
tts = TTS(auto_download=True)

# Get a voice style (10 built-in: M1–M5, F1–F5)
style = tts.get_voice_style(voice_name="F3")

# Generate speech. `lang` is optional — Supertonic-3 auto-resolves to
# the "na" fallback (so unknown text just works); pass an ISO code to
# opt into language-specific handling.
text = "The train delay was announced at 4:45 PM on Wed, Apr 3, 2024 due to track maintenance."
wav, duration = tts.synthesize(text, voice_style=style, lang="en")
# wav: np.ndarray, shape = (1, num_samples)
# duration: np.ndarray, shape = (1,)

# Save to file
tts.save_audio(wav, "output.wav")
```

```python
wav, duration = tts("This is a convenient shorthand method.", voice_style=style)
```

--------------------------------

### Initialize TTS and Synthesize Speech (Python)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/README.md

Initialize the TTS engine and synthesize speech from text. The first run downloads the model. Supports multilingual synthesis by specifying the 'lang' parameter.

```python
from supertonic import TTS

# Note: first run downloads the model (~400MB) into ~/.cache/supertonic3/
tts = TTS(auto_download=True)       # Initialize TTS engine

style = tts.get_voice_style(voice_name="M1")   # 10 built-in voices: M1–M5, F1–F5

wav, duration = tts.synthesize(
    text="Supertonic is a lightning fast, on-device TTS system.",
    voice_style=style,              # Voice style object
    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8
    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
    max_chunk_length=300,           # Max characters per chunk (auto: 120 for Korean)
    silence_duration=0.3,           # Silence between chunks (seconds)
    lang="en",                      # ISO code; see "Supported Languages" below
    verbose=False,                  # Show detailed progress (default: False)
)
tts.save_audio(wav, "output.wav")

# Multilingual — just swap `lang` and the input text
wav_ko, _ = tts.synthesize("회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.", voice_style=style, lang="ko")
wav_es, _ = tts.synthesize("La reunión comienza pronto y todos se sientan en silencio para escuchar.", voice_style=style, lang="es")
```

--------------------------------

### Supertonic Say Command with Options

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Customize speech output using options like voice style, quality steps, and playback speed.

```bash
# Specify voice style
supertonic say 'Hello, welcome to the world!' --voice F1
```

```bash
# Control quality (steps: 5-12 typical, default 8)
supertonic say 'Hello, welcome to the world!' --steps 10
```

```bash
# Adjust speed (0.7-2.0)
supertonic say 'Hello, welcome to the world!' --speed 1.5
```

--------------------------------

### Synthesize Speech in Multiple Languages (CLI)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech in various languages using the supertonic CLI. Supports 31 languages and a fallback 'na' for unknown languages. Use the --lang flag to specify the language.

```bash
# English
supertonic tts 'Hello, welcome to Supertonic!' -o output_en.wav

# Korean
supertonic tts '안녕하세요! 수퍼토닉에 오신 것을 환영합니다.' --lang ko -o output_ko.wav

# Japanese
supertonic tts 'こんにちは！スーパートニックへようこそ。' --lang ja -o output_ja.wav

# German
supertonic tts 'Hallo! Willkommen bei Supertonic.' --lang de -o output_de.wav

# Unknown language fallback
supertonic tts 'Some uncommon text.' --lang na -o output_na.wav
```

--------------------------------

### Import Custom Voice and Synthesize

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Import a custom voice using the Voice Builder export and then synthesize speech using the imported voice.

```bash
curl -X POST http://127.0.0.1:7788/v1/styles/import -F "file=@voices/my_voice.json"
curl -X POST http://127.0.0.1:7788/v1/tts \
  -H 'content-type: application/json' \
  -d '{"text":"Hello in my own cloned voice.","voice":"my_voice","lang":"en"}' \
  -o output_own_voice.wav
```

--------------------------------

### Supertonic CLI Available Commands

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Lists the primary commands available in the Supertonic CLI.

```bash
supertonic {say,tts,list-voices,info,download,version,serve}
```

--------------------------------

### Using Custom Voice Styles with supertonic say

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/say.md

Apply a custom voice style by providing a path to a JSON configuration file using the `--custom-style-path` option.

```bash
supertonic say 'This is a custom voice test.' --custom-style-path ./my_voice.json
```

--------------------------------

### Initialize TTS Engine and Synthesize Speech

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/index.md

Initialize the TTS engine and synthesize speech from text. The first run downloads the model. Customize synthesis with parameters like voice style, quality, speed, and language.

```python
from supertonic import TTS

# Note: first run downloads the model (~400MB) into ~/.cache/supertonic3/
tts = TTS(auto_download=True)       # Initialize TTS engine

style = tts.get_voice_style(voice_name="M1")   # 10 built-in voices: M1–M5, F1–F5

wav, duration = tts.synthesize(
    text="Supertonic is a lightning fast, on-device TTS system.",
    voice_style=style,              # Voice style object
    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8
    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
    max_chunk_length=300,           # Max characters per chunk (auto: 120 for Korean)
    silence_duration=0.3,           # Silence between chunks (seconds)
    lang="en",                      # ISO code; see "Supported Languages" below
    verbose=False,                  # Show detailed progress (default: False)
)
tts.save_audio(wav, "output.wav")
```

```python
# Multilingual — just swap `lang` and the input text
wav_ko, _ = tts.synthesize("회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.", voice_style=style, lang="ko")
wav_es, _ = tts.synthesize("La reunión comienza pronto y todos se sientan en silencio para escuchar.", voice_style=style, lang="es")
```

--------------------------------

### List Available Voices

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/list-voices.md

Use this command to see all voice styles that can be used with the supertonic CLI. The `lv` alias can also be used.

```bash
supertonic list-voices
```

--------------------------------

### Load Custom Voice Styles from JSON (CLI)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech using a custom voice style specified by a JSON file path via the CLI. Use the --custom-style-path flag.

```bash
supertonic tts 'Using a custom voice style from JSON file.' --custom-style-path custom_voice.json -o output_custom.wav
```

--------------------------------

### Supertonic CLI Basic Usage

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Quick playback of text to speech without saving a file, or saving to a WAV file. Options control model, voice, language, quality, speed, and more.

```bash
# Quick playback (no file saved)
supertonic say TEXT [OPTIONS]

# Text-to-speech (saves to file)
supertonic tts TEXT -o OUTPUT.wav [OPTIONS]
```

```bash
# Options:
#   --model NAME              Model: supertonic, supertonic-2, supertonic-3 (default: supertonic-3)
#   --voice STYLE             Voice style: M1–M5, F1–F5 (10 built-in; default: M1)
#   --lang CODE               Language code (supertonic-3: 31 ISO codes + 'na';
#                              default: 'na' for multilingual models, 'en' for v1)
#   --steps N                 Quality steps: 5-12 typical (default: 8)
#   --speed RATE              Speed multiplier: 0.7-2.0 (default: 1.05)
#   --max-chunk-length N      Characters per chunk (default: 300)
#   --silence-duration SECS   Silence between chunks (default: 0.3)
#   --verbose, -v             Show detailed progress and text processing
#   --custom-style-path PATH  Path to custom voice style JSON file (overrides --voice if provided)
```

```bash
# Utilities
supertonic list-voices       # List available voices
supertonic info             # Show model information
supertonic version          # Show version
```

```bash
# Local HTTP server (requires the [serve] extra)
supertonic serve [--host HOST] [--port PORT] [--model NAME] [--cors ORIGINS]
```

--------------------------------

### Synthesize Speech via CLI

Source: https://github.com/supertone-inc/supertonic-py/blob/main/README.md

Use the Supertonic CLI to synthesize speech from text. The first run downloads the model. Supports custom voices and multilingual synthesis.

```bash
# Note: first run will download the model (~400MB) from HuggingFace
supertonic tts 'Supertonic is a lightning fast, on-device TTS system.' -o output.wav

# Pick a built-in voice and bump quality
supertonic tts 'Use a different voice.' -o output.wav --voice F1 --steps 10

# Use a custom voice — Voice Builder export, or a bundled
# ~/.cache/supertonic3/voice_styles/*.json file
supertonic tts 'Hello in my own cloned voice.' -o output.wav \
  --custom-style-path voices/my_voice.json

# Multilingual support — each language with natural text handling
supertonic tts '회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.' -o korean.wav --lang ko
supertonic tts 'La reunión comienza pronto y todos se sientan en silencio para escuchar.' -o spanish.wav --lang es
supertonic tts 'A reunião começa em breve e todos se sentam em silêncio para ouvir.' -o portuguese.wav --lang pt

```

--------------------------------

### Import Custom Voice (Multipart Upload)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Import a custom voice JSON file using multipart upload. The filename stem determines the voice name. You can override the name and allow overwriting existing entries.

```bash
# multipart upload — the filename stem becomes the voice name
curl -X POST http://127.0.0.1:7788/v1/styles/import \
  -F "file=@voices/my_voice.json"
# → {"name":"my_voice","stored_at":"~/.cache/supertonic3/custom_styles/my_voice.json"}

# override the name; allow overwriting an existing entry
curl -X POST "http://127.0.0.1:7788/v1/styles/import?overwrite=true" \
  -F "file=@voices/my_voice.json" \
  -F "name=demo_voice"
```

--------------------------------

### Generate Audio with Native API

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Use the native API for full control over Supertonic parameters like steps and max chunk length. The response is raw audio bytes, with supported formats including wav, flac, and ogg.

```bash
curl -X POST http://127.0.0.1:7788/v1/tts \
  -H 'content-type: application/json' \
  -d '{
            "text": "Supertonic is a lightning fast, on-device TTS system.",
            "voice": "M1",
            "lang": "en",
            "steps": 8,
            "speed": 1.05,
            "response_format": "wav"
          }' \
  -o output.wav
```

--------------------------------

### Supertonic CLI Utility Commands

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Useful commands for managing Supertonic, including listing available voices, checking model information, and displaying the version.

```bash
supertonic list-voices   # List available voices
supertonic info          # Show model information
supertonic version       # Show version
```

--------------------------------

### Utilize Different Voice Styles (CLI)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech using different built-in voice styles via the CLI. Use the --voice flag to specify the desired voice. 'supertonic list-voices' can show available options.

```bash
# List available voices
supertonic list-voices

# Try different voices
supertonic tts 'This is the M1 voice style demonstration.' --voice M1 -o output_m1.wav
supertonic tts 'This is the M2 voice style demonstration.' --voice M2 -o output_m2.wav
supertonic tts 'This is the F1 voice style demonstration.' --voice F1 -o output_f1.wav
supertonic tts 'This is the F2 voice style demonstration.' --voice F2 -o output_f2.wav
```

--------------------------------

### POST /v1/styles/import

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Uploads a Voice Builder JSON file. Supports multipart or JSON body. Files are persisted per-model under `~/.cache/<model>/custom_styles/`.

```APIDOC
## POST /v1/styles/import

### Description
Upload a Voice Builder JSON (multipart or JSON body); persisted per-model under `~/.cache/<model>/custom_styles/`

### Method
POST

### Endpoint
/v1/styles/import

### Parameters
#### Request Body
- **file** (multipart/form-data or JSON) - Required - Voice Builder JSON file or payload.
```

--------------------------------

### Load Supertonic TTS Model

Source: https://github.com/supertone-inc/supertonic-py/blob/main/notebook/supertonic_demo.ipynb

Initializes the Supertonic TTS instance. The model auto-downloads from Hugging Face on first use, requiring approximately 260MB of storage.

```python
from IPython.utils import io
from IPython.display import Audio, display
import time

from supertonic import TTS

# Suppress download progress output for cleaner display
with io.capture_output() as captured:
    tts = TTS(auto_download=True)

print("✅ Download complete!")
```

--------------------------------

### Initialize TTS with Manual Low-Resource Threads

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Manually configures TTS for low-resource environments by setting lower intra- and inter-operation thread counts for ONNX Runtime.

```python
from supertonic import TTS

tts = TTS(intra_op_num_threads=2, inter_op_num_threads=2)
```

--------------------------------

### Supertonic CLI Text-to-Speech

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/index.md

Use the Supertonic command-line interface to synthesize speech. The first run downloads the model. Options include specifying output file, voice, quality, and custom voice paths.

```bash
# Note: first run will download the model (~400MB) from HuggingFace
supertonic tts 'Supertonic is a lightning fast, on-device TTS system.' -o output.wav
```

```bash
# Pick a built-in voice and bump quality
supertonic tts 'Use a different voice.' -o output.wav --voice F1 --steps 10
```

```bash
# Use a custom voice — Voice Builder export, or a bundled
# ~/.cache/supertonic3/voice_styles/*.json file
supertonic tts 'Hello in my own cloned voice.' -o output.wav \
  --custom-style-path ~/voices/my_voice.json
```

```bash
# Multilingual support — each language with natural text handling
supertonic tts '회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.' -o korean.wav --lang ko
supertonic tts 'La reunión comienza pronto y todos se sientan en silencio para escuchar.' -o spanish.wav --lang es
supertonic tts 'A reunião começa em breve e todos se sentam em silêncio para ouvir.' -o portuguese.wav --lang pt
```

--------------------------------

### Generate Audio with OpenAI-Compatible Endpoint

Source: https://github.com/supertone-inc/supertonic-py/blob/main/README.md

Utilize the OpenAI-compatible `/v1/audio/speech` endpoint by simply changing the base URL. This is useful for clients already integrated with the OpenAI API. Multilingual support is available by setting the 'lang' parameter.

```bash
curl -X POST http://127.0.0.1:7788/v1/audio/speech \
  -H 'content-type: application/json' \
  -d '{
        "model": "supertonic-3",
        "input": "Supertonic is a lightning fast, on-device TTS system.",
        "voice": "M1",
        "response_format": "wav"
      }' \
  -o output.wav
```

--------------------------------

### Load Custom Voice Styles from JSON (Python)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech using a custom voice style loaded from a JSON file. Requires TTS initialization and the path to the JSON file.

```python
from supertonic import TTS
from pathlib import Path

tts = TTS()

# Load custom style from JSON
custom_style = tts.get_voice_style_from_path(Path("custom_voice.json"))
wav, dur = tts.synthesize("Using a custom voice style from JSON file.", voice_style=custom_style)
```

--------------------------------

### Utilize Different Voice Styles (Python)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Iterate through available built-in voice styles (M1-M5, F1-F5) and synthesize speech with each. Requires TTS initialization and voice style retrieval.

```python
from supertonic import TTS

tts = TTS()

# List available voices (10 built-in: M1–M5, F1–F5)
voice_list = tts.voice_style_names

# Try different voices
for voice_name in voice_list:
    style = tts.get_voice_style(voice_name)
    wav, dur = tts.synthesize(f"This is the {voice_name} voice style demonstration.", voice_style=style)
    tts.save_audio(wav, f"output_{voice_name}.wav")
```

--------------------------------

### Initialize TTS and Synthesize Speech

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/api/index.md

Initializes the TTS engine and synthesizes speech from text. Ensure the TTS engine is initialized with `auto_download=True` for automatic model downloads. Customize synthesis parameters like `voice_style`, `total_steps`, `speed`, and `max_chunk_length` for desired output quality and characteristics.

```python
from supertonic import TTS

tts = TTS(auto_download=True)       # Initialize TTS engine

style = tts.get_voice_style(voice_name="M1")   # 10 built-in voices: M1–M5, F1–F5

wav, duration = tts.synthesize(
    text="Your text here.",         # Text to synthesize
    voice_style=style,              # Voice style object
    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8
    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
    max_chunk_length=300,           # Max characters per chunk (auto: 120 for Korean)
    silence_duration=0.3,           # Silence between chunks (seconds)
    lang=None,                      # Auto: "na" for multilingual, "en" for v1
    verbose=False,                  # Show detailed progress (default: False)
)
```

--------------------------------

### Enable Verbose Mode for Monitoring

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Activates verbose mode to display detailed synthesis progress, chunking information, and timing statistics for debugging.

```bash
python test8_verbose_mode.py
```

--------------------------------

### Basic Speech Synthesis

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Demonstrates the simplest method for generating natural-sounding speech using Supertonic TTS.

```bash
python test1_simple.py
```

--------------------------------

### Generate Audio with OpenAI-Compatible API

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Integrate with clients already using the OpenAI Audio Speech API by simply changing the base URL. This endpoint supports multilingual input by setting the 'lang' parameter.

```bash
curl -X POST http://127.0.0.1:7788/v1/audio/speech \
  -H 'content-type: application/json' \
  -d '{
            "model": "supertonic-3",
            "input": "Supertonic is a lightning fast, on-device TTS system.",
            "voice": "M1",
            "response_format": "wav"
          }' \
  -o output.wav
```

--------------------------------

### Generate Audio (OpenAI-compatible)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

This endpoint is compatible with the OpenAI Audio Speech API. Clients that already use the OpenAI API can simply change the base URL to interact with Supertonic. Multilingual input is supported by setting the 'lang' parameter.

```APIDOC
## POST /v1/audio/speech

### Description
Generates audio from text using an OpenAI-compatible API endpoint.

### Method
POST

### Endpoint
http://127.0.0.1:7788/v1/audio/speech

### Parameters
#### Request Body
- **model** (string) - Required - The model to use (e.g., "supertonic-3").
- **input** (string) - Required - The text to synthesize.
- **voice** (string) - Required - The voice to use (e.g., "M1").
- **response_format** (string) - Optional - The desired audio format (e.g., "wav", "flac", "ogg"). Defaults to "wav".
- **lang** (string) - Optional - The language of the text. Use codes from Multilingual Support or 'na' for fallback.

### Request Example
```json
{
  "model": "supertonic-3",
  "input": "Supertonic is a lightning fast, on-device TTS system.",
  "voice": "M1",
  "response_format": "wav"
}
```

### Response
#### Success Response (200)
- **audio/wav** (bytes) - Raw audio bytes.
```

--------------------------------

### Import Custom Voice Style

Source: https://github.com/supertone-inc/supertonic-py/blob/main/README.md

Upload a custom voice JSON file using `multipart/form-data`. The filename stem is used as the voice name by default. You can explicitly set the name and allow overwriting existing entries with the `overwrite=true` query parameter.

```bash
# Upload my_voice.json; the stem of the filename becomes its name.
curl -X POST http://127.0.0.1:7788/v1/styles/import \
  -F "file=@voices/my_voice.json"
```

```bash
# Override the name explicitly, and allow overwriting an existing entry:
curl -X POST "http://127.0.0.1:7788/v1/styles/import?overwrite=true" \
  -F "file=@voices/my_voice.json" \
  -F "name=demo_voice"
```

--------------------------------

### load_voice_style_from_json_file

Source: https://github.com/supertone-inc/supertonic-py/blob/main/llms.txt

Loads a voice style from a JSON configuration file.

```APIDOC
## load_voice_style_from_json_file

### Description
Loads a voice style from a JSON configuration file.

### Method
`load_voice_style_from_json_file(path)`

### Parameters
- **path** (str) - The path to the JSON file containing the voice style configuration.
```

--------------------------------

### list_available_voice_style_names

Source: https://github.com/supertone-inc/supertonic-py/blob/main/llms.txt

Lists the names of all available voice styles.

```APIDOC
## list_available_voice_style_names

### Description
Lists the names of all available voice styles.

### Method
`list_available_voice_style_names()`

### Response
- **list[str]** - A list of available voice style names.
```

--------------------------------

### Import Custom Voice

Source: https://github.com/supertone-inc/supertonic-py/blob/main/README.md

Upload a custom voice JSON file to be used for synthesis. The filename stem becomes the voice name by default.

```APIDOC
## POST /v1/styles/import

### Description
Imports a custom voice style from a JSON file.

### Method
POST

### Endpoint
http://127.0.0.1:7788/v1/styles/import

### Parameters
#### Request Body
- **file** (file) - Required - The custom voice JSON file.
- **name** (string) - Optional - Explicitly set the name for the imported voice.
- **overwrite** (boolean) - Optional - Set to `true` to overwrite an existing voice with the same name. Defaults to `false`.

### Request Example
```bash
# Upload my_voice.json; the stem of the filename becomes its name.
curl -X POST http://127.0.0.1:7788/v1/styles/import \
  -F "file=@voices/my_voice.json"

# Override the name explicitly, and allow overwriting an existing entry:
curl -X POST "http://127.0.0.1:7788/v1/styles/import?overwrite=true" \
  -F "file=@voices/my_voice.json" \
  -F "name=demo_voice"
```

### Response
#### Success Response (200)
- **name** (string) - The name of the imported voice.
- **stored_at** (string) - The path where the voice style is stored.

#### Response Example
```json
{
  "name": "my_voice",
  "stored_at": "~/.cache/supertonic3/custom_styles/my_voice.json"
}
```
```

--------------------------------

### Using a Different Voice with supertonic say

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/say.md

Specify a different voice style for speech generation using the `--voice` option. Ensure the specified voice is available.

```bash
supertonic say 'This is a female voice style.' --voice F1
```

--------------------------------

### Basic TTS Usage

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/tts.md

Generate speech from text and save to a WAV file. Use TEXT to specify the input text and -o to specify the output file path. Aliases like 't' can be used for brevity.

```bash
supertonic tts TEXT -o OUTPUT.wav [OPTIONS]
```

--------------------------------

### Synthesize Speech in Multiple Languages (Python)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Synthesize speech in various languages using the TTS class. Supports 31 languages and a fallback 'na' for unknown languages. Requires TTS initialization.

```python
from supertonic import TTS

tts = TTS()
style = tts.get_voice_style("M1")

# English
wav_en, _ = tts.synthesize("Hello, welcome to Supertonic!", voice_style=style, lang="en")

# Korean
wav_ko, _ = tts.synthesize("안녕하세요! 수퍼토닉에 오신 것을 환영합니다.", voice_style=style, lang="ko")

# Japanese
wav_ja, _ = tts.synthesize("こんにちは！スーパートニックへようこそ。", voice_style=style, lang="ja")

# German
wav_de, _ = tts.synthesize("Hallo! Willkommen bei Supertonic.", voice_style=style, lang="de")

# Unknown language fallback — wraps text with the <na> token
wav_na, _ = tts.synthesize("Some uncommon text.", voice_style=style, lang="na")

tts.save_audio(wav_ko, "output_korean.wav")
```

--------------------------------

### Improving Speech Quality with supertonic say

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/say.md

Enhance speech quality by increasing the number of steps using the `--steps` option. Higher values may increase processing time.

```bash
supertonic say 'This is a high quality output.' --steps 10
```

--------------------------------

### Generate Audio (Native API)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Use the native Supertonic API to generate audio from text. You can specify various parameters like steps, max chunk length, and silence duration. The response is raw audio bytes, with useful headers like X-Audio-Duration, X-Sample-Rate, and X-Supertonic-Version. Supported response formats include wav, flac, and ogg.

```APIDOC
## POST /v1/tts

### Description
Generates audio from the provided text using the Supertonic TTS system.

### Method
POST

### Endpoint
http://127.0.0.1:7788/v1/tts

### Parameters
#### Request Body
- **text** (string) - Required - The text to synthesize.
- **voice** (string) - Required - The voice to use (e.g., "M1").
- **lang** (string) - Required - The language of the text (e.g., "en").
- **steps** (integer) - Optional - The number of diffusion steps.
- **max_chunk_length** (integer) - Optional - Maximum length of audio chunks.
- **silence_duration** (float) - Optional - Duration of silence to insert.
- **speed** (float) - Optional - The speech speed multiplier.
- **response_format** (string) - Optional - The desired audio format (e.g., "wav", "flac", "ogg"). Defaults to "wav".

### Request Example
```json
{
  "text": "Supertonic is a lightning fast, on-device TTS system.",
  "voice": "M1",
  "lang": "en",
  "steps": 8,
  "speed": 1.05,
  "response_format": "wav"
}
```

### Response
#### Success Response (200)
- **audio/wav** (bytes) - Raw audio bytes.

#### Response Headers
- **X-Audio-Duration** (float) - Duration of the generated audio in seconds.
- **X-Sample-Rate** (integer) - The sample rate of the audio.
- **X-Supertonic-Version** (string) - The version of the Supertonic system used.
```

--------------------------------

### Configure ONNX Runtime Threads (CLI)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Configure ONNX Runtime threads via environment variables for CLI usage. Set `SUPERTONIC_INTRA_OP_THREADS` and `SUPERTONIC_INTER_OP_THREADS` before running the `supertonic tts` command.

```bash
# Set thread counts via environment variables
export SUPERTONIC_INTRA_OP_THREADS=12
export SUPERTONIC_INTER_OP_THREADS=12

supertonic tts 'This is the thread configuration demonstration.' -o output.wav --voice M1
```

--------------------------------

### OpenAI-Compatible Speech Synthesis

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/serve.md

Utilize the OpenAI-compatible alias `/v1/audio/speech` for synthesis. This is useful for clients already configured for the OpenAI API.

```bash
curl -X POST http://127.0.0.1:7788/v1/audio/speech \
  -H 'content-type: application/json' \
  -d '{"model":"supertonic-3","input":"Hello in my own cloned voice.","voice":"M1","response_format":"wav"}' \
  -o output.wav
```

--------------------------------

### Initialize TTS with Manual High-Performance Threads

Source: https://github.com/supertone-inc/supertonic-py/blob/main/examples/README.md

Manually configures TTS for high-performance scenarios by setting specific intra- and inter-operation thread counts for ONNX Runtime.

```python
from supertonic import TTS

tts = TTS(intra_op_num_threads=8, inter_op_num_threads=8)
```

--------------------------------

### Supertonic TTS Command with Options

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/cli/README.md

Customize the saved speech output using options for voice style, quality steps, and speed.

```bash
# Specify voice style
supertonic tts 'Hello, welcome to the world!' -o output.wav --voice F1
```

```bash
# Control quality (steps: 5-12 typical, default 8)
supertonic tts 'Hello, world!' -o output.wav --steps 10
```

```bash
# Adjust speed (0.7-2.0)
supertonic tts 'Hello, welcome to the world!' -o output.wav --speed 1.5
```

--------------------------------

### Batch Synthesis

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Perform batch synthesis for up to 64 items in a single request. Each item can have different voice, language, and speed settings. The response includes base64-encoded audio for each item.

```APIDOC
## POST /v1/tts/batch

### Description
Accepts up to 64 items in a single request and returns each result as base64-encoded audio. Per-item `voice` / `lang` / `speed` can differ — useful for narration jobs that mix speakers or languages.

### Method
POST

### Endpoint
`/v1/tts/batch`

### Request Body
- **items** (array) - Required - An array of synthesis items, each with `text`, `voice`, `lang`, and optional `speed`.
- **response_format** (string) - Optional - The desired audio format (e.g., "wav").
- **defaults** (object) - Optional - Default settings for synthesis parameters like `steps` and `speed`.

### Request Example
```json
{
  "items": [
    {"text": "Supertonic is a lightning fast, on-device TTS system.", "voice": "M1", "lang": "en"},
    {"text": "회의는 잠시 후에 시작되며 모두가 자리에 앉아 기다립니다.", "voice": "F1", "lang": "ko"},
    {"text": "La reunión comienza pronto y todos se sientan en silencio para escuchar.", "voice": "F1", "lang": "es"}
  ],
  "response_format": "wav",
  "defaults": {"steps": 8, "speed": 1.05}
}
```

### Response
#### Success Response (200)
- **items** (array) - An array of synthesis results, each containing `audio_base64`, `duration_s`, `format`, and `sample_rate`.

#### Response Example
```json
{
  "items": [
    {"audio_base64": "...", "duration_s": 4.32, "format": "wav", "sample_rate": 44100},
    {"audio_base64": "...", "duration_s": 4.88, "format": "wav", "sample_rate": 44100},
    {"audio_base64": "...", "duration_s": 5.36, "format": "wav", "sample_rate": 44100}
  ]
}
```

!!! note "Sequential, not parallel"
    Items are processed sequentially within a process (the ONNX session is serialized) — so batching saves HTTP round-trips and packages related work together, not raw inference time. Any per-item failure returns a `400` with `items[<index>]` in the error message; no audio is emitted partially.
```

--------------------------------

### Configure ONNX Runtime Threads (Python)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Manually configure ONNX Runtime threads for advanced performance tuning. Use `intra_op_num_threads` for within-operation parallelism and `inter_op_num_threads` for between-operation parallelism. Auto-detection is recommended for most use cases.

```python
from supertonic import TTS

# Auto-detect (recommended)
tts = TTS()

# High-performance server
tts = TTS(intra_op_num_threads=12, inter_op_num_threads=12)

# Low-resource environment
tts = TTS(intra_op_num_threads=2, inter_op_num_threads=2)
```

--------------------------------

### Import Custom Voice (JSON Body)

Source: https://github.com/supertone-inc/supertonic-py/blob/main/docs/quickstart.md

Import a custom voice by sending the JSON style data directly in the request body, which is useful for scripting and automation.

```bash
# or send a JSON body directly (handy from scripts / n8n)
curl -X POST http://127.0.0.1:7788/v1/styles/import \
  -H 'content-type: application/json' \
  -d '{"name":"demo_voice","style_ttl":{...},"style_dp":{...}}'
```