跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

text-to-speech

文本转语音工具 - 默认 MiniMax TTS,支持切换 Edge TTS 和 Kokoro TTS (v1.1-zh)

M. · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add wlzh/skills --skill text-to-speech

技能说明


name: text-to-speech description: 文本转语音工具 - 默认 MiniMax TTS,支持切换 Edge TTS 和 Kokoro TTS (v1.1-zh) version: 3.6.0 changelog:

  • 2026-08-01: v3.6.0 新增并默认启用 friendly_tutorial 整期表达档,面向普通大众的免费教程保持正常语速、自然口语和固定声线
  • 2026-08-01: v3.5.0 新增 MiniMax 词级时间戳 sidecar;只保存校验后的时间段,不保存短期签名下载 URL;Edge/Kokoro 显式拒绝该参数
  • 2026-08-01: v3.4.0 新增 MiniMax 声音克隆上传/创建/激活费用门禁、本机 0600 克隆音色档,以及整期固定 commercial_narration 表达档;克隆音色或表达档变化会使下游缓存失效
  • 2026-07-18: v3.3.1 MiniMax 语境适配移除逐 beat emotion 注入,避免同一场景语气跳变;保留 speed/volume/pitch 轻量调整并同步测试文档
  • 2026-07-18: v3.3.0 MiniMax 默认音色改为 Chinese (Mandarin)_Reliable_Executive;新增 MiniMax 专属语境适配层,按开场、总结、解释、步骤、提醒、资源、结论和关注引导自动微调表达;Edge/Kokoro 行为不变
  • 2026-07-17: v3.2.0 新增 MiniMax TTS 引擎并设为默认,默认音色 male-qn-jingying(精英青年)、语速 1.0;API Key 只读取 MINIMAX_API_KEY 环境变量;保留 Kokoro/Edge 可配置切换
  • 2026-05-17: v3.1.0 强化 localhost Kokoro 代理绕过规则——curl/requests 直连本地服务默认必须 NO_PROXY,不允许先走代理失败后重试

author: M.

Text-to-Speech Skill

将文本转换为语音。默认使用 MiniMax TTS(在线高质量中文配音),并保留 Kokoro TTS v1.1-zh(本地 Docker,102 个中文音色)和 Edge TTS(在线)作为可配置后备。

引擎对比

特性MiniMax TTSKokoro TTS v1.1-zhEdge TTS
质量默认推荐,中文短视频旁白更自然本地可用、接近真人标准 Neural 语音
网络需要 MiniMax API不需要(本地 Docker)需要网络连接
默认音色Chinese (Mandarin)_Reliable_Executive(可靠高管)zm_009zh-CN-YunyangNeural
语速调节speed 参数,默认 1.0speed 参数rate/pitch/volume
前提MINIMAX_API_KEY 环境变量Docker 容器需运行安装 edge-tts
配置值minimaxkokoroedge

使用说明

# 默认使用 MiniMax TTS(当前配置)
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py <文本文件>

# 指定引擎
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt --engine minimax
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt --engine kokoro
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt --engine edge

# 指定声音
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt -v zf_094

# 指定输出文件
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt -o output.mp3

# MiniMax 专属:同时保存经过校验的词级时间戳
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt \
  -o output.mp3 --subtitle-output output.subtitles.json

# 调整语速(MiniMax/Kokoro)
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt --speed 1.2

# 列出所有可用声音
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py --list-voices

MiniMax TTS

默认配置:

  • 引擎:tts_engine = "minimax"
  • 模型:speech-2.8-hd
  • 音色:Chinese (Mandarin)_Reliable_Executive(可靠高管)
  • 语速:1.0
  • 输出:MP3

MiniMax 词级时间戳

--subtitle-output <path> 会为 MiniMax 请求启用词级时间戳,下载官方 sidecar 后校验文本、字符范围和时间单调性,再写入本地 JSON。sidecar 只保留 provider/model/voice/subtitle_type/segments,不会记录官方返回的短期签名 URL。该参数属于 MiniMax 专属能力;Edge/Kokoro 会失败关闭,避免下游误把估算时间当成官方时间戳。

整期表达一致性(默认)

minimax_tts.delivery_consistency 默认启用 friendly_tutorial。它用于面向普通大众的免费教程:像真人耐心讲解,允许正文自然使用“好、其实、这里呢、别急”等连接词,但不靠逐句变调制造表演感。同一期视频内所有句子固定使用相同的音色、速度、音量和音调,避免逐 beat 割裂。

  • 默认档:friendly_tutorial,speed 1.0、volume 1.0、pitch 0
  • 显式选择:--delivery-profile friendly_tutorial
  • 保留档:commercial_narration,仅用于公告、品牌声明等确需正式表达的内容
  • 克隆音色选择顺序:--voice > MINIMAX_VOICE_ID > 已激活的本机克隆档 > 仓库系统音色
  • 本机档:~/.config/duanku/minimax-voice.json,必须为 0600,不提交仓库

MiniMax 专属语境适配(兼容回退)

minimax_tts.context_adaptation 只在 MiniMax 分支生效。Edge 和 Kokoro 不读取此配置,也不会改变原请求参数。

  • 仅当 delivery_consistency 关闭时,根据文本自动识别 opening、summary、explanation、instruction、warning、resource、conclusion、call_to_action、neutral
  • 语境档只轻量调整 MiniMax 的语速、音量和音高,不修改原文、不注入 emotion、不自动插入声音标签
  • 未命中规则时使用 explanation
  • 可用 --context warning 等参数显式覆盖自动识别;选择 Edge/Kokoro 时该参数被忽略
  • 调用方无需理解语境规则。视频流水线只需继续提交文本并使用返回音频,音频时长仍由下游实测
# 自动识别语境
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt

# MiniMax 显式指定风险提醒语境
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt --context warning

MiniMax 声音克隆

声音克隆分为不收费的创建阶段和首次 TTS 激活阶段。首次使用新克隆音色合成会产生官方克隆费及试听字符费,脚本要求 quote ID 和精确金额确认,不能用布尔参数绕过。

引擎边界:克隆 profile、克隆 voice_id、--delivery-profile 和克隆样本门禁只允许在实际 tts_engine=minimax 时读取。切换到 Edge 或 Kokoro 后必须完全跳过这些配置,即使本机仍保留已激活的 MiniMax profile,也不得影响非 MiniMax 的音色、请求参数或预检结果。

# 样本检查,不联网、不收费
python3 scripts/minimax_voice_clone.py inspect --sample /path/to/source.m4a

# 输出激活报价,不联网、不收费
python3 scripts/minimax_voice_clone.py quote \
  --voice-id DuankuNarrator20260801 \
  --text "试听文案"

# 上传并创建克隆,不执行 TTS;必须确认拥有声音授权
python3 scripts/minimax_voice_clone.py clone \
  --sample /path/to/source.m4a \
  --voice-id DuankuNarrator20260801 \
  --rights-confirmed

# 首次付费激活并生成试听,必须使用上一步 quote 的 ID 和金额
python3 scripts/minimax_voice_clone.py activate \
  --text "试听文案" \
  --output /path/to/preview.mp3 \
  --confirm-quote-id '<quote_id>' \
  --confirm-amount-usd '<estimated_total_usd>'

样本要求:mp3/m4a/wav、10 秒至 5 分钟、最大 20 MB。克隆脚本默认请求 MiniMax 降噪和音量归一化。

密钥规则:

  • API Key 只从环境变量读取,默认变量名 MINIMAX_API_KEY
  • 克隆 voice_id、远程 file ID 和激活记录只保存在本机 0600 profile
  • 不要把真实 Key 写进 config/tts_config.json、README、命令行参数或提交历史
  • 如果要换变量名,只改 config/tts_config.json 中的 minimax_tts.api_key_env
export MINIMAX_API_KEY="你的本机 key"
python3 ~/.claude/skills/text-to-speech/scripts/text_to_speech.py script.txt -o output.mp3

Kokoro TTS v1.1-zh 声音

使用 --list-voices 查看完整列表(102 个)。

推荐声音

  • zm_009 - 男声(默认)
  • zf_094 - 女声(自然温柔)
  • zf_001 - 女声
  • zm_050 - 男声

英文声音

  • af_maple - 女声(Maple)
  • af_sol - 女声(Sol)
  • bf_vale - 男声(Vale)

声音命名规则

  • zf_XXX - 中文女声(55 个)
  • zm_XXX - 中文男声(44 个)
  • af_/bf_ - 英文声音(3 个)

启动 Kokoro 服务

Kokoro TTS 需要 Docker 容器运行:

# 启动
cd /Users/m/document/QNSZ/project/kokoro-tts && ./start.sh

# 停止
cd /Users/m/document/QNSZ/project/kokoro-tts && ./stop.sh

# Web UI 试听
# http://localhost:8880/web/

核心功能

1. 脚本解析

自动识别并移除播客脚本中的注释和标记:

  • 时间戳:(00:00)
  • BGM 注释:[BGM渐入:...]
  • 舞台指示:(主播声音:...) (停顿 1秒)
  • Markdown 标记:`
阅读完整来源 ↗