supertonic-cli

name	supertonic-cli
description	Use this skill when the user needs to generate speech from text using on-device TTS — 31 languages, 10 voice styles, no cloud, ONNX Runtime.

supertonic-cli — On-Device TTS

Generate speech from text using Supertonic — lightning-fast, on-device, multilingual TTS via ONNX Runtime (5.3k ⭐, MIT).

Installation & Dependencies

pip install supertonic          # Core TTS engine + ONNX Runtime (~100MB)
pip install supertonic-cli      # CLI wrapper

Commands

• supertonic-cli tts synthesize <text> [--voice M1] [--lang en] [-o output.wav] [--machine] — Generate speech to file
• supertonic-cli tts speak <text> [--voice M1] [--lang en] [--machine] — Synthesize and play aloud immediately (auto-cleanup)
• supertonic-cli tts voices — List available voices
• supertonic-cli tts languages — List supported languages
• supertonic-cli self version — Show engine info

Critical Caveats & Pitfalls

1. First Run: Model Download (Mandatory)

The first synthesize or info call downloads the ONNX model from Hugging Face (~300MB, 26 files). Always warn the user about this before running. Do NOT run synthesize without warning.

# Expected first-run output:
Fetching 26 files:   0%|  | 0/26 [00:00<?, ?it/s]
# Download can take 2-5 minutes depending on connection.

Affected commands: synthesize, voices, info Safe commands (no download): languages

2. Timeout Configuration

The default supercli timeout may not be enough for first-run model download. Always use --machine flag which returns faster (no file I/O), OR set timeout_ms higher. First-run synthesize typically needs 120-300 seconds.

3. soundfile / _ctypes Issues

On some Python installations, _ctypes module is missing, causing save_audio() to fail. The CLI has a built-in fallback that writes raw WAV without soundfile. If you see "soundfile library is required", the fallback should handle it automatically.

4. Duration is numpy.float32, not a plain float

When processing machine JSON output, the duration_s field may be a numpy type (not serializable to JSON). The CLI handles this internally by converting to float.

5. Output Format

• Default: 44100Hz mono 16-bit WAV (correct sample rate is critical for natural sound)
• The model outputs at 44100Hz. If audio sounds like a "drunk robot" or slowed down, the WAV was saved at the wrong sample rate (early versions hardcoded 24000Hz). Update to the latest CLI to fix.
• The --machine flag returns metadata without audio to stdout; the WAV file is written to disk

6. Voice Styles

Voice	Style	Best For
M1-M5	Male voices (5 variants)	General purpose, varies by language
F1-F5	Female voices (5 variants)	General purpose, varies by language

Not all voices are equally good for all languages. If output sounds wrong, suggest trying a different voice.

7. Language Codes (31 languages)

Use ISO 639-1 two-letter codes. Full list via supertonic-cli tts languages: en, ko, ja, ar, bg, cs, da, de, el, es, et, fi, fr, hi, hr, hu, id, it, lt, lv, nl, pl, pt, ro, ru, sk, sl, sv, tr, uk, vi

8. Text Length & Quality

• Short text (< 200 chars) works best
• Long text may cause OOM on low-memory systems
• For long text (> 500 chars), consider splitting into sentences and synthesizing separately
• Supertonic handles punctuation, numbers, dates, currency, and abbreviations well
• Supports expressive tags: <laugh>, <breath>, <sigh>

9. Performance Characteristics

• Typical RTF (Real-Time Factor): 0.2-0.5 on modern CPU (faster than real-time)
• ~99M parameters, runs entirely on CPU (no GPU needed)
• Memory usage: ~500MB-1GB during synthesis
• Faster after model is cached (subsequent runs skip download)

10. Model Cache

The ONNX model is cached at Hugging Face's default cache location: ~/.cache/huggingface/hub/ Can be deleted and re-downloaded if corrupted.

11. JSON Output Format

{
  "ok": true,
  "output": "/path/to/output.wav",
  "duration_s": 2.08,
  "real_time_s": 0.56,
  "rtf": 0.267,
  "voice": "M1",
  "lang": "es"
}

12. Speak Command — Say Something Aloud

The speak command synthesizes and plays audio in one step, then deletes the temp file. Useful for agents that want to "say something" when supercli runs on a machine with speakers.

sc supertonic-cli tts speak "Hello, I am ready" --voice M1 --lang en

Player detection (in order): ffplay, paplay, aplay (Linux), afplay (macOS). Headless servers without audio will fail — use synthesize instead.

13. No Cloud / No API

This runs entirely on-device. No internet connection needed after model download. No API keys required. No data leaves the machine. Guarantee this to the user.

Prompt Templates

Best prompts to use with this plugin:

• "Synthesize '[text]' with voice [M1-F5] in [language], save as [filename]"
• "Generate Spanish speech: Hola Ma, anda a dormir — voice M1, save to hola_ma.wav"
• "List available voices and their languages"
• "What languages does supertonic support? Output as a table"
• "Create audio from this text: [long text]. Split into sentences if too long."
• "Download the supertonic model first (warn user about 300MB), then synthesize..."

Common Workflows

One-shot TTS

→ "Generate 'Hello world' in French with voice F2"
← supertonic-cli tts synthesize "Hello world" --voice F2 --lang fr -o hello.wav

Multi-language comparison

→ "Synthesize 'Good morning' in English, Spanish, and Japanese"
← Run 3 separate commands with different --lang codes

JSON for automation

→ "Generate speech from this text and return the duration: 'The quick brown fox'"
← Use --machine flag to get structured output