Immutable. This exact content is served forever at /api/v1/blob/5a649ec5a4252324.
---
name: ttscn
description: Multi-platform Chinese & multilingual TTS text-to-speech via Edge/Doubao/CosyVoice/Azure/Tencent/Baidu/MiniMax/Xunfei plus ElevenLabs/OpenAI/Google — 11 backends, word-level timestamps, [PAUSE:x] pause markers, pinyin pronunciation overrides
author: Agents365-ai
version: 1.7.0
created: 2026-07-08
updated: 2026-07-30
homepage: https://github.com/Agents365-ai/ttsCN
metadata: {"openclaw":{"requires":{"bins":["python3","ffmpeg"]},"emoji":"🔊"}}
---
# ttscn — Multi-Platform Chinese TTS Skill
## Overview
Generate natural speech audio from text. **11 backends** — 8 China-friendly clouds plus 3 international (ElevenLabs / OpenAI / Google).
| # | Backend | Cost | Key strength |
|---|---------|------|-------------|
| 1 | **Edge TTS** (default) | Free | No API key, works everywhere |
| 2 | **Doubao** (ByteDance) | ~1 RMB/10K | Best Chinese naturalness (9/10) |
| 3 | **CosyVoice** (Alibaba) | ~0.2 RMB/1K | Fast streaming, flexible |
| 4 | **Azure** (Microsoft) | ~1 USD/M chars | Enterprise SSML, eastasia |
| 5 | **Tencent Cloud** | **0.75 RMB/10K** | Lowest cost, 380+ voices |
| 6 | **Baidu AI** | Flexible | 30+ voices, emotion + dialects |
| 7 | **MiniMax** | ~$0.10/1K | Best quality, 300+ voices, cloning |
| 8 | **iFlytek Xunfei** | ~2 RMB/10K | MOS 4.8, 500+ voices, pro grade |
| 9 | **ElevenLabs** | Paid tiers (from $5/mo) | Top voice quality, instant cloning |
| 10 | **OpenAI TTS** | ~$15-30/M chars | 6 voices, multilingual, simple REST |
| 11 | **Google Cloud TTS** | ~$16/M chars (free tier) | 220+ voices, 40+ languages |
New in 1.4–1.6: **word-level timestamps** (edge/azure/doubao/minimax/cosyvoice —
best-effort, degrades to no boundaries), **[PAUSE:x] + sound-tag markers** (all
platforms), **--phonemes pronunciation overrides** (azure/minimax).
New in 1.7: **--json flag** (JSON envelope independent of `--format`), idempotency
hits report `cached: true` and **re-synthesize if the cached audio was deleted**,
`--input f out.wav` positional fixed, chunker never splits inside `[PAUSE:x]`.
**Cross-platform**: Windows, macOS, Linux
All paths in this document are relative to this skill's root directory (the
directory containing this SKILL.md) — resolve them against it.
## When to Use This Skill
Automatically activate this skill when:
- User wants to convert Chinese text to speech audio
- Generating voice narration or voiceover for videos
- Creating audiobook or podcast audio from text
- User asks to compare TTS providers, choose a TTS backend, or see what voices are available
- User asks about TTS pricing, features, or which provider supports cloning/SSML/dialects
- User mentions any of: TTS, text-to-speech, 语音合成, 文字转语音, Edge TTS, Doubao TTS, CosyVoice, 火山引擎, 阿里云语音, Azure TTS, 腾讯云TTS, 百度语音, MiniMax, 讯飞语音, ElevenLabs, OpenAI TTS, Google Cloud TTS
- User needs word-level timestamps/subtitles, pause control, or fixing mispronounced Chinese characters (多音字)
- Any task where Chinese text-to-speech would be helpful
## Provider Comparison Page
**When the user wants to browse, compare, or choose a TTS provider, ALWAYS open the
local HTML comparison page in their browser FIRST** — it's a visual, filterable table
that is much faster to scan than reading text output.
```bash
# Cross-platform (path relative to this skill's directory)
python3 -m webbrowser docs/providers.html
# …or the platform-native opener: open (macOS) / xdg-open (Linux) / start (Windows)
```
The comparison page includes:
- **Filterable table** — filter by free, SSML, voice cloning, streaming, dialects, multilingual
- **Per-provider detail panels** — cost, max chars/duration, clone method, emotion, languages
- **Voice cards** — recommended voices with style descriptions and best-use labels
- **API key links** — direct links to each provider's console for key acquisition
This page is auto-generated from `data/providers.json` (the single source of truth
for all provider/voice data). Run `python3 scripts/build_docs.py` to regenerate it
after editing the JSON. The same data is queryable on the CLI via
`python3 scripts/tts.py schema backends|voices` (see Schema Introspection).
**After opening the page**, ask the user which backend and voice they'd like to use,
then proceed to Step 2.
## Workflow
### Step 0 — Show the comparison page (when comparing/choosing)
If the user is browsing, comparing providers, or unsure which backend to use, open
`docs/providers.html` as shown above. Let them explore, then ask which backend +
voice they want.
### Step 1 — Understand the request
Clarify what the user needs:
- **Text**: inline text or a file? Short or long-form?
- **Voice style**: male/female, young/mature, warm/energetic? (see voice guide below)
- **Speed**: normal, faster (+10-20%), slower (-10-20%)?
- **Format**: WAV (lossless) or MP3 (compressed)?
### Step 2 — Pick a backend & voice
Choose based on the use case (see Backend Selection Guide). Default to **Edge TTS**
with `zh-CN-XiaoxiaoNeural` (female, warm, standard) if unsure. Mention your choice.
### Step 3 — Synthesize
Run `scripts/tts.py` with the text and chosen options.
### Step 4 — Report
Confirm: output path, file size, audio duration.
## Backend Selection Guide
### Quick Pick
| Use case | Backend | Voice | Why |
|----------|---------|-------|-----|
| **Default / general** | edge | zh-CN-XiaoxiaoNeural | Free, no setup |
| **Short video / Douyin** | doubao | BV001_streaming | Native short-video style |
| **Audiobook / long-form** | cosyvoice | longxiaochun_v3 | Fast synthesis, natural |
| **Enterprise / SSML** | azure | zh-CN-XiaoxiaoNeural | Rich prosody control |
| **Bulk / lowest cost** | tencent | 101001 | 0.75 RMB/10K chars |
| **Emotion / dialects** | baidu | 3 or 4 | Emotion synthesis, Cantonese |
| **Best quality / cloning** | minimax | female-shaonv | speech-2.6-hd, voice design |
| **Education / pro** | xunfei | xiaoyan | MOS 4.8, 500+ voices |
| **Male narration** | edge | zh-CN-YunxiNeural | Energetic male voice |
| **Documentary** | azure | zh-CN-YunyangNeural | Deep, professional male |
| **Children's content** | edge | zh-CN-XiaomengNeural | Bright, youthful female |
| **Cost-sensitive** | edge | zh-CN-XiaoxiaoNeural | Completely free |
| **English, top quality** | elevenlabs | 21m00Tcm4TlvDq8ikWAM (Rachel) | Best-in-class English voices |
| **English, simple/cheap** | openai | alloy | tts-1-hd, one env var |
| **English, enterprise** | google | en-US-Neural2-F | 220+ voices, free tier |
### Full capability & voice data
The complete capability matrix (cost, max chars/duration per chunk, SSML, cloning
method + cost, emotion, dialects, languages, streaming, setup difficulty) and the
per-backend voice lists live in **one place**: `data/providers.json`. View them via:
- The **comparison page** (`docs/providers.html`) — best for humans
- `python3 scripts/tts.py schema backends --full` — full capability fields per backend
- `python3 scripts/tts.py schema voices` — every voice preset with style descriptions
- `python3 scripts/tts.py --list` — human-readable terminal summary
Do not maintain copies of these tables elsewhere — regenerate from the JSON.
## Voice Cloning (`clone` command)
Create a custom voice from reference audio, store it under a name, then use
the name anywhere `--voice` is accepted. Built-in for **minimax** (local file
OK, 10s-5min audio, paid: ~$1.5/voice global site or ¥9.9 on first use China
site; a new clone is TEMPORARY until its first real synthesis — use it within
7 days [global site] / 48 h [China site] of creation or MiniMax deletes it,
previews don't count; permanent after first use) and **cosyvoice** (enrollment
free, audio must be a PUBLIC http(s) URL, 10-20s, voice expires after 1 year
unused).
```bash
# MiniMax — local file, paid, must confirm with --yes
python3 scripts/tts.py clone create --platform minimax --audio my_voice.wav --name myvoice --yes
# CosyVoice — free, but --audio must be a public URL; --target-model must
# match the synthesis model (default: $COSYVOICE_MODEL or cosyvoice-v3-flash)
python3 scripts/tts.py clone create --platform cosyvoice --audio https://example.com/my.wav --name myvoice
# Manage
python3 scripts/tts.py clone list
python3 scripts/tts.py clone delete --name myvoice [--remote] # --remote: cosyvoice only
# Use it — the stored name resolves to the platform voice_id automatically
python3 scripts/tts.py "用我的声音说这句话" out.wav --platform minimax --voice myvoice
```
Rules the agent MUST follow:
- MiniMax creation is paid — never run `clone create --platform minimax`
without the user's explicit confirmation (the CLI enforces `--yes`).
- Only clone the user's own voice or one they are authorized to use — both
platforms contractually prohibit cloning third parties without consent.
- Reference audio: clean single-speaker speech, no BGM, 10-20s is ideal.
- Named voices live in `~/.ttscn.json` under `cloned_voices`.
Other platforms (Doubao/Tencent/Baidu/Xunfei/Azure) support cloning via
their consoles — the resulting voice id also works as a plain `--voice`.
## Usage
### Basic Usage
```bash
# Default (Edge TTS, free, Xiaoxiao voice)
python3 scripts/tts.py "你好世界" output.wav
# Specific voice
python3 scripts/tts.py --voice zh-CN-YunxiNeural "欢迎收听今天的节目" welcome.wav
# Specific backend
python3 scripts/tts.py --platform doubao "今天天气真好" weather.wav
python3 scripts/tts.py --platform minimax "高品质语音合成" hq.wav
# Adjust speed
python3 scripts/tts.py --rate +15% "快速播报" fast.wav
python3 scripts/tts.py --rate -10% "慢速朗读" slow.wav
```
### From File
```bash
python3 scripts/tts.py --input script.txt output.wav
```
### Output Format
```bash
# MP3 output (compressed, smaller file)
python3 scripts/tts.py --format mp3 "你好" hello.mp3
# JSON envelope + MP3 audio at the same time
python3 scripts/tts.py --json --format mp3 "你好" hello.mp3
```
### Preview (Dry Run)
```bash
# Preview without making API call — no package installs needed
python3 scripts/tts.py --dry-run "这是一段测试文本"
```
### List Options
```bash
python3 scripts/tts.py --list
```
## Expressiveness Markers
Input text may contain markers on **any** platform — they are rendered natively
where supported and stripped everywhere else (never read aloud). The chunker
never splits inside a `[...]` marker.
| Marker | Syntax | azure | minimax | all other platforms |
|--------|--------|-------|---------|---------------------|
| Pause | `[PAUSE:x]` — x = seconds, 0.01-99.99 | `<break time="xs"/>` (SSML) | `<#x#>` | stripped |
| Sound tags | `(laughs)` `(chuckle)` `(sighs)` `(breath)` `(inhale)` `(exhale)` `(coughs)` | stripped | voiced **only if** `MINIMAX_MODEL` starts with `speech-2.8` (else stripped + stderr warning) | stripped |
```bash
python3 scripts/tts.py --platform azure \
"大家好。[PAUSE:0.8] 今天我们聊一个新话题。" out.wav
MINIMAX_MODEL=speech-2.8-hd python3 scripts/tts.py --platform minimax \
"这也太好笑了 (laughs) 好，我们继续。" out.wav
```
## Pronunciation Overrides (`--phonemes`)
Fix polyphonic Chinese characters (多音字) with a JSON dict mapping words to
space-separated pinyin — tone-numbered (`hang2 zhang3`) or tone-marked
(`háng zhǎng`). Keys starting with `_` are comments.
```json
{
"_comment": "pronunciation overrides for bank-themed script",
"行长": "hang2 zhang3",
"重庆": "chóng qìng"
}
```
```bash
python3 scripts/tts.py --platform azure --phonemes phonemes.json \
"行长在重庆开会。" out.wav
```
Per-platform: **azure** → SSML `<phoneme alphabet="sapi">` tags; **minimax** →
inline pinyin annotations like `重(chong2)庆(qing4)` (applied before chunking so
the annotation counts toward the chunk budget); all other platforms silently
ignore the flag.
## Requirements
```bash
# Core (always needed)
pip install edge-tts # For Edge (default, free)
# Optional backends — install only what you use
pip install dashscope # CosyVoice
pip install requests # Doubao, MiniMax, ElevenLabs, OpenAI, Google
pip install azure-cognitiveservices-speech # Azure
pip install tencentcloud-sdk-python-tts # Tencent Cloud
pip install baidu-aip chardet # Baidu AI
pip install websocket-client # Xunfei
```
System requirement: `ffmpeg`
## Environment Variables
```bash
# Global defaults (optional)
export TTS_BACKEND="edge"
export TTS_VOICE="zh-CN-XiaoxiaoNeural"
export TTS_RATE="+5%"
export TTS_FORMAT="wav" # wav | mp3 | json (json = JSON envelope mode)
# Backend tuning (optional)
export MINIMAX_MODEL="speech-2.6-hd" # use speech-2.8-* to voice sound tags
export MINIMAX_GROUP_ID="" # required by some MiniMax accounts
export COSYVOICE_MODEL="cosyvoice-v3-flash"
# ByteDance Volcano Ark (Doubao)
export VOLCENGINE_APPID="your_app_id"
export VOLCENGINE_ACCESS_TOKEN="your_token"
# Alibaba DashScope (CosyVoice)
export DASHSCOPE_API_KEY="your_api_key"
# Microsoft Azure
export AZURE_SPEECH_KEY="your_key"
export AZURE_SPEECH_REGION="eastasia"
export TTS_STYLE="gentle" # optional: mstts:express-as style; unset = plain prosody
# Tencent Cloud
export TENCENT_SECRET_ID="your_secret_id"
export TENCENT_SECRET_KEY="your_secret_key"
# Baidu AI
export BAIDU_APP_ID="your_app_id"
export BAIDU_API_KEY="your_api_key"
export BAIDU_SECRET_KEY="your_secret_key"
# MiniMax
export MINIMAX_API_KEY="your_api_key"
# iFlytek Xunfei
export XUNFEI_APP_ID="your_app_id"
export XUNFEI_API_KEY="your_api_key"
export XUNFEI_API_SECRET="your_api_secret"
# ElevenLabs (international)
export ELEVENLABS_API_KEY="your_api_key"
export ELEVENLABS_MODEL="eleven_multilingual_v2" # optional, this is the default
# OpenAI TTS (international)
export OPENAI_API_KEY="your_api_key"
export OPENAI_TTS_MODEL="tts-1-hd" # optional, this is the default
# Google Cloud TTS (international)
export GOOGLE_TTS_API_KEY="your_api_key"
export GOOGLE_TTS_LANGUAGE="en-US" # optional, auto-derived from voice name
```
Get API Keys:
- Volcano Ark: https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
- DashScope: https://bailian.console.aliyun.com/
- Azure: https://portal.azure.com/
- Tencent Cloud: https://console.cloud.tencent.com/tts
- Baidu AI: https://console.bce.baidu.com/ai/#/ai/speech/overview
- MiniMax: https://platform.minimaxi.com
- Xunfei: https://www.xfyun.cn
- ElevenLabs: https://elevenlabs.io/app/settings/api-keys
- OpenAI: https://platform.openai.com/api-keys
- Google Cloud: https://console.cloud.google.com/apis/credentials
## Config File (Optional)
Create `~/.ttscn.json` for personal defaults, or `.ttscn.json` in a project directory:
```json
{
"backend": "minimax",
"voice": "female-shaonv",
"rate": "+10%"
}
```
Priority (highest first):
1. CLI arguments (`--platform`, `--voice`, `--rate`)
2. Environment variables (`TTS_BACKEND`, `TTS_VOICE`, `TTS_RATE`)
3. Project config (`.ttscn.json` in current directory)
4. User config (`~/.ttscn.json`)
5. Built-in defaults
## Examples
### Quick Narration (Free, Zero Setup)
```bash
python3 scripts/tts.py \
"人工智能正在改变我们的生活方式，从智能助手到自动驾驶，技术革新无处不在。" \
ai_narration.wav
```
### Douyin Style Short Video Voice
```bash
python3 scripts/tts.py \
--platform doubao --voice BV001_streaming --rate +10% \
"家人们，今天给大家推荐一个超好用的神器！" \
douyin_style.wav
```
### Audiobook from Script File (CosyVoice)
```bash
python3 scripts/tts.py \
--platform cosyvoice --voice longxiaoxia_v3 \
--input chapter1.txt chapter1.wav
```
### Bulk Generation at Lowest Cost (Tencent, inline env vars)
```bash
TENCENT_SECRET_ID="xxx" TENCENT_SECRET_KEY="xxx" \
python3 scripts/tts.py \
--platform tencent --voice 101001 \
--input course_script.txt course_audio.wav
```
### Premium Quality with Emotion (MiniMax)
```bash
MINIMAX_API_KEY="xxx" \
python3 scripts/tts.py \
--platform minimax --voice female-shaonv \
"这是一段充满感情的语音合成演示。" premium.wav
```
## Agent-Native CLI Reference
ttscn follows the [agent-native-design](https://github.com/Agents365-ai/agent-native-design) contract.
It serves **humans** (readable terminal output), **AI agents** (structured JSON on stdout), and
**orchestrators** (distinct exit codes + idempotency) simultaneously.
### JSON Mode
```bash
# Explicit JSON envelope mode (independent of --format)
python3 scripts/tts.py --json "你好" out.wav
python3 scripts/tts.py --json --format mp3 "你好" out.mp3
# --format json is a deprecated alias for --json (kept for compatibility)
# Auto-detect: pipe to jq → JSON automatically
python3 scripts/tts.py --list | jq .data.backends[0].name
# Error envelope always structured
python3 scripts/tts.py --json --platform doubao "test" out.wav
# → {"ok":false, "error":{"code":"auth_missing_env","message":"...","retryable":false,...}}
```
### Output Envelope
```json
// Success
{"ok":true, "data":{...}, "meta":{"version":"...","schema_version":"1.2.0","timestamp":"...","ms":123}}
// Error
{"ok":false, "error":{"code":"auth_missing_env","message":"VOLCENGINE_APPID not set","retryable":false,"field":"VOLCENGINE_APPID","backend":"doubao"}, "meta":{...}}
```
### Word Boundaries (edge / azure / doubao / minimax / cosyvoice)
For **edge**, **azure**, **doubao**, **minimax**, and **cosyvoice**, the
success envelope includes native word-level timestamps under
`data.word_boundaries` — absolute seconds within the output file, ascending,
3-decimal rounding. The key is absent for other platforms — and may be absent
on doubao/minimax/cosyvoice too when the provider returns no timing payload
(minority-language doubao voices; minimax subtitle download failure;
cosyvoice-v1 or voices without timestamp support) — so consumers must treat
it as optional.
```json
{"ok":true, "data":{
"output_file": "out.wav",
"word_boundaries": [
{"text": "你好", "offset_sec": 0.1, "duration_sec": 0.45},
{"text": "世界", "offset_sec": 0.562, "duration_sec": 0.5}
]
}}
```
Use these for subtitle/SRT generation or beat-synced animation without a
separate forced-alignment pass.
### Exit Codes
| Code | Meaning | Agent action |
|------|---------|-------------|
| **0** | Success | Parse `data`, proceed |
| **1** | Internal / runtime error | Report to user, do not retry |
| **2** | Validation / fixable error (bad input, missing package) | Fix input or install package, retry allowed |
| **3** | Auth / missing credentials | Ask user for API key, do not retry |
| **4** | Backend API error | Retry with backoff |
### Schema Introspection
```bash
python3 scripts/tts.py schema backends # All 11 backends (compact by default)
python3 scripts/tts.py schema backends --full # All fields (22 per backend)
python3 scripts/tts.py schema backends.doubao # Single backend full detail
python3 scripts/tts.py schema voices # All voice presets per backend
python3 scripts/tts.py schema tags # Tag definitions
python3 scripts/tts.py schema version # Version + providers data freshness
# Field filtering for low-token-cost queries
python3 scripts/tts.py schema backends --fields name,cost,supports_clone,supports_ssml
```
### Idempotency
```bash
# Orchestrators: retried calls return cached result — no double-billing
python3 scripts/tts.py --idempotency-key "daily-podcast-2026-07-08" --input script.txt out.wav
# Cache at ~/.ttscn_idem/, 7-day TTL, SHA-256 keyed
```
A cache hit returns the stored result with `data.cached: true`. If the cached
`output_file` no longer exists on disk, the call **re-synthesizes** instead of
returning a stale success.
### Agent Compatibility Flags
```bash
# No-ops accepted for agent runtime compatibility (ttscn never prompts)
python3 scripts/tts.py --yes --no-input "text" out.wav
```