video2dsprite

视频转 2D 动画

经批准的静帧用于确定身份和几何结构，视频模型提供动作，确定性工具则将其处理为适用于引擎的素材。我们不保证视频比精灵表更小、更无缝或更便宜。

适用场景

• 为角色或生物制作动画：每个动作都来自一张经批准的主静帧，每个动作对应一个片段。
• 基于已接受的主静帧制作流畅动作：待机呼吸、行走、奔跑、攻击、施法、头发、斗篷、生物动作。
• 需要将用户提供的片段转换为带透明背景、已对齐、可循环的帧和引擎视频。

不适用场景

• 特效、图标或道具精灵表：generate2dsprite。
• 静态场景图中的水、火或薄雾：generate2dmap。仅调用 API 或 CLI：generate2dmedia。
• 用户要求用代码绘制的动画：codeart2d。

能力检查（每个会话一次）

运行 python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json，其中 <tools> 列出你自己的工具列表中的媒体工具（image_gen、image_edit、image_to_video），或者填 none。其 ROUTES 区块会显示已配置的 API 密钥（是或否）、本地就绪状态和解析后的顺序。如果 encoding.stdout 失败，请设置 PYTHONUTF8=1。运行 python "<skill-dir>/scripts/video2dsprite.py" doctor 可检查 ffmpeg（5.1+，VP9 Alpha 往返测试）。

美术源

主静帧来自 generate2dsprite（图像生成，经用户批准）或用户提供的素材。动作通过图生视频生成，每个动作都从该主静帧生成一个片段；将路线记录为 art_source，并在回复中注明：

1. API，在密钥已配置时使用：xAI Grok Imagine Video（XAI_API_KEY）、BytePlus Seedance（ARK_API_KEY）或 fal.ai（FAL_KEY：Kling v3、Veo 3.1、Luma Ray 3.2、MiniMax H3、Wan 3.0、Vidu Q3、LTX）（route-media.md）。配置的密钥即表示所有者已同意，因此无需逐次询问。--last-frame <still> 会让待机和攻击片段固定以其首个姿势结束。
2. 本地：如果你有自己的图生视频工具，则使用该工具（Grok 的原生 image_to_video）；否则使用用户的 Grok CLI 的 ACP 模式（无法固定最后一帧；结果会注明 lastFrameUsed）。
3. 用户提供的片段（无需账户）。
4. 仅当用户明确要求用代码绘制动画，或 route_media.py 输出 no-route（退出码 3）时，才使用 codeart2d；否则应准备好任务和提示词，说明缺少的能力，绝不能虚构成功生成的结果。

每个片段都通过一条命令处理：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" video --prompt-file <job>/prompt.txt --reference <job>/input.png --last-frame <job>/input.png --duration 6 --resolution 720p --out-dir <new>。该命令会输出一行 JSON，其中包含 route、artifact、sha256、estimateUsd 和 lastFrameUsed。默认采用 HD 画质；用户要求像素艺术时，可选择像素画质。

从一张静帧生成一整套精灵图

为角色制作游戏动画集时，使用 sprite_set.py：输入一份已批准的主文件（generate2dsprite master.json），输出每个动作对应的一段图像转视频片段，并完成关键色处理、门控检查、注册、剪切、成品处理和打包。若只制作一个片段或使用提供的视频，请使用下方的流程。详情见：sprite-set.md。提示词和修复条款见：motion-prompts.md。

1. 规划。 运行 python "<skill-dir>/scripts/sprite_set.py" plan --master <art>/master.json --output-dir <set>。默认值：--actions idle,walk,run,attack,jump,hurt，--finish 使用主文件中的设置（默认 hd），--target-height 为 hd 模式下的 256 或 pixel 模式下的 80。跳跃动作使用 3:4 画布并预留 34% 的头顶空间，攻击动作使用 16:9 画布；待机和攻击动作会将结束帧固定为主文件。读取 <set>/set_plan.json 中每个动作的 prompt，如有需要，可在运行前编辑其中的 motion、negatives 或 gates。
2. 运行。 运行 python "<skill-dir>/scripts/sprite_set.py" run --plan <set>/set_plan.json。片段由 generate2dmedia route_media.py 生成，然后执行以下操作：
   • 软遮罩抠像；
   • 数值门控检查：面积 0.72-1.32、脚部、身份（除非设计丢失，否则仅警告）、缩放、转身、边缘、背景、多余物体、动作、结束姿势、颜色溢出、单次动作时长；
   • 最多尝试 3 次，每次重拍都会附上针对失败门控项的修复条款；若所有尝试都失败，则保留最佳可用片段；
   • 注册，然后生成循环片段，或根据动作能量将单次动作重新定时为游戏时长（攻击 0.7 s，命中点位于 40%；跳跃 0.9 s；受伤 0.5 s；施法 0.9 s；在计划的 timing 中设置）；
   • 使用 finish_frames.py 进行 hd 或 pixel 模式处理，默认启用与主文件的颜色锁定（plan --no-colour-lock）；
   • 生成并验证 png、webm 和打包文件。 重新运行即可继续处理；不会重复生成内容。
3. 没有路由（退出码 3）。 使用你自己的图像转视频工具，根据摘要中指定的输入和提示词制作片段，将其保存为指定的 media/clip.mp4，然后重新运行。
4. 检查。 运行 python "<skill-dir>/scripts/sprite_set.py" review --plan <set>/set_plan.json，然后查看每个 -sheet.png、每个 -final.png 和 lineup（在 Claude Code 中使用 Read，在 Codex 中使用 view_image）。数值无法判断角色身份、朝向、武器是否改变、是否有文字或脸部是否被遮挡。
5. 决定每个动作。
   • 批准：运行 accept --plan <set>/set_plan.json --action <id> --take <n>。添加 --window START:END 可保留失败尝试中的部分片段。
   • 拒绝：运行 retake --plan <set>/set_plan.json --action <id> --fix <clause id or text>，然后再次运行 run。条款 ID 包括 never-turn、weapon-shape、face-visible、no-text、no-flares 和 keep-colours。
6. 报告。 运行 python "<skill-dir>/scripts/sprite_set.py" report --plan <set>/set_plan.json，可列出路由、尝试次数、质检数值、循环片段、时长和打包路径。在回复中，注明生成每个片段所用的路由。查看对应的图集之前，绝不要称某个动作已获批准。

宿主说明

• Codex： 没有原生图像转视频工具；route_media.py 可使用 xAI API 或 Grok CLI。使用 view_image 查看检查图像。
• Claude Code： 没有媒体工具；route_media.py 可使用相应路由。使用 Read 查看检查 PNG 和联系表；使用 Bash 运行工具；<skill-dir> 为 ${CLAUDE_SKILL_DIR}。
• Grok： 其原生 image_to_video 工具是你自己的工具；同一个 grok 可执行文件也是供其他宿主使用的“Grok (local CLI)”路由。

命令

在用户项目根目录中，将每个工具作为单行命令运行：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir> 是此技能的文件夹；同级技能位于其旁边。将输入和输出保存在项目目录中。每个动词都会写入一个新的 --output-dir：若目录已存在则拒绝运行，并且只有通过检查后才会发布（若有残留内容，--strict 会导致失败）。成功时打印一行 JSON；出错时打印 error: ... 并以退出码 1 退出；用法错误以退出码 2 退出。需要 Python 3.10+、numpy、Pillow 和 ffmpeg 5.1+。--help 会列出所有标志。

单个片段的流水线

1. 关键规划。 video2dsprite.py key-plan --master <master.png>：将 background_sentence 粘贴到提示词中；保护或重新着色 design_colours_at_risk。
2. 准备。 prepare_i2v_input.py prepare --master <art> --action <idle|walk|run|attack|cast|guard|hurt|victory|defeat|ambient|fx> --output-dir <job>；发送 input.png 和 prompt.txt；registration_job.json 会保留变换信息。先对纯色洋红、绿色或蓝色背景上的不透明主图进行抠像（--master-key 用于指定另一种背景色；任务会记录 masterKeying）。--subject 是完整的身份描述；背景行会提及其头部（“围着围巾的冒险者”会生成“在冒险者身后”）。使用 prepare_i2v_input.py lint 检查手写提示词。
3. 使用 route_media.py video 生成（见上文“素材来源”）。
4. 接受生成结果。 register_clip.py qc --job <job>/registration_job.json --video <take>；然后运行 video2dsprite.py triage --video <take> --output-dir <new>。动作过程中如果碰到边框，就必须重新生成，不能补边。
5. 抠像。 video2dsprite.py process --video <take> --output-dir <new> --reference <master.png>（软遮罩）；读取 frames-clean/matte-report.json，并在亮色和暗色背景上查看帧。角色的所有片段都使用相同的抠像设置：--matte-profile <character-profile.json>。设计颜色接近键控色时：--protect-color #rrggbb。已解码的帧（frame_*.png 或 raw_*.png；单帧可用于静态图）：video2dsprite.py clean --raw-dir <dir> --output-dir <new>。
6. 配准。 register_clip.py apply --job <job>/registration_job.json --frames <out>/frames-clean --output-dir <new>；若脚部漂移或跳动：--lock feet；法术或命中效果：--profile fx；每个角色使用统一的缩放比例：运行 register_clip.py profile，然后使用 --character-profile。
7. 循环或调整时长。 行走、跑步、待机：gait_loop.py select --frames-dir <reg>/frames --fps N --output-dir <new>（使用 --kind idle 或 hover）；播放 aids/loop3x.gif。攻击、施法、效果：retime.py --frames-dir <reg>/frames --fps N --output-dir <new> --spans <spans>（冲击、停留、节拍），或者慢动作单次动画使用 --range 0:N --auto-oneshot --duration 700 --key hit=<impact>@0.4+80（剪掉冻结停留帧、固定命中时刻，并压缩至游戏时长）；行走步频：gait_loop.py measure-stride。
8. 收尾并打包。 完成已配准帧的后期处理（见下文“后期处理”），然后运行 engine_export.py package --clean-dir <fin>/frames --output-dir <new> --selection <selection.json> --source-size W,H --source-anchor X,Y --formats png,webm,packed --tiers actor（W,H 和 X,Y 来自 finish.json）。若因残留键控色而被拒绝：重新抠像；只有记录了覆盖项时，才可使用 --allow-key-residue。
9. 验证。 运行 engine_export.py verify --package <dir>，然后运行 validate_animation.py <character dir> --require-states idle,walk --require-verify。--require-states 匹配每个包的 --name（名为 hero-run 的包需要 --require-states hero-run，而不是 run）。

详情：pipeline.md，抠像：matte.md，审查与剪辑：animation-review.md，提示词：prompt-rules.md。

精修（默认 HD，可选像素风）

打包前精修每个已注册动作。精修后的帧保留源名称，因此仍可使用 gait_loop 和 retime 选择。详情：finishing.md。

• HD（默认）： python "<skill-dir>/scripts/finish_frames.py" hd --frames <reg> --output-dir <new> --target-height <px> --role hero --character <id>。静止姿势（第 0 帧或 --rest-frame）决定统一缩放比例。在以脚部为锚点的网格上使用预乘 Alpha 进行盒式缩小，然后清理 Alpha。绝不使用最近邻，绝不放大。--display-sizes 1x,2x 会根据源图重新生成每种尺寸。
• 同一角色的其他动作： 使用 --scale-ref <idle finish dir> 代替 --target-height（缩放比例为 x sqrt(rest-area ratio)，并限制在 +-3% 以内）。出现警告表示静止帧不是基础静帧。
• 像素风（按需）： 首先运行 finish_frames.py palette build --frames <every action's reg dir> --colors 32 [--reserve #hex] --out <palette.json>，然后针对每个动作运行 finish_frames.py pixel ... --target-height <1/8 to 1/12 of the source> --palette <palette.json>。默认采用鲜明的像素风：清晰的 4x4 色簇缩小（无模糊的中间色；保留线条和眼睛）、轻微提升对比度和饱和度、每帧最多使用 --colors（32）种颜色、清理孤立像素但保留眼睛、1 px 局部描边（--outline dark|none）、时间滞后、二值 Alpha、不抖动。--canvas 48x64 会生成固定尺寸的单元格。攻击动作使用 --loop-policy oneshot，索引图集使用 --indexed-sheet。
• 颜色锁定： --colour-lock <keyed master.png> 会将每种设计颜色锁定为主图中的 OKLab 值（仅色度，保持亮度：不进行色调分离），并平滑连续帧中的静态像素；colour_lock.py measure 会报告色相翻转和区域色差。
• 角色阵容检查： finish_frames.py lineup --sets <finished dirs> --out <lineup.png>。角色类型来自 --role 或 ROLE=DIR；默认规则为 hero:1.0、mob:<=1.0、boss:~2.0、spirit:~1.0（按面积）。查看 x1/x3 图集；若规则不通过，命令会以 1 退出。
• 审查： 查看 review-contact.png，并读取 JSON 行中的 qa（flipsPerPair、specksRemoved、alphaBinary）。状态保持为 needs-visual-review。
• 打包： engine_export.py package --clean-dir <fin>/frames --source-size W,H --source-anchor X,Y，其中 W,H 和 X,Y 取自 finish.json 中的 size 和 anchor。不要传入 --registration；像素风精修还需添加 --pixel-art --sampling nearest。

动作与几何规则

• 一个片段对应一个动作。平移、命中时机、伤害和状态变化由游戏负责。
• 每个片段使用一个固定变换；绝不按每帧自身的 Alpha 边界裁剪或缩放（这会导致尺寸跳动，并使腾空的脚部固定不动）。绝不将静帧的 Alpha 固定应用到移动的 RGB 上。
• 同一角色的所有动作共用一个身体高度，以主图的静止姿势为准；绝不放大精修后的精灵图。
• 使用 gait_loop.py select 选择循环，绝不能只凭目测，然后再目测确认。行走动作绝不乒乓循环；攻击动作绝不通过倒放帧来恢复；根据冲击时机调整动作速度并保持姿势。行走动作要体现步频和步幅。
• 关于键控效果的说明必须引用遮罩报告中的数字，并保持 needs-visual-review 状态。--matte binary --despill-mode off 可复现 cfed170 键控器的效果。

运行时和验收

• 验收顺序：打包，然后验证，最后运行 validate_animation.py。交付 animation.json（3.0 版，保留 2.0 版的所有键；durationsMs 使用整数毫秒，fpsRational 保持精确）、QA、海报、PNG 回退方案，以及请求的传输方式。几何数据保持源单位（sourceSize、sourceAnchor、sourceRect）。
• 打包后的 H.264 左侧存储 RGB，右侧存储 Alpha；它不是透明 MP4。绘制合成器的 lease.drawable（使用 references/runtime/packed-alpha-webgl.mjs 作为 packed-alpha-runtime.js 的底层实现）；在解码出帧之前显示海报。由距离驱动的行走、命中停顿和转场：references/runtime/forge-runtime.mjs。
• 在游戏缩放比例下检查：面部和轮廓的稳定性、接触效果、浅色和深色背景上的动态 Alpha 边缘、循环接缝及可读性。在声称支持 Alpha 或达到特定帧率之前，先验证 iPhone 上的实际播放效果；替换精灵图表之前，先比较字节数和解码开销。

数据契约：references/schemas/video.schema.json。