mcpField
T
text-to-speech

text-to-speech

github.com/wlzhクリエイティブ・メディア69464 回インストール3 日前に更新
リポジトリ

text-to-speech について

text-to-speech は、テキストやポッドキャストの台本を音声に変換する Skill です。MiniMax、Kokoro、Edge を選択でき、台本マーカーの除去や任意の後処理にも対応します。

主な機能

  1. 01MiniMax、Kokoro、Edge エンジン対応
  2. 02台本の注釈とマーカーの除去
  3. 03中国語と英語の混在読み上げ
  4. 04MiniMax の単語単位タイムスタンプ
  5. 05voice-changer による任意の後処理

活用シーン

  1. 01動画やポッドキャスト台本のナレーション作成
  2. 02タイムスタンプや演出指示を除去して音声合成
  3. 03MiniMax 音声の単語単位タイムスタンプ生成

インストール

コマンドをコピーしてターミナルで実行します。

$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

詳細

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 を設定してください
  • プロキシをバイパスせずに localhost へ直接 curl/requests することは禁止です。プロキシ経由で失敗してから再試行しないでください。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 対応