SuperAPI AI 工具集

tts

通用与其它

查看项目

更新于 10-26 18:17

技能介绍

用途

该技能用于把提供的文本合成为语音音频文件,写入调用方指定的路径,支持单说话人和多说话人对话两种形式。若需要制作播客、简报或旁白摘要等组合式音频内容,应改用 podcast 技能。

主要能力

  • 单次合成:使用 tts speak 直接把一段文本合成为音频。
  • 多说话人脚本合成:使用 tts synthesize-script 处理带说话人标签的脚本,自动完成文本准备、分块、合成和拼接,支持任意数量的说话人。
  • 语音来源:系统语音位于 /opt/hatch/skills/voice-selector/voice_source.json(按 id 选择),已保存的设计语音位于 user/voices.json(按 voice_id 选择);文件缺失表示没有已保存语音。
  • 默认语音:avocado_v2:MAI_03(Smooth)。推荐优先使用 Meta AI 语音,即 avocado_v2:MAI_01 和 avocado_v2:MAI_03(Warm 与 Smooth)。
  • 语言:默认英语(--language en),可传入其他语言代码,如 es、pt、fr、de,或 pt_BR、es_ES 等区域形式。

使用方式

单次合成示例:

tts speak --text "Hello world" --output /tmp/hello.mp3

tts speak --text "Welcome back." --voice avocado_v2:briggs --output /tmp/welcome.mp3

多说话人对话示例:

tts speak
--text "Speaker 1: Welcome back. Speaker 2: Thanks, good to be here."
--voice avocado_v2:chip
--voice2 avocado_v2:rumi
--voice-prefix "Speaker 1: "
--voice-prefix2 "Speaker 2: "
--output /tmp/dialogue.mp3

脚本合成示例:

tts synthesize-script
--script /path/to/script.txt
--speaker Alex=avocado_v2:briggs
--speaker Jordan=avocado_v2:rumi
--output /tmp/episode.mp3

脚本文件为纯文本,每轮开头带说话人标签,例如:

Alex: Welcome to the show. Today we're diving into async Rust. Jordan: Great topic. Let's start with why async matters. Alex: The big advantage is zero-cost abstractions.

脚本文本会原样发送给 TTS 模型,因此应写成口语形式:数字拼写出来("forty-two" 而非 "42")、缩写拆开("A P I" 而非 "API")、时间口语化("three thirty P M" 而非 "3:30 PM")、网址口语化("example dot com" 而非 "https://example.com")。不要包含舞台指示、标记或视觉格式。

speak 核心参数:--text(必填)、--output(必填)、--voice、--voice2、--voice-prefix、--voice-prefix2、--language(默认 en)、--format(默认 mp3)、--speed(默认 100)、--timeout-secs(默认 120)。

synthesize-script 核心参数:--script(必填)、--speaker Name=voice_id(必填,可重复)、--output(必填)、--language(默认 en)、--chunk-size(默认 1200 字符)、--concurrency(默认 1,顺序执行)、--format(默认 mp3)、--speed(默认 100)、--timeout-secs(默认 300)。

输出契约

两个子命令都会打印紧凑的 JSON 摘要,包含 ok、path、bytes、artifact_id(仅 MP3 且可注册来源时非空,属于内部管道,不应在对话中打印)。synthesize-script 还会包含 chunk_count、duration_secs(实际 MP3 时长)和 shortwave_id(内部追踪 id,不应在对话中打印或描述合成后端)。返回的 path 是权威输出位置。

适用场景

适合把短文本快速转为语音,也适合把带说话人标签的长脚本合成为多说话人音频,例如对话式内容。

限制

  • 非英语质量差异显著:英语质量最高、支持最好;其他语言可能从良好到明显粗糙(发音错误、口音不对)不等。合成非英语时应让 --language 与文本语言一致,不要用 --language en 发送非英语文本。语音选择同样重要,若某语音不适合该语言,可尝试 voice_source.json 中的其他语音。质量重要时应告知用户非英语输出可能不完美。
  • 失败处理:CLI 内部会重试瞬时后端错误。到达调用方的失败多为瞬时(后端超时/容量),应原样重试同一命令,不要更换语音或 TTS 引擎,并按约 5 分钟、10 分钟、30 分钟、1 小时的有界阶梯退避重试;若 1 小时后仍失败则停止,取消已安排的 重试,向用户报告实际错误并建议稍后再试。认证失败和明确的请求错误(不支持的 --language/--format、请求过长)不应重试,应立即报告。HTTP 500 需先核对所有语音 id 是否与两个权威来源逐字符匹配,不匹配则视为永久拒绝,不重试;全部匹配才按上述阶梯原样重试。
  • TTS API 缓存较激进,若语音变更似乎未生效,可先略微改动文本再判断路由是否异常。
  • 除非用户明确需要其他格式,否则优先使用 mp3。
  • 音频应始终写入工作区路径或其他明确的本地路径。