captjt/skill-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": "温暖、自信的产品叙述者",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "欢迎体验全新的“洞察”面板。"},
    {"id": "02-filters", "text": "一键筛选任意图表：按团队、按服务或按发布版本。"},
    {"id": "03-alerts",  "text": "设置一次告警，当任何指标出现偏移时，我们就会立即通知你。", "pause": 1.0},
    {"id": "04-outro",   "text": "“洞察”现已上线，适用于所有套餐。"}
  ]
}

• 顶层字段（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 "脚本中的一行。" 渲染简短样本。提供将选择保存为 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" "构建通过，所有214项测试均为绿色。"
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
较长的文本，或包含引号的任何内容，通过标准输入传入。
EOF

此命令在音频开始播放后立即返回，播放将在后台继续。新的语音会中断当前语音；-q 将其加入队列，tts stop 静音所有内容。

其他选项：

• -p 提供商，-v 语音，-i "风格"，-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。