Communitygithub.com

stage3d-shorts

制作竖屏动画短片(1080x1920,30 fps),采用“黑色舞台”3D 风格,从带单词时间轴的脚本到成品 MP4。适用于任何该风格的新短片,主题不限。

stage3d-shorts 是什么?

这是一个 AI 助手技能,用于从脚本和单词时间轴自动生成“黑色舞台”3D 风格的竖屏动画短片(1080x1920,30 fps)。该技能的核心思想是将视觉风格封装在不可修改的“工具包”(kit)中,每个视频仅通过一个独立的“计划文件”(plan.js)来定义舞台上的元素、时间线和摄像机运动。它适用于想要快速、一致地制作特定 3D 演示/解说风格视频的内容创作者或开发人员。该技能需要访问本地文件夹,并利用 Node.js、ffmpeg 和 Python 进行渲染和质量保证,同时支持本地 GPU 加速,并包含严格的质检门控,确保输出视频符合特定的画面和编码要求。用户需提供一个包含脚本 JSON、单词时间轴 JSON 以及语音/音乐音频的输入目录。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Pimboto/claude-skills/tree/HEAD/skills/stage3d-shorts

在你喜欢的 AI 中提问

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

文档

stage3d 短片

一个带有镜面地板的黑暗舞台。扁平白色药丸人物、霓虹线绘制的道具、人物上方剧场聚光灯、实时 3D 移动的摄像机,每次显示一个字幕词。该风格通过从参考视频(私人研究素材:绝不复制其内容、名称或脚本)中测量逆向工程而来,并进行了改进。

状态:v0.1。 已在两个站点的 9.7 秒片段 (pricetag_demo) 和一个 5 秒测试 (test5) 上验证。尚未在全长视频上验证。在承诺制作某个场景之前,请先阅读“工具包尚未具备的功能”。

核心理念

  • 工具包即风格。 kit/src/ 包含颜色、辉光、镜头、地面、灯光、摄像机曲线和字幕。视频不得对其进行编辑。
  • 视频即计划。 kit/plans/<name>/plan.js 定义舞台上有什么、每件事发生的时间以及摄像机如何移动。它只导入 kit/src/api.js。构建过程会拒绝任何访问工具包内部实现细节的计划。
  • 数据决定,而非观点。 每次渲染都由 scripts/qa.py 测量。不达标的视频不予交付。

工具包所在位置

此技能仅为说明文档。用于绘制视频的代码和参考文件位于 Pimbo 电脑的文件夹中: C:\Users\Pimbo\work\anymation\stage3d\skill(包含 kit/、references/ 和此文件的一个副本)。此技能中的所有路径都相对于该文件夹。

  • 必须将 anymation 文件夹连接到对话中。如果未连接,请请求 Pimbo 连接:没有工具包就无法制作视频,也不应靠记忆重建任何内容。
  • Pimbo 不会手动运行脚本。由您来运行。他提供主题或视频文件夹,查看静态帧并批准。
  • 视频输入来自他自己的流水线:anymation/v2/v8/<video>/(包含 script.json、用于单词时间轴的 asr_<lang>.json、用于语音和音乐的 premix_<lang>.wav、events_<lang>.json)。
  • 如果您可以在他的电脑上运行命令,请直接在该文件夹中工作。如果只有云工作空间:将 stage3d/skill 复制到其中(排除 node_modules、out 和 dist),在 kit/ 内运行 npm install,在那里编写计划并渲染静态帧(无显卡时每帧约 2 秒),向他展示静态帧,然后将完成的 kit/plans/<name>/ 写回他的文件夹。
  • 最终渲染必须在 Pimbo 的电脑上进行:其显卡速度约为云机器的 20 倍。如果您无法在那里运行命令,请在 stage3d/skill 中留下一个 .cmd 文件,该文件从 kit 运行 node scripts\make_video.cjs <name> --gpu --workers=4,请他双击并粘贴输出结果。在宣布视频完成之前,请先阅读 QA 结果。

不可商榷的规则

  1. 绝不为让某个视频能工作而编辑 kit/src/。如果缺少某个道具或镜头类型,请将其作为可复用的部分添加到工具包中(参见 references/PLAN_GUIDE.md 中的“添加道具”),然后重新检查 pricetag_demo。
  2. 计划中的每个帧号都必须来自真实的音频(单词时间轴),绝不能靠猜测。
  3. 每次摄像机移动都必须有一个能用一句话说明的原因。将该句作为注释写在移动上方。
  4. 在渲染片段前先查看静态帧。看画面,而不是看退出代码。
  5. 说明哪些是测量得出的,哪些是假设的。如果您没有检查某些内容,请说明。
  6. 发布视频前,必须有人收听音频:这些脚本通过数值设置电平。

流水线

在 kit/ 中工作。首次在机器上:npm install(需要 three、esbuild、playwright-core;它使用已安装的 Chrome 或 Edge,不会额外下载)。渲染需要 PATH 中有 ffmpeg;QA 需要安装了 numpy 和 opencv 的 Python(pip install numpy opencv-python);音频脚本需要 scipy。

步骤内容命令或文件
1脚本和语音,每个单词都有时间轴在此技能之外;结果:words.json = [{ w, t0, t1, line }],以秒为单位
1b在录制语音当天检查脚本的每个事实网络搜索;在计划旁边写入 SOURCES.md(示例:plans/no_trick/SOURCES.md)
2将脚本分解为站点:每个句子或一个想法plan.js 顶部的注释
3编写计划:构建、动画、摄像机kit/plans/<name>/plan.js;从 pricetag_demo 开始
4音频:基础混音加上事件音效kit/plans/<name>/make_audio.py -> audio.wav
5检查并构建node scripts/build.cjs <name>
6在关键帧处渲染静态帧;调整构图;重复node scripts/render.cjs <name> stills 0,17,62,88
7观看带有声音的动画在浏览器中打开 kit/dist/<name>/preview.html
8渲染、编码、QA 一步完成node scripts/make_video.cjs <name> --gpu --workers=4
9阅读 QA 结果;FAIL 表示需要修复并重复kit/out/<name>/logs/qa.log、qa.json

步骤 8 每步打印一行。在有显卡的 PC 上,5 秒视频大约需要 10 秒;无显卡(省略 --gpu)每帧约需 2 秒,因此只渲染必须渲染的帧。

编写计划(简述)

完整指南和部件列表:references/PLAN_GUIDE.md。工作示例是 kit/plans/pricetag_demo/plan.js。

  • 舞台由一排间隔 14 米的站点组成。每个句子或想法对应一个站点。摄像机在一个镜头上停留在某个站点,并在句子之间甩动平移到下一个站点。
  • build(stage) 创建并放置物体:stage.station(i).add(thing)。人物会自动获得聚光灯:stage.station(i).spotlight(figure)。
  • animate(f, o) 设置帧 f 时所有物体的位置。它必须是帧 f 的纯函数:帧以任意顺序并行渲染。帧之间不能有状态传递,不能有 Math.random,不能有时钟。
  • 物体在其对应的词上出现:pop(thing, f, wordFrame)。某个重要的数字在其被谈论期间保持可见。落地的物体会获得地面光环(pulse)、短暂的 flare 和音效。
  • 仅按名称使用颜色。金色 = 有价值的东西。红色 = 价格、成本、危险。白色 = 人物和中立标签。
  • 变化的文本(如计数器)需要 maxChars 以避免框大小变化。

摄像机(简述)

完整规则及背后的测量数据:references/CAMERA_RULES.md。

  • 一个镜头有一次移动,有时两次或三次。移动之间摄像机保持静止(工具包会添加缓慢的蠕变)。
  • 仅存在三种移动类型:hook(开场推进,从第 0 帧开始)、reframe(20-28 帧,在两个句子之间,在新物体出现前几帧停稳)、slow(整个镜头内的推进或轨道运动)。
  • 当图形元素动画时,摄像机保持静止。列表需要推移;更广泛的声明需要拉远;长时间分析单个物体需要一次缓慢的轨道运动。
  • 3/4 视角(偏航角约 35-40 度)能展现深度。当第二个物体需要空间时使用此视角。
  • 甩动平移仅在想法之间使用。每次都需要在音频中添加一个约提前 3 帧开始的 whoosh 音效。

质量门控

如果出现以下情况,scripts/qa.py 将使视频不合格:缺少或冻结帧;背景不是提升的黑色;钩子或 reframe 不是前负荷的;摄像机在移动之间未保持静止;甩动平移未移动或未变暗;MP4 不是 h264 / yuv420p / BT.709 格式,帧数错误,或音频缺失或长度错误。

它不检查品味、帧边缘裁剪,或字幕是否正确。这些需要在渲染前通过肉眼检查静态帧:确保没有重要内容被帧边缘裁剪,字幕带(画面高度的 75-83%)清晰无亮线,人物高度在画面高度的 25% 到 85% 之间(镜头会拉伸靠近边缘的物体)。

对 kit/src/ 进行任何更改后:重建 pricetag_demo,渲染第 0、17、88、150、174、236 帧,并与 references/frames/ 进行比较。在软件渲染中必须完全匹配;在有显卡时,偏差约在 1 级以内。

工具包已具备的功能

人物(带耳机的药丸人)、标签药丸、带标签和大数值的卡片、令牌、可打开的箱子(金色或普通灰色用于一堆箱子)、带指针的圆形指南针、游戏屏幕的指南针条带、轮廓框(屏幕、缩略图)、骰子、播放按钮、计数标记、虚线指引、图片(黑白 SVG 或 PNG 绘制成光线)、地面光环、虚线地平线、浮动斑点、带地面光斑和阴影的剧场聚光灯、彩色地面光斑、光晕、射线、火花、带运动模糊的甩动平移、字幕、音效库(whoosh、tick、ding、thud、clunk、sparkle、fizz)以及一个可将语音文件和音乐文件混合在它们下方的混音器。

可阅读两个计划:pricetag_demo(10 秒,两个站点,已批准的风格)和 no_trick(47 秒,五个站点,包含语音、音乐和来源的完整短片)。starts_clean(62 秒,六个站点)是纯白色背景,直到最后出现一个金色回报,遵循 Pimbo 的脚本规则。avatar 不是视频:它用于生成头像图片的静态帧。

工具包尚未具备的功能

  • 沿物体行进的推移(用于列表)、条形图和折线图。
  • 一个站点内的多个聚光灯:未尝试(斑点最多同时被两个聚光灯照亮)。一个站点内的多个人物在只有一个聚光灯且其他人物变暗的情况下可以工作(no_trick,站点 2)。
  • 淡入淡出或剪辑:唯一的转场是甩动平移。
  • 特写镜头:摄像机需要其拍摄对象下方的地面在画面内,且在距离拍摄对象约 2 米以内时会失去瞄准目标。更近的画面需要从更广的画面中裁剪出来(plans/avatar)。
  • 除三种移动类型之外的更多类型,以及任何摄像机翻滚。
  • 语音、音乐和单词时间轴:它们来自外部(Pimbo 的 v2/v8 流水线生成)。

这些功能中的每一项都需要先在工具包中构建,并在真实视频上尝试,然后计划才能使用它。

文件

路径说明
kit/src/视觉风格。
api.js 是计划唯一导入的文件
kit/plans/<name>/一个视频:plan.js、words.json、make_audio.py、audio.wav
kit/scripts/build.cjs、render.cjs、encode.cjs、make_video.cjs、qa.py
kit/audio/sfx.py音效和混音器
references/STYLE_BIBLE.md视觉风格的所有数值,标记为测量值、自有值或猜测值
references/CAMERA_RULES.md如何编辑摄像机,包含测量数据
references/PLAN_GUIDE.md如何编写计划;api.js 的所有函数;添加道具
references/KNOWN_ERRORS.md已犯过的错误,以及现在如何预防
references/frames/pricetag_demo 的目标帧

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能