Files
ai-manju/README.md
T
rong a8e10b7b17 fix: 字幕按实测发声段对齐 + 静音镜/包装踩坑 (v1.2.1)
- 纠正 render.md/pitfalls.md「按设计时间缩放字幕」错误做法,改为只认实测发声段
- 新增 scripts/align_subtitles.py(泛化对齐工具,配置外置、支持 dump-segs/init-config/dry-run)
- render_native.py 加 --ass 参数,读对齐 ASS 不被内置设计时间轴覆盖
- pitfalls/native-av/README/SKILL 补六条踩坑;install.sh 清单同步
2026-11-19 17:14:14 +08:00

214 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ai-manju — 同事上手指南
一条流水线把剧本做成 AI 漫剧 / 短剧成片:**源节拍 → 分镜 → 首帧图 → 图生视频(台词镜走音画同出)→ 配音/字幕 → 缝合 → 归档**。
特点是文件驱动、机器可校验、任何一镜可单独重做。工具脚本只用 Python 标准库。
> **2026-11-19 v1.2.1**:新增 `align_subtitles.py`(**字幕按实测发声段对齐**,修「字幕与口型错位」)——
> h3v3 `[Audio]` 的秒数只是设计值,照抄当字幕时间轴会早 0.5–1.5 s。`render_native.py` 新增 `--ass` 读对齐后的 ASS。
> 同时沉淀三条踩坑:静音镜自发吐音需 `volumedetect` 核验后静音、包装叠字统一 `BorderStyle=1` 免蓝底白字、角标文案勿与对白重复。详见 [render.md](references/render.md)「字幕对齐」。
>
> **2026-11-19 v1.2.0 关键变化**:补齐原生音画镜的**出片闭环**。
> 新增 `render_native.py`(台词镜专用缝合器:直拼保留原生音轨、烧 ASS 字幕、可选瑕疵遮盖,不叠 TTS / 不加落版 / 保持 576×1024)、
> `fetch_t2i.py`(出图脚本被杀后按 pid 从服务端救回单图);修复 `queue_h3_native.py --check` 把「被中断/error」误判为"在队"的 bug。
> 缝合前先分流:台词镜走 `render_native.py`,无音轨镜走 `render.py`,两者不要混。见 [references/render.md](references/render.md)。
>
> **2026-11-17 v1.1.0**:人物说话的镜头**不再事后贴嘴**。
> 走 `192.168.1.23:30121`(DCU K100 64 GB)的 MiniMax H3 `fl2va` **音画同出**:首帧锁图 I2V,
> 画面 / 人声 / 环境音一次出,口型模型内对齐。`submit_h3_native.py` / `queue_h3_native.py` / `fetch_h3_native.py`
> 与 [references/native-av.md](references/native-av.md)。Wav2Lip / LatentSync / InfiniteTalk 三条事后贴嘴路线已实测否掉。
---
## 1. 安装(一次性)
把本目录放到 `~/.agents/skills/ai-manju/`,然后:
```bash
cd ~/.agents/skills/ai-manju
chmod +x install.sh
./install.sh # 软链到 ~/.claude/skills、~/.workbuddy/skills、~/.qwenworkcn/skills
./install.sh --check # 随时只读体检
```
如果不用多端软链,直接把整个 `ai-manju/` 目录拷到任一 agent 的 `skills/` 下也能用。
依赖(只在配音/渲染阶段需要):
```bash
pip install --user imageio-ffmpeg # 静态 ffmpeg;不要 brew 装(macOS 12 + Homebrew 6 有 dav1d bug)
pip install --user edge-tts # 免费免密钥配音;商用授权自行核对微软条款
python3 -V # 脚本本身零第三方依赖
```
另需准备:**内网模型端点可达**(模板已预填:台词镜 `192.168.1.23:30121`,出图/静音镜 `192.168.1.30:30113`)。开工自检:
```bash
for U in 192.168.1.23:30121 192.168.1.30:30113; do
printf "%-24s" "$U"; curl -s --noproxy '*' -m 8 "http://$U/system_stats" | head -c 60; echo
done
```
明文 HTTP 会被本机代理改写成 `text/html`,curl 要 `--noproxy '*'`,Python 要 `ProxyHandler({})`。端点全表见 [references/models.md](references/models.md)。
> ⚠️ **两台机器分工(2026-11-17)**:
> `30121` = DCU K100 **64 GB**,H3 音画同出 I2V(台词镜)+ 出图 + A14B 全套权重;**禁调 `/api/free`**(会崩服务)。
> `30113` = K8s 2080Ti **22 GB**,出图 / A14B / H3 **T2V**;**该卡 I2V 必 OOM**。
> 2026-11-19 实测补:30 实为 RTX 2080 Ti / 23.1 GB 显存(4 GiB 是 cgroup 内存限),出图用 `int8_convrot`
> 但单张约 190s(DCU 23 约 52s,慢 4 倍);**连续出图后服务三个端口会整体 Connection refused**,台词镜别排这里,回退 30121。
> 旧 DCU `192.168.1.24`(30120)仍整机不可达,**与 30121 不是一台机**;embed-bge(8801)随之下线。
---
## 2. 建工作空间
```bash
mkdir my-drama && cd my-drama
python3 ~/.agents/skills/ai-manju/scripts/manju.py setup
```
`setup` 会建好目录、写入 `config/pipeline.json` 模板、把 `scripts/` 下全部脚本复制到 `tools/`(含出图救回与两条缝合器)、把模板与 schema 放到 `assets/templates/`。
接着**必须编辑 `config/pipeline.json`**:填 `workspace`、`tts.voice`。`videoModel` / `imageModel` / `textModel` / `embed` 四段已预填内网地址,按需切换(注意:`embed` 段的 8801 已随 DCU 下线,当前无可用向量服务);`cleanup` 段配导出后的服务端清理策略(默认 `auto: false`、`requireOwner: true`:只清自己发起的任务)。产物文件官方没有删除接口,把技能包 `assets/comfyui-manju-cleanup/` 拷到各端点的 `ComfyUI/custom_nodes/` 并重启即可启用扩展(不装会自动降级到 `deleteApi` / `commands`),详见 [models.md §3.4](references/models.md)。密钥绝不写进配置 —— LLM 代理走 `xop run --secret K=llm_key -- CMD < /dev/null`。
> 之后所有脚本都在工作空间根运行(`cd my-drama`)。脚本按 `MANJU_ROOT` → cwd 向上找 `config/pipeline.json` → 脚本上级 的顺序定位工作空间。
---
## 3. 做一集
```bash
# ① 骨架
python3 tools/manju.py init EP01
# ② 填内容(都是 Markdown / JSON,按文件里的提示写)
# projects/EP01/00_brief.md 任务卡:时长、冲突、角色、画风、禁忌
# projects/EP01/10_events.md 源节拍账本:一行一个 E##
# projects/EP01/20_script.md 剧本/旁白全文
# projects/EP01/30_shots.json 分镜表(单一真相源,一镜一行)
# projects/EP01/40_prompts/S01.i2v.txt 逐镜运动提示词原文(静音镜)
# projects/EP01/40_prompts/S01.h3v3.txt 逐镜五段式提示词(台词镜:含秒级台词时间轴)
# ③ 校验:ERROR 必须为 0
python3 tools/manju.py validate projects/EP01/30_shots.json
# ④ 基线资产:内网 H3-Image 出角色锚图 → assets/characters/;HUD/落版用脚本生成
python3 tools/submit_t2i.py --prompt "角色设定长描述..." --out assets/characters/ling.png
python3 tools/make_overlay.py
# ⑤ 配音(**只给无音轨镜/旁白**):生成 vo_NN.mp3 并把实测时长回填 duration
python3 tools/tts.py projects/EP01/30_shots.json
# 台词镜走音画同出,不跑 TTS、不要叠双份人声
# ⑥ 首帧图:内网 H3-Image 出图 → work/EP01/images/Sxx.png(正好是 ⑦ 读取的路径)
python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file projects/EP01/40_prompts/S01.t2i.txt
# 看 [SANITY] 行:ok(...) 才算可用;判 FAIL(纯色图)说明量化档位/端点选错了,别重跑
# (DCU 禁 int8_convrot,K8s-30113 只能用 int8_convrot)
# (也可用宿主 Agent 的图像能力,但会消耗外部积分;出图后审一遍再进 ⑦)
# ⑦ 图生视频:先审首帧,再提交(会消耗算力,先取得授权)
python3 tools/submit_i2v.py projects/EP01/30_shots.json --only S01 # 静音镜,先跑一镜验证
python3 tools/submit_i2v.py projects/EP01/30_shots.json --cleanup # 全量,每镜导出后自动清服务端
# ⑦n 台词镜(音画同出):排队 → 自检 → 取回。单镜约 90 分钟,别挂进程等
python3 tools/queue_h3_native.py --ep EP01 # 排完整集,落盘 prompt_id
python3 tools/queue_h3_native.py --ep EP01 --check # 5 分钟内做一次丢失自检(实例重启会静默清空队列)
python3 tools/fetch_h3_native.py --ep EP01 --status # 只看状态
python3 tools/fetch_h3_native.py --ep EP01 # 取回,顺手检查有没有 aac 音轨
# ⑦b 导出后清理(若没加 --cleanup,或要复核清了什么)
python3 tools/cleanup_comfyui.py --ep EP01 # 预演:逐条打印归属判定 + 将删清单
python3 tools/cleanup_comfyui.py --ep EP01 --apply # 真清(含删后复核)
python3 tools/cleanup_comfyui.py --ep EP01 --apply --free # 整批结束统一释放模型
python3 tools/cleanup_comfyui.py # 不带 --ep:连锚图/集外任务一起清
# (台账写在图片同目录,脚本会递归扫工作空间下所有 t2i_runs.json / a14b_runs.json)
# 显式清某个任务时必须带归属凭证(client_id 在 history 项 prompt[3])
python3 tools/cleanup_comfyui.py --prompt-id <pid> --endpoint http://192.168.1.30:30112 --client-id manju-i2v-ab12cd34 --apply
python3 tools/selftest_cleanup.py # 本地 mock 自检:归属/顺序/复核 26 项断言
# ⑧ 审片:首/中/末联系表;漂移镜截前段(keepSeconds)或换首帧重跑
python3 tools/review.py projects/EP01/30_shots.json --only S13,S15
# ⑨ 字幕对齐(台词镜必做:按实测发声段,别照 [Audio] 设计时间)
python3 tools/align_subtitles.py projects/EP01/30_shots.json --dump-segs
python3 tools/align_subtitles.py projects/EP01/30_shots.json --init-config work/EP01/align_config.json # 人工校准 ALIGN
python3 tools/align_subtitles.py projects/EP01/30_shots.json --config work/EP01/align_config.json --dry-run
python3 tools/align_subtitles.py projects/EP01/30_shots.json --config work/EP01/align_config.json --out work/EP01/render_native/ep.ass
# ⑩ 缝合 + 归档(按路线选脚本,别混)
python3 tools/render_native.py projects/EP01/30_shots.json --ass work/EP01/render_native/ep.ass --mask # 台词镜:直拼+烧对齐字幕
python3 tools/render.py projects/EP01/30_shots.json --name EP01_成片.mp4 # 无音轨镜/旁白镜:TTS配音缝合
python3 tools/manju.py manifest projects/EP01/30_shots.json
# 把成片信息登记到 renders/INDEX.md,计算 sha256
```
---
## 4. 脚本速查
| 脚本 | 作用 | 常用参数 |
|---|---|---|
| `manju.py` | 工作空间入口 | `setup` / `init EPxx` / `validate <shots>` / `hash-file <path>` / `manifest <shots>` |
| `validate_shots.py` | 分镜前置校验 | 由 `manju.py validate` 调用 |
| `tts.py` | edge-tts 配音 + 时长回填 | `<shots.json>` |
| `submit_t2i.py` | **内网 H3-Image 文生图**(锚图/首帧) | `--ep EP01 --shot S01 --prompt-file <p.txt>` / `--prompt` `--out` `--width` `--height` `--force` |
| `fetch_t2i.py` | 出图脚本被杀后按 pid 从服务端救回单图(含自检) | `--pid <pid> --out <png> [--host url]` |
| `submit_i2v.py` | 图生视频提交/预检/续跑(A14B,静音镜) | `<shots.json>` `--only S03` `--force` `--cleanup` |
| `submit_h3_native.py` | **H3 音画同出单镜**(台词镜,64 GB 卡) | `--ep EP01 --shot S04 --seconds 7.3` / `--length 175` `--t2v` |
| `queue_h3_native.py` | 整集排队(不等待)+ 丢失自检 | `--ep EP01` `--only S01a` `--force` `--check` |
| `fetch_h3_native.py` | 取回已完成产物 + 音轨检查 | `--ep EP01` `--status` `--only S04` |
| `cleanup_comfyui.py` | **导出后只清自己发起的任务**:归属闸门 + 扩展删产物 + 官方接口删记录 | `--ep EP01`(不带则连锚图一起清)`--shot S03` `--apply` `--prompt-id <pid> --client-id <cid>` `--purge-input` `--free` |
| `selftest_cleanup.py` | 清理链路自检(本地 mock ComfyUI,29 项断言) | 无参数 |
| `review.py` | 首/中/末审片联系表 | `<shots.json>` `--group 1` `--only S13,S15` |
| `align_subtitles.py` | **字幕对齐实测发声段**(修口型错位):测 `silencedetect` 发声段 + 逐句映射重排时间,台词原文不动 | `<shots.json>` `--dump-segs` `--init-config <path>` `--config <cfg>` `--dry-run` `--out <ep.ass>` `--package-out <path>` |
| `render_native.py` | **台词镜缝合**:直拼保留原生音轨 + 烧 ASS 字幕 + 瑕疵遮盖。**台词镜务必配 `--ass` 用对齐 ASS**,否则内置设计时间轴会错位 | `<shots.json>` `--ass <ep.ass>` `--mask` `--name <file.mp4>` |
| `render.py` | 无音轨镜缝合:配音、字幕、HUD、落版 | `<shots.json>` `--name <file.mp4>` `--crop-bottom N` |
| `make_overlay.py` | 程序化生成 HUD/落版 | 无参数 |
## 5. 关键规则(先看再动手)
1. **资产先行**:锚图/画风先定稿锁只读。I2V 只能"给首帧让它动",首帧决定上限。
2. **配音先于剪辑**:先量实测时长再回填 `duration`,禁止加快语速硬塞;改词后删旧 `vo_NN.mp3` 重生成。
3. **提示词原文留档**:`40_prompts/Sxx.i2v.txt` 一字不改;改词即换哈希、新文件不覆盖旧版。
4. **漂移按类型处理**:姿态/场景漂移用 `keepSeconds` 截前 1.2–2.5s 慢放;首帧硬伤(乱码文字、畸形手)必须换图重跑。
5. **只拼已采用片段**:`rejected` 留作候选;区分「已生成 / 已采用 / 已合成 / 已归集」。
6. **生成前必须授权**:展示对象、数量、模型、**端点**、完整提示词、参数、执行次数;"继续"和沉默不算授权。
7. **端点不照搬**:换模型先查 `/system_stats` / `/object_info`;DCU(ROCm) 与 K8s(CUDA) 节点图互不通用,明文 HTTP 一律绕代理。详见 [models.md](references/models.md)。
8. **出图后必须看 `[SANITY]`**:`submit_t2i.py` 出图后会自动做 PNG 自检(颜色数 / 亮度 / 标准差)。判 `ok(...)` 才算可用;判 FAIL(纯色图 / 全黑)说明**量化档位选错**(DCU 禁 `int8_convrot`,K8s-30113 只能用 `int8_convrot`),**不要重跑**——重跑只会再出一张纯色图。先核对 models.md §2.0 的档位表再改端点。自检未通过时脚本**自动跳过清理**,保留服务端记录与产物当排查证据。
9. **导出即清,且只清自己发起的任务**:成片拉回本地校验大小后,按台账 `clientId` + `client_id` 白名单判归属(`requireOwner=true` 时未通过一律拒绝、不调任何删除接口);再用官方标准接口(`/api/history`、`/api/queue` 的 `{"delete":[...]}`)清记录,**删后必须复核「删前有→删后无」**——200 空 body 是幂等响应,不等于删成功。产物文件官方没有删除 HTTP 路由,优先用自带扩展 `assets/comfyui-manju-cleanup/` 的 `POST /manju/cleanup/purge`(只传 pid,服务端反查 history 并二次校验归属),未装则降级 `cleanup.deleteApi` / `cleanup.commands`。**装了扩展要先删文件再删记录**(purge 依赖 history 反查)。只清服务端,本地成片/提示词/manifest 保留。用 `cleanup_comfyui.py`(默认预演,`--apply` 才删),或给提交脚本加 `--cleanup`;整批结束再加 `--free`。详见 [models.md §3.4](references/models.md)。
10. **台词不做后期贴嘴**:人物说话的画面必须由**音画同出的模型**生成(H3 `fl2va` + 首帧锁图,`30121` 64 GB)。Wav2Lip(96² 糊块)、LatentSync(环境装不下)、InfiniteTalk(78 min / 油画感 / 身份漂移)已实测否掉。见 [native-av.md](references/native-av.md)。
11. **长任务排队、不挂进程**:单镜 90 分钟级,一律「排队 → 落盘 pid → 事后取回」;`queue`/`history` 是内存态,实例重启即静默丢任务(实测 7 镜全丢),**排完 5 分钟内必须 `--check` 自检**。
详细规则按阶段读 `references/`:
- [models.md](references/models.md) — **内网模型服务与 API 全表**(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异)
- [native-av.md](references/native-av.md) — **台词镜头:音画同出**(为什么放弃 lip-sync / 节点图 / 五段式提示词 / 时长网格 / 排队取回)
- [workflow.md](references/workflow.md) — 七阶段与闸门
- [director.md](references/director.md) — 导演内核 12 铁律 + 对白写法 + I2V 提示词模板
- [storyboard.md](references/storyboard.md) — 分镜三角色与连续性
- [submit-i2v.md](references/submit-i2v.md) — 提交协议与预检
- [render.md](references/render.md) — 缝合规格
- [review.md](references/review.md) — 审片与归档
- [pitfalls.md](references/pitfalls.md) — **踩坑速查,出片前务必扫一遍**
配置模板在 `assets/`:[config.template.json](assets/config.template.json)、[shot.schema.json](assets/shot.schema.json)、[policy.template.md](assets/policy.template.md)(叙事与合规清单)。
---
## 6. 换模型 / 换后端
内置 **两个视频模型 + 一个文生图**,端点与完整节点图见 [references/models.md](references/models.md):
| 目标 | 怎么做 |
|---|---|
| 默认 A14B(静音镜) | 直接用 `submit_i2v.py`;UNET / LORA / CLIP / VAE 常量与负向提示词在脚本顶部,端点与规格在 `config/pipeline.json` |
| 台词镜(H3 音画同出) | 用 `queue_h3_native.py` / `submit_h3_native.py`,读 `config.nativeVideoModel`;**只能在 64 GB 卡(30121)跑**,别塞给 2080Ti |
| H3 T2V(只要环境音、无对白) | **不能只改 `videoModel.endpoint`**:采样节点、权重、输出节点都不同,按 models.md §4.3 另写工作流;22 GB 卡上禁 `first_frame` |
| 出图 | `submit_t2i.py` 读 `config.imageModel`;**权重名不用填**(脚本读端点 `/object_info` 自动挑);32 对齐、6 步、cfg 1.0 别乱改;出图后看 `[SANITY]` 行 |
| 非 ComfyUI 后端 | 替换 `submit_i2v.py` / `submit_h3_native.py` 的 `req()` / `build()`,其余脚本不依赖具体模型 |
**五条铁律**:换模型先查 `/system_stats` 和 `/object_info`;**I2V 看卡不看端口**(`first_frame` 只有 64 GB 的 30121 扛得住);DCU(ROCm) 与 K8s(CUDA) 的节点图互不通用;K8s 侧三个端口(30111/30112/30113)是**同一个 0.45 实例**,共用一张 2080Ti,只能串行提交;**出图量化档位不能照搬**(ROCm 只能 `w4a8`、K8s-30113 只能 `int8_convrot`,搞反了静默出纯色图)。
输出规格、音色、字幕/HUD/落版规则全部集中在 `config/pipeline.json`,不要在脚本里散落硬编码。
## 7. 出处与许可
方法论剥离自 [Toonflow](https://github.com/HBAI-Ltd/Toonflow-app)(MIT),逐字原文存于 `references/toonflow/`,许可证见 [TOONFLOW-LICENSE.txt](references/toonflow/TOONFLOW-LICENSE.txt)。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。