mcpField
T
text-to-speech

text-to-speech

github.com/wlzh创意与媒体69464 次安装2 天前更新
代码仓库

关于 text-to-speech

text-to-speech 是将文本或播客脚本转为语音的 Skill，面向需要旁白音频的内容创作者。它可在 MiniMax、Kokoro 和 Edge 引擎间配置，并支持解析脚本标记及可选后处理。

主要功能

  1. 01支持 MiniMax、Kokoro 和 Edge 引擎
  2. 02解析并清理脚本标记
  3. 03支持中英文混合朗读
  4. 04MiniMax 词级时间戳输出
  5. 05可选 voice-changer 后处理

适用场景

  1. 01为视频或播客脚本生成旁白
  2. 02清理时间戳和舞台指示后合成语音
  3. 03为 MiniMax 合成音频生成词级时间戳

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wlzh/skills --skill text-to-speech

安装后在 Claude Code 中输入/text-to-speech确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CHANGELOG.md
README.md
VERSION
config/
tts_config.json
scripts/
minimax_voice_clone.py
text_to_speech.py
tests/
test_minimax_context.py
test_minimax_voice_clone.py

详细介绍

来自项目 README

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 标记：**文本**
2. 中英文混合朗读

v1.1-zh 模型支持中英文混合文本的自然朗读。

3. 后处理集成

可选集成 voice-changer skill 进行变声处理。

配置文件

配置文件位于：~/.claude/skills/text-to-speech/config/tts_config.json

关键配置项：

  • tts_engine: "minimax"、"kokoro" 或 "edge"（默认引擎）
  • minimax_tts: MiniMax 引擎配置（API URL、模型、默认音色、语速；Key 仅从环境变量读取）
  • minimax_tts.context_adaptation: MiniMax 专属语境档和自动识别规则；不影响其他引擎
  • kokoro_tts: Kokoro 引擎配置（API URL、默认声音、语速）
  • edge_tts: Edge 引擎配置（声音、语速、音调、音量）
  • available_voices: 按引擎分组的可用声音列表

工作流程

输入文本/文件
    ↓
脚本解析（移除注释和标记）
    ↓
MiniMax / Kokoro TTS / Edge TTS 语音合成
    ↓
后处理（voice-changer，可选）
    ↓
输出 MP3 文件

代理绕过（重要）

Kokoro TTS 运行在 localhost:8880。如果系统配置了 HTTP 代理（http_proxy/https_proxy），请求 localhost 会被代理拦截导致连接失败（curl 返回 HTTP 000）。

规则：

  • Python 脚本已内置 os.environ.setdefault("no_proxy", "localhost,127.0.0.1")，通过脚本调用无需额外处理
  • 如果 AI 需要直接用 curl 测试或调用 Kokoro API，必须加 --noproxy localhost,127.0.0.1 或设置 no_proxy=localhost,127.0.0.1
  • 如果 AI 直接写 Python requests.post("http://localhost:8880/...")，必须设置 proxies={"http": None, "https": None}，或使用 requests.Session(); session.trust_env = False，并设置 NO_PROXY/no_proxy=localhost,127.0.0.1,::1
  • 禁止不加代理绕过直接 curl/requests localhost；不要先走代理失败再重试，localhost Kokoro 请求默认就必须绕过代理
# 正确：绕过代理
curl --noproxy localhost,127.0.0.1 -X POST http://localhost:8880/v1/audio/speech ...

# 错误：走了代理，返回 HTTP 000
curl -X POST http://localhost:8880/v1/audio/speech ...

依赖

  • MiniMax TTS: MINIMAX_API_KEY 环境变量
  • Kokoro TTS: Docker（容器运行在 localhost:8880）
  • Edge TTS: pip install edge-tts

性能参考

  • Kokoro TTS: 1000字约 3-5 秒（本地 Docker CPU）
  • Edge TTS: 1000字约 10-20 秒（受网络影响）

评论

支持 Markdown