Communitygithub.com

yazzang-homelab/motion-studio

搭建 motion-studio 影片项目(支持 seek(t) 渲染器、弹簧、节拍网格、合成音效、评审工具),安装配置、设置浏览器并运行诊断。适用于“设置 motion studio”、“新建影片项目”、“初始化工作室”。

motion-studio 是什么?

Motion Studio 是一个专为 AI 代理(如 Claude Code)设计的技能,用于快速搭建一个具备完整动画渲染与评审管线的影片制作项目。它通过一个基于 Node.js 的脚手架脚本 (`init.mjs`) 创建项目结构,支持设置标题、时长、帧率、BPM、循环标志和品牌 URL 等参数。该技能会指导代理完成 `npm install`、安装 Playwright 无头浏览器(Windows 上使用 chromium-headless-shell 以避免账户锁定问题),并运行 `npm run doctor` 诊断所有环境依赖是否就绪。它还提供了 `stills`(生成节拍静帧联系表)、`critique`(综合评审)、`gate`(质量门槛检查)和 `render:final`(最终渲染)等命令,形成一个从创建到交付的完整工作流。项目支持 Windows、macOS 和 Linux,并内置了秘密信息(如 token、密码)剥离逻辑,确保在存储品牌 URL 时不会泄露敏感数据。

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

在你喜欢的 AI 中提问

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

文档

工作室初始化(课程步骤 02)

创建一个能够渲染、播放并查看自身帧的影片项目。聊天应用可以编写动画;只有拥有 shell 权限的代理才能关闭渲染、查看、修复循环。这个循环是“还行”的首次尝试与值得发布的影片之间的区别。

请求参数(可以为空),仅显示一次:

1. 选择目录和设置

  • 目录:第一个参数;如果工作目录为空则为 .;否则询问(默认为 ./<标题的 slug>)。切勿在插件目录内搭建项目。
  • 请求中的设置:标题、时长、格式、帧率、bpm、循环、品牌 URL。其余设置保持模板默认值(studio.json:12 秒、60 fps、4 子帧、120 BPM、9x16 主格式)。

2. 搭建项目

node "${CLAUDE_SKILL_DIR}/scripts/init.mjs" <dir> --title "<Title>" [--duration S] [--fps N] [--bpm N] [--formats a,b] [--loop] [--brand-url URL] [--install] [--json]
标志作用
<dir>目标目录;如果不存在则创建
--title Tstudio.json 中的标题和交付文件的 slug
--duration S, --fps N, --bpm N时间设置
--formats a,b9x16、1x1、16x9、4x5 的子集(或 all);除非列表中不包含,否则 primaryFormat 保持不变
--loop无缝循环影片(UI 变形)
--brand-url URL将产品 URL 存储在 brand.url 中。在写入任何内容之前,会移除 user:password@ 以及看似秘密的参数(query、;matrix、fragment:token、key、secret、password、auth、sig、session、code……);stderr 会输出被移除的内容,--json 会在 redacted 中列出它们。仍请传入一个普通的公共 URL:作为裸路径段(/reset/<token>)的秘密无法被识别。普通 URL 会按原样存储
--install在新项目中运行 npm install(在 Windows 上处理 npm.cmd)
--force将旧项目刷新到当前模板(见下表)
--json在标准输出上打印一行 JSON 结果

如果目标非空目录已存在,则会进行合并:仅添加缺失的文件,并列出跳过的文件。向用户报告跳过的列表;切勿删除他们的文件。

对已有项目使用 --force(通过 init.mjs 检查):

路径使用 --force
studio.json, film/**, docs/**, assets/fonts/fonts.json保留并列为 kept;缺失的文件仍会被创建。诸如 --bpm 等标志仍会修补 studio.json
package.json合并,绝不替换:设置 type: module,添加 private、engines 以及项目缺失的每个模板脚本或依赖项。命令不同的模板脚本会重置为模板命令(init 会打印每条记录为 was ..., now ...,并在 packageReset 中返回它们)。依赖版本从不更改,包括模板依赖项:现有范围保持不变,无论是更新、更旧还是固定版本。名称、版本、其他脚本和其他字段保持不变
.gitignore合并:在 # motion-studio 下添加缺失的模板行,不移除任何内容
其他所有内容(CLAUDE.md, lib/**, tools/**, prompts/**, index.html, .env.example, 捆绑的字体)覆盖并列为 overwritten。对这些文件的本地编辑将丢失:请先提交或复制
你自己的其他文件不受影响

未使用 --force 时,package.json 和 .gitignore 的合并方式相同,但命令不同的脚本会保留你的命令。Init 会列出每个与模板不同的脚本和依赖版本,并提示 kept your package.json values, which differ from the template(在 --json 结果中的 packageKept):那些 npm run 名称运行你的命令,而 --force 会重置模板脚本(绝不重置依赖版本)。如果 scripts、devDependencies 或 optionalDependencies 部分不是对象,则保持原样并发出警告。由于 docs/** 被保留,较新的模板文档永远不会到达现有项目:更新后请手动与插件的 template/docs/ 进行比较。

3. 安装、浏览器、诊断

  1. 未使用 --install 时,在项目内运行 npm install。playwright 是唯一必需的依赖项;ffmpeg-static 是可选的,可能在代理后面下载失败。
  2. 浏览器(npm run setup:browser 与 npx 命令相同):
    • Windows:运行 npx playwright install chromium-headless-shell(约 115 MB 下载,270 MB 磁盘空间)。studio.json 中的 browser: "auto" 仅启动该捆绑的无头 shell,绝不启动已安装的 Chrome 或 Edge。原因:使用新配置文件(每次工具运行时)启动已安装的 Chrome 或 Edge 会使 Chrome 测试 Windows 账户的空密码,这算作一次登录失败。实测笔记本电脑在 10 分钟内 10 次登录失败会锁定账户,并在 24 小时内记录了 464 次。除非用户要求并接受风险,否则不要将 browser 切换为 chrome 或 msedge,也不要将 MOTION_CHROME_PATH 设置为 chrome.exe 或 msedge.exe:每次启动都会打印警告,10 分钟内的第 4 次启动会被拒绝,3 次可以通过(启动保护)。Shell 未签名,因此实时防病毒软件可能使每次工具运行慢 15 到 25 秒(已测量):告知用户一次;对 %LOCALAPPDATA%\ms-playwright 添加防病毒排除项由用户或其 IT 部门决定。
    • macOS 和 Linux:auto 会先尝试已安装的 Chrome,然后是 Edge,最后是捆绑的浏览器,且无警告。如果都未安装,运行 npx playwright install chromium-headless-shell(Linux:npx playwright install --with-deps chromium-headless-shell),或者将 MOTION_CHROME_PATH 设置为 Chromium 系列的可执行文件。
  3. npm run doctor。在交付出前修复每个 FAIL 行,在 Windows 上还需修复 WARN 浏览器行(选择了已安装的 Chrome 或 Edge:清除它并安装无头 shell);每个操作系统的修复方法见 references/troubleshooting.md。带有 librosa 的 Python 是可选的(JS 节拍引擎已覆盖)。仅路线 B 工具需要 Node 22+。
  4. 验证:运行 npm run stills,然后打开 out/review/9x16/contact.png(长影片会分页:contact.png 是第 1 页,然后是 contact-2.png……每页高度不超过 1800 px;打开每一页)并查看。附带的 12 秒演示必须在 0 秒处显示一个合成帧,并且在每个强拍上都有变化。npm run preview 打开实时预览(空格键播放/暂停,箭头键逐帧移动,F 键循环切换格式,G 键安全区域参考线)。

4. 向用户解释项目

用几行总结,然后指向参考文档:

  • 布局和谁编辑什么:references/project-layout.md
  • 所有命令:references/commands.md
  • 所有 lib/ 签名和默认值:新项目中的 docs/API.md(完整参考是插件仓库中的 docs/ARCHITECTURE.md)
  • 行为准则存于项目的 CLAUDE.md 中,Claude Code 每次运行时都会读取。

如果 init 打印了一行 ★ 星号线(--json 结果中的 starHint;每台机器仅在新项目的首次运行时出现),则用这一行原文结束你的总结。切勿为用户 star 仓库或运行 gh。

命令功能
npm run preview在浏览器中实时预览
npm run stills每个节拍生成一张静帧联系表
npm run critique联系表、胶片条、手机测试、指标、评审日志块
npm run gate评审门槛:3 轮,所有维度 >= 8,无 P0
npm run render:final每种格式,最终质量(强制通过门槛)
npm run sfx / npm run mix合成提示音效 / 混音至 -14 LUFS 并封装
npm run deliver交付检查并打包 out/deliver/ 目录
npm run build音效缺失则生成,音效、最终渲染、混音、交付

5. 工作量和路线

工作工作量通过以下设置
小修复、重新渲染中等/effort medium
一部新影片超高/effort xhigh(motion-reel 技能会为你设置)
旗舰产品的开头 3 秒最大/effort max

/model 在选择 Opus 5.5 时也提供工作量选择。路线 A(此引擎)为默认。仅当用户明确指定时才使用 Remotion 或 HyperFrames;/motion-studio:seek-engine 负责交接,包括 Remotion 许可门槛。

6. 密钥

仅在需要密钥时复制 .env.example 到 .env(语音:ELEVENLABS_API_KEY;路线 C 图片/视频:FAL_KEY)。让用户自行将值粘贴到 .env 中。在提示和日志中仅提及变量名。.env 已在项目的 .gitignore 中。

7. 可选伴侣工具

仅在相关时提及。安装命令和注意事项:references/companions.md。

伴侣工具用途注意
claude-animation (buildwithhanif)手绘、笔刷、故事书风格MIT;独立的 Node Canvas 渲染器
HyperFrames (heygen-com)HTML + GSAP 合成Apache-2.0;需要 Node 22+
RemotionReact 系列和模板对于超过 3 名员工的企业需要公司许可

下一步:使用 /motion-studio:showreel 测试引擎,或使用 /motion-studio:motion-reel 制作一部真正的影片。

Individual skills in this repo

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

yazzang-homelab/motion-studio

Make Claude watch its own frames: critique.mjs evidence, harsh 7-axis scores, timestamped P0/P1/P2 problems in docs/review_log.md, fix the 3 worst, re-check, pass the gate. Use for 'critique it', 'review the frames', 'is it good'.

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

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'.

相关技能