Communitygithub.com

MattiaIppoliti/tia-skills

驱动 Remotion CLI 开发循环:脚手架、工作室、类型检查、合成、帧探测、单次和批量渲染、打包、Lambda 和 Cloud Run 渲染、基准测试、版本管理、升级和 GPU 检查。同时也用于诊断构建或渲染失败,或查找已退役的 HyperFrames CLI 曾拥有的能力。

tia-skills 是什么?

此技能专门为使用 Remotion CLI 的开发者设计,提供了一个完整的从开发到诊断的工作流程。它详细说明了如何通过 `npx remotion <command>` 执行各项原生 Remotion 命令,包括项目脚手架搭建、类型检查、合成列表查询、单帧探测、工作室预览、本地渲染、打包以及 Lambda 和 Cloud Run 的远程渲染。技能强调使用 `npx remotion still` 进行快速帧探测是迭代验证的首选方式,因为它比完整渲染快得多,并建议在用户批准前使用 `npx remotion studio` 进行审查。同时,该技能还包含了全面的渲染性能优化建议(如并发参数、JPEG 格式),以及一个详细的诊断表格,用于解决常见的失败问题,如构建失败、超时和版本不匹配。最后,它明确映射了已退役的 HyperFrames CLI 各命令到 Remotion 的等效操作,防止用户使用过时的指令。该技能适用于 Claude Code、Cursor 和 Codex 等 AI Agent 平台,帮助代理工具高效管理 Remotion 视频渲染项目。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

Remotion CLI

工具是 remotion,来自 @remotion/cli。每个命令都通过 npx remotion <command> 运行,并且每个命令都会先打包项目,因此类型错误或有问题的导入会表现为打包失败,而不是渲染失败。

npx remotion --help 和 npx remotion <command> --help 是标志参数的最高权威。 标志参数会随版本移动;请阅读帮助输出,不要轻信任何列表(包括本列表)。以下内容是工作流程和失败模式,而非标志参考。

工作流程

阶段命令原因
脚手架npx create-video@latest --blank写入匹配的 package.json、remotion.config.ts、tsconfig
类型检查npx tsc --noEmit最便宜的门控;在任何渲染前捕获 schema/prop 漂移
列表npx remotion compositions确认您即将渲染的 id 确实存在
探测帧npx remotion still <id> out/probe.png --frame=<n>秒级而非分钟级;迭代的主力工具
审查npx remotion studio交给用户;他们自己擦洗时间线并编辑属性
渲染npx remotion render <id> out/video.mp4仅在用户批准后执行
远程发布npx remotion bundle → npx remotion lambda render <url> <id>分布式渲染;需要已部署的 AWS 基础设施

在渲染前先探测帧

完整渲染一个 45 秒 1080p 的合成需要几分钟。而一帧探测只需要几秒钟,并且能回答大多数问题:文字是否在画面内、资产是否加载成功、颜色是否正确。探测每个场景的中段,查看每张图片,然后再开始渲染。

npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180

永远不要仅凭打包通过就报告合成功。请查看像素。

工作室是审查界面,不是您的调试器

npx remotion studio 提供一个带有时间线、由 Zod schema 驱动的属性编辑器以及帧级精确擦洗的项目界面。将其交给用户进行审批。对于您自己的验证,更倾向于使用 still 探测:它们是可脚本化的,并且您可以在不要求用户描述他们所看到内容的情况下查看输出。

传递属性

--props 接受一个 JSON 字符串或一个 JSON 文件的路径,并覆盖 defaultProps:

npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'

如果属性未通过合成的 Zod schema,则会大声渲染失败。这就是声明 schema 的意义所在,因此请保持其准确。

批量渲染

没有批量子命令。直接在 shell 中对 id 或属性负载进行循环:

for id in $(npx remotion compositions --quiet); do
  npx remotion render "$id" "out/$id.mp4"
done

对于同一个合成需要多次渲染不同数据集的情况,更建议在 Node 脚本中使用 @remotion/renderer 的 renderMedia():它只打包一次,而不是每次渲染都打包,这通常会占用大部分时间。

渲染性能

  • --concurrency=<n> 设置并行工作线程数。默认值是 CPU 核心数的一半(上限为 8);最大值是核心数,请求更多核心会报错,不会自动降低。在内存紧张的机器上,降低此值可以修复看起来像渲染器错误导致的崩溃。
  • --jpeg(覆盖默认的 PNG 帧格式)在合成不需要保留透明度时能显著提速。
  • npx remotion benchmark 测量一次真实的渲染,因此可用它来证明并发数或编解码器更改的合理性,而不是猜测。
  • npx remotion gpu 报告浏览器实际将加速的内容。在将渲染慢的原因归咎于着色器或重型滤镜之前,值得先检查一下。

诊断失败

症状可能的原因
打包失败类型错误或有问题的导入。运行 npx tsc --noEmit 以获取可读的相同错误版本。
"No composition with id …"Root.tsx 中的 id 与您传入的不同。npx remotion compositions 可以确认。
渲染挂起,然后超时delayRender() 没有匹配的 continueRender()。每个延迟句柄都必须被释放。
每一帧看起来都像第 0 帧CSS 动画/过渡,或 requestAnimationFrame。渲染器不会推进浏览器时钟。
动画在帧之间闪烁或频闪未播种的 Math.random()。请使用 random(seed)。
向前擦洗时动作正常,跳到某帧时中断状态驱动的动画。请改为从 useCurrentFrame() 派生状态。
仅在 Lambda 或打包的渲染中资产 404使用了硬编码路径而不是 staticFile()。
毫无意义的版本错误Remotion 包版本不匹配。npx remotion versions 会报告差异。
渲染过程中内存不足机器的并发数过高。降低 --concurrency。

报告失败时请提供实际的错误输出。不要复述堆栈跟踪。

已退役的 HyperFrames CLI 能力去向

旧的 hyperframes CLI 中打包了 Remotion CLI 没有的创作、媒体和 QA 命令。以下都不是 Remotion 命令,因此不要尝试运行它们:

已退役命令当前能力所在位置
initnpx create-video@latest --blank,然后 /hyperframes-core → references/project-structure.md
lint、check、layout、validatenpx tsc --noEmit 加上 still 探测。那些门控执行的 data-* 契约已被移除。
snapshot、compare、grade-compare在选定帧上使用 npx remotion still;使用您自己的工具对 PNG 进行差异比较。
preview、play、presentnpx remotion studio
add、catalog/hyperframes-registry
capture/product-launch-video(站点捕获)和 /media-use
tts、transcribe、remove-background/media-use
beats、keyframes/hyperframes-creative(节拍规划)、/hyperframes-keyframes
cloud、publishnpx remotion bundle + remotion lambda / remotion cloudrun,或您自己的托管方案
skills、docs、upgrade、doctor这些技能已嵌入此仓库;npx remotion upgrade 和 npx remotion versions

如果有工作流技能或参考文件仍指示您运行 npx hyperframes <anything>,则该指令已过时。请使用上表中的 Remotion 等效操作,并在您的摘要中说明您遇到了过时指针,以便修复。

Individual skills in this repo

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

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

MattiaIppoliti/tia-skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

MattiaIppoliti/tia-skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

MattiaIppoliti/tia-skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

相关技能