ttscn

ttscn — 多平台中文 TTS 技能

概述

将文本转换为自然语音音频。15 种后端——11 种适合中国用户的云服务，以及 4 种国际或统一 API（ElevenLabs / OpenAI / Google / Atlas Cloud）。

#	后端	费用	主要优势
1	Edge TTS（默认）	免费	无需 API 密钥，随处可用
2	Doubao（ByteDance）	约 1 RMB/10K	中文自然度最佳（9/10）
3	CosyVoice（Alibaba）	约 0.2 RMB/1K	流式处理速度快，灵活
4	Qwen3-TTS（Alibaba）	约 1 RMB/10K	支持 10 种语言，可通过指令控制
5	StepFun（阶跃星辰）	低成本	兼容 OpenAI，约 10 秒即可克隆
6	GLM-TTS（Zhipu）	低成本	情感控制，简单 REST
7	Azure（Microsoft）	约 1 USD/M 字符	企业级 SSML，eastasia
8	Tencent Cloud	0.75 RMB/10K	成本最低，380 多种声音
9	Baidu AI	灵活	30 多种声音，支持情感和方言
10	MiniMax	约 $0.10/1K	音质最佳，300 多种声音，支持克隆
11	iFlytek Xunfei	约 2 RMB/10K	MOS 4.8，500 多种声音，专业级
12	ElevenLabs	付费套餐（$5/月起）	顶级音质，即时克隆
13	OpenAI TTS	约 $15-30/M 字符	6 种声音，多语言，简单 REST
14	Google Cloud TTS	约 $16/M 字符（有免费套餐）	220 多种声音，支持 40 多种语言
15	Atlas Cloud TTS	按模型计费	统一异步 API，多语言声音

1.4–1.6 版新增：词级时间戳（edge/azure/doubao/minimax/cosyvoice — 尽力提供，无法提供时会降级为不带边界），[PAUSE:x] + 声音标签标记（所有平台），--phonemes 发音覆盖（azure/minimax）。 1.7 版新增：--json 标志（输出 JSON 封装，不受 --format 影响），幂等命中时会报告 cached: true，且若缓存的音频已删除则重新合成， --input f out.wav 位置参数已修复，分块器不会在 [PAUSE:x] 内部拆分。 1.8 版新增：MiniMax 默认使用 speech-2.8-hd（开箱即用，可为声音标签配音），支持 CosyVoice v3.5-flash（仅限自定义/克隆声音——预设声音需要 cosyvoice-v3-flash）。 1.9 版新增：Qwen3-TTS（DashScope，复用 DASHSCOPE_API_KEY）、StepFun （复用 STEP_API_KEY）、GLM-TTS（复用 ZHIPUAI_API_KEY）和 Atlas Cloud TTS（异步生成、有界轮询、无需凭证即可下载媒体、多语言预设声音）后端——后端总数达到 15 种。

跨平台：Windows、macOS、Linux

本文档中的所有路径均相对于此技能的根目录（即包含此 SKILL.md 的目录）——请以该目录为基准解析。

何时使用此技能

在以下情况下自动启用此技能：

• 用户希望将中文文本转换为语音音频
• 为视频生成语音旁白或配音
• 根据文本制作有声书或播客音频
• 用户询问如何比较 TTS 服务商、选择 TTS 后端或查看可用声音
• 用户询问 TTS 定价、功能，或哪个服务商支持克隆/SSML/方言
• 用户提到以下任一内容：TTS、text-to-speech、语音合成、文字转语音、Edge TTS、Doubao TTS、CosyVoice、火山引擎、阿里云语音、Azure TTS、腾讯云TTS、百度语音、MiniMax、讯飞语音、ElevenLabs、OpenAI TTS、Google Cloud TTS、Atlas Cloud TTS
• 用户需要词级时间戳/字幕、停顿控制，或修正中文字符的错误发音（多音字）
• 任何适合使用中文文本转语音的任务

服务商比较页面

当用户想要浏览、比较或选择 TTS 服务商时，始终先在浏览器中打开 本地 HTML 比较页面——这是一个可视化、可筛选的表格，浏览速度远快于阅读文本输出。

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

比较页面包括：

• 可筛选表格——可按免费、SSML、语音克隆、流式传输、方言、多语言筛选
• 各服务商的详情面板——费用、最大字符数／时长、克隆方法、情感表达、语言
• 语音卡片——推荐语音，附风格说明和最佳用途标签
• API 密钥链接——直达各服务商控制台的链接，方便获取密钥

此页面由 data/providers.json 自动生成（这是所有服务商／语音数据的唯一真实来源）。编辑 JSON 后，运行 python3 scripts/build_docs.py 重新生成页面。也可以通过 CLI 查询相同的数据：python3 scripts/tts.py schema backends|voices（参见“架构查询”）。

打开页面后，询问用户想使用哪个后端和语音，然后继续执行第 2 步。

工作流

第 0 步——显示比较页面（比较／选择时）

如果用户正在浏览、比较服务商，或不确定该使用哪个后端，请按上述说明打开 docs/providers.html。让用户自行浏览，然后询问他们想使用哪个后端和语音。

第 1 步——了解需求

确认用户的需求：

• 文本：直接输入文本还是使用文件？短文本还是长篇内容？
• 语音风格：男声／女声、年轻／成熟、温暖／有活力？（参见下方的语音指南）
• 语速：正常、较快（+10-20%）、较慢（-10-20%）？
• 格式：WAV（无损）还是 MP3（压缩）？

第 2 步——选择后端和语音

根据使用场景选择（参见“后端选择指南”）。如果不确定，默认使用 Edge TTS 和 zh-CN-XiaoxiaoNeural（女声、温暖、标准）。说明你的选择。

第 3 步——合成

使用文本和选定的选项运行 scripts/tts.py。

第 4 步——报告结果

确认输出路径、文件大小和音频时长。

后端选择指南

快速选择

使用场景	后端	语音	原因
默认／通用	edge	zh-CN-XiaoxiaoNeural	免费，无需设置
短视频／抖音	doubao	BV001_streaming	原生短视频风格
有声书／长篇内容	cosyvoice	longxiaochun_v3	合成速度快，自然
企业／SSML	azure	zh-CN-XiaoxiaoNeural	丰富的韵律控制
批量／最低成本	tencent	101001	每 10K 字符 0.75 RMB
情感／方言	baidu	3 or 4	情感合成、粤语
最佳音质／克隆	minimax	female-shaonv	speech-2.8-hd、语音设计
教育／专业	xunfei	xiaoyan	MOS 4.8，500+ 种语音
男声旁白	edge	zh-CN-YunxiNeural	有活力的男声
纪录片	azure	zh-CN-YunyangNeural	深沉、专业的男声
儿童内容	edge	zh-CN-XiaomengNeural	明快、年轻的女声
注重成本	edge	zh-CN-XiaoxiaoNeural	完全免费
英语，顶级音质	elevenlabs	21m00Tcm4TlvDq8ikWAM (Rachel)	一流的英语语音
英语，简单／低价	openai	alloy	tts-1-hd，只需一个环境变量
英语，企业级	google	en-US-Neural2-F	220+ 种语音，免费层级
多语言／指令控制	qwen	Cherry	支持 10 种语言、通过自然语言控制风格、复用你的 DASHSCOPE 密钥
营销／快速	stepfun	cixingnansheng	兼容 OpenAI，可复用你的 STEP 密钥
简单／情感表达	zhipu	tongtong	精简的 REST 接口，可复用你的 ZHIPUAI 密钥

完整能力与语音数据

完整能力矩阵（费用、每个分块的最大字符数／时长、SSML、克隆方式与费用、情感、方言、语言、流式传输、设置难度）以及各后端的语音列表都集中在一个地方：data/providers.json。可通过以下方式查看：

• 比较页面（docs/providers.html）——最适合人类阅读
• python3 scripts/tts.py schema backends --full — 查看每个后端的完整能力字段
• python3 scripts/tts.py schema voices — 查看所有语音预设及风格说明
• python3 scripts/tts.py --list — 查看便于人类阅读的终端摘要

不要在其他地方维护这些表格的副本——请从 JSON 重新生成。

语音克隆（clone 命令）

从参考音频创建自定义语音，为其指定名称，然后在任何接受 --voice 的地方使用该名称。minimax（支持本地文件，音频时长为 10 秒至 5 分钟；付费：全球站点约 $1.5／个语音，中国站点首次使用 ¥9.9；新克隆的语音在首次实际合成前为临时状态——请在创建后 7 天内［全球站点］／48 小时内［中国站点］使用，否则 MiniMax 会将其删除，预览不计入使用；首次使用后将永久保留）和 cosyvoice（注册免费，音频必须是公开的 http(s) URL，时长为 10-20 秒；语音在闲置 1 年后过期）内置了此功能。

# 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).
# v3.5-flash has NO preset voices — it needs a custom/cloned voice created with
# the same model (voice IDs are not interchangeable across models).
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

Agent 必须遵守以下规则：

• MiniMax 创建语音需要付费——未经用户明确确认，绝不运行 clone create --platform minimax（CLI 会强制要求使用 --yes）。
• 只能克隆用户自己的声音，或用户获准使用的声音——两个平台的合同均禁止未经同意克隆第三方的声音。
• 参考音频：清晰的单人语音，不含背景音乐；理想时长为 10-20 秒。
• 命名语音保存在 ~/.ttscn.json 的 cloned_voices 下。

其他平台（Doubao/Tencent/Baidu/Xunfei/Azure）支持通过其控制台克隆语音——生成的语音 ID 也可直接用作 --voice。

用法

基本用法

# 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
python3 scripts/tts.py --platform atlas "统一 API 多语言语音合成" atlas.wav

# Adjust speed
python3 scripts/tts.py --rate +15% "快速播报" fast.wav
python3 scripts/tts.py --rate -10% "慢速朗读" slow.wav

从文件读取

python3 scripts/tts.py --input script.txt output.wav

输出格式

# 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 without making API call — no package installs needed
python3 scripts/tts.py --dry-run "这是一段测试文本"

列出选项

python3 scripts/tts.py --list

表达力标记

输入文本可在任何平台使用标记——在支持的平台上会以原生方式处理，在其他平台上则会被移除（绝不会朗读出来）。分块器不会在 [...] 标记内部拆分。

标记	语法	azure	minimax	所有其他平台
停顿	[PAUSE:x] — x = 秒数，0.01-99.99	<break time="xs"/>（SSML）	<#x#>	移除
音效标签	(laughs) (chuckle) (sighs) (breath) (inhale) (exhale) (coughs)	移除	仅当 MINIMAX_MODEL 以 speech-2.8 开头时才会发声（否则移除并输出 stderr 警告）	移除

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

发音覆盖（--phonemes）

使用 JSON 字典修正中文多音字，将词语映射到以空格分隔的拼音——可使用数字标调（hang2 zhang3）或符号标调（háng zhǎng）。以 _ 开头的键为注释。

{
  "_comment": "pronunciation overrides for bank-themed script",
  "行长": "hang2 zhang3",
  "重庆": "chóng qìng"
}

python3 scripts/tts.py --platform azure --phonemes phonemes.json \
  "行长在重庆开会。" out.wav

各平台的处理方式：azure → 使用 SSML <phoneme alphabet="sapi"> 标签；minimax → 使用行内拼音标注，例如 重(chong2)庆(qing4)（在分块前应用，因此标注内容会计入分块字数上限）；所有其他平台都会静默忽略此标志。

要求

# 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

系统要求：ffmpeg

环境变量

# 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.8-hd"       # default; sound tags need speech-2.8-*
export MINIMAX_GROUP_ID=""                 # required by some MiniMax accounts
export COSYVOICE_MODEL="cosyvoice-v3-flash"  # or cosyvoice-v3.5-flash (custom/cloned voices only)

# ByteDance Volcano Ark (Doubao)
# v3 (recommended, no appid): API key from the new console (Ark API Key page)
export VOLCENGINE_API_KEY="your_api_key"
export VOLCENGINE_RESOURCE_ID="seed-tts-2.0"   # optional; seed-tts-1.0 / seed-icl-2.0 also valid
# v1 (legacy, appid + token): only when VOLCENGINE_API_KEY is unset
export VOLCENGINE_APPID="your_app_id"
export VOLCENGINE_ACCESS_TOKEN="your_token"

# Alibaba DashScope (CosyVoice + Qwen3-TTS)
export DASHSCOPE_API_KEY="your_api_key"
export QWEN_TTS_MODEL="qwen3-tts-flash"   # or qwen3-tts-instruct-flash (instructions control)
export QWEN_TTS_LANGUAGE=""              # optional: Chinese / English / ... ; unset = Auto
export QWEN_TTS_INSTRUCTIONS=""          # optional: natural-language style, instruct models only

# StepFun (阶跃星辰)
export STEP_API_KEY="your_api_key"
export STEPFUN_TTS_MODEL="step-tts-mini"   # or step-tts-2 / stepaudio-2.5-tts

# Zhipu (智谱)
export ZHIPUAI_API_KEY="your_api_key"
export ZHIPU_TTS_MODEL="glm-tts"

# 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

# Atlas Cloud TTS (unified API)
export ATLASCLOUD_API_KEY="your_api_key"
export ATLASCLOUD_TTS_LANGUAGE="auto"                # optional, this is the default

获取 API 密钥：

• 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
• Atlas Cloud：https://www.atlascloud.ai/console/api-keys

配置文件（可选）

创建 ~/.ttscn.json 设置个人默认值，或在项目目录中创建 .ttscn.json：

{
  "backend": "minimax",
  "voice": "female-shaonv",
  "rate": "+10%"
}

优先级（从高到低）：

1. CLI 参数（--platform、--voice、--rate）
2. 环境变量（TTS_BACKEND、TTS_VOICE、TTS_RATE）
3. 项目配置（当前目录中的 .ttscn.json）
4. 用户配置（~/.ttscn.json）
5. 内置默认值

示例

快速旁白（免费，无需设置）

python3 scripts/tts.py \
  "人工智能正在改变我们的生活方式，从智能助手到自动驾驶，技术革新无处不在。" \
  ai_narration.wav

抖音风格短视频配音

python3 scripts/tts.py \
  --platform doubao --voice BV001_streaming --rate +10% \
  "家人们，今天给大家推荐一个超好用的神器！" \
  douyin_style.wav

根据脚本文件制作有声书（CosyVoice）

python3 scripts/tts.py \
  --platform cosyvoice --voice longxiaoxia_v3 \
  --input chapter1.txt chapter1.wav

以最低成本批量生成（Tencent，内联环境变量）

TENCENT_SECRET_ID="xxx" TENCENT_SECRET_KEY="xxx" \
python3 scripts/tts.py \
  --platform tencent --voice 101001 \
  --input course_script.txt course_audio.wav

搭配情感表达的高品质语音（MiniMax）

MINIMAX_API_KEY="xxx" \
python3 scripts/tts.py \
  --platform minimax --voice female-shaonv \
  "这是一段充满感情的语音合成演示。" premium.wav

面向 Agent 的 CLI 参考

ttscn 遵循 agent-native-design 契约。 它同时服务于人类（易读的终端输出）、AI Agent（stdout 上的结构化 JSON）和 编排器（独立的退出代码 + 幂等性）。

JSON 模式

# 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,...}}

输出封装

// Success
{"ok":true, "data":{...}, "meta":{"version":"...","schema_version":"1.2.0","timestamp":"...","ms":123}}

// Error
{"ok":false, "error":{"code":"auth_missing_env","message":"set one of: VOLCENGINE_APPID+VOLCENGINE_ACCESS_TOKEN / VOLCENGINE_API_KEY","retryable":false,"field":"VOLCENGINE_APPID","backend":"doubao"}, "meta":{...}}

契约：每个封装（成功和错误）的 meta.schema_version 都是一个 semver 字符串。只有在封装发生破坏性变更时才会提升主版本号——消费者应检查它是否与其所依据的架构主版本号一致（例如，video-podcast-maker 要求主版本号为 1），否则应以明确的错误退出。缺少 schema_version 表示使用的是契约发布前的 ttscn 版本。

词边界（edge / azure / doubao / minimax / cosyvoice）

对于 edge、azure、doubao、minimax 和 cosyvoice，成功封装会在 data.word_boundaries 下包含原生词级时间戳——相对于输出文件的绝对秒数，按升序排列， 精确到 3 位小数。其他平台不会提供此键；而当服务提供商未返回时间数据时， doubao/minimax/cosyvoice 也可能不提供此键 （少数语言的 doubao 语音；minimax 字幕下载失败；cosyvoice-v1 或不支持时间戳的语音）， 因此消费者必须将其视为可选项。

{"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}
  ]
}}

可将这些数据用于生成字幕/SRT，或制作与节拍同步的动画，无需单独进行强制对齐。

退出代码

Code	含义	Agent 操作
0	成功	解析 data，继续
1	内部 / 运行时错误	告知用户，不要重试
2	验证 / 可修复错误（输入错误、缺少软件包）	修正输入或安装软件包，可重试
3	身份验证 / 缺少凭据	向用户索取 API 密钥，不要重试
4	后端 API 错误	退避后重试

架构自省

python3 scripts/tts.py schema backends              # All 15 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

幂等性

# 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

命中缓存时会返回已存储的结果，并设置 data.cached: true。如果缓存的 output_file 已不在磁盘上，调用会重新合成，而不是返回过期的成功结果。

Agent 兼容性标志

# No-ops accepted for agent runtime compatibility (ttscn never prompts)
python3 scripts/tts.py --yes --no-input "text" out.wav