video-talkcraft

一个把 Claude Code 或 Codex 变成口播视频动效工作室的 agent 技能，也是本档案里出自同一个账号的第三条记录。你给它一份口播稿和一条成品配音——任何 TTS 合成的声音，或者真人录音——它在本机把两者逐字对齐，默认后端是跑在 sherpa-onnx 上的 767 MB 语音模型，备选是免手动下载的识别后端；随后它把每个语义拍写进 SHOTBOOK 分镜，再用 108 张动效配方卡渲染成片。每张卡有三份产物：一份配方文档、一份除 React 与 Remotion 之外什么都不 import 的自包含组件，以及一份可直接在浏览器里跑、并带一张音效 cue 表的预览。一套靠减法定义的相机系统给每个场景只留一条极缓推或极缓拉，并把静止帧当作缺陷；一个浏览器工作台能把交付后的成片按七类轨道重新打开。许可是 PolyForm Noncommercial 1.0.0：个人、教育、研究用途免费，商业用途需事先授权，而你用它做出来的视频归你所有。1,318 个星、126 个 fork、约 30 MB，只有一次 release，而且那是一次媒体投放，不是版本号。

谁做的仓库挂在 GitHub 账号 Vincentwei1021 下——video-shotcraft 与 anything2explainer 也出自这个账号——README 的落款是 Vincent。仓库建于 2026-08-22，第一次提交在六天之后，也就是 2026-08-28。82 次提交里 79 次来自这个账号：44 次署 Vincentwei1021、用的是该账号的 noreply 邮箱，35 次署 Yihao、用的是 gmail 邮箱；余下三次各来自一位外部贡献者——leksautomate、ltppp、scpcn01vision-oss。其中 57 次带着共同作者尾注，49 条写的是 Claude 模型：Fable 5.1 三十三次、带百万 token 上下文的 Opus 5 十次、Fable 5 六次；另外八条写的是 Vincentwei1021 本人。

1. 01

   三条记录、一个账号，以及三件不同的东西在决定画面

   本档案里现在有三条记录出自 Vincentwei1021 这个账号。video-shotcraft 建于 2026-07-19，做的是产品宣传片，重心是 157 张镜头配方卡，外加一轮覆盖 149 个音效和五首垫底曲的声音设计。anything2explainer 建于 2026-09-08，从主题或文档出发，交付一支 1280×720 的解说片，且旁白在任何一个镜头动工之前就已经冻结成帧号；它没有卡片目录，也没有音效库。video-talkcraft 建在这两者之间，2026-08-22，从一条已经存在的配音出发，并把那条声音当作时钟。资产因此各不相同：shotcraft 的运动是从十二支具名的产品片里读出来、进门时已经去掉品牌的；anything2explainer 用代码画自己的图解；这一条收下口播稿、录音，以及可选的人物素材、B-roll 或截图——而它自己的卡库有一部分正是从 shotcraft 长出来的：2026-09-05 的第八批把那边 19 张产品片镜头卡翻译成本库的契约，库存从 89 变成 108。机器也在三者之间流动：本仓库的浏览器工作台被搬到了 video-shotcraft，那边的记录写着它于 2026-09-04 到达；三者还共用同一个 runtime/ 目录里的依赖。许可证不一样，而且同时用其中两个库的用户把话说明白了——shotcraft 是 Apache-2.0，没有协议问题；这一条是 PolyForm Noncommercial，于是他正式写信申请商用条件。

2. 02

   二十六天、八十二次提交，和一个不是版本号的 release

   仓库建于 2026-08-22，第一次提交在六天之后到达，也就是 2026-08-28，用短短一行把整个想法说了出来。八月落了六次提交，九月落了 76 次，82 次里的最后一次在 2026-09-22，是 pull request 42 的合并。唯一那个 release 叫 gallery-media，日期是 2026-08-28——和第一次提交同一天——打的是画廊里的动效预览，不是版本；标签列表里也只有这一个名字，整个项目从来没有版本号，对一个在一个月内就交出浏览器工作台和共享 runtime 的仓库来说，这不太寻常。周围是 1,318 个星、126 个 fork、两个 watcher、一个未关条目，仓库约 30 MB，而 GitHub 报的语言是 HTML，因为那座画廊是一个 2.87 MB 的单页。issue 与 pull request 的编号从 14 排到 43，其中 30 条留了档：对这么年轻的项目来说，队列本身就是项目，因为几乎每条改动都先写清哪里错了，再写改了什么。外部反响以两种形式到来，而不是以报道的形式。一家商业 agent 工作空间的团队装上了这个 skill，把一场会议的纪要做成了分镜、节拍与配音时序数据，并把交付物连同报告一起公开；另有一位同时用着这位作者两个库的开发者，正式写信询问能否为小微商家做片的商用授权，得到的回复是一个邮箱地址。

3. 03

   配音就是时钟，而这只时钟跑在你自己机器上

   字级对齐是 README 里的第一条卖点，也是整件事里最不显眼的一段活。scripts/timestamps_cpu.py 默认用跑在 sherpa-onnx 上的 FireRedASR2-CTC int8 模型把口播稿贴合到音频——这个模型 767 MB，只需下载一次——备选是 faster-whisper，适合不想手动下载任何东西的人。README 给出的实测数字是：一段 110 秒的中英混合口播，对着 GPU 强制对齐器比，字级偏差中位 20 到 40 毫秒、最差 200 毫秒，且自家质检零误报，于是每个动效节拍都能钉在确切的字上。材料把上限记得比成绩更清楚。一段 193 秒的口播跑完用了 54 秒、峰值内存 8.6 GB；而 210、225、240、317 秒的输入全部崩在编码器里的同一处，因为那里的相对位置编码表是定长的，且内存随长度平方增长。修法是在实测静音处切段，切点落在 20 到 75 秒的窗口内，再把每段的偏移加回时间戳。拿同一段 193 秒录音做单变量复测：按 75 秒切段后 token 数同样是 975，其中 98.6% 可配，起点差中位 10 毫秒、最差 150 毫秒——约 3% 的 token 超过一帧——而耗时与峰值内存从 54 秒、8.6 GB 降到 34 秒、2.4 GB。2026-09-10 加进来的一步排在这之前：scripts/voice_trim.py 从真人录音里剪掉口水词、结巴、重说和过长停顿，并输出一份编辑单，可以用同一份编辑单去剪同录的人物视频，音画逐帧同长。它的判定写的是「宁漏勿错」——稿子是真相，所以只有稿子里没有的插入段才成为候选，而识别器听错的稿内字永不剪。唯一的云端路径是可选加入的：2026-09-15 一条社区 pull request 接进了一个免费的流式语音服务，一次请求同时返回音频与字级时间戳；维护者把它作为贡献者本人的提交合入，后面跟两条独立修复，并以 25 项离线测试验证，其中包含 ffmpeg 输出检查。

4. 04

   一百零八张卡、每张三份产物，以及一次对着代码做的审计

   卡库是重心，而且每个动效都被存了三遍。每一张都有一份配方文档放在 references/cards/ 下，一份自包含组件放在 template/cards/ 下——除 React 与 Remotion 之外什么都不 import，并导出一块写着宽、高、帧率与时长的元数据——还有一份能直接打开的 HTML 预览放在 demos/ 下；规则写得很明白：预览是视觉真值，组件必须与它逐帧一致，改了一边就必须改另一边。第四份产物更小、也更容易被忽略：每张卡一张音效 cue 表，以预览秒计，音色从十三种里选，其中十种是从姊妹库的 Mixkit 库搬来、以 base64 内嵌在本仓库里的真实采样。2026-08-26 的全库重配把 cue 总数从 439 压到 269，音量上限压到 0.65，把收尾叮当与重砸从全库清零，还故意给两张循环卡留了空 cue 表；从 2026-08-27 起这些 cue 还会跟着进片，选中一张卡，它的音效就一起上。数量本身在仓库里有两个答案：账号页上的项目简介写的是 109 张动效配方卡，而 README 横幅、配方目录、组件目录说的都是 108——108 份配方文档、108 份组件、108 份预览，缩略图却有 109 张，因为其中一张属于那个视频边框组件，而不是某张卡。这里最有教益的改动是一次审计而不是一次新增。2026-09-21，九个子代理把每一份配方文档与实现它的组件逐张对照——仓库把组件当作真值——结果是准确 29、有小偏差 66、不准确 13：十张卡声称吃它们代码从未读取的素材，三张归错了输入类型，能量档从五个标签归一成三个，还有若干节奏数字在动效定版之后没有回写。动的只有文档。第二天，用户找出了更深一层的毛病：选卡漏斗只有一道过滤，看的是一个镜头里有哪些材料，而从来没有人写下稿子里的每句话在做什么，于是一句自我介绍配到了全库能量最低的文字卡，而一张「也用于自我介绍」写在自家说明里的人名条卡就摆在货架上。三份独立评审都放过了那一镜，因为评分表核的是「摆上去的对不对」，不核「该摆的在不在」。

5. 05

   一套靠减法定义的「反幻灯片」系统

   项目简介里管它叫反幻灯片运镜系统，而它实际上是一串禁令。每个场景只给一条连续的相机曲线，且只允许两种——从 1.00 极缓推到 1.04 至 1.06 之间，或者极缓拉——而 2026-09-04 之后，环境呼吸、idle 微动与曝光脉冲全部默认关闭，理由是画面该靠那一条曲线和它自己的内容活着，而不是靠装饰。静止帧被当作本该结构性地不可能出现的缺陷，而仓库并不指望这一点自动成立：scripts/freeze_probe.py 每镜渲三个点，把相隔 0.8 秒的两帧拿编码器同款的帧间绝对差判据比对，低于标定阈值就判为静止候选，在 45 个采样点上与成片母版一致率 98%，而 90 张静帧的普查只要约两分钟。纪律的另一半是变化，而它是从一条投诉里学来的。一支十一镜的片子交回来，其中八镜都是同一个 60/40 分屏、左下圆章、右侧文字，规则于是改成：单条 B-roll 的呈现必须七式轮换，相邻两镜不得同式，同一式在全片占比不得超过三分之一；规则旁边那句注脚说，轮换是换构图，不是加运动——七式里每一式仍然只有那一条极缓推。纯文字镜也不再允许裸放：它配一张由图标、方框和箭头组成的线稿示意图，图从这句话推出来，缺了会被检查报 WARN。单一视频的镜头必须包进八式边框之一——复古浏览器窗、杂志相框、带齿孔的 35mm 胶片、拍立得、工程图纸——一片一式，而且绝不做假播放器，因为最初那版就是播放器，得到的定论是不要进度条、不要播放键。网页是被「拍」而不是被贴上去的：长截图在被滚动、巡游、放大或标注的时候，相机保持不动；录屏被直接否掉，理由是 Remotion 在静帧上工作既 seek 安全、又能对词下锚，而录屏帧率不稳，还会在懒加载和粘性头上穿帮。

6. 06

   机器闸抓住了什么，以及一位用户的账单抓住了什么

   这套检查机制诞生于糟糕的一周，而且对自己的来历记得异常具体。一支口播片做了 7 小时 21 分钟，产出六个整片母版、废掉五个，还蒸发了三次评审；其中最严重的两个坑——25fps 的人物素材混进 30fps 的成片、空的 B-roll 目录一路走到交付——其实早就写在文档里了，所以结论不是文档缺失，而是文档没有在对的时刻被读。于是 scripts/preflight.py 把入场硬规变成开工前必跑的断言：逐条核对人物素材的帧率、宽高比与时长是否与成片一致，查找能暴露源片不匹配的重复帧签名，并要求分镜里每一镜的素材行都指向一个真实存在的文件，对一支完全没有 B-roll 或图片的片子直接判 FAIL。交付由三道闸看着——画面上的静止段与并发光栅抖动检测、纯音效轨的逐 cue 能量检查、以及一轮针对锚点帧与静帧拼图的独立评审——之后修完 P0 与 P1 即交付。工序的顺序也出于同一个理由改了：不再把十三个镜头全部实现完再给用户看，而是先把骨架搭全、其余镜头用替身占位，只渲一镜并用只属于它自己那一段的音频出预览，然后只问一次——测试工程里一条 6.22 秒的首镜花了 47 秒，与之相对的是返工整片的代价。一块实时看板按盘上文件推导每一镜的状态，而不是按 agent 的记忆，于是过期的镜头会显示为过期。队列里最锋利的一条至今没关：一位用户报告，一个晚上九次整片直渲产出约 2.5 GB、烧掉约 10000 积分，折合约 150 元人民币；事后调查的结论是渲染本身不要钱，因为它跑在本地——真正花钱的是驱动它的那个循环，每一次导出都是又一轮 agent 轮次，而长会话会把整段上下文重新付一遍，那九次里有九次都绕开了 skill 里写好的迭代纪律。作者给出的解法走向另一边：先做一镜，问一次，再往下做。