video-talkcraft

video-talkcraft

口播视频的 agent skill：字级配音同步 · 108 张动效配方卡 · 七层反 PPT 镜头系统 · 三重验收

中文 | English

video-talkcraft 是 video-shotcraft 系列的口播视频篇：一个把 Claude Code / Codex 变成口播视频动效工作室的 AI agent skill。 给它一份口播稿和一条成品配音，它在本机对齐字级时间戳、把每个语义拍写进 SHOTBOOK 分镜，然后用 Remotion 渲出高质量的解说成片——动态字卡、 证据截图、运镜、素排字幕、影视级音效，全部锁在人声上。

🖼️ 在线画廊：108 张动效预览一页全览 »

统一依赖（runtime/）

所有口播工程的 remotion/node_modules 与 workbench/node_modules 都软链到 runtime/node_modules，版本只在 runtime/package.json 钉一处（@remotion/* 全家同号）。

• 新片开工：bash runtime/check-runtime.sh --upgrade（装依赖 + 共享无头浏览器 + 链 workbench；Remotion 有新版就升级并冒烟渲 1 帧，不过回滚）。
• 接工程：bash runtime/link-runtime.sh <工程根>（软链 + package.json 版本对齐）。工程目录里不跑 npm install。
• 一份 node_modules ≈ 760 MB（含 190 MB 无头浏览器）；之前每支片各装一份，六个工程 3.9 GB。

🆕 更新（What's new）

2026-09-11

• ✂️ 配音预剪 scripts/voice_trim.py——真人录音先以口播稿为真值剪掉口水词 / 结巴重说 / 过长停顿再做时间戳（只剪稿子里没有的插入段，ASR 听错的字永不剪），词表来源可选 FireRed ASR / 逐字 SRT / 词级 JSON，切点吸附帧网格、同一 EDL 可剪人物视频保音画同长（→ SKILL.md ②-0）。
• 🫥 工作台右键导出透明通道——时间轨上右键任一动效片段可导出只含这一段的透明视频（MOV ProRes 4444 / WebM VP9 alpha），根底透明、自动去掉卡根层幕底与人物剪影占位，给剪映 / PR / AE 当叠加素材；右键菜单同时带分割 / 复制 / 删除（→ workbench/GUIDE.md ⑦）。
• 📺 工作台实时看板（L1）——⑤-1 骨架搭完就接入并开着工作台：阶段栏 + 进度轨（每镜 占位 / 已实现 / 已渲 / 已过闸 / 过期 / 红点）+ 镜头视图（单镜预览 · issues · SHOTBOOK 段落）+ 实时成片卡（2026-09-21 起单轨成片卡下线，看板即多轨），状态按盘上产物自动推、scripts/pipeline_state.mjs --pass/--issue 只补人工判定，代码半成品不再盖页（→ SKILL.md ⑤-2、workbench/docs/live-pipeline.md）。
• 🔗 工作台接入加固——kbsrc 改按真实路径解析、契约模块缺哪个只回退哪个 stub、导出形态差异由 src/kb/ 适配层归一：接入 skill 正式工程（Main.tsx + scenes/，无 promo 模块）不再整页 500，「拆解导入」按钮按契约自动禁用（→ workbench/README.md「接入口播成片工程」）。

2026-09-09

• 🎬 首镜先做先确认——⑤ 实现改为先搭全合成骨架、其余镜头占位，只做样板镜并用 --seg-audio 出一条有声单镜预览给用户确认，确认后再做其余镜头；⑥-1.5 只剩"整片还是逐镜"一问（→ SKILL.md ⑤-1）。

2026-09-07

• ✏️ G5 线稿示意图系统——纯文字镜必配一张图标 + 方框 + 箭头的线稿陪衬图，文字不裸放、每句至少一个可见变化，缺陪衬行 preflight 报 WARN（→ template/motion-systems/schematic.tsx、references/schematic.md）。
• 🎞️ 视频容器边框八式 + 章节主题层——单视频镜头必须包一式主题边框（浏览器窗 / 胶片 / 拍立得 / 图纸等八式，一片一式、不做假播放器），章节卡按章换色 + 线稿 motif（→ template/components/theme-frame.tsx、design-language §1.3）。

2026-09-05

• 🔁 19 张 video-shotcraft 移植卡（89 → 108）——从姊妹库 video-shotcraft 两轮筛选移植（09-06 删定格圈注余 18），tsx 改成本库自包含契约、带母本溯源（→ references/taxonomy.md 第八批◎）。
• 🎨 领域定风格 · 中性卡蒙皮——开工先由口播稿判定领域、派生风格档写进 SHOTBOOK G0；库里的卡是中性 UI，进片按风格档改皮不改运动命门，每镜写蒙皮行（→ references/design-language.md §0）。
• 🧩 10 张多素材同屏新卡（79 → 89）——并列句排版、三联画接力、对比分屏、传送带、卡堆扇开、照片墙推轨 / 时间线照片带等，每卡标注输入类型与常用场景，选卡先按素材类型过滤（→ references/taxonomy.md 输入类型索引）。
• 📐 排版规范 references/layout.md——12 栏栅格、间距令牌、字阶最小档、包围盒不相交等九项自检，选中卡的「已知坑 / 落位自检」必须抄进 SHOTBOOK。
• 🎨 12 款动态幕底入库——template/motion-systems/backdrop.tsx 深浅各 6 款、frame 驱动零随机，默认幕底改为浅 pastel-mesh-flow / 深 mesh-flow-dark。

2026-09-04

• 🎥 运动系统做减法——每场景只保留一条极缓推拉相机曲线 + 让位，idle 微动 / 环境呼吸 / 脉冲全部默认关闭。
• 🌐 网页拍摄不贴图——网页素材不再静态贴屏，改为镜头滚动 / 巡游 / 放大镜 / 划重点"拍"出来，坐标全吃 Playwright 实测（→ SKILL.md §③、references/shot-design.md §2④）。

2026-09-02

• 🎛️ 动效工作台 workbench/——剪映式的成片后期台：多轨时间线 + 素材库（素材 / 动效库 / 音效 / 背景）+ schema 属性面板 + 实时预览 + 一键「导出成片」。108 张动效卡 100% 参数化（文案 / 颜色 / 字号 / 位置可调， 节奏命门固定不暴露）；口播成片可一键拆成字幕 / 转场 / 环境 / 数字人 / 镜头 / 配音 / 音效七类多轨单元逐项微调。 skill 交付成片后会主动打开它。→ 图文指南 workbench/GUIDE.md

• ⚡ 渲染提速：分段渲染母版制——scripts/render_shots.mjs 按镜头切段并行渲、段内单进程保光栅一致， 拼装 + 整条音轨混入 + 帧数断言；改一个镜头只重渲该段±邻段。scripts/render_stills.mjs 一次 bundle 批量出静帧。

• 🧮 评审 token 减量——scripts/contact_sheet.py 把 QA 帧拼成 3×4 网格给评审子代理整版浏览；连拍三帧对只对标了 "burst": true 的状态切换锚点抽（曾占评审材料 2/3）。

• ✅ 一轮审片即交付——机器闸全过后只做 1 轮独立审片、修完 P0/P1 即交付，再询问是否续审（累计封顶 3 轮）， 替代旧的"循环到全过"。

实测（201s 竖屏片）	之前	现在
全片首渲	13 min	9 min
改一个镜头出有声新片	整渲	53 s
43 张静帧抽样	11 min	~1 min
评审读 160 张 QA 帧	≈16 万 token / 21 min	≈4 万 token / 7 min（拼图）

• 🤝 新卡：社区贡献 douyin-follow-card 抖音主页关注卡（@scpcn01vision-oss），库存 79 张。

✨ 亮点

• 字级配音同步——scripts/timestamps_cpu.py 把口播稿对齐到音频 （默认 FireRedASR2-CTC int8，备选 faster-whisper 免手动下载）。110s 中英混合口播 对照 GPU 强制对齐器实测：字级偏差中位 20–40ms、最差 200ms、质检零误报。 每个动效节拍都锚在确切的字上。
• 108 张动效配方卡——每张有意图、参数、已知坑、可直接复制的自包含 Remotion tsx 源码和可跑的 HTML 预览， 在线画廊一页全览 （本地 open gallery/index.html 同款）。动态字卡、数据镜头、证据巡游、 六式运动承接转场、长镜头世界画布、人物合成等。
• 七层反 PPT 系统——每场景一条极缓推进 / 拉出的相机曲线 + 让位生命周期 + 六式运动承接转场 （2026-09-04 起做减法：不再要求主体 idle 与环境呼吸）。 静止帧在结构上不可能出现（漏网的也会被自动检测抓住）。
• 经得住审片的排版纪律——语义拍分镜、同屏元素预算、留白锚、枢轴句切镜规则、 用真实检测（scripts/face_bbox.py）量出来的人脸安全区，不靠目测。
• 三重验收——画面健康双判定（静止段 + 并发光栅抖动，时域缺陷机器抓）、 纯音效轨逐 cue 能量验证、带动效锚点帧与评审拼图的独立评审。

🚀 快速开始

最直接的方式：把仓库链接丢给你的 agent。 在 Claude Code / Codex 里直接说：

帮我安装这个 skill：https://github.com/Vincentwei1021/video-talkcraft

或用 skills CLI / 手动安装：

npx skills add Vincentwei1021/video-talkcraft

git clone https://github.com/Vincentwei1021/video-talkcraft.git
cd video-talkcraft
ln -s "$(pwd)" ~/.claude/skills/video-talkcraft   # Claude Code
# 或
ln -s "$(pwd)" ~/.codex/skills/video-talkcraft    # Codex

环境（agent 会按需自行配置）：

• Node 18+（Remotion 渲染；单片工程内 npm install）
• Python 3.10+
  • 本机 CPU 时间戳对齐：pip install zhconv pypinyin sherpa-onnx soundfile numpy （首次使用下载一次 767MB 的 FireRedASR2-CTC 模型，地址见 scripts/timestamps_cpu.py 头注释；或加 --backend whisper 免手动下载）
  • 一键流式配音+时间戳（Fish Audio 免费层）：pip install requests python-dotenv
• ffmpeg

然后这样下需求：

用 video-talkcraft 把这份口播稿 + voiceover.wav 做成视频。
做一条 100 秒的 <话题> 解说，稿子和音频在这里。

🎙️ 可选：Fish Audio 生成配音 + 字级时间戳

默认仍是「成品配音 + 本机 CPU 对齐」。没有录音时，可主动选择 Fish Audio 接入；脚本默认请求 s2.1-pro-free，模型的免费额度与可用期限以 Fish Audio 为准。

1. 安装 ffmpeg 和 Python 依赖 pip install requests python-dotenv。
2. 复制 .env.example 为 .env，填写 `FISH_AUDIO_API_