Supertonic CLI Guide¶

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

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

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

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

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

The supertonic command-line tool provides easy access to text-to-speech synthesis. You can start by viewing the help message with:

supertonic --help

Available Commands:

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

say¶

Generate speech from text and play it directly without saving a file.

Requires sounddevice

Install with: pip install supertonic[playback]

Basic usage:

supertonic say 'Hello, welcome to the world!'

With options:

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

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

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

See supertonic say for the full reference of all available arguments.

tts¶

Generate speech from text and save to a WAV file.

Basic usage:

supertonic tts 'Hello, welcome to the world!' -o output.wav

With options:

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

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

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

See supertonic tts for the full reference of all available arguments.

list-voices¶

List all available voice styles.

supertonic list-voices

Aliases: lv

info¶

Show model information including cache location and available voices.

supertonic info

Aliases: i

download¶

Download model from HuggingFace Hub.

supertonic download

Aliases: d

This is useful for pre-downloading the model before first use or in Docker/CI environments.

version¶

Show installed version.

supertonic version

Aliases: v

serve¶

Run a thin local HTTP server with a native /v1/* namespace and an OpenAI-compatible alias.

Requires fastapi + uvicorn

Install with: pip install 'supertonic[serve]'

supertonic serve --host 127.0.0.1 --port 7788

Once running, hit it with any HTTP client — e.g. n8n, browser extensions, or the OpenAI SDK pointed at http://127.0.0.1:7788/v1. See supertonic serve for the full reference of arguments and endpoints.

Environment Variables¶

SUPERTONIC_CACHE_DIR

Override the default cache directory for model files.

export SUPERTONIC_CACHE_DIR=/custom/cache/path

Default: ~/.cache/supertonic3 (depends on the loaded model — e.g., ~/.cache/supertonic2 for supertonic-2)

SUPERTONIC_INTRA_OP_THREADS

Configure ONNX Runtime intra-operator thread count.

export SUPERTONIC_INTRA_OP_THREADS=8

Default: Auto-detected

SUPERTONIC_INTER_OP_THREADS

Configure ONNX Runtime inter-operator thread count.

export SUPERTONIC_INTER_OP_THREADS=8

Default: Auto-detected

More Help¶

For detailed options of any subcommand, use:

supertonic <subcommand> --help