多供应商旁白 TTS(awk-tts)
火山 openspeech v3 单向流式 + 百炼 SpeechSynthesizer 双后端,凭据自动路由。
用于单纯人声旁白、干声 TTS 和音色复刻/设计。需要背景音、环境音、音效或带这些声音的人声时,优先用 aigc-video-gen audio 一次生成完整音轨;单纯 BGM 用 bgm-library。不要把 qwen-audio-3.1-tts-next 当作本技能的普通 TTS 候选模型,它使用 text_prompt 与参考音频协议。
供应商路由(脚本内部,凭据在哪家走哪家)
| 优先级 | 供应商 | 触发凭据 | 模型/资源 |
|---|---|---|---|
| 1 | 火山豆包语音合成 2.0 | VOLC_TTS_APP_ID+VOLC_TTS_ACCESS_KEY(旧双头)或 VOLC_TTS_APP_KEY(新单头) |
seed-tts-2.0(克隆音色 S_xxx 自动路由 seed-icl-2.0) |
| 2 | 百炼业务空间 | WORKSPACE_ID + MODELSTUDIO_API_KEY/DASHSCOPE_API_KEY |
qwen-audio-3.1-tts-plus → qwen-audio-3.1-tts-flash → qwen-audio-3.0-tts-plus → qwen-audio-3.0-tts-flash |
| 3 | 百炼 agent plan | AWK_API_KEY(token-plan 端点) |
qwen-audio-3.0-tts-plus → qwen-audio-3.0-tts-flash,以账号模型权限为准 |
- 候选链仅在服务明确返回模型不存在/不可用时使用;
--model显式指定后锁定模型。AllocationQuota.FreeTierOnly属额度/付费限制,401/InvalidApiKey 属认证,模型不支持、429限频、网络与服务错误分别报告;不因403盲重登或遍历模型。 - 默认音色:3.1 Plus 为
longanlingxin_v3.1,3.1 Flash 为longanhuan_v3.1,3.0 Plus 为longanlingxin,3.0 Flash 为longanhuan_v3.6。显式音色必须同时指定匹配的--model;跨供应商音色直接拒绝,不自动换声。已有音色档案继续锁定原模型,不自动升级。 - 日志打印当前
route和fallback。默认不跨通路回退;仅在用户已有授权时加--fallback-platform agent-plan,workspace 额度错误后使用现有 AWK_API_KEY 尝试一次,须显式锁定 model/voice,保持语速等参数。绑定音色档案不允许跨通路。失败即停止,不充值、不修改计费;不确定授权时先报告分类与可选通路。 - 格式映射:火山
ogg_opus在百炼自动转opus;百炼不支持 32000 采样率。 - 语速
--speech-rate [-50,100]在百炼线性映射为 rate [0.5,2.0];响度--loudness映射为 volume [0,100]。 - 三组凭据都缺 → exit 1 并列出配置方式。应该 spawn IT engineer subagent 写入实例环境变量,不要自己写环境变量文件。
Run
Do NOT set env vars inline(例如 VOLC_TTS_ACCESS_KEY=... python3 ...)。env var 已在系统环境里,inline 赋值会破坏 exec 权限检查。
# 基础中文旁白,默认落 ./tmp/awk-tts-<ts>/speech.mp3
awk-tts --text "大家好,欢迎来到今天的视频。"
# 从文件读文本
awk-tts --text-file ./scripts/script.txt --out-dir ./assets/audio
# Fragment 工作流:读 tts_requirement.md,抽音色/语速设置,
# 出 speech.mp3 + speech.json 到 ./fragments/01-hook/artifacts/
awk-tts ./fragments/01-hook/ --overwrite
# 指定音色 + 格式 + 精确输出路径
awk-tts \
--text "This is a demo voiceover." \
--voice "en_female_dacey_uranus_bigtts" \
--format wav \
--sample-rate 44100 \
--output ./assets/audio/demo.wav
# 字级时间戳(旁白对齐用):火山走流式原生返回,百炼走 SSE + word_timestamp_enabled
awk-tts --text "..." --enable-subtitle --output ./assets/audio/narration.mp3
合成后脚本会测真峰值。超过 -2.5 dBTP 时自动衰减并复测,给后续数字人驱动和转码留余量;元数据 peak_guard 记录前后峰值。若原始 TTS 已有可闻削波,降低音量不能恢复波形,应重新合成并试听。生成文件用于驱动数字人后不要再换音轨;换音轨须重新生成数字人并核对 job 哈希。
Parameters
| Flag | Default | Description |
|---|---|---|
fragment_dir |
— | Optional fragment directory under fragments/; when set, reads tts_requirement.md and defaults output to artifacts/speech.<format> |
--text |
— | Text to synthesize. Required unless --text-file or fragment_dir is set |
--text-file |
— | UTF-8 text file to synthesize. Must be relative and under scripts, assets, tmp, output_videos, fragments, or <platform>/outputs/ |
--voice |
火山 zh_female_shuangkuaisisi_uranus_bigtts / 业务空间 longanlingxin_v3.1 / Plan longanlingxin |
音色 ID(按路由到的供应商选默认) |
--model |
— | 百炼模型 ID(显式指定关闭候选链 fallback;火山模式忽略) |
--fallback-platform agent-plan |
off | 明确授权 workspace 额度错误后转现有 Plan 一次;必须显式锁定模型和音色 |
--diagnostics |
— | 脱敏事件摘要路径:记录状态、事件类型、request_id、字节数,不含密钥/正文/URL/音频内容 |
--format |
mp3 |
Audio format: mp3, pcm, wav, opus(火山另收 ogg_opus,百炼自动映射为 opus) |
--sample-rate |
火山不设 / 百炼 24000 | 8000/16000/22050/24000/44100/48000(火山另收 32000) |
--speech-rate |
— | Speech rate -50–100(0=默认, 100=2x, -50=0.5x;百炼线性映射 rate) |
--loudness |
— | Loudness -50–100(0=默认;百炼映射 volume) |
--context-text |
— | 情感/风格控制上下文(火山 context_texts;百炼 instruction) |
--output |
— | Exact output file path under assets/audio, tmp, output_videos, fragments, or <platform>/outputs/ |
--out-dir |
./tmp/awk-tts-<ts> |
Output directory under assets/audio, tmp, output_videos, fragments, or <platform>/outputs/ when --output is not set |
--overwrite |
off | Overwrite existing output audio/metadata files |
--no-asr-check |
off | Skip ASR self-check after TTS generation |
--enable-subtitle |
off | 产出 <audio>.subtitle.json 字级时间戳(火山流式原生;百炼 SSE 流式),schema {sentences:[{text, words:[{word,startTime,endTime}]}]}(秒) |
Recommended voices
火山官方 2.0 音色(_uranus_bigtts 后缀,路由到火山时可用):
| Speaker ID | 名称 | 场景 |
|---|---|---|
zh_female_shuangkuaisisi_uranus_bigtts |
爽快思思 2.0 ⭐火山默认 | 通用 |
zh_female_cancan_uranus_bigtts |
知性灿灿 2.0 | 角色扮演 |
zh_female_tianmeixiaoyuan_uranus_bigtts |
甜美小源 2.0 | 通用 |
zh_female_vv_uranus_bigtts |
Vivi 2.0 | 多语种通用(中/日/印尼/墨西哥西语) |
zh_female_xiaohe_uranus_bigtts |
小何 2.0 | 通用 |
zh_female_kefunvsheng_uranus_bigtts |
暖阳女声 2.0 | 客服 |
zh_male_m191_uranus_bigtts |
舟 2.0 | 通用男声 |
zh_male_taocheng_uranus_bigtts |
小天 2.0 | 通用男声 |
en_female_dacey_uranus_bigtts |
Dacey | 多语种(英) |
en_male_tim_uranus_bigtts |
Tim | 多语种(英) |
克隆音色(
S_xxx开头)走seed-icl-2.0资源 ID,脚本自动路由,需model_type=4(脚本自动加)。仅火山模式有效。
百炼 Qwen-Audio-TTS 系统音色(路由到百炼时可用)。音色与模型绑定:显式指定音色时同时指定匹配的 --model,不要跨模型混用音色。
qwen-audio-3.1-tts-plus(业务空间默认)使用 longanlingxin_v3.1(龙安灵心_v3.1)。
qwen-audio-3.1-tts-flash 系统音色(百炼业务空间):
| voice 参数 | 名称 | 性别 |
|---|---|---|
longanhuan_v3.1 |
龙安欢_v3.1(3.1 Flash 默认) | 女 |
longanlingxin_v3.1 |
龙安灵心_v3.1 | 女 |
longanfengyue_v3.1 |
龙安风悦_v3.1 | 女 |
xunanchuan_v3.1 |
许南川 | 男 |
awk-tts --platform workspace --model qwen-audio-3.1-tts-flash --text "大家好,今天我们讲清楚一个问题。"
qwen-audio-3.0-tts-plus 系统音色:
| voice 参数 | 名称 | 特质(性别/年龄) | 场景 |
|---|---|---|---|
longanlingxin |
龙安灵心 | 知心温暖音(女/25) | 社交陪伴·旗舰 |
longanlufeng |
龙安鲁风 | 明亮开朗音(男/25) | 社交陪伴·旗舰 |
qwen-audio-3.0-tts-flash 系统音色(该模型默认 longanhuan_v3.6):
| voice 参数 | 名称 | 特质(性别/年龄) | 场景 |
|---|---|---|---|
longanhuan_v3.6 |
龙安欢 | 3.0 Flash 默认(女/25) | 通用 |
longanfengyue |
龙安风悦 | 自然亲切音(女/30) | 社交陪伴 |
longanlingxi |
龙安灵希 | 可爱甜美音(女/25) | 社交陪伴 |
longanxiaoxin |
龙安小昕 | 亲切活泼音(女/22) | 社交陪伴 |
longanyuanfei |
龙安元妃 | 高傲妃子音(女/30) | 社交陪伴 |
longjielidou_v3.6 |
龙杰力豆 | 天真男童(男/5) | 儿童陪伴/智能玩具 |
longpaopao_v3.6 |
龙泡泡 | 软糯可爱音(女/5) | 儿童陪伴/智能玩具 |
longhuohuo_v3.6 |
龙火火 | 顽皮少年音(男/8) | 角色音/游戏 |
longchuanshu_v3.6 |
龙川叔 | 川普大叔音(男/40) | 角色音/游戏 |
loongmary |
loongmary | 温暖英音(女/20) | 精品英文(仅英文) |
loongeva_v3.6 |
loongeva | 高智美音(女/28) | 精品英文(仅英文) |
loongjohn |
loongJohn | 沉稳亲切美音(男/28) | 精品英文(仅英文) |
语言范围:除
loong*三款纯英文外均为中文(普通话)+英文;text超出音色语言范围会发音错误或语音不自然。 3.0 Plus 默认音色为longanlingxin,3.0 Flash 默认音色为longanhuan_v3.6;其他音色须按模型对齐。遇到InvalidParameter时核对--voice与--model,不要将音色错误当成模型未开通。 两模型另各有 500+ 声音复刻基础音色,命名qwen-audio-3.0-tts-{plus|flash}-{后缀},--voice直传即可,完整列表见官方音色列表页 Excel;也可用声音复刻免费定制专属音色。
Output
音频先在临时文件中验证非空、音轨可完整解码、时长大于0,再替换目标文件;验证失败不会发布假成功音频或覆盖原产物。百炼 SSE 优先下载同次请求末尾的完整音频 URL,亦支持完成事件后的 audio.data 分片及网关返回 JSON 的情况;不重新提交合成。缺少字级时间码时明确 subtitle_unavailable,不生成空字幕文件;用 expert-video 的 video-producer narration-align 对已生成音频做公共 ASR。不要通过换音色恢复。
- Audio file:
speech.<format>或--output指定路径 - Metadata file:
speech.json(同目录),含:provider:volcengine-openspeech-v3/bailian-workspace/bailian-agent-plan- 火山:
resource_id;百炼:model(实际使用的候选链模型) speaker/format/text_chars/audio_bytes/duration/file
--enable-subtitle时另出speech.subtitle.json(字级时间戳,秒;narration-align 优先消费此文件)
Fragment 工作流模式下,脚本读 tts_requirement.md、抽 ## 配音文案 / ## Voiceover Text 段、读音色/语速设置、直接写到 fragment 的 artifacts/ 目录。脚本合成时跳过 markdown heading、注释、音色设置行。
ASR Self-Check
合成后自动跑 ASR 自检(除非 --no-asr-check):
- 复用公共
skills/_shared/asr.py:火山录音文件极速版(VOLC_ASR_*在即启用)→ 百炼业务空间 → Agent Plan,某家失败继续尝试下一家。业务空间模型按qwen-audio-3.1-asr-flash→qwen-audio-3.0-asr-flash尝试,Plan 保留qwen-audio-3.0-asr-flash。BAILIAN_ASR_MODEL显式指定后关闭百炼模型回退。 - 清洗标点空白后做序敏感相似度比对(中英文统一)
- 阈值 0.5——实测 0.5 已够实用质量;过高阈值会假阴性
- 结果打印
PASS/WARN,不 abort
ASR 凭据全部未配置时跳过自检;全部后端失败时打印警告,不影响已生成音频。
Environment Variables
| Variable | Description |
|---|---|
VOLC_TTS_APP_ID + VOLC_TTS_ACCESS_KEY |
火山旧控制台双头鉴权(优先) |
VOLC_TTS_APP_KEY |
火山新控制台单头鉴权 |
VOLC_TTS_API_BASE |
Optional 火山 API base override,默认 https://openspeech.bytedance.com/api/v3 |
VOLC_TTS_RESOURCE_ID |
Optional 火山资源 ID override,默认 seed-tts-2.0(按 speaker 特征自动路由) |
WORKSPACE_ID + MODELSTUDIO_API_KEY/DASHSCOPE_API_KEY |
百炼业务空间(火山凭据缺失时启用) |
AWK_API_KEY |
百炼 agent plan(token-plan 端点;业务空间凭据也缺失时启用) |
VOLC_ASR_APP_ID + VOLC_ASR_ACCESS_KEY / VOLC_ASR_APP_KEY |
ASR 自检火山凭据 |
VOLC_ASR_RESOURCE_ID |
Optional ASR 资源 ID override,默认 volc.bigasr.auc_turbo |
BAILIAN_ASR_MODEL |
Optional 百炼 ASR 模型 override;设置后关闭模型回退。业务空间默认 3.1 Flash → 3.0 Flash,Plan 默认 3.0 Flash |
声音复刻与音色设计
使用同一默认凭据顺序:火山 → 百炼业务空间 → 百炼 Agent Plan。可用 --platform volc|workspace|agent-plan 指定;凭据选路后不因错误静默跨供应商创建另一个音色。Agent Plan 的 customization 权限由套餐决定,返回不支持时使用已开通的业务空间,不宣称所有套餐都支持创建音色。
音色必须保存为 voice.json 并在后续 TTS 传 --voice-profile:档案绑定供应商、业务空间/APP、模型和音色,不再按环境重选供应商,也不沿通用模型链切换。常规 TTS 不传档案时仍保持原候选链。
创建与试听
# 默认按凭据选路;火山必须指定已购的空闲 S_ 槽位
awk-tts voice-design --speaker-id S_EXAMPLE --description "成年男性,中音温暖自然,普通话清晰,适合知识讲解" --preview-text "大家好,今天我们用三张图,讲清楚一个复杂的问题。" --out-dir /absolute/voices/design
awk-tts voice-clone --speaker-id S_EXAMPLE --audio /absolute/authorized-sample.wav --out-dir /absolute/voices/clone
# 显式在百炼业务空间创建;无需火山槽位
awk-tts voice-design --platform workspace --name narrator --description "温暖自然的成年男性,语速适中,日常聊天感" --preview-text "大家好,今天我们用三张图,讲清楚一个复杂的问题。" --out-dir /absolute/voices/bailian-design
awk-tts voice-clone --platform workspace --name narrator --audio /absolute/authorized-sample.wav --out-dir /absolute/voices/bailian-clone
# 查询已创建音色;失败/超时后先查,不盲目重复创建
awk-tts voice-status --profile /absolute/voices/clone/voice.json --wait 60
awk-tts voice-list --platform workspace --prefix narrator
# 用绑定音色合成,自动保持供应商和模型一致
awk-tts --voice-profile /absolute/voices/clone/voice.json --text-file /absolute/voiceover.md --output /absolute/narration.wav --format wav --enable-subtitle
- 火山复刻/设计使用现有
VOLC_TTS_APP_ID+VOLC_TTS_ACCESS_KEY或VOLC_TTS_APP_KEY,不是VOLC_SEEDANCE_API_KEY。旧鉴权在音色接口用X-Api-App-Key,在合成接口用X-Api-App-Id。--speaker-id也可由VOLC_TTS_SPEAKER_ID配置。使用确认可覆盖的音色槽位;工具不购买槽位、不自动启用后付费自定义 ID。 - 火山文本设计描述最多200字,试听文本最多300字;当前 CLI 提供文本设计。设计/复刻通过后用
seed-icl-2.0合成,新版训练返回的 model_type=5 会保存在档案并在合成时使用。 - 百炼使用
voice-enrollment,业务空间默认绑定qwen-audio-3.1-tts-plus,Plan 默认仍为qwen-audio-3.0-tts-plus;也可显式指定支持的--target-model。--name1–10位英文字母/数字;描述1–500字符,试听文本15–200字符。 - 复刻 CLI 接收10–20秒、<10MB的 WAV/MP3/M4A 清晰单人音频,样本使用本人或有授权的声音;提供文件或 HTTP(S) URL 均可。火山直接传 Base64;百炼使用模型绑定的临时上传。URL 会先下载校验,确保上传的是已核验样本。
voice-design保存试听文件,voice-clone保存音色档案;火山返回试听 URL 时立即下载。只有远端状态可用才将档案标为 OK;创建状态不确定时保留记录,先查询,勿自动重复消耗创建/训练次数。- 试听确认清晰度、音色、语气后再用于全稿。复刻声与设计声均是合成声音,不能承诺等同真人原录音或保证通过平台检测。deck-talk 已有用户原录音时优先原声,不主动替换。
- 输出文件已存在即停止,换目录创建新音色;不会覆盖现有档案。程序不修改
~/.openclaw/.env。