Kanban Motion
由 Kanban Studios 制作。以代码编写动态图形,并与语音锁定。此技能包含两层:
- Motion as Code(如下,未更改):Motion as Code 工具包的完整工作流。
- Kanban Motion 补充(在其后):一个无需外部项目的入门工具包,包含旁白生成与词语对齐、产品发布视频规划(检查、规划、调性、创意法则)、原创背景音乐、CC0 音效库与混音器,以及交付功能(海报帧与分享文案)。
当用户拥有或正在编辑工具包时,使用完整工具包。否则使用入门工具包。两者适用相同规则:场景是时间的纯函数,渲染前检查静态帧,完整渲染前需询问用户。
Motion as Code
一个通过代码制作动态图形的工作流,与旁白锁定,无需 After Effects。每个场景("plate")是一个 TypeScript 文件,将每一帧作为时间的纯函数绘制;旁白的逐词时间码告知每个场景何时动画化。浏览器预览与导出的 MP4 完全相同。
输出:1920x1080,60 fps。技术栈:TypeScript + three.js,bun + Vite,headless Chrome + ffmpeg。
工具包位置
项目文件夹为 Motion_as_kit,位于用户的 Documents 文件夹中(Windows PC 上为 C:\Users\awaiz\OneDrive\Documents\Motion_as_kit)。如果无法访问或已移动,请询问用户其位置。保持文件夹结构完全不变:脚本使用相对路径。
在会话中进行第一次更改之前,请阅读 README.md、app/src/timeline.ts 和 app/src/engine/scene.ts。
要求(在用户机器上)
- bun (bun.sh):安装包并运行脚本
- Google Chrome:渲染器以无头模式驱动它(设置
BROWSER_CHANNEL,例如msedge,以使用其他浏览器) - 支持 libx264 的 ffmpeg
- Python + uv,仅用于重新对齐新旁白或重建音效混音;以
python -m uv运行
app/node_modules 不随附。在其他操作之前,在 app/ 内运行 bun install。
布局
| 路径 | 作用 |
|---|---|
audio/voiceover.mp3 | 旁白 |
audio/sfx/ | 28 个音效(name_1.mp3、name_2.mp3 是备用版本) |
data/lyrics.json | 逐词时间码,由 analysis/align_vo.py 生成(CTC 强制对齐,wav2vec2 ONNX) |
data/audio.json | 语音响度包络、词语起始点、标称节拍网格,由 analysis/audio_vo.py 生成 |
analysis/sfx_mix.py | 提示表(约 500 个提示)和音效混音器 |
app/src/engine/ | pdoom-video 引擎。请勿编辑。 |
app/src/scenes/_vo.ts | 共享工具包:2D 相机、绘图笔、世界空间卡拉 OK 词语、网格纸 |
app/src/scenes/*.ts | 场景(plates) |
app/src/timeline.ts | 每个场景播放的时间;剪辑位于每行前 0.18 秒的暂停处 |
app/scripts/render.ts | 离线渲染器:headless Chrome 到原始帧到 ffmpeg |
out/ | 渲染输出 |
内置演示包含九个场景:hook、model、prompt、crazy、code、frames、pipeline、edits、verdict(共 92.6 秒;verdict 循环回第 0 帧)。
规则
- 场景中的一切必须是时间的确定性函数。不允许无种子的
Math.random()、不允许挂钟时间、不允许在 seek 时未重置的状态。 - 不要编辑
app/src/engine/。 - 未经用户许可,不要运行完整渲染,更不要运行 4K 渲染。使用静态帧检查工作。
- 在每次更改前,用一两句话解释更改内容。
- 保留项目中的
LICENSE.pdoom-engine(引擎和视觉风格来自 mexicat 的 pdoom-video,使用 MIT 许可)。
工作流
1. 预览(快速循环)
cd app
bun install # 仅首次
bunx vite # http://localhost:5173
编辑实时重载。快捷键:空格 播放/暂停,左/右 移动 1 秒(Shift 键为 5 秒),, . 逐帧步进,[ ] 上一个/下一个场景,l 循环场景,h 隐藏 UI。在 URL 中添加 ?t=35 以从 35 秒开始。
2. 编辑时检查静态帧
cd app
bun scripts/render.ts stills --t 12.5,40.2 --only code --out ../out/wip
渲染单帧(此处为 code 场景在 12.5 秒和 40.2 秒处)。查看静态帧并在提议完整渲染前展示给用户。
3. 渲染视频(先询问)
cd app
bun run render
相当于 bun scripts/render.ts video --samples auto --min-samples 4 --max-samples 12 --shutter 0.5 --crf 17 --out ../out/motion-as-code.mp4。
--samples 4:约快 4 倍的草稿;快速移动会显示步进副本--samples auto:在运动快速的地方使用更多子帧(默认)--scale 2:4K(3840x2160)
4. 音效
无需重新渲染:重建混音,然后复制画面并添加音频。从项目根目录运行。
python -m uv run --no-project --with numpy python analysis/sfx_mix.py
cd out
ffmpeg -i motion-as-code.mp4 -i mix.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 320k -shortest motion-as-code_sfx.mp4
音效在语音下最多降低 7 dB;混音标准化至 -14 LUFS。要更改某个音效的响度,请编辑提示表中其 db 值;要移动它,请编辑其时间表达式。
5. 更换旁白
- 替换
audio/voiceover.mp3。 - 编辑
analysis/align_vo.py中的SCRIPT(以及数字和缩写的SPOKEN)。 - 从项目根目录重新运行:
python -m uv run --no-project --with onnxruntime --with numpy python analysis/align_vo.py
python -m uv run --no-project --with numpy python analysis/audio_vo.py
场景通过内容(lineOf、wordOf)找到词语,因此使用相同脚本时,每个动画都会自动重新调整时间。如果措辞更改,请更新 timeline.ts 中 cut(...) 调用的锚定短语,并告知用户哪些发生了变化。
编写或更改场景
场景是一个扩展 Scene(app/src/engine/scene.ts)的类,并且是文件的默认导出。引擎每帧调用一次 render(f, out):
f.t歌曲时间,f.lt场景开始以来的时间,f.p场景进度 0 到 1f.a该时刻的音频特征(语音包络、敲击脉冲)f.seeked在搜索后为 true;有状态的场景必须在其上重置
要添加场景:创建 app/src/scenes/yourplate.ts,然后在 timeline.ts 中添加一行 E('yourplate', 'yourplate', start, end)。开始时间来自脚本:cut('This is Claude') 在该行第一个词语前 0.18 秒处剪辑。timeline.ts 中的文件名必须与 app/src/scenes/ 中的文件匹配。
prompt 场景从 app/src/scenes/prompt-data.ts 读取其 token 分解。
在编写新场景之前,请研究现有场景和 _vo.ts,并重用工具包和调色板(ink、bone、signal orange),而不是发明新的辅助函数。
故障排除
| 问题 | 解决方法 |
|---|---|
| localhost:5173 空白页面 | 在 app/ 中运行 bun install;检查 vite 终端错误 |
| 预览中没有声音 | 按空格键;浏览器在交互前阻止音频。检查标签页未静音 |
| 渲染找不到 Chrome | 安装 Chrome,或设置 BROWSER_CHANNEL(例如 msedge) |
| 找不到 ffmpeg / 没有 libx264 | 安装完整 ffmpeg 构建;在新终端中确认 ffmpeg -version |
| 渲染非常慢 | 草稿使用 --samples 4;使用静态帧命令渲染单个场景 |
| 新旁白后动画漂移 | 重新运行两个分析脚本;如果措辞更改,更新 cut(...) 短语 |
| 未找到场景模块 | timeline.ts 中的文件名必须与 app/src/scenes/ 中的文件匹配 |
Kanban Motion 补充
以下所有内容均基于上述 Motion as Code 工作流进行补充;不替换任何部分。<skill-dir> 是包含此 SKILL.md 的文件夹(Claude Code 会将其打印为此技能的"基目录")。不要猜测安装路径。
选择路径
| 情况 | 执行此操作 |
|---|---|
用户拥有 Motion_as_kit,或要求在其中编辑场景、渲染或更换旁白 | 遵循上述 Motion as Code。在适当的地方使用补充功能(旁白生成、背景音乐、发布规划、交付)。 |
| 从项目、网站、脚本或构思制作新视频,且没有工具包 | 使用下面的入门工具包,加上发布工作流。 |
| "制作发布视频"、"将此转为视频"、"宣传" | 在所有可用工具包上运行发布工作流(检查、规划、构建、交付)。 |
输出到当前目录的 kanban-motion-output/,如果该文件夹已存在,则输出到带时间戳的 kanban-motion-output-YYYY-MM-DD-HHmmss/。内部包含:reel/(场景),out/(渲染、混音、静态帧),work/(下载、草稿),以及 plan.md、script.txt 和 share-copy.txt。
入门工具包
一个小的、无依赖的同一概念版本:浏览器中的纯 ES 模块,帧由 headless Chrome 捕获,由 ffmpeg 编码。要求:Node 18+、Chrome 或 Edge、带 libx264 的 ffmpeg、以及 uv(用于音频脚本)。每台机器一次:npm install --prefix <skill-dir>/scripts。
将 <skill-dir>/template/ 复制到 kanban-motion-output/reel/。在第一次更改前,阅读 reel.js、engine.js 和一个场景。
| 路径 | 作用 |
|---|---|
reel.js | 时间线:每个场景一行 E(plate({...}), start, end),通过 cut('phrase') 从旁白中获取剪辑 |
engine.js | 预览、搜索和渲染钩子。请勿编辑。 |
motion.js | 工具包:range、ease、闭式 spring、带种子的 rng/hash、typed,以及语音同步 lineOf、wordOf、wordsIn、cut |
plates/*.js | paper(随语音呼吸的网格纸背景)、say(说话时落地的动态词语)、code(打字编辑器)、shot(窗口中的真实截图)、outro(名称、笔划下划线、标语、URL)。用于发布视频:bg(漂移渐变)、photo(全出血图像,带推进和可选扫描线"翻转到"第二张图像)、screen(带相机键和跟踪标注的真实 UI)、typewrite(逐字母标题)、stats(计数数字)、steps(随语音点亮的管道)、cap(正在说出的行的字幕)、logo(带标语、徽章、URL 和致谢的 Logo 揭示)。用于电影序列:space(通过一个由变形线框实体、透视网格和 3D 动态字体组成的 3D 场景的一次无缝相机移动) |
style.css | 调色板和类型标记(ink、bone、signal orange)。替换为项目的精确颜色和字体。 |
audio/、data/、cues.json | 旁白和音乐;words.json、lines.json 和 audio.json;音效提示表。模板内置了所有三个的工作演示,因此预览和渲染立即可用。将图像放入 assets/。 |
场景是 { name, setup(root), draw(f) }。draw 接收 f.t(全局时间)、f.lt(场景开始以来的时间)、f.p(场景进度 0 到 1)、f.dur、f.env(语音响度 0 到 1)和 f.fps。它必须仅从 f 设置所有视觉属性:不允许 Math.random()(使用 rng(seed))、不允许挂钟时间、不允许 seek 不会重置的状态。在 E(...) 中为场景指定 tail: 0.4 使其与下一个场景重叠以实现过渡。
node <skill-dir>/scripts/render.mjs preview --dir reel # http://127.0.0.1:5173,快捷键与工具包相同
node <skill-dir>/scripts/render.mjs stills --dir reel --plates --out out/wip # 每个场景的稳定帧 + 切入帧
node <skill-dir>/scripts/render.mjs stills --dir reel --t 2.4,6.1 --only say --out out/wip
node <skill-dir>/scripts/render.mjs video --dir reel --samples 4 --audio out/mix.wav --out out/reel.mp4 # 先询问
渲染标志与工具包相同:--samples(运动模糊子帧,草稿用 4,最终版用 8 到 12)、--shutter 0.5、--scale 2(4K,先询问)、--crf 17、--from/--to、--fps。如果缺少 Chrome,使用 BROWSER_CHANNEL=msedge 或 BROWSER_PATH=...。通过更改 reel.js 中的 width/height 可实现竖版(1080x1920)和方形(1080x1080);执行此操作时,请在静态帧中重新检查每个场景的布局。
工作示例位于仓库的 examples/ 文件夹中(五个真实项目:带旁白的横版、节拍剪辑竖版、带旁白的方形解说视频,以及两个 3D 电影序列)。在编写新 reel 之前,阅读最接近请求的示例。将真实 UI 捕获为"展示事物"的素材:
- 实时网站: 使用 2x 的 headless Chrome 截图。
- 用户拥有的应用: 在 localhost 上运行它们,如果应用有演示或"填充"登录,则使用其自身的演示。
然后使用每张截图的网格副本上读出的 0..1 分数来瞄准相机和标注。
旁白
当用户要求旁白或配音,或传递 --voice 时添加。详情见 references/voiceover.md。
- 编写
script.txt:每拍一行,因为行会成为剪辑。空行添加更长的暂停;[pause 0.8]添加精确暂停;[at 6.0]在精确时间开始下一行,以将语音适配到现有剪辑。按照口语方式编写数字和缩写。旁白应补充视觉内容而非照读,匹配场景节奏,听起来像对话,并针对产品进行具体描述。预算约每秒 2.5 个词。 - 生成它 使用 Kokoro,一个本地运行的开源权重语音模型。模型下载一次(约 340 MB)。
好用的语音:uv run <skill-dir>/scripts/voiceover.py script.txt -o reel/audio/voiceover.wav --lines reel/data/lines.json --voice af_heartaf_heart、af_bella、am_michael、am_fenrir、bf_emma、bm_george(通过--voice af_heart:0.6,af_bella:0.4混合它们;通过--speed调整语速)。--engine system使用操作系统语音,无需下载。如果用户录制了自己的语音,将其放在reel/audio/voiceover.wav并跳过此步骤。 - 对齐它 以获得逐词时间码。faster-whisper 的词时间码被快照到脚本自身的词语上,并且步骤 2 中的行边界被精确固定:
这写入uv run <skill-dir>/scripts/align.py reel/audio/voiceover.wav --script script.txt --lines reel/data/lines.json -o reel/data/words.jsonwords.json和audio.json(f.env背后的语音包络)。 - 同步场景:
cut('Every frame')在该行前 0.18 秒开始一个场景。lineOf、wordOf和wordsIn通过精确的词语文字查找时间。如果脚本更改,场景会自动重新同步。检查静态帧以确保词语动画在正确的时间触发。
音乐
入门工具包附带一个 CC0 音乐床。放置一个 .wav 或 .mp3 在 reel/audio/music.wav;如果未提供,则使用无音乐文件。对于发布视频,生成一个匹配文案基调的原创节拍。详情见 references/music.md。
音效
使用 cues.json 中的提示表。每个提示是一个 { name, start, duration, file, db } 条目。混音器:
uv run <skill-dir>/scripts/sfx_mix.py reel/cues.json -o out/mix.wav
然后与视频结合:
ffmpeg -i out/reel.mp4 -i out/mix.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 320k -shortest out/reel_sfx.mp4
发布工作流海报帧和分享文案
渲染视频后:
node <skill-dir>/scripts/render.mjs stills --dir reel --t 0 --out out/wip
获取第 0 帧。选择最佳帧,复制到 out/poster.png。编写 share-copy.txt,包含视频的简短推文/领英描述,加上针对特定平台(YouTube 描述、Instagram 字幕、网页嵌入标头)的变体。重点讲述故事而非功能,以“我们构建了 X”开头,突出 1-2 个结果,并以行动号召(CTA)结尾。在写 plan.md 时使用这种基调:面向开发者的发布视频使用清晰、功能优先的语言,面向大众受众的视频使用吸引人的故事和情感语言。
工作流提示
- 会议(1. 检查,2. 规划,3. 构建,4. 交付):为每个会议创建一个新的
plan.md。以对项目、受众和情绪的分析开始。收集参考文献(调色板、字体、徽标使用指南、截图、分享链接)。然后同时起草script.txt和plan.md并在工作前让用户批准。 - 镜头:为屏幕场景使用真实截图/直播,通过网格放置相机。为图像场景使用全出血图像;使用
turn: true进行分步过渡。避免白背景。 - 3D 电影效果:
space场景支持通过其设置进行无缝相机移动和变形线框。对于高端外观,在reel.js中使用plateSettings。 - 如果用户提供了自己的
.wav或.mp3文件:将其放在reel/audio/voiceover.wav并直接运行对齐步骤(步骤 3)。 - 始终询问是否渲染。分享静态帧和潜在的海报帧以供批准。