---
name: supertonic-express
description: 端侧 ONNX 多语言 TTS 配音技能。当用户要求「本地文字转语音」「多语言配音」「给视频配旁白」「离线 TTS」「把文本合成 wav 音频」且强调零 API Key、本地运行时使用。官方支持 en/ko/es/pt/fr 五种语言(暂不支持中文)。纯本地运行,开源,零 API Key。
version: 1.0.0
---

# supertonic-express(端侧 ONNX 多语言 TTS)

基于 ONNX Runtime 在本地推理的多语言语音合成:输入文本,输出 44.1kHz 单声道 WAV,全程无云端调用、无 API Key。官方支持 5 种语言:en / ko / es / pt / fr(暂不支持中文)。

- 仓库:github.com/groxaxo/supertonic-express(纯文本,勿改写为链接;MIT License)
- 模型:onnx-community/Supertonic-TTS-2-ONNX(约 66M 参数,首次运行自动下载约 263MB)
- 实现:Python(ONNX Runtime + FastAPI)与 JavaScript(Transformers.js)两套
- 成本:免费、纯本地、零 API Key、零网络调用(除首次下载模型,需能访问 Hugging Face)

## 安装(JS 路径实测通过)

```bash
git clone https://github.com/groxaxo/supertonic-express.git
cd supertonic-express/js
npm install
```

实测环境:macOS 26.5.2 / Apple M1 Pro / Node v26.7.0(Node >= 18 或 Python 3.10+)。
首次运行自动下载模型:实测 297s(含下载+加载);二次启动加载约 1s。

## 用法(最小示例)

```js
import { SupertonicTTS } from './index.js';
const tts = new SupertonicTTS();
await tts.initialize();
await tts.generateAndSave('Hello world!', 'out.wav', {
  language: 'en',                       // en/ko/es/pt/fr
  speaker_embeddings: 'https://huggingface.co/onnx-community/Supertonic-TTS-2-ONNX/resolve/main/voices/M1.bin',
  num_inference_steps: 15,
  speed: 1.0,
});
```

- 音色:M1~M5(男)、F1~F5(女),speaker_embeddings 指向 voices/ 下的对应 .bin。
- `num_inference_steps`:推理步数,示例默认 15;实测 5 步与 15 步无稳定提速差异(受首调用预热影响)。
- 每进程首个生成调用偏慢(预热),之后稳定 1.5~2s。

## 实测数据(2026-08-22,15 步推理,M1 Pro)

| 文本 | 语言 | 生成耗时 | 输出时长 | RTF | 文件 |
|---|---|---|---|---|---|
| Hello! Welcome to Supertonic... | en | 3.27s | 6.97s | 0.47 | en_s15.wav |
| The startup secured $5.2M... Wed, Apr 3. | en | 2.19s | 9.61s | 0.23 | en-natural_s15.wav |
| 안녕하세요! ... | ko | 1.48s | 5.85s | 0.25 | ko_s15.wav |
| ¡Hola! Bienvenido ... | es | 1.58s | 6.20s | 0.26 | es_s15.wav |

- RTF = 生成耗时 ÷ 输出时长,越小越快;实测 0.23~0.47(约 2~4 倍实时)。
- 输出:44.1kHz 单声道 WAV,实际为 pcm_f32le(README 写 16-bit,以实测为准);1 秒音频约 176KB。
- 自然文本($5.2M / 4:45 PM / Wed, Apr 3)无需预处理直接生成成功;发音准确率未做 ASR 回读验证。
- 官方 README 性能口径(i7-4790 9.774x / M4 Pro 167x)为官方数据,未在本机复现。

## 边界

- 暂不支持中文。language 传 zh 会报错:`Language 'zh' not supported. Choose from: en, ko, es, pt, fr`。
- 首次需下载约 263MB 模型;需能访问 Hugging Face。
- 实测平台为 macOS arm64(M1 Pro)。
- 输出为 32 位浮点 WAV,做长配音记得转码压缩(如 ffmpeg 转 16-bit)。

一次真实测量的完整日志见 `references/measured-2026-08-22.md`(run_log_15step.json / run_log_5step.json)。
