Communitygithub.com

yazzang-homelab/motion-studio

让克劳德审视自己渲染的画面:通过 critique.mjs 生成证据,进行严格的 7 轴评分,在 docs/review_log.md 中记录带时间戳的 P0/P1/P2 问题,修复最差的 3 个问题,重新检查,通过关卡。用于“审视它”、“检查帧”、“是否合格”等场景。

motion-studio 是什么?

Motion Studio 是一个 AI 代理技能,旨在通过严格的自动审查和迭代循环来提升电影/动画作品的质量。它基于这样的理念:迭代不是失败,而是完善作品的方法,即使是一部短小的 45 秒影片也可能需要数百次模型调用。该技能主要运行在 Claude(或其他支持技能的 AI 代理)平台上,通过 `critique.mjs` 工具生成截图、指标等证据,然后在 7 个不同轴线上进行评分,并在 `docs/review_log.md` 中记录带时间戳的 P0/P1/P2 问题。关键的工作流程是:生成证据 -> 评分并记录问题 -> 修复最差的 3 个问题 -> 重新检查受影响的片段 -> 进入下一轮,直到满足至少 3 轮、最后一轮所有轴线得分 ≥ 8(除非在“gate.naAllowed”中列出)且没有 P0 问题的通关条件。该技能支持对实时影片和渲染后的 MP4 视频进行审查,并包含多种指标来判断静帧、噪点、跳跃、字体覆盖、音画同步和音频质量等问题,确保最终输出经过严格的质量把关。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/critique-loop

在你喜欢的 AI 中提问

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

文档

批评循环(课程步骤 11)

Opus 可以读取图像,因此它能审视自己渲染的内容。这个习惯区分了成功的作品和那些被评价为“有点一般”的作品。迭代是一种方法,而非失败:一部广泛传播的 45 秒短片在大约 6.75 小时内调用了 163 次模型。本技能以 high 努力度运行,因为诚实地评判帧需要有意识的关注。

critique.mjs 证据 -> 查看所有 PNG -> 7 轴评分 -> 带有时间戳的 P0/P1/P2 -> 将一轮结果追加到
docs/review_log.md -> 修复最差的 3 个问题 -> 重新检查受影响的秒数 -> 下一轮
直到: >= 3 轮 且 最后一轮每个轴线的得分 >= 8 (除非 gate.naAllowed 列表中有允许) 且 无 P0 ->  npm run gate  ->  npm run render:final

在影片项目根目录(包含 studio.json 的文件夹)中工作。参数(格式和哪些发生了变化,都是可选的;格式默认为 studio.json 中的 primaryFormat),如下所示:

本技能的文件位于 ${CLAUDE_SKILL_DIR} 中;下面的相对链接指向那里。

仅审查,不重新渲染:当用户要求您审查已经存在的证据(如联系表、剧照、视频)而不涉及代码时,跳过步骤 1、5 和 6。查看现有文件,进行评分,并追加该轮结果(步骤 4)。

0. 在第一轮之前

  • docs/shotlist.md 已获批准,npm run lint 干净,影片可以在 npm run preview 中播放。
  • 声音轴线需要音频才能评判:首先运行 npm run score(或者对于提供的音轨运行 npm run beats -- <track>)和 npm run sfx,以便存在提示点、节拍网格和同步指标。
  • 声音轴线是根据混合渲染结果评分的,而批评者无法渲染或混音。在每个提示点、音乐或画面时序发生变化的轮次之前(总是在第一轮和最后一轮中)构建它:node tools/render.mjs --format <fmt> --draft --sub 1 --scale 0.5,npm run sfx,node tools/mix.mjs --format <fmt>。然后在评分或告知批评者之前,先生成步骤 1 的两个证据。

1. 生成证据

两个步骤永远不会互相覆盖。根据此类 PC 的测量结果:实时步骤大约需要 115 秒(对于 12 秒的演示)和大约 145 秒(对于 20 秒的影片,其中三次确定性测试加上 15 到 25 秒的浏览器启动时间占主导地位),--video 步骤大约需要 85 秒(对于 20 秒的影片),一次 motion-critic 运行需要 5 到 12 分钟。在后台启动每个步骤并轮询其日志,切勿在前台等待超过约 2 分钟:

node tools/critique.mjs --format 9x16                              # 实时影片 -> out/review/9x16/
node tools/critique.mjs --format 9x16 --video out/9x16/final.mp4   # 混合渲染 -> out/review/9x16/video/

实时步骤包含确定性测试、精确像素、loop.png 和提示点同步;其音频行显示为 n/a。视频步骤包含响度、真实峰值、音频长度以及编码实际包含的内容;它跳过确定性测试并且不写入 loop.png。从视频步骤评估声音,其他所有方面从两个步骤评估。没有混音,声音就没有证据:将其评为 4 或更低,并附带一个 P1 问题,指明缺少的证据(这样的轮次不能是最后一轮)。

out/review/<fmt>/ 中的文件(video/ 中的文件名相同)显示内容查看内容
metrics.md / metrics.json确定性不匹配、绘制文本的字形覆盖率(字体,实时步骤)、死区、爆音、第 0 帧、循环接缝、边角、边框、提示点同步、音频和静音段(--video 步骤)以及每个图集的每一页列表首先阅读;每个标志都变成一个问题或被书面驳回
contact.png每个节拍一张剧照,标记为 时间 · 节拍 · 镜头。每个图集(联系表、镜头、手机、条状图;npm run stills 和 critique.mjs 都是如此)被分割成整行的页面:没有页面高于 --page-height(默认为 1800 像素)或宽于 1990 像素,第 1 页是 contact.png,然后是 contact-2.png,contact-3.png ...;metrics.md 列出所有页面,全部打开。--from S --to S 审查单个章节死节拍、重复的镜头、状态变化时的重叠
phone.png每秒一张 360 像素宽的剧照在手机上的可读性
shots.png每个镜头中点一张剧照构图、禁止的外观、层次
strip.png最快动作周围连续的 12 帧(使用 --strip-at S 选择)滑动、爆音、重新开始、文字重叠
loop.png仅限循环影片(studio.json 中的 loop: true,画布影片,实时模式):下面描述的窗格接缝跳跃,未闭合的循环

node tools/critique.mjs 的每个标志(使用 --help 可查看相同列表):

标志效果
-f, --format <fmt>要审查的格式;默认为 primaryFormat。文件将输出到 out/review/<fmt>/
--video [path]审查渲染后的 mp4 而不是实时影片。单独的 --video 使用 out/<fmt>/final.mp4,否则使用 silent.mp4。添加综合响度(LUFS)、真实峰值和音频长度;跳过确定性测试;不写入 loop.png(只有连续性指标)。所有内容输出到 out/review/<fmt>/video/,因此实时证据保持不变;报告会指明这两个文件夹
--from <sec>, --to <sec>审查长影片的单个章节:剧照、每个图集和每个指标(死区、爆音、确定性样本、字形覆盖率、静音段、提示点)仅覆盖该范围,metrics.json 在 range 中记录它。第 0 帧和循环接缝仅针对整个影片进行检查(报告为已跳过),响度始终是整个文件,自动条状图保持在范围内。错误的范围(--from 超出末尾,--to 不大于 --from,少于 3 帧)是使用错误,退出代码为 2
--page-height <px>单个图集图像的最大高度(默认 1800;图像查看器会缩小超过约 2000 像素的图像)。较高的图集被分割成完整瓷砖行的页面(contact.png,contact-2.png ...);0 = 一张高图集。页面宽度也永远不会超过 1990 像素(--cols 会被降低以适应)
--strip-at <sec>将 12 帧条状图集中在一个时刻,例如问题时间(默认:运动最多的时刻)
--no-determinism当确定性测试在此轮中已通过且只有画面发生改变时,跳过三次哈希测试
--skip-determinism-repeat当影片哈希值、assets/ 下的每个文件(图像、字体、音频、提示点数据:名称、大小和内容)、格式、--from/--to 以及测试的代码未发生变化时,重用上一次实时运行通过的确定性测试结果(文件夹中的 determinism-cache.json);任何对 film/**、lib/**、studio.json 或 assets/ 的编辑都会更改密钥,因此测试会再次运行。失败的测试结果永远不会被重用。指标行显示为 n/a ... reused from the run of <时间>。Chrome 升级不属于密钥的一部分:升级后运行一次不带该标志的测试
--check-hash不启动浏览器:比较实时影片(film/** + lib/** + studio.json 的 sha256 值)与 out/review/<fmt>/ 中的证据(添加 --video 用于 video/);退出代码 0 = 相同影片,1 = 已更改或无哈希值,并会列出更改的文件
--json输出一行 JSON 结果(路径、每个图集的 pages、range、摘要、发现项、nextRound、关卡状态),而不是报告
-h, --help用法

不带 --json 时,会打印报告:证据列表、指标表、机器发现的候选问题、评分标准以及一个准备好填充的审查日志块,其中包含下一轮的编号(也保存为 metrics.md)。该工具从不评分。使用 --json 时,该行会携带 dir(此次运行写入的位置)和 other(另一种模式的文件夹、模式和时间,或 null)。

loop.png 窗格,从左到右(所有窗格以相同方式缩放):

窗格显示内容解读
最后一帧帧 N-1接缝前的状态
t=dur 未包裹在 t = duration 时的原始结束状态仅当运行时尊重 hash(t, { wrap: false }) 时才存在,工具会首先测试
seek(0)第 0 帧接缝后的状态
`last - firstx4`
`end - firstx4`

metrics.json 中的循环判定结果 loop = { enabled, unwrapped, invariant, hashEqual, endDiff, seamDiff, prevDiff, ratio, continuity, closes, pass }。continuity 表示最后一帧到第一帧的步长最多是最后两帧之间步长的 1.5 倍(或低于 critique.staticEps);closes 表示 hash(0) 等于 hash(duration, { wrap: false }),或者它们的平均差低于 0.1。失败是影片末尾的 P0 问题。如果没有未包裹窗格(旧运行时,DOM 影片),则仅测量连续性,并且报告会说明这一点。

每个证据文件夹还包含 film-hash.json(证据显示的影片版本;filmHash 在 metrics.json 中重复出现)和 baseline.json(上一次运行的爆音、跳跃和死区候选时间)。这对审查有两个影响:

  • 影片版本:在您从实时影片渲染任何放大剧照之前,运行 node tools/critique.mjs --check-hash --format <fmt>。不匹配意味着剧照将显示比联系表更新的影片:停止,报告不匹配(该命令列出更改的文件),并请求新的证据;切勿混合版本。在批评者审查时不要编辑影片。
  • 差异:从文件夹中的第二次运行开始,metrics.md 会打印 same as previous run: N of M candidates 并首先列出 NEW 的候选(机器发现的列表在每个严重性级别内将新的发现放在前面,并标记其他为 [same as the previous run])。完整审查新的发现,并且仅当影片在其时间附近发生更改时才重新验证旧的发现。

逐帧动画(像素艺术,“双帧”影片)故意制造硬步骤。在 studio.json 中设置:critique.stepped: true 将每个 jump 列为信息(metrics.json 中的 pops.info,metrics.md 中的“Suppressed by studio.json”部分),而不是 P2 发现;单帧的 flicker 仍然是 P1。critique.popIgnore: [[t0, t1], ...](秒,0 <= t0 < t1)在预期的区间内抑制这两种类型(pops.ignored 列出带有其区间的爆音)。metrics.md 说明每个设置阻止了多少候选以及原因。这是影片的语法规则,不是阈值调整:真正的故障仍然会显示为逐帧区间外的闪烁或跳跃。

指标语义,以便正确分类标志:

指标失败条件发现
确定性任何采样时间点的哈希值在顺序、打乱或新页面上不同(样本跨越每个镜头边界和提示点)P0
字体(实时步骤)影片绘制的字符在其字体中没有字形,或者字体族未注册或为通用字体(sans-serif):机器会绘制系统字体(每台计算机不同)或豆腐块。页面以 window.__TEXT_TRACK__ = true 打开,因此 text()、kinetic() 和 textWidth() 会记录它们绘制的内容,并由 __studio.coverage() 进行判断。每个字体行的发现会指明字体族和字重、最多 40 个缺失字符、总数和修复方法。没有 textUse() 的页面会给出注释 preflight: unavailable,永远不会是发现;未渲染帧上的文本不会被看到P0 font-fallback
死区平均帧差低于 critique.staticEps(0.35)持续 critique.deadSpanSec(2 秒)或更久P1
爆音,flicker某一帧与两个相邻帧的差异都超过 critique.popRatio(3)乘以相邻两帧之间的差异P1(靠近提示点的预期闪光会被书面驳回)
爆音,jump差异峰值超过 popRatio 乘以四个相邻差异的平均值:有物体瞬间移动、弹出或翻转工具给出 P2;当它损害镜头时,您将其提升为 P1。使用 critique.stepped: true 时仅为信息;在 critique.popIgnore 区间内无影响
第 0 帧几乎为空:不到 0.5% 的像素与平滑背景不同(纯色填充、渐变或晕影都算作背景)P0
边角,边框在 30% 或更多采样帧中,边角框(critique.cornerPct,8%)内存在小内容;在 25% 或更多的帧中,三条或更多边上存在带有突变的细均匀边缘线(晕影、渐变或彩色背景上的卡片不是边框)工具给出 P1,肉眼确认后为 P0(禁止的外观)
同步低于 80% 的命中提示点(四个或更多提示点)在 25 毫秒内接近节拍,或者镜头切换不在重拍上;渐强效果、呼啸声和嗖嗖声故意领先节拍,不计算在内P2
音频(--video)没有音频流、响度超出目标、真实峰值超出目标、音频长度与视频相差超过一帧没有音频流或真实峰值高于 0 dBTP 时为 P0,否则为 P1
静音(--video)持续 1 秒或更长的静音段(低于 -50 dB)(每个间隙一个发现,如 silence 3.2 s at 00:08.1),但以下情况除外:在前 0.3 秒内开始的、在最后 1.0 秒内开始的、或者位于 critique.allowSilence 区间内的静音段。提前结束的音轨在混音后仍然会测量为 -14 LUFS,因此响度无法发现它P1 audio-gap(音频行显示为 WARN)

两种爆音还需要在 0-255 尺度上的平均步长大于 1.0,以便近乎静态的场景不会触发它们。镜头边界上的硬切换被列为切换,而不是爆音。画布影片以半尺寸或更大尺寸(pixelScale)进行扫描,因为 Chrome 的 CPU 画布会将字形对齐到小尺寸下的整像素,从而产生虚假的跳跃;DOM 影片以 10 fps 的截图进行采样。切勿更改 critique 阈值来消除标志。

2. 仔细查看

使用阅读工具打开每一张图片。不要仅从 metrics.md 评分,也不要从代码的记忆中评分。顺序:metrics.md,contact.png,phone.png,shots.png,strip.png,loop.png(每个都带有其所有页面:contact-2.png,contact-3.png ...;metrics.md 证据列表会列出它们,或者列出文件夹内容),然后是 video/metrics.md 的音频行。与 docs/shotlist.md(是什么)进行比较

…

[为翻译截断]

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Build, debug or speed up the seek(t) render engine: render contract, canvas vs page capture, workers/subframes/chunks, determinism fixes, Remotion or HyperFrames handoff. Use for 'render is slow', 'frames differ', 'use Remotion'.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Score a film to its beat grid: measure a track (beats.mjs) or synthesize one (score.mjs), cue SFX from the film, add voice, mix to -14 LUFS / -1 dBTP at exact length. Use for 'add music', 'sync to the beat', 'SFX', 'loudness'.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

相关技能