feat(v1.3.0): 新增火山引擎语音合成 2.0 作为可选配音引擎
流水线开跑前先问用户用哪个 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 节点
This commit is contained in:
MohZhuang committed
1 parent
09aa089354
commit
0d74a1097d
16 files changed
+1769
-45
No files matched your search
+11
@@ -14,6 +14,17 @@ node_modules/
|
||||
# ---------- Distribution bundles ----------
|
||||
dist/
|
||||
|
||||
# ---------- Secrets ----------
|
||||
# 火山引擎（豆包）TTS 的 API Key 只存在 tts.env 里，永不入库。
|
||||
# ★ 这个文件是密钥的唯一入口；agent 不需要、也不应该读取它 ——
|
||||
# scripts/tts_volcano.py 会自己读。模板见 tts.env.example（那个是入库的）。
|
||||
tts.env
|
||||
*.env
|
||||
!*.env.example
|
||||
secrets/
|
||||
*.key
|
||||
*.pem
|
||||
|
||||
# ---------- Per-project runtime artifacts ----------
|
||||
# html-explainer generates these inside a *video project* directory.
|
||||
# Ignored here so a demo project created inside the repo never gets committed.
|
||||
|
||||
@@ -9,6 +9,87 @@
|
||||
|
||||
---
|
||||
|
||||
## [1.3.0] — 2026-09-23
|
||||
|
||||
### 新增
|
||||
|
||||
- **★ 火山引擎（豆包）语音合成 2.0 作为可选配音引擎。** 原先只有 edge-tts；
|
||||
现在 `tts_build.py --provider edge|volcano`，`project.json` 记 `provider` 字段。
|
||||
两个引擎产出的 `audio-manifest.json` **结构完全一致**（`boundaries` 均为「秒 + 原始坐标系」），
|
||||
因此 `timeline_build.py` / `subs.py` / 渲染器**零改动**。
|
||||
- **`scripts/tts_volcano.py`** —— 火山 TTS 接口包（SDK 层）。走 **HTTP Chunked 单向流式**
|
||||
`POST /api/v3/tts/unidirectional`：与 edge-tts 形态同构（发一次、收一串），
|
||||
故缓存 / 硬超时 / 退避重试 / 裁静音 / 两级时钟全部原样复用。
|
||||
**零第三方依赖**（只用标准库 `urllib`）。`--check` / `--voices` / `--synth` 三个子命令。
|
||||
- **`scripts/tts_setup.py`** —— 配音方案向导：选方案 → 缺密钥则生成 `tts.env` 模板并停下 →
|
||||
测连接 → 选音色 → 写回 `project.json`。输出 `NEXT_ACTION=…` 供 agent 判断下一步。
|
||||
- **`tts.env.example`** —— 密钥模板（入库；真实 `tts.env` 被忽略）。
|
||||
|
||||
### 安全
|
||||
|
||||
- **★ 密钥纪律：agent 不读、仓库不记、日志不吐、分发不含。** 四条都由结构保证：
|
||||
① 密钥只从 `tts.env` 读取，而只有 `tts_volcano.py` 读它 —— agent 只调接口包；
|
||||
② 异常信息过 `_redact()` 脱敏（只抹本次实际加载的密钥值与 `AKLT…` 形态 token，
|
||||
保留 reqid/logid 以便排查）；
|
||||
③ `.gitignore` 新增 `tts.env` / `*.env` / `*.key` / `*.pem` / `secrets/`；
|
||||
④ **`check_integrity.py` 新增「密钥防线」检查**（gitignore 覆盖 + 遍历仓库抓非空密钥赋值与
|
||||
`AKLT…` token，空模板不算违规），CI 在无密钥环境下跑通。
|
||||
- **★ 修掉一个真实的密钥外泄口：`package_skill.py` 原先不排除 `tts.env`** ——
|
||||
技能目录里若放了这个文件，打包会把用户的 API Key 一起塞进可分发的 zip。
|
||||
已加入 `EXCLUDE_NAMES` / `EXCLUDE_SUFFIX`（`tts.env`、`*.env`、`*.key`、`*.pem`），
|
||||
模板 `tts.env.example` 保留。已实测：打包后 zip 内无密钥文件、内容级扫描无密钥串。
|
||||
|
||||
### 修复
|
||||
|
||||
- **`tts_setup.py` 的方案选定后未落盘**：用户选火山 → 生成模板 → 填密钥 → 回来跑 `--check`，
|
||||
此时 `project.json` 还写着 `edge`，会**静默去测 edge 并报「就绪」**。现在方案一旦确定立刻写盘。
|
||||
- `--check` 现在先打印 `测试方案：<provider>`，避免「测的其实不是你以为的那个」。
|
||||
- `ensure_env_file()` 的查找顺序改成与 `tts_volcano.env_candidates()` 一致
|
||||
（项目目录 → 技能目录 → 新建于项目目录），消除「向导认技能目录的、接口包认项目目录的」错位。
|
||||
|
||||
### 修复（首次真机联调后补齐）
|
||||
|
||||
> v1.3.0 在合并前用**真实 API Key** 跑了完整链路（向导 → 真合成 → timeline → subs → 打包），
|
||||
> 又抓出 4 个只看代码发现不了的问题。以下都已修复并实测通过；v1.3.0 此前从未发布，故不另起版本号。
|
||||
|
||||
- **★ 字级时间戳必须显式开 `audio_params.enable_subtitle: true`。** 官方文档的响应示例里
|
||||
`sentence.words[]` 是有值的，容易误以为「默认就给」——**实测不传这个参数 `words` 恒为空数组**
|
||||
（同文本对照：`false` → `words=0`，`true` → `words=10`）。而且它**完全不报错**：音频正常、
|
||||
时长正常、`sentence.text` 也正常。下游 `subs.py` 会静默退回**按字数插值**，成片照样出、
|
||||
字幕开始飘。现已在接口包默认开启，并在拿到音频却没有时间戳时返回 `warning`
|
||||
让 `tts_build.py` 打到台面上。该能力仅豆包 2.0 的中英文音色支持。
|
||||
- **计费字数永远是 0**：`usage.text_words` 挂在**结束标记那一行**（`code=20000000`），
|
||||
而解析循环先判结束标记就 `continue` 了，那一行从没被读完。同时补上
|
||||
`X-Control-Require-Usage-Tokens-Return: *` 请求头（不传该头服务端根本不返回 `usage`）。
|
||||
修后实测：`计费 20 字` 与文本逐字对上。
|
||||
- **★ 命中缓存时丢失首裁量 → 首跑与重跑产出不一致。** 词边界是原始坐标系，下游靠
|
||||
`lead_cut_sec` 平移；缓存只存了边界数组，于是**重跑 `lead_cut_sec=0`、首跑是 0.037**
|
||||
——字幕整体晚一帧，且只在第二次跑时出现。缓存格式改为
|
||||
`{"boundaries": [...], "lead_cut_sec": x}`，并对旧版裸列表格式做兼容读取。
|
||||
- **CLI 把中文音色名原样当 `speaker` 发出去**：`--voice "云舟 2.0"` 被服务端拒绝，
|
||||
报的是 `55000000 resource ID is mismatched with speaker related resource`
|
||||
——完全看不出是「名字没解析」。现把 `resolve_voice_token()`（名称/序号/ID）与
|
||||
`parse_rate_percent()`（`+8%`/`8`/`0.08`）都收进接口包，`tts_setup.py` 改为委托，
|
||||
消除两份实现跑偏的可能。
|
||||
- 火山项目的 `rate` 会沿用 `new_project.py` 写的 edge 格式 `+8%`，现按引擎清洗
|
||||
（火山存 int 百分比）；`--status` 在 `rate=0` 时不再误报「未设置」（`0` 是 falsy）。
|
||||
- `check_integrity.py` 缺模板时新增提示：若同目录存在 `tts.env`，直接说明
|
||||
**「疑似把模板改名成了 tts.env」**（实测踩到的真实用法）。
|
||||
|
||||
### 备注
|
||||
|
||||
- 火山接口的坑已处理并写进文档：**结束标记 `code=20000000`（不是 0，误判会丢最后一段音频）**、
|
||||
单请求文本上限 ~200 字（超了按标点切分并按实际时长平移词边界）、
|
||||
**字级时间戳需显式开 `audio_params.enable_subtitle`**（见上）。
|
||||
- `openspeech.bytedance.com` 是境内端点，接口包**默认绕过系统代理直连**；需要时设 `VOLC_PROXY`。
|
||||
- edge 独有的「相邻数字补逗号」对火山**不启用** —— 它会改动送进去的文本，
|
||||
影响词边界与解说词的逐字对齐，而火山不熔读相邻数字。
|
||||
- 真机联调的验收口径：3 段共 20 块字幕，**每块起点与其首字词边界的误差均为 0.000s**；
|
||||
首跑与缓存重跑的 manifest 深度 diff（982 个字段）完全一致；
|
||||
打包 zip 38 个成员，密钥文件名与内容级扫描**双无命中**。
|
||||
|
||||
---
|
||||
|
||||
## [1.2.3] — 2026-09-22
|
||||
|
||||
### 新增
|
||||
@@ -151,6 +232,7 @@
|
||||
- 23 种画面风格目录，8 个类别，按改编成本分类。
|
||||
- `setup_env.sh` 做首次环境自检，`--install` 装缺失依赖；`package_skill.py` 打可移植 zip。
|
||||
|
||||
[1.3.0]: https://github.com/OneMoh/html-explainer/releases/tag/v1.3.0
|
||||
[1.2.3]: https://github.com/OneMoh/html-explainer/releases/tag/v1.2.3
|
||||
[1.2.2]: https://github.com/OneMoh/html-explainer/releases/tag/v1.2.2
|
||||
[1.2.1]: https://github.com/OneMoh/html-explainer/releases/tag/v1.2.1
|
||||
|
||||
+88
-5
@@ -8,7 +8,7 @@ Write scenes in HTML → deterministic frame-by-frame rendering → a real MP4.
|
||||
locally; the core pipeline needs no API key and charges no per-render fee.
|
||||
|
||||
[](LICENSE)
|
||||
[](CHANGELOG.md)
|
||||
[](CHANGELOG.md)
|
||||
[](SKILL.md)
|
||||
[](#install)
|
||||
[](#install)
|
||||
@@ -107,7 +107,7 @@ exception and only reads `.claude/skills/`.)
|
||||
|
||||
| Item | Minimum | Notes |
|
||||
|---|---|---|
|
||||
| Python | 3.9+ | `edge-tts==7.2.8` (pinned deliberately — v7 changed the boundary API), `numpy`, `pillow`, `imageio-ffmpeg` |
|
||||
| Python | 3.9+ | `edge-tts==7.2.8` (pinned deliberately — v7 changed the boundary API), `numpy`, `pillow`, `imageio-ffmpeg`. **The Volcano engine needs nothing extra** (stdlib `urllib` only, no SDK) |
|
||||
| Node.js | 18+ | Used by the renderer and the cover builder |
|
||||
| Browser | Chrome or Edge | Auto-detected; playwright chromium (~115MB, one time) only if neither exists |
|
||||
| ffmpeg | any version | Looked up on `PATH`; falls back to the static binary bundled with `imageio-ffmpeg` |
|
||||
@@ -117,6 +117,81 @@ exception and only reads `.claude/skills/`.)
|
||||
|
||||
---
|
||||
|
||||
## Voice-over: two engines
|
||||
|
||||
Before the pipeline starts the agent **asks which TTS you want**, then lists candidate voices for
|
||||
you to pick from (or you can just hand it a voice ID):
|
||||
|
||||
| | `edge-tts` | Volcano Engine TTS 2.0 |
|
||||
|---|---|---|
|
||||
| What you do | nothing | paste an API Key once |
|
||||
| Cost | free | billed per character |
|
||||
| Voices | a set of built-in zh/en voices | Doubao 2.0 voice library, incl. voice cloning |
|
||||
| Word timestamps | `WordBoundary` | `sentence.words[]` |
|
||||
| Extra deps | `edge-tts==7.2.8`, `imageio-ffmpeg` | **none** — stdlib `urllib` only |
|
||||
| When to pick it | default; works out of the box | when you want more natural prosody / better quality |
|
||||
|
||||
Both engines emit an **identical** `audio-manifest.json`, so the timeline, the subtitles and the
|
||||
renderer **all stay untouched** — switching engines is a one-field change.
|
||||
|
||||
### With Volcano, the only thing you touch
|
||||
|
||||
The first time it runs Volcano, the skill **creates a `tts.env` and stops**, then tells you to paste
|
||||
your API Key into it (console → Speech → API Key management). Say "done" and the agent tests the
|
||||
connection, confirms the voice, and carries on.
|
||||
|
||||
**That step deliberately bypasses the chat window** — the key is never sent to the agent, and the
|
||||
agent never needs to know it.
|
||||
|
||||
Built-in voices (full list in the
|
||||
[official voice docs](https://docs.volcengine.com/docs/6561/1257544)):
|
||||
|
||||
| Male | Female |
|
||||
|---|---|
|
||||
| Yunzhou 2.0 (default) · Wennuan Ahu 2.0 · Jieshuo Xiaoming 2.0 · Cixing Jieshuo Nan 2.0<br>Xuanyi Jieshuo 2.0 · Guanggao Jieshuo 2.0 · Ruya Qingnian 2.0 · Shaonian Zixin 2.0 · Shenye Boke 2.0 | Xiaohe 2.0 · Vivi 2.0 · Zhixing Cancan 2.0<br>Tianmei Taozi 2.0 · Linjia Nvhai 2.0 · Wenrou Shunv 2.0 |
|
||||
|
||||
If the built-in list is not enough, a voice ID from voice cloning works too.
|
||||
|
||||
### Key discipline
|
||||
|
||||
The API Key lives only in `tts.env`, and **only one interface package inside the skill reads it**.
|
||||
The agent calls that package, so it neither gets nor needs the key value:
|
||||
|
||||
```
|
||||
you (fill it in once) → tts.env (already gitignored)
|
||||
↓ only the interface package reads it
|
||||
synthesis call ← the agent calls this; never sees the key
|
||||
↓
|
||||
Volcano Engine
|
||||
```
|
||||
|
||||
- **Never in the chat**: ask the agent for key status; what comes back is a masked summary
|
||||
(`ef90******86c8`).
|
||||
- **Never in the repo**: `.gitignore` covers `tts.env` / `*.env` / `*.key` / `*.pem` / `secrets/`;
|
||||
the repo self-check has a dedicated **key-defence** rule, itself proven by a negative test —
|
||||
a deliberately planted fake key gets caught.
|
||||
- **Never in logs**: error messages are redacted — only the key value actually used and `AKLT…`
|
||||
tokens are scrubbed. Deliberately **not** a broad "any long string is a secret" rule, which would
|
||||
also erase the request IDs you need for support.
|
||||
- **Never in a distribution**: packaging the skill excludes key files.
|
||||
- **Backstop** (the real security boundary): if it leaks anyway, keep the blast radius small — use
|
||||
a **sub-account with speech-synthesis-only permission**, set **usage alerts and quotas**, and
|
||||
**rotate** the key.
|
||||
|
||||
> Bluntly: the synthesis code runs on your machine, so the key is visible to that process at
|
||||
> runtime — **"the agent can never read it" is not achievable**. What is guaranteed is *not in the
|
||||
> chat, not in the repo, not in the logs, not in the distribution*, which shrinks a leak into one
|
||||
> revocable incident.
|
||||
>
|
||||
> Also **don't store the key in an environment variable** — many hosts dump the process environment
|
||||
> straight into the session transcript.
|
||||
|
||||
**Don't rename `tts.env.example` to `tts.env` and fill that in.** It is the template meant to stay
|
||||
in the repo; renaming it leaves everyone else without one (the repo self-check reports it).
|
||||
Copy it, then fill the copy.
|
||||
|
||||
---
|
||||
|
||||
## Video project layout
|
||||
|
||||
Say one sentence and the agent walks the whole pipeline inside a **video project directory**;
|
||||
@@ -161,7 +236,9 @@ The trade-off: **every animation must be seekable.** Wall-clock animation (`setI
|
||||
| | |
|
||||
|---|---|
|
||||
| **Beats anchored to narration** | Scenes position animation by **matching subtitle text** (`B('block text')`), never by hardcoded frame numbers. Edit the script and the whole video re-times with zero scene-code changes. |
|
||||
| **Word-boundary subtitles** | Timing comes from edge-tts `WordBoundary` events, never interpolated by character count — in Chinese two phrases of equal length can differ 3× in duration. |
|
||||
| **Word-boundary subtitles** | Timing comes from the TTS engine's **character-level timestamps**, never interpolated by character count — in Chinese two phrases of equal length can differ 3× in duration. `WordBoundary` for edge-tts, `sentence.words[]` for Volcano Engine. |
|
||||
| **Two voiceover engines** | `edge-tts` (free, no key, default) or **Volcano Engine TTS 2.0** (better quality, needs an API key). Both emit an identical manifest, so nothing downstream changes — switch with `--provider`. |
|
||||
| **The API key never reaches the agent or the repo** | The Volcano key lives only in `tts.env` (gitignored) and **only the interface package reads it** — the agent calls `tts_volcano.py` and never needs the key. Errors are redacted, `check_integrity.py` enforces a secret guard, and packaging excludes key files. |
|
||||
| **Two-level clock** | Frame length uses MP3 **container duration** (keeps A/V in sync); the final subtitle block ends on **actual speech end**. |
|
||||
| **23 visual styles** | 8 categories, each with its canvas, type scale, timeline and colour discipline recorded. No designing from a blank page. |
|
||||
| **Dual covers** | Every video ships a 16:9 cover plus an **independently re-laid-out** 3:4 cover — not a crop. Cropping loses 57.8% of the width. |
|
||||
@@ -176,7 +253,8 @@ The trade-off: **every animation must be seekable.** Wall-clock animation (`setI
|
||||
flowchart LR
|
||||
A["Topic"] --> B["Research<br/><i>every figure sourced</i>"]
|
||||
B --> C["narration.json<br/><i>pipes split subtitle blocks</i>"]
|
||||
C --> D["tts_build.py<br/><i>edge-tts to MP3 + word boundaries</i>"]
|
||||
C --> S["tts_setup.py<br/><i>ask engine · key · voice</i>"]
|
||||
S --> D["tts_build.py<br/><i>edge-tts / Volcano to MP3 + word boundaries</i>"]
|
||||
D --> E["timeline_build.py<br/><i>global axis + stitched track</i>"]
|
||||
E --> F["subs.py<br/><i>subs.json, srt/vtt, beats.js</i>"]
|
||||
F --> G["frames/*.html<br/><i>one scene per line, styled from the library</i>"]
|
||||
@@ -266,8 +344,13 @@ rules and the pre-upload checklist: [`references/cover-guide.md`](references/cov
|
||||
| Cover renders at 1× | Same trap, `deviceScaleFactor` twin | Pass to `newPage()` + `screenshot({ scale: 'device' })` |
|
||||
| Numbers render but never move | The seek suppressed `onUpdate` callbacks | Renderer fixed (`pause(t, false)`); use a transform-based number reel in scenes |
|
||||
| `No such file or directory` on Windows | Non-ASCII path — Windows ffmpeg reads UTF-8 as ANSI | Keep paths ASCII |
|
||||
| Subtitles drift / land in the wrong place | TTS returned no word timestamps, so `subs.py` fell back to **character-count interpolation** (a single stderr warning) | Check whether `tts_build` printed `⚠ no word timestamps`; switch to a supported voice (zh/en Doubao 2.0) |
|
||||
| Volcano error `resource ID is mismatched with speaker related resource` | `speaker` got a display name instead of a voice ID; or a cloned voice paired with the preset resource ID | Use a built-in voice name/ID (the package resolves it); for cloned voices set `VOLC_RESOURCE_ID=seed-icl-2.0` |
|
||||
| Volcano `HTTP 401/403` | Wrong key in `tts.env`, or the service is not enabled | Verify `VOLC_API_KEY`; check the masked status via `tts_setup.py --status` |
|
||||
| Volcano `network unreachable` | The package **bypasses the system proxy by default** (China-mainland endpoint) | If you really need a proxy, set `VOLC_PROXY=http://127.0.0.1:<port>` |
|
||||
| Subtitles sit one frame late after a re-run | A cache hit dropped the head-trim amount (historical bug, fixed) | Upgrade to v1.3.0+; the cache format now carries `lead_cut_sec` |
|
||||
|
||||
**`references/lessons.md` is the most valuable file in this repository.** 34 numbered entries, each
|
||||
**`references/lessons.md` is the most valuable file in this repository.** 56 numbered entries, each
|
||||
one a bug where "the video looked fine but was wrong" — including how it was misdiagnosed at first.
|
||||
Read it before debugging from scratch.
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
HTML 写画面 → 确定性逐帧渲染 → 真 MP4。全本地跑，核心链路零 API key、零按次计费。
|
||||
|
||||
[](LICENSE)
|
||||
[](CHANGELOG.md)
|
||||
[](CHANGELOG.md)
|
||||
[](SKILL.md)
|
||||
[](#安装)
|
||||
[](#安装)
|
||||
@@ -102,7 +102,7 @@ Windows 上 `~` 就是 `C:\Users\<你的用户名>`。
|
||||
|
||||
| 项 | 最低 | 说明 |
|
||||
|---|---|---|
|
||||
| Python | 3.9+ | `edge-tts==7.2.8`（刻意钉死 —— v7 改过边界 API）、`numpy`、`pillow`、`imageio-ffmpeg` |
|
||||
| Python | 3.9+ | `edge-tts==7.2.8`（刻意钉死 —— v7 改过边界 API）、`numpy`、`pillow`、`imageio-ffmpeg`。**火山引擎引擎零额外依赖**（只用标准库 `urllib`，不需要装 SDK） |
|
||||
| Node.js | 18+ | 渲染器与封面器用 |
|
||||
| 浏览器 | Chrome 或 Edge | 自动探测；都没有才下载 playwright chromium（约 115MB，只需一次） |
|
||||
| ffmpeg | 任意版本 | 先在 `PATH` 找；没有则用 `imageio-ffmpeg` 自带的静态二进制 |
|
||||
@@ -112,6 +112,71 @@ Windows 上 `~` 就是 `C:\Users\<你的用户名>`。
|
||||
|
||||
---
|
||||
|
||||
## 配音：两个引擎
|
||||
|
||||
流水线开始前，智能体会**先问你用哪个 TTS**，再列候选音色让你挑（也可以直接给它音色 ID）：
|
||||
|
||||
| | `edge-tts` | 火山引擎语音合成 2.0 |
|
||||
|---|---|---|
|
||||
| 你要做什么 | 什么都不用做 | 填一次 API Key |
|
||||
| 费用 | 免费 | 按字符计费 |
|
||||
| 音色 | 内置中英文若干 | 豆包 2.0 音色库，含声音复刻 |
|
||||
| 字级时间戳 | `WordBoundary` | `sentence.words[]` |
|
||||
| 额外依赖 | `edge-tts==7.2.8`、`imageio-ffmpeg` | **零** —— 只用标准库 `urllib` |
|
||||
| 什么时候选它 | 默认。开箱可用、够用 | 想要更自然的语气与更好音质 |
|
||||
|
||||
两者产出的 `audio-manifest.json` **结构完全一致**，所以时间轴、字幕、渲染**全都不用改** ——
|
||||
换引擎只是换一个字段的事。
|
||||
|
||||
### 选火山时，你唯一要动手的地方
|
||||
|
||||
技能第一次跑火山时会**生成一个 `tts.env` 并停下来**，然后告诉你把 API Key 填进去
|
||||
（火山控制台 → 语音技术 → API Key 管理）。你填好回来说一声，智能体就去测连接、确认音色，
|
||||
然后接着往下跑。
|
||||
|
||||
**这一步刻意不经过对话窗口** —— 密钥不发给智能体，智能体也不需要知道它。
|
||||
|
||||
内置常用音色（完整列表见[官方音色文档](https://docs.volcengine.com/docs/6561/1257544)）：
|
||||
|
||||
| 男声 | 女声 |
|
||||
|---|---|
|
||||
| 云舟 2.0（默认）· 温暖阿虎 2.0 · 解说小明 2.0 · 磁性解说男声 2.0<br>悬疑解说 2.0 · 广告解说 2.0 · 儒雅青年 2.0 · 少年梓辛 2.0 · 深夜播客 2.0 | 小何 2.0 · Vivi 2.0 · 知性灿灿 2.0<br>甜美桃子 2.0 · 邻家女孩 2.0 · 温柔淑女 2.0 |
|
||||
|
||||
内置列表不够用时，也可以直接用声音复刻出来的音色 ID。
|
||||
|
||||
### 密钥纪律
|
||||
|
||||
API Key 只存在 `tts.env` 里，而且**只有技能里的一个接口包读它**。
|
||||
智能体调的是那个接口包，拿不到、也不需要读密钥的值：
|
||||
|
||||
```
|
||||
你（手工填一次）→ tts.env（已被 .gitignore 忽略）
|
||||
↓ 只有接口包读
|
||||
合成调用 ← 智能体只调这个，永远拿不到密钥值
|
||||
↓
|
||||
火山引擎
|
||||
```
|
||||
|
||||
- **不进对话**：问智能体密钥状态，它给你的是脱敏摘要（`ef90******86c8`）。
|
||||
- **不进仓库**：`.gitignore` 覆盖 `tts.env` / `*.env` / `*.key` / `*.pem` / `secrets/`；
|
||||
仓库自检里有专门的**密钥防线**，并且做过反向自证 —— 故意植入一个假密钥会被当场抓到。
|
||||
- **不进日志**：出错信息过脱敏，只抹「这次实际用到的密钥值」与 `AKLT…` 形态的 token ——
|
||||
刻意**不**用「长字符串就算密钥」这种宽规则，否则连排查要用的请求 ID 一起抹掉。
|
||||
- **不进分发**：技能打包时排除密钥文件。
|
||||
- **兜底层**（真正的安全边界）：万一还是泄了，损失要可控 —— 建议在火山控制台用
|
||||
**子账号只授语音合成权限**、设**用量告警与限额**，密钥**可随时轮换**。
|
||||
|
||||
> 说句实话：合成代码是在你本机执行的，运行时进程里密钥对那一段脚本可见，
|
||||
> **「智能体绝对读不到」做不到**。上面保证的是**不进对话、不进仓库、不进日志、不进分发**，
|
||||
> 把泄露半径收敛成一次可撤销的事故。
|
||||
>
|
||||
> 另外**别用环境变量存密钥** —— 很多宿主会把进程环境原样打进会话记录。
|
||||
|
||||
**别把 `tts.env.example` 改名成 `tts.env` 去填**：那是要留在仓库里的模板，
|
||||
改名会让后来的人没模板可抄（仓库自检会报错并提示）。复制一份再填。
|
||||
|
||||
---
|
||||
|
||||
## 视频项目结构
|
||||
|
||||
说一句需求，智能体会在一个**视频项目目录**里走完整个流水线；产物落在 `out/`：
|
||||
@@ -152,7 +217,9 @@ CSS `transition` 入场）不可能工作，会被 `lint_frames.py` 直接拒绝
|
||||
| | |
|
||||
|---|---|
|
||||
| **节拍锚定解说词** | 画面按**匹配字幕文本**定位动画（`B('块文本')`），绝不硬编码帧号。改解说词，全片自动重排时间，画面代码零改动。 |
|
||||
| **词边界字幕** | 时序来自 edge-tts 的 `WordBoundary` 事件，不按字数插值 —— 中文里两个同字数的短语时长可以差 3 倍。 |
|
||||
| **词边界字幕** | 时序来自 TTS 的**字级时间戳**，不按字数插值 —— 中文里两个同字数的短语时长可以差 3 倍。edge-tts 取 `WordBoundary`，火山引擎取 `sentence.words[]`。 |
|
||||
| **两个配音引擎** | `edge-tts`（免费、免密钥、默认）或**火山引擎语音合成 2.0**（音质更好，需 API Key）。两者产出的 manifest 结构一致，下游零改动。切换用 `--provider`。 |
|
||||
| **密钥不进 agent、不进仓库** | 火山 API Key 只存 `tts.env`（已 gitignore），**只有接口包读它** —— agent 只调 `tts_volcano.py`，拿不到也不需读密钥。异常信息脱敏；`check_integrity.py` 有专门的密钥防线检查；打包排除密钥文件。 |
|
||||
| **两级时钟** | 帧长用 MP3 **容器时长**（保音画同步）；末块字幕按**语音真实结束**收尾。 |
|
||||
| **23 种画面风格** | 8 个类别，每种都记录了画布、字阶、时间轴与配色纪律。不用对着空白页从零设计。 |
|
||||
| **封面双方案** | 每条成片附带 16:9 与**独立重排**的 3:4 封面 —— 不是裁切，裁切会丢掉 57.8% 的画面宽度。 |
|
||||
@@ -166,8 +233,9 @@ CSS `transition` 入场）不可能工作，会被 `lint_frames.py` 直接拒绝
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["主题"] --> B["调研<br/><i>每个数字带出处</i>"]
|
||||
B --> C["narration.json<br/><i>竖线切字幕块</i>"]
|
||||
C --> D["tts_build.py<br/><i>edge-tts → MP3 + 词边界</i>"]
|
||||
B --> C["narration.json<br/><i>竖线切字幕块</i>"]
|
||||
C --> S["tts_setup.py<br/><i>问 TTS 方案 · 配密钥 · 选音色</i>"]
|
||||
S --> D["tts_build.py<br/><i>edge-tts / 火山引擎 → MP3 + 词边界</i>"]
|
||||
D --> E["timeline_build.py<br/><i>全局轴 + 拼接音轨</i>"]
|
||||
E --> F["subs.py<br/><i>subs.json · srt/vtt · beats.js</i>"]
|
||||
F --> G["frames/*.html<br/><i>一句一场景，风格取自风格库</i>"]
|
||||
@@ -251,8 +319,13 @@ tl.fromTo('.verdict', { scale: 0.8 }, { scale: 1, duration: 0.6 },
|
||||
| 封面出成 1 倍图 | 同上，`deviceScaleFactor` 的孪生坑 | 传 `newPage()` + `screenshot({ scale: 'device' })` |
|
||||
| 数字能渲染但永远不动 | seek 抑制了 `onUpdate` 回调 | 渲染器已修（`pause(t, false)`）；帧里改用 transform 数字卷轴 |
|
||||
| Windows 上 `No such file or directory` | 非 ASCII 路径 —— Windows 的 ffmpeg 把 UTF-8 当 ANSI 读 | 路径保持 ASCII |
|
||||
| 字幕开始飘 / 位置对不上 | TTS 没返回字级时间戳，`subs.py` 退回**按字数插值**（只有一行 stderr 警告） | 看 `tts_build` 有没有打 `⚠ 未返回字级时间戳`；换个受支持的音色（中英文 2.0） |
|
||||
| 火山报 `resource ID is mismatched with speaker related resource` | `speaker` 收到了中文显示名而不是音色 ID；或复刻音色配了预置资源 ID | 音色用内置名/ID（接口包会解析）；复刻音色配 `VOLC_RESOURCE_ID=seed-icl-2.0` |
|
||||
| 火山报 `HTTP 401/403` | `tts.env` 里的 key 不对，或该服务未开通 | 核对 `VOLC_API_KEY`；`tts_setup.py --status` 看脱敏状态 |
|
||||
| 火山报 `网络不可达` | 本包默认**绕过系统代理直连**（境内端点） | 确实需要代理时设 `VOLC_PROXY=http://127.0.0.1:<port>` |
|
||||
| 重跑后字幕整体晚一帧 | 命中缓存时丢掉了首裁量（历史 bug，已修） | 升级到 v1.3.0+；缓存格式已带 `lead_cut_sec` |
|
||||
|
||||
**`references/lessons.md` 是这个仓库里最值钱的文件。** 34 条编号记录，每一条都是一个
|
||||
**`references/lessons.md` 是这个仓库里最值钱的文件。** 56 条编号记录，每一条都是一个
|
||||
「成片看着挺正常、其实是错的」的 bug —— 包括它一开始是怎么被误判的。从零开始 debug 之前，
|
||||
先读它。
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: html-explainer
|
||||
version: 1.2.3
|
||||
description: 把任意主题做成「讲解/科普视频」并渲染成 MP4：调研→审查→解说词→字幕→edge-tts 配音→并行构建 HTML 场景→确定性逐帧渲染→成片后出双方案封面。**画面语言内置 23 个模板风格 / 8 个类别**（大胆信号卡、奢华极简、NYT 数据图表、瑞士网格、故障艺术、胶片漏光、流体 Hero、Logo 收尾、东方柔和有机、VFX 文字光标…共 23 种风格，含每种的画布/配色/字体/时间轴规范，见 references/style-catalog.md），流程规范与音画同步体系承自 anything2explainer（词边界字幕、两级时钟、语速标定、多 agent 分工与 QC 判据），渲染层为自研 seek 式渲染器。**封面双方案**：抖音主封面 1920×1080 + 兼容 3:4 的 1440×1080（独立重排，防主页栅格切字）。独立可移植：GSAP 内置、playwright-core 随包、ffmpeg 走 imageio-ffmpeg 回退、浏览器自动探测 Chrome/Edge；**不依赖 html-video / anything2explainer 任何代码或目录**。触发场景：要做科普/讲解/教学/知识/产品类视频、"讲一下 X 做成视频"、要用 html-video 那种模板化画面但更稳的音画同步、要挑某种视觉风格（极简/数据/赛博/电影感/品牌）出片、要出抖音封面/竖版封面、anything2explainer 换 HTML 渲染、或提到 html-explainer / HTML 讲解视频 / explainer video / MG 视频。
|
||||
version: 1.3.0
|
||||
description: 把任意主题做成「讲解/科普视频」并渲染成 MP4：调研→审查→解说词→字幕→配音（edge-tts，或火山引擎语音合成 2.0）→并行构建 HTML 场景→确定性逐帧渲染→成片后出双方案封面。**画面语言内置 23 个模板风格 / 8 个类别**（大胆信号卡、奢华极简、NYT 数据图表、瑞士网格、故障艺术、胶片漏光、流体 Hero、Logo 收尾、东方柔和有机、VFX 文字光标…共 23 种风格，含每种的画布/配色/字体/时间轴规范，见 references/style-catalog.md），流程规范与音画同步体系承自 anything2explainer（词边界字幕、两级时钟、语速标定、多 agent 分工与 QC 判据），渲染层为自研 seek 式渲染器。**封面双方案**：抖音主封面 1920×1080 + 兼容 3:4 的 1440×1080（独立重排，防主页栅格切字）。独立可移植：GSAP 内置、playwright-core 随包、ffmpeg 走 imageio-ffmpeg 回退、浏览器自动探测 Chrome/Edge；**不依赖 html-video / anything2explainer 任何代码或目录**。触发场景：要做科普/讲解/教学/知识/产品类视频、"讲一下 X 做成视频"、要用 html-video 那种模板化画面但更稳的音画同步、要挑某种视觉风格（极简/数据/赛博/电影感/品牌）出片、要出抖音封面/竖版封面、anything2explainer 换 HTML 渲染、或提到 html-explainer / HTML 讲解视频 / explainer video / MG 视频。
|
||||
agent_created: true
|
||||
---
|
||||
|
||||
@@ -59,6 +59,7 @@ bash <skill>/setup_env.sh # 自检；--install 联网补装
|
||||
```
|
||||
|
||||
依赖：Python≥3.9（edge-tts==7.2.8 钉死 / numpy / pillow / imageio-ffmpeg）、Node≥18、
|
||||
**火山引擎零额外依赖**（`tts_volcano.py` 只用标准库 `urllib`，不需要装任何 SDK）。
|
||||
Chrome 或 Edge（几乎必有；都没有才下载 playwright chromium ~115MB）、ffmpeg（PATH 或
|
||||
imageio-ffmpeg 静态二进制自动回退）。Windows 注意：项目路径全 ASCII；给 Node/Python
|
||||
传 `C:/...` 正斜杠路径；别用 heredoc 给 Python 传正则。
|
||||
@@ -68,6 +69,7 @@ imageio-ffmpeg 静态二进制自动回退）。Windows 注意：项目路径全
|
||||
```bash
|
||||
PY=<venv python 绝对路径> # 派子 agent 时必须展开成绝对路径写进 prompt
|
||||
"$PY" <skill>/scripts/new_project.py <dir> <slug> --topic "主题" # 阶段 0 建项目
|
||||
"$PY" <skill>/scripts/tts_setup.py --project . # ★ 先定配音方案 + 音色（问用户：edge / 火山）
|
||||
"$PY" <skill>/scripts/tts_build.py --project . # 配音：audio/*.mp3 + manifest
|
||||
"$PY" <skill>/scripts/timeline_build.py --project . # 全局时间轴：layout.json + narration-full.mp3
|
||||
"$PY" <skill>/scripts/subs.py --project . # 字幕：subs.json + beats.js + srt/vtt
|
||||
@@ -77,6 +79,12 @@ node <skill>/scripts/render_video.mjs . [--preview 30] [--keep-frames] [--only
|
||||
node <skill>/scripts/cover_build.mjs . # 封面双方案：out/cover_169.png + cover_34.png
|
||||
```
|
||||
|
||||
配音引擎（**跑之前必须先问用户**，见确认点 3）：`edge`（默认，免费免密钥）或
|
||||
`volcano`（火山引擎语音合成 2.0，音质更好，需 API Key）。两者产出的 manifest 结构一致，
|
||||
下游零改动。切换：`--provider edge|volcano` 或 `TTS_PROVIDER` 环境变量。
|
||||
**火山密钥只存 `tts.env`（已 gitignore）—— agent 只调 `tts_volcano.py`，不读该文件。**
|
||||
详见 `references/volcano-tts.md`。
|
||||
|
||||
辅助工具（随时可用，不进主流水线）：
|
||||
|
||||
```bash
|
||||
@@ -129,7 +137,7 @@ node <skill>/scripts/peek_frame.mjs . <帧id> --at 40,80 # 单帧速览：秒
|
||||
|---|---|
|
||||
| 帧时长 | MP3 **容器时长**（tts_build 裁首尾静音后回填）。词边界时长每段少 ~0.86s，用它必错位 |
|
||||
| 末块字幕收尾 | 语音**真实结束**（speech_end_sec）—— 两级时钟，混用则「字幕过了语音还没过」 |
|
||||
| 字幕节拍 | edge-tts **WordBoundary** 首字对帧号，绝不按字数插值（中文同字数时长差 3 倍） |
|
||||
| 字幕节拍 | 词级时间戳首字对帧号，绝不按字数插值（中文同字数时长差 3 倍）。edge 取 `WordBoundary`，火山取 `sentence.words[]`（**需显式开 `audio_params.enable_subtitle`，本包默认开**；不开会静默退回插值） |
|
||||
| 画面节拍 | 场景 HTML 里 `B('块文本')` 取该词起播秒排 GSAP —— 画面与吐字同源 |
|
||||
| 渲染 | **确定性 seek**：`tl.pause(t, false)` + CSS 动画 `currentTime=t×1000` → 截图 → ffmpeg 合成。无实时录制，html-video 的引导期/起播/字体坑整类不存在。**第二参必须传 `false`**，少了它 `onUpdate` 类回调被静默抑制（数字滚动恒为初值，见 lessons #27） |
|
||||
| 字幕层/进度条 | 渲染器注入并逐帧驱动（`#mg-subs` 44px 白字黑边 bottom 96px；`#mg-progress` accent 填充），帧作者零负担 |
|
||||
@@ -140,7 +148,17 @@ node <skill>/scripts/peek_frame.mjs . <帧id> --at 40,80 # 单帧速览：秒
|
||||
|
||||
0. **建项目**（5 分钟）：`new_project.py` + 定主题（`make_theme.py --topic/--preset … --use`，颜色全在 theme.css 的 CSS 变量里，画面代码禁止色值字面量）
|
||||
1. **调研**（20 分钟，1 agent）：research/调研.md，每个数字带 URL；**确认点 1**（时长/语言）并行问
|
||||
2. **解说词**（30 分钟）：narration.json（`|` 切字幕块，中文 ≤16 字/块）→ 填 order → **确认点 2**（文案定稿）→ **确认点 3**（TTS 偏好）→ tts/timeline/subs 三连 → 核对时长区间（差 >15% 改句子，别改语速硬凑）→ **定稿后不改词**
|
||||
2. **解说词**（30 分钟）：narration.json（`|` 切字幕块，中文 ≤16 字/块）→ 填 order → **确认点 2**（文案定稿）→ **确认点 3**（配音方案 + 音色）→ tts/timeline/subs 三连 → 核对时长区间（差 >15% 改句子，别改语速硬凑）→ **定稿后不改词**
|
||||
|
||||
**确认点 3 必须问两件事**（用 `tts_setup.py` 落实）：
|
||||
① **方案** —— 「配音用 edge-tts（免费、免密钥、开箱可用）还是火山引擎语音合成 2.0
|
||||
（音质更好，需要 API Key，约 1 分钟配置）」；
|
||||
② **音色** —— 选定方案后列候选让用户挑，也可自定义 ID。
|
||||
选火山时：缺 `tts.env` → `tts_setup.py` 生成空模板并**停下来**，让用户手工填密钥
|
||||
（**agent 不读该文件、不参与填值**）；用户说填好了 → `--check` 测连接 → 再选音色。
|
||||
★ 提醒用户用 `cp tts.env.example tts.env` **复制**，别把 `tts.env.example` **改名**成
|
||||
`tts.env` —— 那是要留在仓库里的模板（改名会让 `check_integrity.py` 报错）。
|
||||
详见 `references/volcano-tts.md`。
|
||||
3. **分镜（含选风格，20 分钟）**：script/storyboard.md，每场景一行 ——
|
||||
**先从风格库挑风格**（`references/style-catalog.md`，按「挑风格的实用建议」表匹配内容类型，
|
||||
并核对时长档），再写画面/主角·尺寸/光/B() 锚点；末尾全局约束
|
||||
@@ -185,7 +203,9 @@ GSAP 用 `../assets/gsap.min.js`（本地内置）→ 主体动画压在 speech_
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `scripts/new_project.py` | 阶段 0 脚手架：建目录树 + `project.json` + `narration.json` 占位 + `theme.css` + 两份封面 HTML |
|
||||
| `scripts/tts_build.py` | edge-tts：缓存/超时/重试/裁静音，manifest 写两级时长 |
|
||||
| `scripts/tts_setup.py` | **配音方案向导**：选 edge/火山 → 缺密钥则生成 `tts.env` 模板并停下 → 测连接 → 选音色 → 写回 project.json。输出 `NEXT_ACTION=…` 供 agent 判断下一步 |
|
||||
| `scripts/tts_volcano.py` | **火山引擎语音合成 2.0 接口包**：唯一读 `tts.env` 的地方；`--check` / `--voices` / `--synth`。密钥不回显、异常脱敏（`_redact`） |
|
||||
| `scripts/tts_build.py` | 配音合成：edge-tts **或** 火山引擎（`--provider`）；缓存/硬超时/退避重试/裁静音，manifest 写两级时长。两引擎 manifest 结构一致 |
|
||||
| `scripts/timeline_build.py` | layout.json 全局轴 + narration-full.mp3（gap 显式插入） |
|
||||
| `scripts/subs.py` | 字幕三出口（subs.json / srt+vtt / 画面内层由渲染器注入）+ beats.js 节拍器 |
|
||||
| `scripts/lint_frames.py` | **渲染前静态体检**：八条契约违规逐条报（外链字体/色值字面量/墙钟/`B()\|\|N`/字幕带压内容/缺中文字体族…） |
|
||||
|
||||
+5
-1
@@ -36,10 +36,14 @@ EXCLUDE_DIRS = {
|
||||
"render", "research", "script", # 项目级产物（防在技能目录内建过 demo）
|
||||
}
|
||||
# 文件名 / 后缀排除
|
||||
EXCLUDE_SUFFIX = (".pyc", ".pyo", ".beats.js", ".mp4", ".mp3", ".wav", ".log")
|
||||
EXCLUDE_SUFFIX = (".pyc", ".pyo", ".beats.js", ".mp4", ".mp3", ".wav", ".log",
|
||||
".env", ".key", ".pem") # 密钥类：绝不进可分发包
|
||||
EXCLUDE_NAMES = {
|
||||
"package-lock.json", ".DS_Store", "Thumbs.db", "qc_sheet.jpg", "qc_report.md",
|
||||
".gitignore", ".gitattributes",
|
||||
# ★ 密钥文件。tts.env 是火山 TTS 的 API Key 唯一落点，打包进 zip 等于把
|
||||
# 用户的密钥随技能一起发出去。模板 tts.env.example 是入库的，不在此列。
|
||||
"tts.env", "secrets",
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -389,3 +389,108 @@
|
||||
验收口径（别只看渲染日志的「✓ 成片」）：**帧号连续无缺口 + 成片时长 == layout 总长**。
|
||||
本片收尾实测 6194 帧、0 缺帧、`Duration 00:03:26.47` 与 layout 的 206.47s 逐位一致。
|
||||
|
||||
|
||||
46. **★（2026-09-23）「用户需要中断流程去手工做一件事」时，那个选择必须先落盘。**
|
||||
加火山 TTS 时踩的：向导让用户选方案 → 选火山 → 生成 `tts.env` 模板让用户去填密钥 →
|
||||
**此时 `project.json` 还没写 `provider`**（原本要等全部步骤走完才写）→ 用户填完回来跑
|
||||
`--check`，脚本从 `project.json` 读到默认的 `edge`，于是**静默去测 edge 并报「✓ 就绪」**。
|
||||
用户会以为密钥配好了。
|
||||
规则：**只要流程中间存在「需要用户离开去手工完成」的断点，断点之前已经确定的状态就要立刻持久化**。
|
||||
顺带把「我测的是哪个」显式打印出来（`测试方案：volcano`）—— 加了这一行，同类错位就不可能再静默。
|
||||
更一般的判据：**任何带默认值的回退，都要问一句「这个默认值在什么情况下会冒充用户的真实选择」**。
|
||||
|
||||
47. **密钥只能用「单点接触」的接口包封装，且默认值不能替用户做安全决定。**
|
||||
本技能的密钥纪律是「agent 不读、仓库不记、日志不吐、分发不含」。让它成立的**不是自觉，
|
||||
是结构**：密钥只存在 `tts.env`，**只有 `tts_volcano.py` 读它**，agent 只调这个包。
|
||||
四条各有对应机制：
|
||||
- 不读 → 接口包自己读；agent 想知道状态就跑 `--status`（输出脱敏摘要）
|
||||
- 不记 → `.gitignore` + `check_integrity.py` 的密钥防线检查（遍历仓库抓非空赋值与 `AKLT…`）
|
||||
- 不吐 → 异常过 `_redact()`。**脱敏规则别写成「长字符串就当密钥」**：那会把 reqid/logid
|
||||
一起抹掉，排查时没有定位线索。只抹「本次实际加载的密钥值」+ 明确形态（`AKLT…`）即可，
|
||||
因为密钥只可能从这两个来源进入输出。
|
||||
- 不含 → `package_skill.py` 排除密钥文件（见 #48）
|
||||
**必须对用户说清的实话**：合成代码是 agent 在本机执行的，运行时进程里密钥对脚本可见，
|
||||
「agent 绝对读不到」做不到。能保证的是**不进对话、不进仓库、不进日志、不进分发**，
|
||||
再加**最小权限子账号 + 用量告警 + 可随时轮换**把泄露半径收敛成一次可撤销的事故。
|
||||
★ 附实证：**环境变量比凭据文件更不安全** —— 本机 `env` 的输出会被工具结果带进会话记录
|
||||
（早前 `env | grep proxy` 连 MCP 的 bearer token 都打出来过）。要存密钥就用
|
||||
系统凭据管理器或仓库外的文件，**别用环境变量**。
|
||||
|
||||
48. **加了新的敏感文件类型，要同时检查「打包/分发」与「gitignore」两条路 —— 它们不共享规则。**
|
||||
`package_skill.py` 的排除表原先只有仓库卫生文件，**没有 `.env`**。
|
||||
也就是说：技能目录里一旦放了 `tts.env`，`package_skill.py` 会把它打进可分发的 zip，
|
||||
用户把包转给别人 = 把 API Key 一起发出去。gitignore 挡不住这条（打包不看 gitignore）。
|
||||
修完必须**实测**而不是只看代码：往技能目录放一个假 `tts.env`，打包，
|
||||
再开 zip 列表 + 对每个成员做**内容级**扫描（`b'AKLT...' in z.read(n)`）。
|
||||
验收三条：密钥文件不在包里、模板 `tts.env.example` 仍在包里、内容扫描无命中。
|
||||
|
||||
49. **「非 0 的状态码 = 错误」是错的 —— 先查清楚协议里的成功/结束码各是什么。**
|
||||
火山 V3 单向流式的响应是 NDJSON，音频块 `code=0`，而**结束标记是 `code=20000000` 且 `data=null`**。
|
||||
社区记录里有人只判 `code===0` 收音频，症状是「合并出来的音频末尾嘎然而止」——**最后一段丢了**，
|
||||
而 HTTP 200、日志一切正常。本包按 `code` 显式区分三种：`0` 收音频 / `20000000` 结束 /
|
||||
其他抛错，并且**离线断言过**（本地假服务端按官方响应结构回包，断言音频字节数、
|
||||
时间戳换算、请求头与请求体字段）。这类「协议细节只听文档会错」的地方，
|
||||
花十分钟搭个假服务端做断言，比拿真 key 反复试便宜得多。
|
||||
|
||||
50. **对外接口的「同构」是省事的关键 —— 适配新引擎时先看能不能让下游零改动。**
|
||||
火山 TTS 有五种接入方式（WS 双向流式 / WS 单向流式 / HTTP Chunked / SSE / 已弃用的 v1），
|
||||
选的是 **HTTP Chunked 单向流式**，唯一理由是它和 edge-tts **形态同构**：发一次文本、收一串音频。
|
||||
于是缓存 / 硬超时 / 退避重试 / 裁静音 / 两级时钟**一行没改**，
|
||||
两引擎产出的 manifest 结构完全一致，`timeline_build.py` / `subs.py` / 渲染器零改动。
|
||||
双向流式是为 LLM 实时对话设计的（可打断、多轮 session 状态机），离线出片要它纯属负担。
|
||||
★ 判断依据要落在**数据契约**上而不只是传输方式：这里真正的关键不是「怎么发」，
|
||||
而是「词级时间戳拿不拿得到」——火山 `sentence.words[]` 给字级 `startTime`/`endTime`（秒），
|
||||
正好等价于 edge 的 `WordBoundary`，**不需要「强制对齐」那一步**
|
||||
（注意：**前提是显式开 `audio_params.enable_subtitle`**，见第 51 条）。
|
||||
接新引擎前先确认这一点；拿不到词级时间戳就**别接**——按字数插值是这个技能明确禁止的退化。
|
||||
|
||||
51. **★（2026-09-23）官方文档示例里「有值」的字段，不等于你不传参数它就会返回。**
|
||||
火山文档的响应示例里 `sentence.words[]` 带着完整的字级时间戳，很容易让人以为「默认就给」。
|
||||
实测：**不传 `audio_params.enable_subtitle: true`，`words` 恒为空数组**（同文本对比
|
||||
false→`words=0`，true→`words=10`）。这个坑的可怕之处在于**它完全不报错**：
|
||||
音频正常、时长正常、`sentence.text` 也正常，只有时间戳是空的。
|
||||
下游会静默退化——`subs.py` 发现没有词边界就**按字数插值**（只打一行 stderr 警告），
|
||||
成片照样能出，字幕却开始飘。**判据：凡是「文档示例里看着有值」的字段，
|
||||
都要用一个显式关掉参数的对照组实测一次**，别接受单边证据。
|
||||
顺带：该开关仅豆包 2.0 的中英文音色支持，所以本包在拿到音频却没有时间戳时
|
||||
会往结果里塞 `warning`，让 `tts_build.py` 能把它打到台面上，而不是安静地飘字幕。
|
||||
|
||||
52. **计费/统计字段常挂在「流结束」那一行上 —— 别在结束标记处提前 `continue`。**
|
||||
同一个坑的第二层：`usage.text_words` 就挂在 `code=20000000`（结束标记）那一行。
|
||||
解析循环写成「先判结束标记 → `continue` → 再读其他字段」，
|
||||
结果**计费字数永远是 0**，而请求本身完全正常。加上 `X-Control-Require-Usage-Tokens-Return: *`
|
||||
这个头之后依然读到 0 —— 因为问题不在服务端给不给，而在**我们把那一行跳过了**。
|
||||
症状极易被误判成「是不是免费额度？」。**顺序原则：一行的所有字段先全部读完，
|
||||
再决定这行要不要跳过它的「主语义」**。修完实测：`计费 20 字` 与文本长度逐字对上。
|
||||
|
||||
53. **缓存里必须连「裁剪量」一起存 —— 否则首跑与重跑产出的 manifest 不一致。**
|
||||
词边界是**原始坐标系**（合成完那一刻的时间），下游 `subs.py` 靠 `lead_cut_sec` 平移。
|
||||
缓存只存了边界数组、命中缓存时把首裁量当 0，于是**重跑的 `lead_cut_sec=0`、首跑是 0.037**
|
||||
——字幕整体晚一帧。这类 bug 只在「第二次跑」出现，而第二次跑恰恰是最常发生的场景。
|
||||
修法：缓存改成 `{"boundaries": [...], "lead_cut_sec": x}`，并对旧版**裸列表**格式做兼容读取。
|
||||
验收必须是**深度 diff**（见 55）。
|
||||
|
||||
54. **★ 别把仓库里的 `*.example` 模板「改名」成真文件 —— 模板会消失，而其他用户再也配不起来。**
|
||||
实证：用户把 `tts.env.example` 改名成 `tts.env` 去填 key。功能上没问题（gitignore 也确实
|
||||
挡住了它入库），但**仓库里少了模板**，`check_integrity.py` 的密钥防线当场报错。
|
||||
这类错之所以常见，是因为「复制」和「改名」在资源管理器里只差一个字。
|
||||
**两道改进**：① 模板开头直接写清「请复制，不要改名」；
|
||||
② 校验脚本在「缺模板」时**再看一眼同目录有没有真文件**，有就直说「疑似改名」——
|
||||
错误信息能指向原因，比只报「缺文件」有用得多。
|
||||
|
||||
55. **★ 验证脚本本身要先 sanity check ——「没发现差异」可能是比较器根本没比到。**
|
||||
验证「首跑 vs 重跑一致」时，第一版 diff 把 `items` 这个**列表**当成不透明值
|
||||
（只记 `<list 3>`），于是 982 个字段里一个都没深入比较，第二轮打印出
|
||||
「✓ 两次 manifest 完全一致」。而同一时刻终端上明明显示首裁 `0.037s` vs `0.000s`。
|
||||
**两个互相矛盾的证据同时出现时，先怀疑那个「更省事」的结论**。
|
||||
改成递归进入列表后，立刻暴露 3 处不一致。
|
||||
★ 通用规则：**验证器要能被证伪** —— 先拿一个已知有差异的输入试一次，
|
||||
看它会不会报差异；会报，才有资格说「一致」。
|
||||
|
||||
56. **「名称 / 序号 / 原始 ID」的解析必须收在接口包里，不能让调用方各写一份。**
|
||||
火山 CLI 的 `--voice "云舟 2.0"` 把中文显示名**原样当成 speaker 发出去**，
|
||||
服务端拒了，报的是 `55000000 resource ID is mismatched with speaker related resource`
|
||||
——完全看不出「其实是名字没解析」。修法是把 `resolve_voice_token()` 放进接口包，
|
||||
`tts_setup.py` 改为委托它，语速换算（`parse_rate_percent`）同理。
|
||||
**判据：凡是「用户会手输、而协议只认机器格式」的字段（音色名、语速、路径），
|
||||
解析逻辑有且只能有一份，且放在离协议最近的那一层。** 两份实现必然慢慢跑偏。
|
||||
@@ -0,0 +1,195 @@
|
||||
# 火山引擎语音合成 2.0（豆包）接入说明
|
||||
|
||||
`html-explainer` 支持两个配音引擎。**跑 `tts_build.py` 之前必须先问用户用哪个**（SKILL.md 确认点 3）。
|
||||
|
||||
| 引擎 | 密钥 | 音色 | 词级时间戳 | 什么时候用 |
|
||||
|---|---|---|---|---|
|
||||
| `edge`（默认） | 不需要 | edge-tts 内置音色 | 有（`WordBoundary`） | 默认。免费、开箱可用、够用 |
|
||||
| `volcano` | **需要 API Key** | 豆包语音合成模型 2.0 | 有（`sentence.words[]`） | 想要更好的音质/更自然的语气 |
|
||||
|
||||
两个引擎产出的 `audio-manifest.json` **结构完全一致**（`boundaries` 都是「秒 + 原始坐标系」），
|
||||
所以 `timeline_build.py` / `subs.py` / 渲染器**零改动**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 密钥纪律（读这一节就够）
|
||||
|
||||
用户裁定：**agent 不许读取 `tts.env`，仓库不许记录它。**
|
||||
|
||||
这不是靠自觉，是靠结构保证的：
|
||||
|
||||
```
|
||||
你（手工填一次）→ tts.env（被 .gitignore 忽略）
|
||||
↓ 只有 scripts/tts_volcano.py 读它
|
||||
tts_volcano.synthesize() ← agent 只调这个，永远拿不到密钥值
|
||||
↓
|
||||
openspeech.bytedance.com
|
||||
```
|
||||
|
||||
- **agent 侧**：只调用 `scripts/tts_volcano.py`（或 `tts_build.py --provider volcano`）。
|
||||
不需要 `cat` / `grep` / 读 `tts.env` —— 接口包会自己读。
|
||||
想确认密钥状态时跑 `tts_setup.py --status`，它输出的是**脱敏摘要**。
|
||||
- **密钥不进输出**：接口包保证不打印、不记录、不回显密钥；异常信息过 `_redact()` 脱敏
|
||||
（只抹「本次实际加载的密钥值」和 `AKLT…` 形态 token，reqid / logid 保留 —— 排查要线索）。
|
||||
- **密钥不进仓库**：`.gitignore` 忽略 `tts.env` / `*.env` / `*.key` / `*.pem` / `secrets/`；
|
||||
`check_integrity.py` 有专门的**密钥防线**检查（见第 5 节）。
|
||||
- **密钥不进分发**：`package_skill.py` 排除 `tts.env` / `*.env` / `*.key` / `*.pem`
|
||||
（模板 `tts.env.example` 保留，用户要照抄它）。
|
||||
- **兜底层（真正的安全边界）**：万一还是泄了，损失要可控 —— 建议在火山控制台用
|
||||
**子账号只授 TTS 权限**、设**用量告警与限额**，并且密钥**可随时轮换**。
|
||||
|
||||
> 说句实话：合成代码是 agent 在本机执行的，运行时进程里密钥对脚本可见，
|
||||
> 「agent 绝对读不到」做不到。上面保证的是**不进对话、不进仓库、不进日志、不进分发**，
|
||||
> 把泄露半径收敛成一次可撤销的事故。
|
||||
|
||||
---
|
||||
|
||||
## 2. 三步配置
|
||||
|
||||
```bash
|
||||
# ① 选方案（会问用户：edge 还是火山）
|
||||
python <skill>/scripts/tts_setup.py --project .
|
||||
# 选火山且缺 tts.env → 生成带注释的空模板并退出（退出码 2，NEXT_ACTION=fill_env）
|
||||
|
||||
# ② 用户手工填 tts.env（这一步 agent 不参与）
|
||||
# 火山引擎控制台 → 语音技术 → API Key 管理
|
||||
# https://console.volcengine.com/speech/new/setting/apikeys
|
||||
|
||||
# ③ 回来测连接 + 选音色
|
||||
python <skill>/scripts/tts_setup.py --project . --check # 测连接
|
||||
python <skill>/scripts/tts_setup.py --project . --list-voices # 列候选音色
|
||||
python <skill>/scripts/tts_setup.py --project . --provider volcano --voice "解说小明 2.0"
|
||||
```
|
||||
|
||||
配置写进 `project.json` 的 `provider` / `voice` / `rate` 三个字段。
|
||||
**方案一旦选定立刻落盘** —— 因为填密钥会中断流程，若不落盘，用户回来跑 `--check` 时
|
||||
`project.json` 还写着 `edge`，会静默去测 edge（这个坑真踩过）。
|
||||
|
||||
非交互场景（agent 代跑）看这三个标记：`NEXT_ACTION=ask_user_provider` /
|
||||
`NEXT_ACTION=fill_env` / `NEXT_ACTION=ask_user_voice` / `NEXT_ACTION=done`。
|
||||
|
||||
---
|
||||
|
||||
## 3. tts.env 格式
|
||||
|
||||
```ini
|
||||
VOLC_API_KEY= # 必填。也可以用旧版鉴权（见下）
|
||||
VOLC_RESOURCE_ID=seed-tts-2.0
|
||||
VOLC_APP_ID= # 可选：旧版鉴权（APP ID + Access Token）
|
||||
VOLC_ACCESS_KEY= # 可选：填了则与 VOLC_APP_ID 配对使用
|
||||
```
|
||||
|
||||
探测顺序（`tts_volcano.env_candidates()`，与向导保持一致）：
|
||||
`$TTS_ENV_FILE` → `<项目>/tts.env` → `<技能目录>/tts.env` → `~/.workbuddy/tts.env`
|
||||
|
||||
资源 ID：**预置音色用 `seed-tts-2.0`**；你自己克隆的音色用 `seed-icl-2.0`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口规格（2026-09 核对官方文档）
|
||||
|
||||
```
|
||||
POST https://openspeech.bytedance.com/api/v3/tts/unidirectional
|
||||
Header: X-Api-Key / X-Api-Resource-Id / 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}}}
|
||||
```
|
||||
|
||||
**为什么选这条路**：这是 **HTTP Chunked 单向流式**——一次性发文本、流式收音频。
|
||||
与 edge-tts 的形态同构（发一次、收一串），所以 `tts_build.py` 的缓存 / 硬超时 /
|
||||
退避重试 / 裁静音 / 两级时钟逻辑全部原样复用。
|
||||
|
||||
**不用双向流式**（`wss://.../api/v3/tts/bidirection`）：那是给 LLM 实时对话设计的
|
||||
（文本流式进、可打断、多轮 session 状态机）。离线出片用不上，纯开销。
|
||||
|
||||
### 响应：NDJSON，逐行 JSON
|
||||
|
||||
```jsonc
|
||||
{"code":0, "message":"OK", "data":"<base64 音频块>", "sentence":{"text":"你好","words":[
|
||||
{"word":"你","startTime":0.195,"endTime":0.335,"confidence":0.9}]}}
|
||||
{"code":0, "message":"OK", "data":"<base64 音频块>"}
|
||||
{"code":20000000, "message":"OK", "data":null, "usage":{"text_words":7}} // ★ 结束标记
|
||||
```
|
||||
|
||||
**四个必须知道的点**：
|
||||
|
||||
1. **结束标记的 `code` 是 `20000000`,不是 `0`。** 只判 `code===0` 收音频会丢最后一段
|
||||
（症状：合并出来的音频末尾「嘎然而止」）。本包按 `code` 显式区分。
|
||||
2. **★ 字级时间戳必须显式开 `audio_params.enable_subtitle: true`。**
|
||||
官方文档的响应示例里 `words[]` 是有值的，**很容易误以为默认就给** ——
|
||||
实测不传该参数 `words` **恒为空数组**（同文本对照：`false` → `words=0`，`true` → `words=10`）。
|
||||
它**不报错**：音频、时长、`sentence.text` 全正常，只有时间戳是空的；
|
||||
下游会静默退回按字数插值，字幕开始飘。本包默认开启。
|
||||
开了之后拿到的是字级 `word` / `startTime` / `endTime` / `confidence`（单位**秒**），
|
||||
即 edge-tts `WordBoundary` 的等价物，**不需要「强制对齐」那一步**。
|
||||
→ 映射成 `{"text","offset_sec","duration_sec"}`。
|
||||
仅豆包 2.0 的**中英文**音色支持；拿到音频却没有时间戳时本包会在结果里塞 `warning`。
|
||||
3. **`usage` 挂在结束标记那一行。** 解析循环若「先判结束标记 → `continue`」，
|
||||
就会**永远读不到计费字数（恒为 0）**，容易被误判成「免费额度」。
|
||||
另外**不传请求头 `X-Control-Require-Usage-Tokens-Return: *`，服务端根本不返回 `usage`**。
|
||||
4. **单请求文本上限 ~200 字。** 超了本包按标点切分（不在词中间劈开），
|
||||
后续片段的词边界按前面片段用 ffmpeg 量出的实际时长平移。
|
||||
|
||||
参数换算：语速 `speech_rate ∈ [-50,100]`，映射 `倍率 = 1 + speech_rate/100`
|
||||
（100 = 2.0 倍、-50 = 0.5 倍，线性）。`parse_rate_percent()` 统一接受
|
||||
`"+8%"` / `"8"` / `0.08` / `8` 四种写法，`tts_setup.py` 与 `tts_build.py` 共用这一份
|
||||
（**不要各写一份**：`tts_volcano.py` CLI 曾把中文音色名直接当 `speaker` 发出去，
|
||||
被服务端以 `55000000 resource ID is mismatched with speaker…` 拒绝，看不出是没解析）。
|
||||
音色名解析同理走 `resolve_voice_token()`。
|
||||
默认 `sample_rate=24000` / `format=mp3` / `bit_rate=160000`。
|
||||
|
||||
**代理**：`openspeech.bytedance.com` 是**境内端点，默认绕过系统代理直连**。
|
||||
本机常驻代理会让境内域名绕远甚至失败（见 lessons）。要强制走代理就设 `VOLC_PROXY`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 密钥防线的自动化检查
|
||||
|
||||
`python scripts/check_integrity.py` 多跑两项：
|
||||
|
||||
```
|
||||
✓ 密钥防线：.gitignore 已忽略 tts.env / *.env / *.key
|
||||
✓ 密钥防线：仓库内未发现真实密钥（模板里的空赋值不算）
|
||||
```
|
||||
|
||||
第二项会遍历仓库（跳过 `.git`/`node_modules`/二进制），抓两类形态：
|
||||
非空密钥赋值（`VOLC_API_KEY=…`）与 `AKLT…` token。**空模板不算违规**，所以
|
||||
`tts.env.example` 可以入库。CI 也跑这个 —— 它在无密钥环境下能通过。
|
||||
|
||||
---
|
||||
|
||||
## 6. 音色
|
||||
|
||||
`tts_setup.py --list-voices` 会列内置常用音色（可自定义 ID）。默认 **云舟 2.0**。
|
||||
2.0 音色的 `voice_type` 都以 `_uranus_bigtts` 结尾。
|
||||
|
||||
| 音色 | voice_type | 定位 |
|
||||
|---|---|---|
|
||||
| 云舟 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_female_xiaohe_uranus_bigtts` | 女声 · 通用 |
|
||||
| Vivi 2.0 | `zh_female_vv_uranus_bigtts` | 女声 · 活泼通用 |
|
||||
| 知性灿灿 2.0 | `zh_female_cancan_uranus_bigtts` | 女声 · 知性 |
|
||||
|
||||
完整列表（上百个）见官方音色文档：<https://docs.volcengine.com/docs/DoubaoVoice/Tonelist-1>
|
||||
|
||||
**注意**：切了引擎要重跑 `tts_build.py`（缓存 sig 含 provider，不会串音）；
|
||||
语速标定结论不能跨引擎沿用 —— edge 的 `RATE` 与火山的 `speech_rate` 是两套刻度，
|
||||
换引擎后如需精密控速要重新标定。另外 edge 独有的「相邻数字补逗号」处理对火山**不启用**：
|
||||
它会改动送进去的文本、影响词边界与解说词的逐字对齐，而火山不熔读相邻数字。
|
||||
|
||||
---
|
||||
|
||||
## 7. 排查
|
||||
|
||||
| 现象 | 原因 / 处理 |
|
||||
|---|---|
|
||||
| `没有找到 tts.env` | 跑 `tts_setup.py --project .` 生成模板后填写 |
|
||||
| `HTTP 401` / `Invalid X-Api-Key` | 密钥错、未开通服务，或该用旧版鉴权（填 `VOLC_APP_ID` + `VOLC_ACCESS_KEY`） |
|
||||
| `HTTP 404` | 音色与资源 ID 不匹配 —— 预置音色要配 `seed-tts-2.0` |
|
||||
| `网络不可达` | 本包默认直连；若确实需要代理，设 `VOLC_PROXY=http://127.0.0.1:<port>` |
|
||||
| 音频末尾「嘎然而止」 | 结束标记 `code=20000000` 的处理问题（本包已处理；自研代码要留意） |
|
||||
| 字幕与音频错位 | 检查 `sentence.words[]` 是否被正确映射成 `offset_sec`（单位是**秒**） |
|
||||
| 想确认测的到底是哪个引擎 | `--check` 会先打印 `测试方案：<provider>` |
|
||||
@@ -44,15 +44,24 @@ bash <skill>/setup_env.sh # 首台机器先跑一次
|
||||
text 内用 `|` 切字幕块（中文每块 ≤16 字，切点落在语义边界）
|
||||
2. 填 `project.json` 的 `order`（= id 顺序，可选 `chapters: [{title, startSegment}]`）
|
||||
3. **确认点 2**：全文 + 章节划分 + 字数/预估时长贴给用户
|
||||
4. **确认点 3**：问一句「配音有偏好的 TTS 吗？」默认 edge-tts 云希 +8%
|
||||
5. 跑流水线（顺序不能乱）：
|
||||
4. **确认点 3 —— 配音方案与音色，必须问两件事**：
|
||||
① 方案：「edge-tts（免费、免密钥、开箱可用）还是火山引擎语音合成 2.0（音质更好，需 API Key）」
|
||||
② 音色：用 `--list-voices` 列候选让用户挑，也接受自定义音色 ID
|
||||
|
||||
5. 跑设置向导 + 流水线（顺序不能乱）：
|
||||
|
||||
```bash
|
||||
"$PY" <skill>/scripts/tts_setup.py --project . # 定方案 + 音色；缺密钥会生成 tts.env 模板并停下
|
||||
"$PY" <skill>/scripts/tts_build.py --project .
|
||||
"$PY" <skill>/scripts/timeline_build.py --project .
|
||||
"$PY" <skill>/scripts/subs.py --project .
|
||||
```
|
||||
|
||||
**选火山时的正确停顿姿势**：向导生成 `tts.env` 后退出码 2、打印 `NEXT_ACTION=fill_env`
|
||||
→ 告诉用户「请打开这个文件填 API Key，填好告诉我」→ **agent 不要读该文件、不要代填**
|
||||
→ 用户说填好了 → `tts_setup.py --project . --check` 测连接 → 再选音色。
|
||||
密钥纪律与排查见 `references/volcano-tts.md`。
|
||||
|
||||
6. 核对成片时长落在用户要的区间（差 >15% 加/删句子重跑，别改语速硬凑）
|
||||
7. **定稿后不再改词**（帧时长与节拍全部随配音重排）
|
||||
|
||||
|
||||
@@ -14,6 +14,9 @@ check_integrity.py —— 仓库自洽性检查（CI 与本地都能跑，零第
|
||||
—— 授权信息缺失会让 THIRD_PARTY_NOTICES 失真。
|
||||
5. 帧模板 / 封面模板不得出现外链字体或 CDN 资源
|
||||
—— 离线渲染硬要求，见 frame-contract.md 契约 2。
|
||||
6. 密钥防线：.gitignore 必须忽略 tts.env / *.env / *.key，且仓库内不得出现
|
||||
真实的火山引擎密钥（非空赋值 / AKLT 形态 token）
|
||||
—— 火山 TTS 是本技能唯一需要密钥的功能，泄露即永久失守。
|
||||
|
||||
用法：
|
||||
python scripts/check_integrity.py # 以脚本所在技能的根目录为准
|
||||
@@ -159,6 +162,75 @@ def check_no_remote_assets(root: str, fails: list[str]) -> None:
|
||||
print(f"{OK} 模板无外链资源：{len(targets)} 个模板检查通过")
|
||||
|
||||
|
||||
def check_no_secrets(root: str, fails: list[str]) -> None:
|
||||
"""密钥防线：tts.env 必须被忽略，且仓库里不得出现真实密钥。
|
||||
|
||||
对应 2026-09-23 加入的火山引擎 TTS 支持 —— 那是本技能唯一需要密钥的功能。
|
||||
密钥纪律是「agent 不读、仓库不记」，所以这里做两道自动化检查：
|
||||
a) .gitignore 覆盖 tts.env / *.env / *.key，且 tts.env.example 模板仍被跟踪；
|
||||
b) 草签文件里不得出现非空的密钥赋值或 AKLT 形态的 token。
|
||||
"""
|
||||
gi = os.path.join(root, ".gitignore")
|
||||
if os.path.isfile(gi):
|
||||
text = read(gi)
|
||||
need = ["tts.env", "*.env", "*.key"]
|
||||
missing = [n for n in need if n not in text]
|
||||
if missing:
|
||||
fails.append(f"secret: .gitignore 未忽略 {', '.join(missing)}"
|
||||
f" —— 密钥可能被提交进公开仓库")
|
||||
else:
|
||||
print(f"{OK} 密钥防线：.gitignore 已忽略 tts.env / *.env / *.key")
|
||||
else:
|
||||
fails.append("secret: 没有 .gitignore —— 密钥无保护")
|
||||
|
||||
example = os.path.join(root, "tts.env.example")
|
||||
if not os.path.isfile(example):
|
||||
if os.path.isfile(os.path.join(root, "tts.env")):
|
||||
# 实证过这种踩法：用户把仓库里的 tts.env.example **改名**成 tts.env 去填 key，
|
||||
# 于是模板没了、仓库里多了一份（被忽略的）密钥文件。给个能指向原因的说法。
|
||||
fails.append("secret: 缺 tts.env.example 模板，但同目录有 tts.env —— "
|
||||
"疑似把模板文件改名成了 tts.env。请恢复 tts.env.example"
|
||||
"（模板要留在仓库），tts.env 另行复制")
|
||||
else:
|
||||
fails.append("secret: 缺 tts.env.example 模板（用户没有可照抄的密钥模板）")
|
||||
|
||||
# 真实密钥形态：非空赋值 / AKLT 前缀
|
||||
SECRET_ASSIGN = re.compile(
|
||||
r"^\s*(VOLC_API_KEY|VOLC_ACCESS_KEY|X_Api_Key|X-Api-Key)\s*[=:]\s*[\"']?([^\s\"'#]+)",
|
||||
re.M)
|
||||
AKLT = re.compile(r"AKLT[A-Za-z0-9_\-]{8,}")
|
||||
SKIP_DIRS = {".git", "node_modules", "__pycache__", "dist", ".venv", "venv"}
|
||||
SKIP_EXT = {".mp4", ".mp3", ".wav", ".png", ".jpg", ".jpeg", ".ttf", ".otf",
|
||||
".woff", ".woff2", ".zip", ".ico"}
|
||||
hits: list[str] = []
|
||||
for dirpath, dirnames, filenames in os.walk(root):
|
||||
dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
|
||||
for fn in filenames:
|
||||
if os.path.splitext(fn)[1].lower() in SKIP_EXT:
|
||||
continue
|
||||
p = os.path.join(dirpath, fn)
|
||||
rel = os.path.relpath(p, root)
|
||||
# tts.env 本体跳过：它是用户本地文件，本检查只保证它不入库
|
||||
if fn in ("tts.env",) or rel in ("tts.env",):
|
||||
continue
|
||||
try:
|
||||
body = read(p)
|
||||
except (UnicodeDecodeError, OSError):
|
||||
continue
|
||||
for m in AKLT.finditer(body):
|
||||
hits.append(f"{rel}: AKLT 形态 token")
|
||||
if fn.endswith(".example"):
|
||||
continue
|
||||
for m in SECRET_ASSIGN.finditer(body):
|
||||
if m.group(2).strip(): # 有值才算泄露，空模板是合规的
|
||||
hits.append(f"{rel}: {m.group(1)} 有非空值")
|
||||
if hits:
|
||||
for h in sorted(set(hits)):
|
||||
fails.append(f"secret: 疑似真实密钥 —— {h}")
|
||||
else:
|
||||
print(f"{OK} 密钥防线：仓库内未发现真实密钥（模板里的空赋值不算）")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--root", default=None, help="仓库根目录（默认 = 本脚本所在技能的根）")
|
||||
@@ -173,6 +245,7 @@ def main() -> int:
|
||||
count = check_catalog(root, fails)
|
||||
check_catalog_count(root, count, fails)
|
||||
check_no_remote_assets(root, fails)
|
||||
check_no_secrets(root, fails)
|
||||
|
||||
print("-" * 40)
|
||||
if fails:
|
||||
|
||||
@@ -59,6 +59,9 @@ def main() -> int:
|
||||
"order": [], # 写完 narration.json 后把 id 按顺序填进来
|
||||
"theme": "violet",
|
||||
"progress": True,
|
||||
# 配音引擎：edge = 免费免密钥；volcano = 火山引擎语音合成 2.0（需 tts.env）。
|
||||
# ★ 建项目后先问用户用哪个 —— python <skill>/scripts/tts_setup.py --project .
|
||||
"provider": "edge",
|
||||
"voice": "zh-CN-YunxiNeural" if args.lang == "zh" else "en-US-GuyNeural",
|
||||
"rate": "+8%",
|
||||
}
|
||||
|
||||
@@ -54,6 +54,14 @@ def main() -> int:
|
||||
order = pj.get("order") or []
|
||||
gap = args.gap if args.gap >= 0 else float(pj.get("gap", 0.35))
|
||||
|
||||
if not order:
|
||||
# 不拦这一下的话，下游 ffmpeg 会报 `Failed to set value ';concat=n=0:...'`
|
||||
# —— 看不出根因在哪。直接说清楚该改哪个文件的哪个字段。
|
||||
print("✗ project.json 的 order 是空的 —— 它是场景顺序表，先填上再跑。\n"
|
||||
" 形如：\"order\": [\"intro\", \"point1\", \"ending\"]（= narration.json 里 id 的顺序）",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
|
||||
man_path = os.path.join(proj, "audio-manifest.json")
|
||||
if not os.path.exists(man_path):
|
||||
print("✗ 先跑 tts_build.py（缺 audio-manifest.json）", file=sys.stderr)
|
||||
|
||||
+129
-26
@@ -1,7 +1,19 @@
|
||||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
tts_build.py —— html-explainer 的配音与时间轴数据源（edge-tts）。
|
||||
tts_build.py —— html-explainer 的配音与时间轴数据源。
|
||||
|
||||
【两个 TTS 引擎】`--provider` / 环境变量 TTS_PROVIDER / project.json 的 provider 字段
|
||||
（优先级从左到右）。**跑之前先问用户用哪个**（SKILL.md 确认点 3）：
|
||||
|
||||
edge 默认。edge-tts 云端合成，免费、免密钥、有词级边界。
|
||||
VOICE 默认 zh-CN-YunxiNeural（云希）。
|
||||
volcano 火山引擎（豆包）语音合成 2.0。音质更好，**需要 API Key**。
|
||||
密钥由 scripts/tts_volcano.py 从 tts.env 读取 —— 本文件从不接触密钥值。
|
||||
音色默认 zh_male_m191_uranus_bigtts（云舟 2.0）。
|
||||
设置向导：python <skill>/scripts/tts_setup.py --project .
|
||||
★ 两个引擎产出的 manifest 结构完全一致（boundaries 都是「秒 + 原始坐标系」），
|
||||
timeline_build.py / subs.py / 渲染器零改动。
|
||||
|
||||
【血统与口径】工程化外壳移植自 anything2explainer 的 tts_build.py（经
|
||||
html-video-workbuddy-driver 的 tts_edges.py 二次实战），核心五件事：
|
||||
@@ -10,7 +22,7 @@ html-video-workbuddy-driver 的 tts_edges.py 二次实战），核心五件事
|
||||
② 每次合成 asyncio.wait_for 硬超时 45s —— edge-tts 的 websocket 会
|
||||
偶发**永久挂起**（不抛错不返回零日志），必须把挂死变成可重试失败
|
||||
③ 指数退避重试 4 次（微软端点连续请求会限流抛 NoAudioReceived）
|
||||
④ 句间 0.8s 间隔 + 磁盘缓存（sig 含 boundary 与 trim —— 参数变了旧缓存自动失效）
|
||||
④ 句间 0.8s 间隔 + 磁盘缓存（sig 含 engine/boundary 与 trim —— 参数变了旧缓存自动失效）
|
||||
⑤ 默认裁首尾静音（首回退 0.03s 保爆破音、尾保留 0.12s 保收音），
|
||||
裁完段间停顿才由 GAP 显式控制
|
||||
|
||||
@@ -19,6 +31,8 @@ html-video-workbuddy-driver 的 tts_edges.py 二次实战），核心五件事
|
||||
按字数插值。必须显式传 boundary='WordBoundary'。
|
||||
2) 相邻数字熔成大数（「沪深300」「4479.55点」→「三百万四千…」），
|
||||
数字与数字之间补中文逗号。
|
||||
※ 数字补逗号只在 edge 引擎做：它会改动送进去的文本，从而影响词边界与解说词的
|
||||
逐字对齐。火山引擎不熔读，原样送原文（对齐最稳）。
|
||||
|
||||
时长两级口径（manifest 同时写两个，下游各取所需）：
|
||||
container_duration_sec 裁完后 MP3 容器时长 → **帧时长用这个**（音画同步）
|
||||
@@ -26,7 +40,8 @@ html-video-workbuddy-driver 的 tts_edges.py 二次实战），核心五件事
|
||||
duration_sec 词边界末尾（原始坐标系）→ 仅排查用
|
||||
|
||||
用法（项目目录内）：
|
||||
python tts_build.py --project . [--rate +8%] [--voice zh-CN-YunxiNeural] [--no-trim]
|
||||
python tts_build.py --project . [--provider edge|volcano] [--rate +8%]
|
||||
[--voice zh-CN-YunxiNeural] [--no-trim]
|
||||
产出：
|
||||
audio/<id>.mp3 + audio-manifest.json
|
||||
"""
|
||||
@@ -44,6 +59,9 @@ import sys
|
||||
|
||||
import edge_tts
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
import tts_volcano # noqa: E402
|
||||
|
||||
DEFAULT_VOICE_ZH = "zh-CN-YunxiNeural" # 云希，男声
|
||||
DEFAULT_VOICE_EN = "en-US-GuyNeural"
|
||||
DEFAULT_RATE = "+8%"
|
||||
@@ -52,6 +70,8 @@ DEFAULT_PITCH = "+0Hz"
|
||||
DEFAULT_TIMEOUT = 45.0
|
||||
DEFAULT_RETRIES = 4
|
||||
RETRY_SLEEP = 0.8
|
||||
VOLCANO_TIMEOUT = 60.0
|
||||
VOLCANO_RETRIES = 3
|
||||
|
||||
TRIM_HEAD_BACKOFF = 0.03
|
||||
TRIM_TAIL_KEEP = 0.12
|
||||
@@ -152,8 +172,18 @@ def trim_edges(path: str, sr: int = 48000) -> float:
|
||||
return round(a / sr, 3)
|
||||
|
||||
|
||||
def cache_paths(text, voice, rate, volume, pitch, cache_dir, trim):
|
||||
sig = f"{voice}|{rate}|{volume}|{pitch}|{_boundary_kwarg()}|{int(trim)}|{text}"
|
||||
def _rate_to_int(rate) -> int:
|
||||
"""'+8%' / '8' / 0.08 / 8 → 8。火山引擎的 speech_rate 是整数百分比（[-50,100]）。
|
||||
|
||||
实现在 tts_volcano.parse_rate_percent —— 语速换算只保留一份，
|
||||
tts_setup 做格式清洗时用的是同一份逻辑。
|
||||
"""
|
||||
return tts_volcano.parse_rate_percent(rate)
|
||||
|
||||
|
||||
def cache_paths(text, voice, rate, volume, pitch, cache_dir, trim, provider="edge"):
|
||||
sig = (f"{provider}|{voice}|{rate}|{volume}|{pitch}|"
|
||||
f"{_boundary_kwarg() if provider == 'edge' else 'chars'}|{int(trim)}|{text}")
|
||||
h = hashlib.sha1(sig.encode("utf-8")).hexdigest()[:16]
|
||||
d = os.path.join(cache_dir, "trim") if trim else cache_dir
|
||||
os.makedirs(d, exist_ok=True)
|
||||
@@ -161,21 +191,41 @@ def cache_paths(text, voice, rate, volume, pitch, cache_dir, trim):
|
||||
|
||||
|
||||
async def synth(text, out_path, voice, rate, volume=DEFAULT_VOLUME, pitch=DEFAULT_PITCH,
|
||||
cache_dir="", timeout=DEFAULT_TIMEOUT, retries=DEFAULT_RETRIES, trim=True) -> dict:
|
||||
cache_dir="", timeout=None, retries=None, trim=True,
|
||||
provider="edge", project_dir="") -> dict:
|
||||
"""合成一段。provider='edge' 走 edge-tts，'volcano' 走火山引擎（密钥由接口包自理）。"""
|
||||
os.makedirs(os.path.dirname(os.path.abspath(out_path)) or ".", exist_ok=True)
|
||||
spoken = sanitize_for_tts(text)
|
||||
if provider == "volcano":
|
||||
# 火山不熔读相邻数字 → 原样送原文，词边界与解说词逐字对齐最稳
|
||||
spoken = text
|
||||
timeout = VOLCANO_TIMEOUT if timeout is None else timeout
|
||||
retries = VOLCANO_RETRIES if retries is None else retries
|
||||
else:
|
||||
spoken = sanitize_for_tts(text)
|
||||
timeout = DEFAULT_TIMEOUT if timeout is None else timeout
|
||||
retries = DEFAULT_RETRIES if retries is None else retries
|
||||
|
||||
cache_mp3 = cache_js = ""
|
||||
if cache_dir:
|
||||
cache_mp3, cache_js = cache_paths(text, voice, rate, volume, pitch, cache_dir, trim)
|
||||
cache_mp3, cache_js = cache_paths(text, voice, rate, volume, pitch, cache_dir,
|
||||
trim, provider=provider)
|
||||
if os.path.exists(cache_mp3) and os.path.exists(cache_js):
|
||||
bounds = json.load(open(cache_js, encoding="utf-8"))
|
||||
cached = json.load(open(cache_js, encoding="utf-8"))
|
||||
# 缓存里必须连「首裁了多少」一起存。词边界是原始坐标系，下游 subs.py 靠
|
||||
# lead_cut_sec 平移；命中缓存时若把它当 0，重跑出来的字幕会比首跑晚约一帧
|
||||
# （实测 0.037s）。见 lessons.md #51。
|
||||
if isinstance(cached, dict):
|
||||
bounds = cached.get("boundaries") or []
|
||||
head_cut = float(cached.get("lead_cut_sec") or 0.0)
|
||||
else: # 旧版缓存是裸列表，没有首裁记录
|
||||
bounds = cached
|
||||
head_cut = 0.0
|
||||
with open(cache_mp3, "rb") as f:
|
||||
open(out_path, "wb").write(f.read())
|
||||
dur = bounds[-1]["offset_sec"] + bounds[-1]["duration_sec"] if bounds else 0.0
|
||||
return _result(text, spoken, out_path, voice, rate, bounds, dur, 0.0, trim)
|
||||
return _result(text, spoken, out_path, voice, rate, bounds, dur, head_cut, trim)
|
||||
|
||||
async def _once():
|
||||
async def _once_edge():
|
||||
kw = {}
|
||||
b = _boundary_kwarg()
|
||||
if b != "n/a":
|
||||
@@ -196,10 +246,28 @@ async def synth(text, out_path, voice, rate, volume=DEFAULT_VOLUME, pitch=DEFAUL
|
||||
raise RuntimeError("empty audio stream")
|
||||
return bytes(audio), bounds
|
||||
|
||||
# 接口包在「要了字幕却没拿到时间戳」时会返回 warning；必须往上抛，
|
||||
# 否则下游只能看到「没有词边界」，排查时不知道是音色不支持还是接口出问题。
|
||||
warns: list[str] = []
|
||||
|
||||
async def _once_volcano():
|
||||
# 同步 HTTP 调用丢到线程里；接口包负责读 tts.env、脱敏、切片与重试
|
||||
r = await asyncio.to_thread(
|
||||
tts_volcano.synthesize, spoken, voice, _rate_to_int(rate),
|
||||
"mp3", 24000, 160000, timeout, 1, None, project_dir)
|
||||
if r.get("warning"):
|
||||
warns.append(str(r["warning"]))
|
||||
return r["audio"], r["boundaries"]
|
||||
|
||||
_once = _once_volcano if provider == "volcano" else _once_edge
|
||||
|
||||
last: Exception | None = None
|
||||
for attempt in range(retries):
|
||||
try:
|
||||
audio, bounds = await asyncio.wait_for(_once(), timeout=timeout)
|
||||
audio, bounds = await asyncio.wait_for(_once(), timeout=timeout + 15)
|
||||
for w in warns:
|
||||
print(f" ⚠ {w}", file=sys.stderr)
|
||||
warns.clear()
|
||||
with open(out_path, "wb") as f:
|
||||
f.write(audio)
|
||||
await asyncio.sleep(RETRY_SLEEP)
|
||||
@@ -207,16 +275,27 @@ async def synth(text, out_path, voice, rate, volume=DEFAULT_VOLUME, pitch=DEFAUL
|
||||
if cache_dir:
|
||||
with open(cache_mp3, "wb") as f:
|
||||
f.write(open(out_path, "rb").read())
|
||||
json.dump(bounds, open(cache_js, "w", encoding="utf-8"), ensure_ascii=False)
|
||||
json.dump({"boundaries": bounds, "lead_cut_sec": round(head_cut, 4)},
|
||||
open(cache_js, "w", encoding="utf-8"), ensure_ascii=False)
|
||||
dur = bounds[-1]["offset_sec"] + bounds[-1]["duration_sec"] if bounds else 0.0
|
||||
return _result(text, spoken, out_path, voice, rate, bounds, dur, head_cut, trim)
|
||||
except Exception as e: # noqa: BLE001
|
||||
last = e
|
||||
print(f" [retry {attempt + 1}/{retries}] {type(e).__name__}: {e}", file=sys.stderr, flush=True)
|
||||
if getattr(e, "retryable", True) is False:
|
||||
break # 永久性错误（密钥/音色/参数），重试是白等
|
||||
await asyncio.sleep(1.5 * (attempt + 1))
|
||||
raise SystemExit(
|
||||
f"edge-tts 连续 {retries} 次失败：{type(last).__name__}: {last}\n"
|
||||
f"已合成段落走缓存不会重复耗时，稍后重跑即可。")
|
||||
label = "火山引擎" if provider == "volcano" else "edge-tts"
|
||||
if getattr(last, "retryable", True) is False:
|
||||
# 永久性错误（密钥/音色/参数）：只试了一次就别谎报「连续 N 次失败」
|
||||
detail = f"{label}：{last}"
|
||||
else:
|
||||
detail = f"{label} 连续 {attempt + 1} 次失败：{type(last).__name__}: {last}"
|
||||
if provider == "volcano":
|
||||
# 抛普通异常（不是 SystemExit）：SystemExit 不是 Exception 子类，
|
||||
# 会被 run() 里给火山准备的友好提示漏掉，用户就只看到一串原始报错。
|
||||
raise tts_volcano.VolcanoTTSError(detail)
|
||||
raise SystemExit(detail + "\n已合成段落走缓存不会重复耗时，稍后重跑即可。")
|
||||
|
||||
|
||||
def _result(text, spoken, out_path, voice, rate, bounds, dur, head_cut, trimmed) -> dict:
|
||||
@@ -251,18 +330,39 @@ async def run(args) -> int:
|
||||
if isinstance(narration, dict):
|
||||
narration = narration.get("items") or []
|
||||
|
||||
voice = args.voice or pj.get("voice") or DEFAULT_VOICE_ZH
|
||||
rate = args.rate or pj.get("rate") or DEFAULT_RATE
|
||||
# 引擎优先级：命令行 --provider > 环境变量 TTS_PROVIDER > project.json
|
||||
provider = (args.provider or os.environ.get("TTS_PROVIDER")
|
||||
or pj.get("provider") or "edge").strip().lower()
|
||||
if provider not in ("edge", "volcano"):
|
||||
print(f"✗ 未知 provider：{provider}（只支持 edge / volcano）", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
if provider == "volcano":
|
||||
voice = args.voice or pj.get("voice") or tts_volcano.DEFAULT_VOICE
|
||||
rate = args.rate or pj.get("rate") or 0
|
||||
else:
|
||||
voice = args.voice or pj.get("voice") or DEFAULT_VOICE_ZH
|
||||
rate = args.rate or pj.get("rate") or DEFAULT_RATE
|
||||
|
||||
out_dir = os.path.join(proj, "audio")
|
||||
cache = os.path.join(out_dir, "cache")
|
||||
results = []
|
||||
print(f"[tts] 引擎 {provider} · 音色 {voice} · 语速 {rate}", file=sys.stderr)
|
||||
|
||||
for item in narration:
|
||||
key, text = item["id"], item["text"]
|
||||
r = await synth(text, os.path.join(out_dir, f"{key}.mp3"),
|
||||
voice=item.get("voice", voice), rate=item.get("rate", rate),
|
||||
cache_dir="" if args.no_cache else cache,
|
||||
trim=not args.no_trim)
|
||||
try:
|
||||
r = await synth(text, os.path.join(out_dir, f"{key}.mp3"),
|
||||
voice=item.get("voice", voice), rate=item.get("rate", rate),
|
||||
cache_dir="" if args.no_cache else cache,
|
||||
trim=not args.no_trim, provider=provider, project_dir=proj)
|
||||
except Exception as e: # noqa: BLE001
|
||||
if provider == "volcano":
|
||||
print(f"✗ [{key}] 火山引擎合成失败：\n{e}\n"
|
||||
f" 排查：python <skill>/scripts/tts_setup.py --project . --check",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
raise
|
||||
r["id"] = key
|
||||
results.append(r)
|
||||
print(f" [{key}] {r['bytes']:>8}B 容器 {r['container_duration_sec']:>7.3f}s "
|
||||
@@ -270,10 +370,11 @@ async def run(args) -> int:
|
||||
f"bounds={r['boundary_count']}", file=sys.stderr)
|
||||
|
||||
manifest = {
|
||||
"voice": voice, "rate": rate,
|
||||
"provider": provider, "voice": voice, "rate": rate,
|
||||
"trimmed": not args.no_trim,
|
||||
"engine": f"edge-tts {edge_tts.__version__}",
|
||||
"boundary_mode": _boundary_kwarg(),
|
||||
"engine": ("volcano doubao-tts-2.0 (seed-tts-2.0)" if provider == "volcano"
|
||||
else f"edge-tts {edge_tts.__version__}"),
|
||||
"boundary_mode": _boundary_kwarg() if provider == "edge" else "char-timestamps",
|
||||
"items": results,
|
||||
}
|
||||
mp = os.path.join(proj, "audio-manifest.json")
|
||||
@@ -285,8 +386,10 @@ async def run(args) -> int:
|
||||
|
||||
|
||||
def main() -> int:
|
||||
p = argparse.ArgumentParser(description="html-explainer 配音合成（edge-tts）")
|
||||
p = argparse.ArgumentParser(description="html-explainer 配音合成（edge-tts / 火山引擎）")
|
||||
p.add_argument("--project", default=".")
|
||||
p.add_argument("--provider", default="", choices=["", "edge", "volcano"],
|
||||
help="edge=免费免密钥（默认）；volcano=火山引擎语音合成 2.0（需 tts.env）")
|
||||
p.add_argument("--voice", default="")
|
||||
p.add_argument("--rate", default="")
|
||||
p.add_argument("--no-trim", action="store_true", help="不裁首尾静音（不建议）")
|
||||
|
||||
@@ -0,0 +1,335 @@
|
||||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
tts_setup.py —— 配音方案设置向导（选 TTS 引擎 → 配密钥 → 测连接 → 选音色）。
|
||||
|
||||
【它在流程里的位置】SKILL.md 的「确认点 3」要求先问用户用哪个 TTS。
|
||||
本脚本把那次对话落成可复现的三步，并保证**密钥永不经过对话窗口**：
|
||||
|
||||
① 选方案 edge-tts（免费、免密钥、开箱可用） / 火山引擎语音合成 2.0（音质更好，需 API Key）
|
||||
② 配密钥 选火山但缺 tts.env → 生成带注释的空模板 → 打印指引 → 退出（NEXT_ACTION=fill_env）
|
||||
用户填好回来说一声 → 重跑本脚本（或 --check）→ 测连接
|
||||
③ 选音色 列出内置常用音色（可自定义 ID）→ 写进 project.json
|
||||
|
||||
【密钥纪律】本脚本**从不打印、不落盘、不回显**密钥值；状态摘要走 tts_volcano.describe_env()
|
||||
（内部已脱敏）。也不会因为测连接失败而把密钥打进日志。
|
||||
|
||||
用法：
|
||||
python tts_setup.py --project . --status # 当前配置 + 脱敏密钥状态
|
||||
python tts_setup.py --project . --provider volcano # 选火山（缺 env 则生成模板后退出）
|
||||
python tts_setup.py --project . --list-voices # 列出候选音色
|
||||
python tts_setup.py --project . --check # 测连接（火山走真合成；edge 查依赖）
|
||||
python tts_setup.py --project . --provider volcano --voice "解说小明 2.0" # 一步到位
|
||||
python tts_setup.py --project . # 交互式（人在终端时用）
|
||||
|
||||
退出码：0 完成；2 = 需要用户手工填 tts.env 后再来；1 = 出错。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
import tts_volcano # noqa: E402
|
||||
|
||||
ENV_FILENAME = "tts.env"
|
||||
ENV_TEMPLATE = """\
|
||||
# ---------------------------------------------------------------
|
||||
# 火山引擎（豆包）语音合成 2.0 —— 密钥配置
|
||||
# 本文件由 tts_setup.py 生成，已被 .gitignore 忽略，不会进 git 仓库。
|
||||
# ★ agent 不需要、也不应该读取本文件；接口包 scripts/tts_volcano.py 会自己读。
|
||||
# ---------------------------------------------------------------
|
||||
|
||||
# 【必填】API Key —— 火山引擎控制台 → 语音技术 → API Key 管理
|
||||
# https://console.volcengine.com/speech/new/setting/apikeys
|
||||
VOLC_API_KEY=
|
||||
|
||||
# 资源 ID：seed-tts-2.0 = 预置音色；seed-icl-2.0 = 声音复刻音色
|
||||
VOLC_RESOURCE_ID=seed-tts-2.0
|
||||
|
||||
# 【可选】旧版鉴权：若你拿到的是 APP ID + Access Token 而不是 API Key，填这两项
|
||||
VOLC_APP_ID=
|
||||
VOLC_ACCESS_KEY=
|
||||
"""
|
||||
|
||||
# edge-tts 常用音色（名称, voice, 说明）。完整列表：edge-tts --list-voices
|
||||
EDGE_VOICES: list[tuple[str, str, str]] = [
|
||||
("云希（默认）", "zh-CN-YunxiNeural", "中文男声 · 年轻，解说常用"),
|
||||
("云健", "zh-CN-YunjianNeural", "中文男声 · 浑厚，纪录片感"),
|
||||
("晓晓", "zh-CN-XiaoxiaoNeural", "中文女声 · 通用"),
|
||||
("晓伊", "zh-CN-XiaoyiNeural", "中文女声 · 甜"),
|
||||
("云扬", "zh-CN-YunyangNeural", "中文男声 · 新闻播报"),
|
||||
("云夏", "zh-CN-YunxiaNeural", "中文男声 · 少年"),
|
||||
("辽宁小北", "zh-CN-liaoning-XiaobeiNeural", "中文女声 · 东北方言"),
|
||||
("Guy（英文）", "en-US-GuyNeural", "英文男声"),
|
||||
("Aria（英文）", "en-US-AriaNeural", "英文女声"),
|
||||
]
|
||||
|
||||
EDGE_DEFAULT_ZH = "zh-CN-YunxiNeural"
|
||||
EDGE_DEFAULT_EN = "en-US-GuyNeural"
|
||||
|
||||
|
||||
def catalog(provider: str) -> list[tuple[str, str, str]]:
|
||||
return tts_volcano.VOICES if provider == "volcano" else EDGE_VOICES
|
||||
|
||||
|
||||
def resolve_voice(provider: str, token: str) -> str:
|
||||
"""名称 / 序号 / 原始 ID 都能接受。返回 "" 表示「用户没指定」。"""
|
||||
token = (token or "").strip()
|
||||
if not token:
|
||||
return ""
|
||||
if provider == "volcano":
|
||||
# 交给接口包解析，避免两处规则各写一份、慢慢跑偏
|
||||
return tts_volcano.resolve_voice_token(token)
|
||||
cat = catalog(provider)
|
||||
if token.isdigit() and 1 <= int(token) <= len(cat):
|
||||
return cat[int(token) - 1][1]
|
||||
for name, vid, _ in cat:
|
||||
if token == name or token == vid:
|
||||
return vid
|
||||
# 允许带括注的名字，如「云希（默认）」
|
||||
for name, vid, _ in cat:
|
||||
if name.startswith(token) or token.startswith(name):
|
||||
return vid
|
||||
return token # 自定义 ID 原样返回
|
||||
|
||||
|
||||
def _normalize_rate(provider: str, value) -> object:
|
||||
"""把语速写成该引擎的表示法：火山 = int 百分比，edge = '+N%'。
|
||||
|
||||
new_project.py 默认写 '+8%'（那是 edge 的格式）。用户后来切到火山时若不清洗，
|
||||
火山项目的 project.json 里就一直留着 edge 字符串 —— 下游换算虽然能兜住，
|
||||
但 --status 打出来会让人以为配错了引擎。
|
||||
"""
|
||||
if value is None or value == "":
|
||||
return 0 if provider == "volcano" else "+8%"
|
||||
pct = tts_volcano.parse_rate_percent(value)
|
||||
if provider == "volcano":
|
||||
return max(-50, min(100, pct))
|
||||
return f"{pct:+d}%"
|
||||
|
||||
|
||||
def print_voices(provider: str) -> None:
|
||||
label = "火山引擎语音合成 2.0" if provider == "volcano" else "edge-tts"
|
||||
print(f"{label} 候选音色：")
|
||||
for i, (name, vid, note) in enumerate(catalog(provider), 1):
|
||||
print(f" {i:>2}. {name:<22} {note}")
|
||||
print(f" {vid}")
|
||||
print(" （也可以直接给音色 ID 自定义）")
|
||||
|
||||
|
||||
def load_project(project: str) -> tuple[str, dict]:
|
||||
proj = os.path.abspath(project or ".")
|
||||
pj_path = os.path.join(proj, "project.json")
|
||||
if not os.path.isfile(pj_path):
|
||||
print(f"✗ 找不到 {pj_path}（--project 要指向视频项目目录）", file=sys.stderr)
|
||||
raise SystemExit(1)
|
||||
return proj, json.load(open(pj_path, encoding="utf-8"))
|
||||
|
||||
|
||||
def save_project(proj: str, pj: dict) -> None:
|
||||
with open(os.path.join(proj, "project.json"), "w", encoding="utf-8") as f:
|
||||
json.dump(pj, f, ensure_ascii=False, indent=2)
|
||||
|
||||
|
||||
def ensure_env_file(proj: str) -> tuple[str, bool]:
|
||||
"""返回 (路径, 是否本次新建)。已存在则原样返回，**不读内容**。
|
||||
|
||||
优先级与 tts_volcano.env_candidates() 保持一致：项目目录 → 技能目录 → 新建于项目目录。
|
||||
不按同序查找会出现「向导认技能目录的、接口包认项目目录的」这种静默错位。
|
||||
"""
|
||||
project_env = os.path.join(proj, ENV_FILENAME)
|
||||
if os.path.isfile(project_env):
|
||||
return project_env, False
|
||||
skill_env = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), ENV_FILENAME)
|
||||
if os.path.isfile(skill_env):
|
||||
return skill_env, False
|
||||
with open(project_env, "w", encoding="utf-8") as f:
|
||||
f.write(ENV_TEMPLATE)
|
||||
return project_env, True
|
||||
|
||||
|
||||
def cmd_status(proj: str, pj: dict) -> int:
|
||||
provider = pj.get("provider") or os.environ.get("TTS_PROVIDER") or "edge"
|
||||
rate = pj.get("rate")
|
||||
if rate is None or rate == "":
|
||||
rate_shown = "(未设置，将用默认)"
|
||||
elif provider == "volcano":
|
||||
rate_shown = f"{rate}%（快慢百分比，0 = 原速）"
|
||||
else:
|
||||
rate_shown = str(rate)
|
||||
print(f"当前方案：{provider}")
|
||||
print(f"当前音色：{pj.get('voice') or '(未设置，将用默认)'}")
|
||||
print(f"当前语速：{rate_shown}")
|
||||
if provider == "volcano":
|
||||
st = tts_volcano.describe_env(proj)
|
||||
if st["status"] == "ok":
|
||||
print(f"tts.env ：已就绪 {st['env_file']}")
|
||||
print(f"密钥 ：{st['key_masked']}（脱敏显示）· 鉴权 {st['auth']} · 资源 {st['resource_id']}")
|
||||
else:
|
||||
print(f"tts.env ：未就绪 —— {st['detail']}")
|
||||
else:
|
||||
try:
|
||||
import edge_tts # noqa: F401
|
||||
print("edge-tts：已安装（免费，无需密钥）")
|
||||
except ImportError:
|
||||
print("edge-tts：未安装 → pip install edge-tts")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_check(proj: str, provider: str, voice: str) -> int:
|
||||
print(f"测试方案：{provider}", flush=True) # flush：否则与 stderr 的错误信息交错乱序
|
||||
if provider == "volcano":
|
||||
st = tts_volcano.check(proj, 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']} · 密钥 {st['key_masked']}")
|
||||
return 0
|
||||
print(f"✗ 火山接口未通过（{st['stage']}）\n{st['detail']}", file=sys.stderr)
|
||||
return 1
|
||||
try:
|
||||
import edge_tts # noqa: F401
|
||||
except ImportError:
|
||||
print("✗ edge-tts 未安装：pip install edge-tts", file=sys.stderr)
|
||||
return 1
|
||||
if shutil.which("ffmpeg") is None:
|
||||
try:
|
||||
import imageio_ffmpeg # noqa: F401
|
||||
except ImportError:
|
||||
print("✗ 缺 ffmpeg（edge 引擎裁静音/量时长要用）：pip install imageio-ffmpeg",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
print("✓ edge-tts 与 ffmpeg 就绪（edge 不需要密钥）")
|
||||
return 0
|
||||
|
||||
|
||||
def interactive_ask(prompt: str, options: list[tuple[str, str]], default_idx: int = 0) -> str:
|
||||
print(prompt)
|
||||
for i, (label, note) in enumerate(options, 1):
|
||||
mark = "（默认）" if i - 1 == default_idx else ""
|
||||
print(f" {i}. {label}{mark} {note}")
|
||||
while True:
|
||||
raw = input(f"选择 [1-{len(options)}]，直接回车用默认：").strip()
|
||||
if not raw:
|
||||
return options[default_idx][0]
|
||||
if raw.isdigit() and 1 <= int(raw) <= len(options):
|
||||
return options[int(raw) - 1][0]
|
||||
print(" 输入不在范围内，再试一次。")
|
||||
|
||||
|
||||
def run(args) -> int:
|
||||
proj, pj = load_project(args.project)
|
||||
provider = (args.provider or os.environ.get("TTS_PROVIDER")
|
||||
or pj.get("provider") or "").lower()
|
||||
|
||||
if args.status:
|
||||
return cmd_status(proj, pj)
|
||||
|
||||
# ---- ① 选方案 ----
|
||||
if provider not in ("edge", "volcano"):
|
||||
if not sys.stdin.isatty():
|
||||
print("当前未设置配音方案。可选：", file=sys.stderr)
|
||||
print(" --provider edge 免费、免密钥、开箱可用（默认）", file=sys.stderr)
|
||||
print(" --provider volcano 火山引擎语音合成 2.0，音质更好，需 API Key", file=sys.stderr)
|
||||
print("NEXT_ACTION=ask_user_provider")
|
||||
return 1
|
||||
choice = interactive_ask(
|
||||
"配音用哪个 TTS？",
|
||||
[("edge-tts", "免费、免密钥、开箱可用"),
|
||||
("火山引擎语音合成 2.0", "音质更好、需 API Key（约 1 分钟配置）")])
|
||||
provider = "edge" if choice.startswith("edge") else "volcano"
|
||||
|
||||
# ★ 方案一旦确定立刻落盘。用户填 key 会中断流程，若不落盘，
|
||||
# 回来跑 --check 时 project.json 还写着 edge，会静默去测 edge（踩过这个坑）。
|
||||
if pj.get("provider") != provider:
|
||||
pj["provider"] = provider
|
||||
save_project(proj, pj)
|
||||
|
||||
# ---- ② 密钥（仅火山） ----
|
||||
if provider == "volcano":
|
||||
env_path, created = ensure_env_file(proj)
|
||||
if created:
|
||||
print(f"✓ 已生成密钥模板：{env_path}")
|
||||
print(" （该文件已被 .gitignore 忽略，不会进仓库；我也不会读它的内容）")
|
||||
print()
|
||||
print("请手动完成两步：")
|
||||
print(" 1. 打开上面这个文件，把 VOLC_API_KEY= 后面填上你的 API Key")
|
||||
print(" API Key 获取：https://console.volcengine.com/speech/new/setting/apikeys")
|
||||
print(" 2. 存盘后回来告诉我「填好了」，我再测连接并继续")
|
||||
print()
|
||||
print("NEXT_ACTION=fill_env")
|
||||
return 2
|
||||
voice_for_check = resolve_voice("volcano", args.voice or pj.get("voice", ""))
|
||||
st = tts_volcano.check(proj, voice_for_check)
|
||||
if not st["ok"]:
|
||||
print(f"✗ 密钥已存在但连接未通过（{st['stage']}）：\n{st['detail']}", file=sys.stderr)
|
||||
print(f" tts.env：{env_path}", file=sys.stderr)
|
||||
return 1
|
||||
print(f"✓ 连接正常 · 音色 {st['voice']} · 密钥 {st['key_masked']}")
|
||||
|
||||
# ---- ③ 选音色 ----
|
||||
name_or_id = args.voice or ""
|
||||
if not name_or_id:
|
||||
if not sys.stdin.isatty():
|
||||
default = tts_volcano.DEFAULT_VOICE if provider == "volcano" else EDGE_DEFAULT_ZH
|
||||
print(f"未指定音色，使用默认 {default}")
|
||||
print("NEXT_ACTION=ask_user_voice")
|
||||
name_or_id = default
|
||||
else:
|
||||
print_voices(provider)
|
||||
name_or_id = input("音色（填序号 / 名称 / 直接给 ID，回车用默认）：").strip() or ""
|
||||
|
||||
default_voice = tts_volcano.DEFAULT_VOICE if provider == "volcano" else EDGE_DEFAULT_ZH
|
||||
voice = resolve_voice(provider, name_or_id) or default_voice
|
||||
|
||||
# ---- 写回 project.json ----
|
||||
pj["provider"] = provider
|
||||
pj["voice"] = voice
|
||||
pj["rate"] = _normalize_rate(provider, args.rate or pj.get("rate"))
|
||||
save_project(proj, pj)
|
||||
|
||||
print()
|
||||
print(f"✓ 已写入 {os.path.join(proj, 'project.json')}")
|
||||
rate_shown = f"{pj['rate']}%（快慢百分比）" if provider == "volcano" else pj["rate"]
|
||||
print(f" 方案 {provider} · 音色 {voice} · 语速 {rate_shown}")
|
||||
if provider == "volcano":
|
||||
print(" 下一步：python <skill>/scripts/tts_build.py --project .")
|
||||
else:
|
||||
print(" 下一步：python <skill>/scripts/tts_build.py --project .")
|
||||
print("NEXT_ACTION=done")
|
||||
return 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
p = argparse.ArgumentParser(description="html-explainer 配音方案设置向导")
|
||||
p.add_argument("--project", default=".")
|
||||
p.add_argument("--provider", default="", choices=["", "edge", "volcano"])
|
||||
p.add_argument("--voice", default="")
|
||||
p.add_argument("--rate", default="")
|
||||
p.add_argument("--status", action="store_true", help="显示当前配置与脱敏密钥状态")
|
||||
p.add_argument("--check", action="store_true", help="只测连接")
|
||||
p.add_argument("--list-voices", action="store_true", help="列出候选音色")
|
||||
p.add_argument("--env-file", default="", help="显式指定 tts.env（仅本次）")
|
||||
args = p.parse_args()
|
||||
|
||||
if args.env_file:
|
||||
os.environ["TTS_ENV_FILE"] = args.env_file
|
||||
|
||||
proj, pj = load_project(args.project)
|
||||
provider = (args.provider or os.environ.get("TTS_PROVIDER")
|
||||
or pj.get("provider") or "edge").lower()
|
||||
|
||||
if args.list_voices:
|
||||
print_voices(provider)
|
||||
return 0
|
||||
if args.check:
|
||||
return cmd_check(proj, provider, resolve_voice(provider, args.voice))
|
||||
return run(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,598 @@
|
||||
#!/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())
|
||||
@@ -0,0 +1,22 @@
|
||||
# ---------------------------------------------------------------
|
||||
# 火山引擎（豆包）语音合成 2.0 —— 密钥配置【模板】
|
||||
#
|
||||
# 用法：把本文件复制成 tts.env 再填，不要直接改本文件：
|
||||
# cp tts.env.example tts.env # 放到本技能目录，或某个视频项目目录
|
||||
# 注意别把本文件「改名」成 tts.env —— 本文件是要留在仓库里的模板，
|
||||
# 改名会让仓库少掉模板（check_integrity.py 会报错）。
|
||||
#
|
||||
# 真实 tts.env 已被 .gitignore 忽略，不会进 git 仓库。
|
||||
# ★ agent 不需要、也不应该读取 tts.env；接口包 scripts/tts_volcano.py 会自己读。
|
||||
# ---------------------------------------------------------------
|
||||
|
||||
# 【必填】API Key —— 火山引擎控制台 → 语音技术 → API Key 管理
|
||||
# https://console.volcengine.com/speech/new/setting/apikeys
|
||||
VOLC_API_KEY=
|
||||
|
||||
# 资源 ID：seed-tts-2.0 = 预置音色；seed-icl-2.0 = 声音复刻音色
|
||||
VOLC_RESOURCE_ID=seed-tts-2.0
|
||||
|
||||
# 【可选】旧版鉴权：若你拿到的是 APP ID + Access Token 而不是 API Key，填这两项
|
||||
VOLC_APP_ID=
|
||||
VOLC_ACCESS_KEY=
|
||||
Reference in new issue
Block a user