Files
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

18 KiB
Raw Permalink Blame History

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「字幕对齐」。

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。

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。Wav2Lip / LatentSync / InfiniteTalk 三条事后贴嘴路线已实测否掉。


1. 安装(一次性)

把本目录放到 ~/.agents/skills/ai-manju/,然后:

cd ~/.agents/skills/ai-manju
chmod +x install.sh
./install.sh            # 软链到 ~/.claude/skills、~/.workbuddy/skills、~/.qwenworkcn/skills
./install.sh --check    # 随时只读体检

如果不用多端软链,直接把整个 ai-manju/ 目录拷到任一 agent 的 skills/ 下也能用。

依赖(只在配音/渲染阶段需要):

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)。开工自检:

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。

⚠️ 两台机器分工(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. 建工作空间

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。密钥绝不写进配置 —— LLM 代理走 xop run --secret K=llm_key -- CMD < /dev/null。

之后所有脚本都在工作空间根运行(cd my-drama)。脚本按 MANJU_ROOT → cwd 向上找 config/pipeline.json → 脚本上级 的顺序定位工作空间。


3. 做一集

# ① 骨架
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。
  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。
  10. 台词不做后期贴嘴:人物说话的画面必须由音画同出的模型生成(H3 fl2va + 首帧锁图,30121 64 GB)。Wav2Lip(96² 糊块)、LatentSync(环境装不下)、InfiniteTalk(78 min / 油画感 / 身份漂移)已实测否掉。见 native-av.md。
  11. 长任务排队、不挂进程:单镜 90 分钟级,一律「排队 → 落盘 pid → 事后取回」;queue/history 是内存态,实例重启即静默丢任务(实测 7 镜全丢),排完 5 分钟内必须 --check 自检。

详细规则按阶段读 references/:

  • models.md — 内网模型服务与 API 全表(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异)
  • native-av.md — 台词镜头:音画同出(为什么放弃 lip-sync / 节点图 / 五段式提示词 / 时长网格 / 排队取回)
  • workflow.md — 七阶段与闸门
  • director.md — 导演内核 12 铁律 + 对白写法 + I2V 提示词模板
  • storyboard.md — 分镜三角色与连续性
  • submit-i2v.md — 提交协议与预检
  • render.md — 缝合规格
  • review.md — 审片与归档
  • pitfalls.md — 踩坑速查,出片前务必扫一遍

配置模板在 assets/:config.template.json、shot.schema.json、policy.template.md(叙事与合规清单)。


6. 换模型 / 换后端

内置 两个视频模型 + 一个文生图,端点与完整节点图见 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(MIT),逐字原文存于 references/toonflow/,许可证见 TOONFLOW-LICENSE.txt。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。