MohZhuang
0d74a1097d
流水线开跑前先问用户用哪个 TTS。两引擎产出的 audio-manifest.json
结构完全一致，故 timeline_build / subs / 渲染器零改动。
新增
- scripts/tts_volcano.py 接口包，唯一读 tts.env 的地方。零第三方依赖
（只用标准库 urllib），HTTP Chunked 单向流式，
与 edge-tts「发一次收一串」形态同构
- scripts/tts_setup.py 向导：选方案 → 配密钥 → 测连接 → 选音色，
输出 NEXT_ACTION=… 供智能体识别
- tts.env.example 密钥模板（真实 tts.env 已 gitignore）
- references/volcano-tts.md 密钥纪律 / 配置步骤 / 接口规格 / 音色表 / 排查表
安全
- Key 只存 tts.env，只有 tts_volcano.py 读它；异常过脱敏，只抹本次实际
加载的密钥值与 AKLT… 形态，刻意不用「长字符串即密钥」的宽规则
- check_integrity.py 新增密钥防线检查（含「疑似把模板改名」提示）
- package_skill.py 排除 .env / .key / .pem，修掉一个真实外泄口
修复（真机联调暴露，均只在实跑时复现）
- enable_subtitle 必须显式开启，否则 words 恒为空数组且完全不报错，
下游会静默退回按字数插值、字幕开始飘
- usage 挂在结束标记那一行，提前 continue 导致计费恒为 0
- 缓存未存首裁量，命中缓存时 lead_cut_sec=0，重跑字幕比首跑晚一帧
- CLI 把中文音色名原样当 speaker 发出，服务端报 resource ID mismatched
文档
- README 中英双语新增「配音：两个引擎」章节，按用户要求不写命令
（那是智能体的职责），只讲「会问你什么 / 你唯一要动手的地方」
- 疑难排查补 6 条火山症状；lessons 34 → 56 条；流水线图加 tts_setup 节点
599 lines
26 KiB
Python
599 lines
26 KiB
Python
#!/usr/bin/env python
|
||
# -*- coding: utf-8 -*-
|
||
"""
|
||
tts_volcano.py —— 火山引擎（豆包）语音合成 2.0 接口包。
|
||
|
||
【为什么单独成一个包】密钥只在这一个文件里被读取，调用方（含 AI agent）
|
||
只传「文本 + 音色 + 语速」，永远拿不到也不需要密钥值。本包保证：
|
||
|
||
★ 不打印、不记录、不回显密钥；异常信息一律脱敏（见 _redact）。
|
||
★ 不把密钥写进任何文件；只读 tts.env，从不写 tts.env。
|
||
★ 上游返回体里也没有密钥，缓存与 manifest 里也不会出现密钥。
|
||
→ agent 只需要会调用本包，不需要（也不应该）读 tts.env。
|
||
|
||
【接口】与 tts_build.py 的 edge 引擎同构，下游 timing 逻辑零改动：
|
||
synthesize(text, voice, rate=0, ...) -> {
|
||
"audio": bytes, # mp3 字节
|
||
"boundaries": [{"text","offset_sec","duration_sec"}], # 原始坐标系
|
||
"usage": {"text_words": int} | {},
|
||
"requests": int, # 实际请求数（长文本会切分）
|
||
}
|
||
★ boundaries 的时间单位是**秒**，坐标系 = 返回音频的起点，
|
||
与 edge-tts 的 WordBoundary 语义一致（下游 subs.py 按 offset_sec - lead_cut 平移）。
|
||
|
||
【接口规格】（2026-09 核对官方文档）
|
||
POST https://openspeech.bytedance.com/api/v3/tts/unidirectional
|
||
Header: X-Api-Key（必选）/ X-Api-Resource-Id（必选，TTS2.0 = seed-tts-2.0）
|
||
/ X-Api-Request-Id（必选，uuid）/ Content-Type: application/json
|
||
Body: {user:{uid}, req_params:{text, speaker, audio_params:{format,sample_rate,bit_rate,speech_rate}}}
|
||
响应: NDJSON，逐行 JSON；音频块 code=0 + data(base64)；
|
||
**sentence.words[] 直接给字级时间戳**（word / startTime / endTime / confidence，单位秒）；
|
||
结束标记 code=20000000 且 data=null（★ 不是 code=0，误判会丢最后一段音频）。
|
||
|
||
【本机注意】openspeech.bytedance.com 是境内端点，默认**绕过系统代理**直连
|
||
（本机常驻代理会让境内域名绕远甚至失败）。要强制走代理时设 VOLC_PROXY。
|
||
|
||
用法：
|
||
python tts_volcano.py --check # 连通性自检（用一句话试合成）
|
||
python tts_volcano.py --voices # 列出内置常用音色
|
||
python tts_volcano.py --synth "测试文本" out.mp3 # 手动合成一段
|
||
python tts_volcano.py --env-file <路径> ... # 指定 tts.env（默认自动探测）
|
||
被 tts_build.py 作为库调用（provider=volcano 时）。
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import base64
|
||
import json
|
||
import os
|
||
import re
|
||
import sys
|
||
import time
|
||
import urllib.error
|
||
import urllib.request
|
||
import uuid
|
||
|
||
ENDPOINT = "https://openspeech.bytedance.com/api/v3/tts/unidirectional"
|
||
DEFAULT_RESOURCE_ID = "seed-tts-2.0" # TTS 2.0 预置音色
|
||
CLONE_RESOURCE_ID = "seed-icl-2.0" # 声音复刻音色
|
||
END_CODE = 20000000 # ★ 结束标记；不是 0
|
||
MAX_TEXT_LEN = 200 # 单请求文本上限（超了按标点切分）
|
||
DEFAULT_TIMEOUT = 60.0
|
||
DEFAULT_RETRIES = 3
|
||
RETRY_SLEEP = 1.0
|
||
|
||
# 音色 ID 末尾都是 _uranus_bigtts = 豆包语音合成模型 2.0
|
||
DEFAULT_VOICE = "zh_male_m191_uranus_bigtts" # 云舟 2.0
|
||
ENV_FILENAME = "tts.env"
|
||
|
||
# 内置常用音色（名称, voice_type, 说明）。完整列表见官方音色文档。
|
||
VOICES: list[tuple[str, str, str]] = [
|
||
# —— 男声：解说 / 通用 ——
|
||
("云舟 2.0", "zh_male_m191_uranus_bigtts", "男声 · 沉稳通用（默认，最稳）"),
|
||
("温暖阿虎 2.0", "zh_male_wennuanahu_uranus_bigtts", "男声 · 温暖"),
|
||
("解说小明 2.0", "zh_male_jieshuoxiaoming_uranus_bigtts", "男声 · 解说"),
|
||
("磁性解说男声 2.0", "zh_male_cixingjieshuonan_uranus_bigtts", "男声 · 磁性解说"),
|
||
("悬疑解说 2.0", "zh_male_xuanyijieshuo_uranus_bigtts", "男声 · 悬疑叙事"),
|
||
("广告解说 2.0", "zh_male_guanggaojieshuo_uranus_bigtts", "男声 · 广告调"),
|
||
("儒雅青年 2.0", "zh_male_ruyaqingnian_uranus_bigtts", "男声 · 青年儒雅"),
|
||
("少年梓辛 2.0", "zh_male_shaonianzixin_uranus_bigtts", "男声 · 少年"),
|
||
# —— 女声 ——
|
||
("小何 2.0", "zh_female_xiaohe_uranus_bigtts", "女声 · 通用（默认女声）"),
|
||
("Vivi 2.0", "zh_female_vv_uranus_bigtts", "女声 · 活泼通用"),
|
||
("知性灿灿 2.0", "zh_female_cancan_uranus_bigtts", "女声 · 知性"),
|
||
("甜美桃子 2.0", "zh_female_tianmeitaozi_uranus_bigtts", "女声 · 甜美"),
|
||
("邻家女孩 2.0", "zh_female_linjianvhai_uranus_bigtts", "女声 · 邻家"),
|
||
("温柔淑女 2.0", "zh_female_wenroushunv_uranus_bigtts", "女声 · 温柔"),
|
||
("深夜播客 2.0", "zh_male_shenyeboke_uranus_bigtts", "男声 · 深夜播客/低语"),
|
||
# —— 英文 ——
|
||
("Tim", "en_male_tim_uranus_bigtts", "美式英语 · 男声"),
|
||
("Dacey", "en_female_dacey_uranus_bigtts", "美式英语 · 女声"),
|
||
]
|
||
|
||
VOICE_BY_NAME = {name: vid for name, vid, _ in VOICES}
|
||
VOICE_IDS = {vid for _, vid, _ in VOICES}
|
||
|
||
|
||
def resolve_voice_token(token: str, default: str = "") -> str:
|
||
"""把「名称 / 序号 / 原始 ID」统一成音色 ID。空 token → default。
|
||
|
||
必需：speaker 字段只认 ID。直接传中文显示名会被服务端拒掉，
|
||
报的还是 `55000000 resource ID is mismatched with speaker related resource`
|
||
这种看不出是「名字没解析」的错误。
|
||
"""
|
||
token = (token or "").strip()
|
||
if not token:
|
||
return default or DEFAULT_VOICE
|
||
if token.isdigit() and 1 <= int(token) <= len(VOICES):
|
||
return VOICES[int(token) - 1][1]
|
||
if token in VOICE_BY_NAME:
|
||
return VOICE_BY_NAME[token]
|
||
if token in VOICE_IDS:
|
||
return token
|
||
for name, vid, _ in VOICES: # 允许带括注的名字，如「云舟 2.0（默认）」
|
||
if name.startswith(token) or token.startswith(name):
|
||
return vid
|
||
return token # 自定义 ID（如复刻音色）原样返回
|
||
|
||
|
||
def parse_rate_percent(value) -> int:
|
||
"""把各种语速写法统一成整数百分比：'+8%' / '8' / 0.08 / 8 → 8。
|
||
|
||
火山 `speech_rate` 与 edge `rate` 语义相同（都表示「快百分之几」），
|
||
只是表示法不同：火山要 int，edge 要 '+N%' 字符串。
|
||
两个下游脚本共用这一个换算，避免各写一份慢慢跑偏。
|
||
"""
|
||
if isinstance(value, bool) or value is None or value == "":
|
||
return 0
|
||
if isinstance(value, (int, float)):
|
||
v = float(value)
|
||
return int(round(v * 100 if abs(v) <= 1.5 else v))
|
||
m = re.search(r"([-+]?\d+(?:\.\d+)?)", str(value))
|
||
if not m:
|
||
return 0
|
||
v = float(m.group(1))
|
||
if "%" in str(value):
|
||
return int(round(v))
|
||
return int(round(v * 100 if abs(v) <= 1.5 else v))
|
||
|
||
# 形如 AKLT... 的火山 AccessKey —— 只认这种明确形态，避免把普通 request-id 也抹掉
|
||
_SECRET_PAT = re.compile(r"AKLT[A-Za-z0-9_\-]{6,}")
|
||
|
||
|
||
class VolcanoTTSConfigError(RuntimeError):
|
||
"""缺 tts.env 或字段不全 —— 由 tts_setup.py 负责引导用户补齐。"""
|
||
|
||
|
||
class VolcanoTTSError(RuntimeError):
|
||
"""调用失败（已脱敏，可安全打印）。
|
||
|
||
retryable=False 表示**重试没有意义**（密钥错、音色 ID 错、参数错这类 4xx）。
|
||
退避重试只对网络抖动、超时、5xx、429 有意义 —— 对 401 重试三次只是白等两轮。
|
||
"""
|
||
|
||
def __init__(self, message: str, retryable: bool = True):
|
||
super().__init__(message)
|
||
self.retryable = retryable
|
||
|
||
|
||
# ---------------------------------------------------------------- 密钥读取
|
||
def _skill_root() -> str:
|
||
return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||
|
||
|
||
def env_candidates(project_dir: str = "") -> list[str]:
|
||
"""tts.env 探测顺序：显式指定 → 项目目录 → 技能目录 → 用户目录。"""
|
||
out: list[str] = []
|
||
explicit = os.environ.get("TTS_ENV_FILE", "").strip()
|
||
if explicit:
|
||
out.append(explicit)
|
||
if project_dir:
|
||
out.append(os.path.join(os.path.abspath(project_dir), ENV_FILENAME))
|
||
out.append(os.path.join(_skill_root(), ENV_FILENAME))
|
||
out.append(os.path.join(os.path.expanduser("~"), ".workbuddy", ENV_FILENAME))
|
||
seen, uniq = set(), []
|
||
for p in out:
|
||
if p not in seen:
|
||
seen.add(p)
|
||
uniq.append(p)
|
||
return uniq
|
||
|
||
|
||
def find_env_file(project_dir: str = "") -> str:
|
||
for p in env_candidates(project_dir):
|
||
if os.path.isfile(p):
|
||
return p
|
||
return ""
|
||
|
||
|
||
def parse_env(path: str) -> dict[str, str]:
|
||
"""极简 KEY=VALUE 解析（与 python-dotenv 兼容的最小子集），不执行任何代码。"""
|
||
vals: dict[str, str] = {}
|
||
with open(path, encoding="utf-8-sig") as f:
|
||
for raw in f:
|
||
line = raw.strip()
|
||
if not line or line.startswith("#") or "=" not in line:
|
||
continue
|
||
k, v = line.split("=", 1)
|
||
k, v = k.strip(), v.strip()
|
||
if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
|
||
v = v[1:-1]
|
||
vals[k] = v
|
||
return vals
|
||
|
||
|
||
def load_credentials(project_dir: str = "") -> dict[str, str]:
|
||
"""读取密钥。返回的 dict 里含密钥，**调用方不得打印或落盘**。"""
|
||
path = find_env_file(project_dir)
|
||
if not path:
|
||
raise VolcanoTTSConfigError(
|
||
"没有找到 tts.env。跑到项目根目录执行：python <skill>/scripts/tts_setup.py\n"
|
||
"（它会生成一份带注释的空模板，你手工填入 API Key 即可。）")
|
||
vals = parse_env(path)
|
||
api_key = vals.get("VOLC_API_KEY", "").strip()
|
||
app_id = vals.get("VOLC_APP_ID", "").strip()
|
||
access_key = vals.get("VOLC_ACCESS_KEY", "").strip()
|
||
if not api_key and not (app_id and access_key):
|
||
raise VolcanoTTSConfigError(
|
||
f"{path} 里还没有填密钥。请打开该文件填入 VOLC_API_KEY 后告诉我，我来测连接。\n"
|
||
" API Key 获取：火山引擎控制台 → 语音技术 → API Key 管理\n"
|
||
" https://console.volcengine.com/speech/new/setting/apikeys")
|
||
return {
|
||
"path": path,
|
||
"api_key": api_key,
|
||
"app_id": app_id,
|
||
"access_key": access_key,
|
||
"resource_id": vals.get("VOLC_RESOURCE_ID", "").strip() or DEFAULT_RESOURCE_ID,
|
||
}
|
||
|
||
|
||
def describe_env(project_dir: str = "") -> dict[str, str]:
|
||
"""给 agent/用户看的**脱敏**状态摘要 —— 这个函数的输出可以安全打印。"""
|
||
try:
|
||
c = load_credentials(project_dir)
|
||
except VolcanoTTSConfigError as e:
|
||
return {"status": "missing", "detail": str(e).splitlines()[0]}
|
||
mode = "X-Api-Key" if c["api_key"] else "X-Api-App-Id + X-Api-Access-Key"
|
||
return {
|
||
"status": "ok",
|
||
"env_file": c["path"],
|
||
"auth": mode,
|
||
"key_masked": _mask(c["api_key"] or c["access_key"]),
|
||
"resource_id": c["resource_id"],
|
||
}
|
||
|
||
|
||
def _mask(secret: str) -> str:
|
||
if not secret:
|
||
return "(未设置)"
|
||
if len(secret) <= 8:
|
||
return "*" * len(secret)
|
||
return f"{secret[:4]}{'*' * 6}{secret[-4:]}（长度 {len(secret)}）"
|
||
|
||
|
||
def _redact(text: str) -> str:
|
||
"""把可能混进错误信息的密钥抹掉。异常与日志一律过这一层。
|
||
|
||
只做两件事：抹掉**本次实际加载的**密钥值，以及 AKLT 形态的 token。
|
||
刻意不用「长字符串就当密钥」这种宽规则 —— 那会把 reqid、logid 一起抹掉，
|
||
排查问题时就看不到定位线索了（而密钥只可能从下面这两个来源进入输出）。
|
||
"""
|
||
try:
|
||
c = load_credentials("")
|
||
for k in ("api_key", "access_key"):
|
||
v = c.get(k) or ""
|
||
if len(v) >= 8 and v in text:
|
||
text = text.replace(v, _mask(v))
|
||
except Exception:
|
||
pass
|
||
return _SECRET_PAT.sub(lambda m: _mask(m.group(0)), text)
|
||
|
||
|
||
# ---------------------------------------------------------------- 请求构造
|
||
def _headers(cred: dict[str, str]) -> dict[str, str]:
|
||
h = {
|
||
"Content-Type": "application/json",
|
||
"Accept-Encoding": "identity", # 不要 gzip，NDJSON 逐行读
|
||
"X-Api-Resource-Id": cred["resource_id"],
|
||
"X-Api-Request-Id": str(uuid.uuid4()),
|
||
# 不加这个头，响应里就没有 usage.text_words（计费字数恒为 0）
|
||
"X-Control-Require-Usage-Tokens-Return": "*",
|
||
}
|
||
if cred["api_key"]:
|
||
h["X-Api-Key"] = cred["api_key"]
|
||
else: # 旧版鉴权兜底
|
||
h["X-Api-App-Id"] = cred["app_id"]
|
||
h["X-Api-Access-Key"] = cred["access_key"]
|
||
return h
|
||
|
||
|
||
def _opener() -> urllib.request.OpenerDirector:
|
||
"""默认不走代理：境内端点直连更快更稳；需要时用 VOLC_PROXY 显式指定。"""
|
||
proxy = os.environ.get("VOLC_PROXY", "").strip()
|
||
if proxy:
|
||
return urllib.request.build_opener(
|
||
urllib.request.ProxyHandler({"http": proxy, "https": proxy}))
|
||
return urllib.request.build_opener(urllib.request.ProxyHandler({}))
|
||
|
||
|
||
def split_long_text(text: str, limit: int = MAX_TEXT_LEN) -> list[str]:
|
||
"""按标点切分到 <=limit 字，保证不把一个词从中间劈开。"""
|
||
if len(text) <= limit:
|
||
return [text]
|
||
parts = re.split(r"(?<=[。！？；，、,.!?;：:\n])", text)
|
||
out: list[str] = []
|
||
for p in parts:
|
||
if not p:
|
||
continue
|
||
if len(p) <= limit and (not out or len(out[-1]) + len(p) > limit):
|
||
out.append(p)
|
||
elif len(p) <= limit:
|
||
out[-1] += p
|
||
else: # 单句仍超长 → 硬切
|
||
for i in range(0, len(p), limit):
|
||
out.append(p[i:i + limit])
|
||
return [s for s in out if s.strip()] or [text]
|
||
|
||
|
||
def _one_request(text: str, voice: str, cred: dict[str, str], rate: int,
|
||
fmt: str, sample_rate: int, bit_rate: int,
|
||
timeout: float, enable_subtitle: bool = True,
|
||
context_texts: list[str] | None = None,
|
||
uid: str = "") -> tuple[bytes, list[dict], dict]:
|
||
"""单次请求 → (mp3 字节, boundaries, usage)。"""
|
||
audio_params: dict = {"format": fmt, "sample_rate": sample_rate}
|
||
if fmt == "mp3" and bit_rate:
|
||
audio_params["bit_rate"] = bit_rate
|
||
# ★ 不传这个开关，响应里的 sentence.words 恒为空数组 —— 字级时间戳拿不到。
|
||
# 实测（2026-09-23）：同文本 false→words=0，true→words=10。
|
||
# 官方文档示例里默认带词时间戳，容易让人以为「不用开」，实际必须显式打开。
|
||
# 仅豆包语音合成大模型 2.0 音色、仅中英文语种支持。
|
||
if enable_subtitle:
|
||
audio_params["enable_subtitle"] = True
|
||
if rate:
|
||
audio_params["speech_rate"] = int(rate) # [-50,100] → 0.5x~2.0x
|
||
|
||
req_params: dict = {"text": text, "speaker": voice, "audio_params": audio_params}
|
||
if context_texts:
|
||
req_params["context_texts"] = list(context_texts)
|
||
body = {"user": {"uid": uid or f"html-explainer-{uuid.uuid4().hex[:12]}"},
|
||
"req_params": req_params}
|
||
|
||
req = urllib.request.Request(
|
||
ENDPOINT, data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
|
||
headers=_headers(cred), method="POST")
|
||
|
||
chunks: list[bytes] = []
|
||
boundaries: list[dict] = []
|
||
usage: dict = {}
|
||
try:
|
||
with _opener().open(req, timeout=timeout) as resp:
|
||
for raw in resp: # NDJSON：逐行
|
||
line = raw.strip()
|
||
if not line:
|
||
continue
|
||
try:
|
||
obj = json.loads(line.decode("utf-8"))
|
||
except Exception:
|
||
continue
|
||
code = obj.get("code")
|
||
data = obj.get("data")
|
||
# ★ usage 挂在**结束行**上（code=20000000、data=null 那一行）。
|
||
# 先判结束标记再读 usage，会把计费字数永远读成 0（踩过）。
|
||
if obj.get("usage"):
|
||
usage = obj["usage"]
|
||
if code == END_CODE: # ★ 结束标记，且不含音频
|
||
continue
|
||
if code not in (0, None):
|
||
raise VolcanoTTSError(
|
||
f"接口返回 code={code} message={obj.get('message')!r}")
|
||
if data:
|
||
try:
|
||
chunks.append(base64.b64decode(data))
|
||
except Exception:
|
||
raise VolcanoTTSError("音频块 base64 解码失败（流可能被截断）")
|
||
sent = obj.get("sentence") or {}
|
||
for w in (sent.get("words") or []):
|
||
txt = (w.get("word") or "").strip()
|
||
if not txt:
|
||
continue
|
||
st = float(w.get("startTime") or 0.0)
|
||
et = float(w.get("endTime") or st)
|
||
boundaries.append({
|
||
"text": txt,
|
||
"offset_sec": round(st, 4),
|
||
"duration_sec": round(max(0.0, et - st), 4),
|
||
})
|
||
except urllib.error.HTTPError as e:
|
||
detail = ""
|
||
try:
|
||
detail = e.read().decode("utf-8", "replace")[:400]
|
||
except Exception:
|
||
pass
|
||
hint = ""
|
||
# 4xx 基本都是永久性错误（密钥/音色/参数），重试无益；429 与 5xx 才值得重试
|
||
retryable = e.code == 429 or e.code >= 500
|
||
if e.code in (401, 403):
|
||
hint = "\n → 鉴权失败：核对 tts.env 里的 VOLC_API_KEY 是否正确、是否已开通该服务。"
|
||
elif e.code == 404:
|
||
hint = "\n → 音色或资源 ID 不对：预置音色要配 seed-tts-2.0。"
|
||
raise VolcanoTTSError(
|
||
f"HTTP {e.code} {e.reason}{hint}\n {_redact(detail)}", retryable=retryable)
|
||
except urllib.error.URLError as e:
|
||
raise VolcanoTTSError(
|
||
f"网络不可达：{_redact(str(e.reason))}\n"
|
||
" → 本包默认绕过系统代理直连。若你的网络确实需要代理，设 VOLC_PROXY=http://127.0.0.1:<port>。")
|
||
except TimeoutError:
|
||
raise VolcanoTTSError(f"请求超时（{timeout}s）")
|
||
|
||
if not chunks:
|
||
raise VolcanoTTSError("没有收到任何音频块（检查音色 ID 与文本是否为空）")
|
||
return b"".join(chunks), boundaries, usage
|
||
|
||
|
||
def _looks_like_mp3(b: bytes) -> bool:
|
||
if len(b) < 4:
|
||
return False
|
||
head = b[:4].hex()
|
||
return head.startswith("494433") or head.startswith("fff3") or head.startswith("fffb") \
|
||
or head.startswith("fffa") or head.startswith("fff2")
|
||
|
||
|
||
def synthesize(text: str, voice: str = DEFAULT_VOICE, rate: int = 0,
|
||
fmt: str = "mp3", sample_rate: int = 24000, bit_rate: int = 160000,
|
||
timeout: float = DEFAULT_TIMEOUT, retries: int = DEFAULT_RETRIES,
|
||
context_texts: list[str] | None = None,
|
||
project_dir: str = "",
|
||
enable_subtitle: bool = True) -> dict:
|
||
"""合成一段文本 → {audio, boundaries, usage, requests}。失败抛 VolcanoTTSError。
|
||
|
||
enable_subtitle=True（默认）会要求服务端返回字级时间戳。关掉只在
|
||
「音色不支持字幕（非中英文）」时有意义 —— 那种情况下 words 必为空。
|
||
"""
|
||
text = (text or "").strip()
|
||
if not text:
|
||
raise VolcanoTTSError("文本为空")
|
||
cred = load_credentials(project_dir)
|
||
|
||
last: Exception | None = None
|
||
for attempt in range(max(1, retries)):
|
||
try:
|
||
pieces = split_long_text(text)
|
||
audio_all: list[bytes] = []
|
||
bounds_all: list[dict] = []
|
||
usage: dict = {}
|
||
# 长文本切分时，后续片段的词边界要按前面片段的实际时长平移
|
||
for i, piece in enumerate(pieces):
|
||
audio, bounds, u = _one_request(
|
||
piece, voice, cred, rate, fmt, sample_rate, bit_rate,
|
||
timeout, enable_subtitle, context_texts)
|
||
if i:
|
||
offset = _bytes_duration(b"".join(audio_all), fmt)
|
||
bounds = [{**b, "offset_sec": round(b["offset_sec"] + offset, 4)}
|
||
for b in bounds]
|
||
audio_all.append(audio)
|
||
bounds_all.extend(bounds)
|
||
if u:
|
||
usage = u
|
||
audio = b"".join(audio_all)
|
||
if not _looks_like_mp3(audio) and fmt == "mp3":
|
||
raise VolcanoTTSError("返回的音频不是有效 MP3 头（可能被截断）")
|
||
result = {"audio": audio, "boundaries": bounds_all,
|
||
"usage": usage, "requests": len(pieces)}
|
||
# ★ 要了字幕却一个时间戳都没回来 —— 大概率踩到「音色不支持字幕」。
|
||
# 静默放行会让下游字幕整段塌掉，所以这里显式记一条可打印的警告。
|
||
if enable_subtitle and not bounds_all:
|
||
result["warning"] = (
|
||
"未返回字级时间戳（sentence.words 为空）。"
|
||
"该能力仅豆包语音合成大模型 2.0 的中英文音色支持；"
|
||
"当前音色若不支持，字幕将退化为按整段均分——建议换成 zh_*_uranus_bigtts。")
|
||
return result
|
||
except VolcanoTTSConfigError:
|
||
raise
|
||
except VolcanoTTSError as e:
|
||
if not e.retryable:
|
||
raise # 密钥/参数错，重试是白等
|
||
last = e
|
||
if attempt + 1 < max(1, retries):
|
||
time.sleep(RETRY_SLEEP * (attempt + 1))
|
||
except Exception as e: # noqa: BLE001
|
||
last = e
|
||
if attempt + 1 < max(1, retries):
|
||
time.sleep(RETRY_SLEEP * (attempt + 1))
|
||
raise VolcanoTTSError(_redact(f"连续 {retries} 次失败：{type(last).__name__}: {last}"))
|
||
|
||
|
||
def _bytes_duration(data: bytes, fmt: str) -> float:
|
||
"""用 ffmpeg 量已合成字节的时长（长文本切片拼接时算偏移用）。"""
|
||
import subprocess
|
||
import tempfile
|
||
from shutil import which
|
||
ff = which("ffmpeg")
|
||
if not ff:
|
||
try:
|
||
import imageio_ffmpeg
|
||
ff = imageio_ffmpeg.get_ffmpeg_exe()
|
||
except Exception:
|
||
return 0.0
|
||
fd, tmp = tempfile.mkstemp(suffix=f".{fmt}")
|
||
try:
|
||
with os.fdopen(fd, "wb") as f:
|
||
f.write(data)
|
||
r = subprocess.run([ff, "-hide_banner", "-i", tmp],
|
||
capture_output=True, text=True, errors="replace")
|
||
for line in r.stderr.splitlines():
|
||
if "Duration:" in line:
|
||
t = line.split("Duration:")[1].split(",")[0].strip()
|
||
h, m, s = t.split(":")
|
||
return round(int(h) * 3600 + int(m) * 60 + float(s), 3)
|
||
finally:
|
||
try:
|
||
os.remove(tmp)
|
||
except OSError:
|
||
pass
|
||
return 0.0
|
||
|
||
|
||
def check(project_dir: str = "", voice: str = "", timeout: float = 30.0) -> dict:
|
||
"""连通性自检：用一句短文本试合成。返回可安全打印的状态 dict。"""
|
||
try:
|
||
cred = load_credentials(project_dir)
|
||
except VolcanoTTSConfigError as e:
|
||
return {"ok": False, "stage": "env", "detail": str(e)}
|
||
v = resolve_voice_token(voice)
|
||
try:
|
||
r = synthesize("连接测试，这句话只用来验证接口是否可用。",
|
||
voice=v, timeout=timeout, retries=1, project_dir=project_dir)
|
||
return {
|
||
"ok": True, "stage": "api", "voice": v,
|
||
"env_file": cred["path"],
|
||
"key_masked": _mask(cred["api_key"] or cred["access_key"]),
|
||
"resource_id": cred["resource_id"],
|
||
"audio_bytes": len(r["audio"]),
|
||
"boundaries": len(r["boundaries"]),
|
||
"chars_billed": (r.get("usage") or {}).get("text_words", 0),
|
||
}
|
||
except VolcanoTTSError as e:
|
||
return {"ok": False, "stage": "api", "voice": v, "env_file": cred["path"],
|
||
"detail": str(e)}
|
||
|
||
|
||
# ---------------------------------------------------------------- CLI
|
||
def _print_voices() -> None:
|
||
print("内置常用音色（完整列表见官方音色文档）：")
|
||
for i, (name, vid, note) in enumerate(VOICES, 1):
|
||
print(f" {i:>2}. {name:<18} {note}\n {vid}")
|
||
|
||
|
||
def main() -> int:
|
||
p = argparse.ArgumentParser(description="火山引擎语音合成 2.0 接口包")
|
||
p.add_argument("--project", default="", help="项目目录（用于探测 tts.env）")
|
||
p.add_argument("--env-file", default="", help="显式指定 tts.env 路径")
|
||
p.add_argument("--check", action="store_true", help="连通性自检")
|
||
p.add_argument("--voices", action="store_true", help="列出内置音色")
|
||
p.add_argument("--synth", default="", help="合成一段文本")
|
||
p.add_argument("--out", default="volcano_tts_test.mp3")
|
||
p.add_argument("--voice", default="")
|
||
p.add_argument("--rate", type=int, default=0)
|
||
args = p.parse_args()
|
||
|
||
if args.env_file:
|
||
os.environ["TTS_ENV_FILE"] = args.env_file
|
||
|
||
if args.voices:
|
||
_print_voices()
|
||
return 0
|
||
|
||
if args.check:
|
||
st = check(args.project, args.voice)
|
||
if st["ok"]:
|
||
print(f"✓ 连接正常 · 音色 {st['voice']} · 音频 {st['audio_bytes']}B · "
|
||
f"时间戳 {st['boundaries']} 个 · 计费 {st['chars_billed']} 字")
|
||
print(f" tts.env: {st['env_file']}")
|
||
print(f" 密钥: {st['key_masked']} · 资源 {st['resource_id']}")
|
||
return 0
|
||
print(f"✗ 未通过（{st['stage']}）\n{st['detail']}", file=sys.stderr)
|
||
return 1
|
||
|
||
if args.synth:
|
||
try:
|
||
r = synthesize(args.synth, voice=resolve_voice_token(args.voice),
|
||
rate=args.rate, project_dir=args.project)
|
||
except (VolcanoTTSError, VolcanoTTSConfigError) as e:
|
||
print(f"✗ {e}", file=sys.stderr)
|
||
return 1
|
||
with open(args.out, "wb") as f:
|
||
f.write(r["audio"])
|
||
print(f"✓ {args.out} · {len(r['audio'])}B · 时间戳 {len(r['boundaries'])} 个 "
|
||
f"· 请求 {r['requests']} 次")
|
||
if r.get("warning"):
|
||
print(f"⚠ {r['warning']}", file=sys.stderr)
|
||
return 0
|
||
|
||
p.print_help()
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|