tts

文本转语音

运行 ${CLAUDE_SKILL_DIR}/scripts/tts 中的启动器，该路径在此技能目录下为 scripts/tts。下文将其简称为 tts。首次运行时会下载一个约 7 MB 的二进制文件，并在运行前检查其 SHA-256。

每条 tts 命令都要单独作为一次 Bash 调用运行。不要用 ;、&& 或管道将命令串联起来，这样才能让命令处于技能预先批准的权限范围内。

有两种用途：

• 视频配音： tts render。生成文件和时间清单，供视频流水线的其余环节使用。
• 大声朗读： tts "text"。通过扬声器播放，并立即返回。

视频配音

1. 撰写脚本

每个场景或镜头写一段，并沿用视频的场景 ID，使音频与画面对应：

{
  "provider": "elevenlabs",
  "voice": "JBFqnCBsd6RMkjVDRZzb",
  "instructions": "warm, confident product narrator",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "Meet the new Insights dashboard."},
    {"id": "02-filters", "text": "Filter any chart in one click: by team, by service, or by release."},
    {"id": "03-alerts",  "text": "Set an alert once, and we'll tell you the moment a metric drifts.", "pause": 1.0},
    {"id": "04-outro",   "text": "Insights is available today, on every plan."}
  ]
}

• 顶层字段（provider、voice、model、instructions、speed、pause）适用于所有段落。每段都可以覆盖 voice、model、instructions、speed 和 pause；pause 是该段结束后在合并音轨中的静音时长。
• 整条视频使用同一个提供方和声音，这样听起来才像同一位旁白。
• 按适合听的方式撰写： 使用短句，将数字写成读出来的形式（“百分之四十”“版本二”），不要使用 Markdown。如果产品名称的发音不正确，请在 text 中按读音拼写。
• 选择提供方和声音。 如果脚本未设置提供方，且 tts config show 中没有 voiceover_provider，请询问用户要使用哪个提供方和声音。为了方便比较，可以使用 tts -o sample-NAME.wav -p PROVIDER -v VOICE "One line of the script." 渲染简短样例。可以提出将用户的选择保存为 tts config set voiceover_provider NAME 和 tts config set NAME.voice VOICE。Kokoro 和 system 免费且可在本地运行；其他选项均需付费。ElevenLabs、使用 instructions 的 OpenAI，以及 Gemini 的音色最自然。

2. 渲染

"${CLAUDE_SKILL_DIR}/scripts/tts" render script.json -o voiceover/

这会生成：

• 每段对应的 voiceover/<id>.wav，已剪去开头和结尾的静音，因此时长精确。
• 合并所有段落及其停顿后的 voiceover/voiceover.wav。
• 字幕 voiceover/voiceover.srt。
• voiceover/manifest.json，同时也会打印到标准输出：

{"provider": "elevenlabs", "sample_rate": 24000, "channels": 1, "duration": 17.08,
 "combined": {"file": "/abs/voiceover/voiceover.wav", "duration": 17.08},
 "captions": "/abs/voiceover/voiceover.srt",
 "segments": [{"id": "01-intro", "file": "/abs/voiceover/01-intro.wav", "duration": 3.872,
               "start": 0, "end": 3.872, "text": "...", "voice": "...", "cached": false}, ...]}

渲染选项：

• --format mp3|m4a 设置合并音轨的格式。
• --no-combine 仅生成各段的文件。
• -p/-v/-i/-s 设置脚本中未指定的默认值。
• --jobs N 设置并行数。

除非另行指定，render 会使用各提供方保真度最高的模型：eleven_multilingual_v2 和 gemini-3.8-flash-tts。

3. 使用时间信息

• 场景时长： 每个场景的时长至少应与对应段落的 duration 一样长。留出一小段喘息空间，或延长场景使其与之匹配。
• 放置音频： 将每段的文件放在对应场景的开始时间，或将 voiceover.wav 作为单条音轨，并用 start/end 设置偏移量。
• 使用 ffmpeg 混流：
  • 整条音轨：ffmpeg -i video.mp4 -i voiceover/voiceover.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
  • 在 4.47 秒处添加一个段落：添加输入 -i voiceover/02-filters.wav，然后使用 -filter_complex "[1]adelay=4470:all=1[a]" -map 0:v -map "[a]"。

4. 迭代

编辑脚本，然后再次运行同一条命令。文本、声音、模型、风格和速度均未更改的段落会从上次渲染中复用（"cached": true）。只会重新渲染并计费有更改的段落。使用 --force 可重新渲染全部内容。如果部分段落失败，其他段落会保留；再次运行时只会重试失败的段落。

大声朗读

"${CLAUDE_SKILL_DIR}/scripts/tts" "The build passed and all 214 tests are green."
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
Longer text, or anything with quotes, goes on stdin.
EOF

音频开始播放后，此命令即会返回，播放将在后台继续。新的语音会打断当前语音；使用 -q 则会将其排队，而 tts stop 会停止所有播放。

其他选项：

• -p 指定提供方，-v 指定语音，-i "style" 指定风格，-s 指定语速。
• -w 等待播放完成。
• -o FILE [--json] 将内容写入文件，而不是播放。--json 会输出时长和路径。

朗读时：

• 概括内容，不要照读。 除非用户要求朗读全文，否则使用两到四个口语化句子。
• 用文字描述代码，不要直接读出代码。Markdown 和代码块会自动移除。
• 通知内容要简短，连续播报时使用 -q。

提供方、费用与隐私

• 使用已配置的默认值（tts config show）。只有当用户或脚本指定了提供方时才传入 -p。
• system 和 kokoro 在本机运行，且免费。其他提供方会将文本发送给相应公司，并从用户的账户扣费。未经询问，绝不要更改默认提供方。
• 绝不要将机密、凭据或私人数据发送给云端提供方。
• 付费提供方拒绝每条命令中超过 20,000 个新字符的内容。请缩短文本；如果用户希望朗读全部内容，则传入 --max-chars N。

设置与故障排除

• tts doctor 会显示音频输出、默认提供方以及已就绪的提供方。
• tts providers 和 tts voices -p NAME [filter] 会列出提供方和语音。
• tts config set KEY VALUE 用于设置默认值。键包括 provider、voiceover_provider、max_chars 和 NAME.voice|model|speed|instructions|base_url。
• 缺少 API 密钥： 告知用户设置环境变量（例如 ELEVENLABS_API_KEY），或在自己的终端中运行 tts auth set elevenlabs。绝不要让用户把密钥粘贴到聊天中，也绝不要将密钥放在命令行中。
• 未经测试的云端提供方： openai、gemini、cartesia 和 deepgram 尚未针对其线上 API 进行测试。目前只有 system、kokoro 和 elevenlabs 经过测试。如果其中某个提供方因请求本身出错（例如未知字段、无效参数或意外响应）而失败，这很可能是此技能中的错误，而不是用户操作有误。向用户展示完整错误信息，建议他们前往 github.com/captjt/skill-tts/issues 报告，并提供 kokoro 或 system 作为备用方案。不要继续用猜测的参数重试。身份验证错误（401/403）和配额错误（429）仍应由用户自行解决。
• 无法连接 Kokoro： 使用 docker run -d --name kokoro -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.9.0 启动它。
• 没有音频设备（SSH、容器）：使用 render 或 -o；它们不需要扬声器。

每个提供方对应的语音、模型和选项见 references/providers.md。