Communitygithub.com

4waiz/kanban-motion

用代码创建或编辑动态图形视频:产品发布视频、解说视频和宣传视频,支持项目、网站或脚本生成,配有合成或录制的旁白、背景音乐和音效,所有元素逐词同步。与 Motion as Code 工具包(旁白同步场景、预览、静态帧、渲染、音效混音)或内置入门工具包配合使用。

kanban-motion 是什么?

Kanban Motion 是一个 AI Agent 技能,专为使用代码驱动动态图形视频制作而设计。它支持两种工作流:完整的 Motion as Code 工具包(基于 TypeScript + three.js 构建)和一个零依赖的入门工具包。用户可以通过自然语言指令(如 "编辑场景"、"渲染视频"、"添加旁白")与技能交互,技能会自动选择合适的工具包。核心功能包括:根据脚本生成旁白(使用 Kokoro 本地模型)、逐词对齐时间码、从项目或网站素材制作产品发布视频、添加背景音乐和音效混音。该技能主要在 Claude Code 中使用,但也适用于 Cursor 等支持 SKILL.md 的 AI 编码工具。工作流强调精确性:每个场景(plate)都是时间的纯函数,确保预览和渲染完全一致,并且所有动画都与旁白精确同步。它支持实时代码热重载、静态帧预览和全高清渲染,输出为 60fps 的 1920x1080 MP4 文件。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/4waiz/kanban-motion/tree/HEAD/skills/kanban-motion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Kanban Motion

由 Kanban Studios 制作。以代码编写动态图形,并与语音锁定。此技能包含两层:

  1. Motion as Code(如下,未更改):Motion as Code 工具包的完整工作流。
  2. 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. 更换旁白

  1. 替换 audio/voiceover.mp3。
  2. 编辑 analysis/align_vo.py 中的 SCRIPT(以及数字和缩写的 SPOKEN)。
  3. 从项目根目录重新运行:
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 到 1
  • f.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/*.jspaper(随语音呼吸的网格纸背景)、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。

  1. 编写 script.txt:每拍一行,因为行会成为剪辑。空行添加更长的暂停;[pause 0.8] 添加精确暂停;[at 6.0] 在精确时间开始下一行,以将语音适配到现有剪辑。按照口语方式编写数字和缩写。旁白应补充视觉内容而非照读,匹配场景节奏,听起来像对话,并针对产品进行具体描述。预算约每秒 2.5 个词。
  2. 生成它 使用 Kokoro,一个本地运行的开源权重语音模型。模型下载一次(约 340 MB)。
    uv run <skill-dir>/scripts/voiceover.py script.txt -o reel/audio/voiceover.wav --lines reel/data/lines.json --voice af_heart
    
    好用的语音:af_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 并跳过此步骤。
  3. 对齐它 以获得逐词时间码。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.json
    
    这写入 words.json 和 audio.json(f.env 背后的语音包络)。
  4. 同步场景: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)。
  • 始终询问是否渲染。分享静态帧和潜在的海报帧以供批准。

相关技能