Communitygithub.com

MattiaIppoliti/tia-skills

用于构建一个可渲染Remotion项目的合成合约。涵盖项目结构、`<Composition>`注册、`<Sequence>`时间控制、图层/轨道排列、场景组件、props和schema、框架自有的媒体播放等。

tia-skills 是什么?

该技能是HyperFrames核心中关于构建可渲染Remotion项目的技术合约。它定义了项目结构、组件注册、时间控制、图层叠加和媒体播放等核心规则。基于Remotion框架,所有动画值都是`useCurrentFrame()`的纯函数,确保渲染可寻址和可重现。支持Tailwind项目以及`STORYBOARD.md`和`SCRIPT.md`计划格式。该技能提供了详细的参考文件列表,指导开发者从最小合成项目开始,逐步处理时间、图层、props和媒体等具体问题。它强调了非协商规则,如禁止使用墙钟、非种子随机数和状态驱动动画,以确保渲染的确定性和可复制性。适合所有使用Remotion进行视频合成的开发者,无论是在本地还是Lambda环境中。

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

在你喜欢的 AI 中提问

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

文档

HyperFrames 核心

输出框架为 Remotion。 一个合成组件是一个使用 <Composition> 注册的 React 组件树;当前帧是唯一的时钟;媒体播放归属于 Remotion 的 <Video> / <Audio> 组件,而非 DOM。

本技能是 技术合约:如何构建一个项目。以下正文为构建指南;各主题详情存在于 references/ 中,按需阅读。其他关注点位于同属的领域技能中:hyperframes-animation,hyperframes-creative,media-use,hyperframes-cli,hyperframes-registry。/hyperframes 中的能力图指明了每个技能涵盖的内容。

移植说明。 此合约取代了旧的 HTML + data-* + 暂停的 GSAP 时间线合约。如果你发现某个项目的 index.html 带有 data-composition-id / data-start / data-duration,或者有描述 window.__timelines 的参考文件,说明你正在查看旧合约。在操作之前请阅读 references/legacy-html-contract.md。

参考文件

文件阅读目的…
references/minimal-composition.md从最小的可渲染项目骨架开始
references/project-structure.md布局 src/,将场景拆分为组件,决定单体式还是模块化
references/timing.md将秒转换为帧,放置 <Sequence>,使用 <Series> / <TransitionSeries>,相对其他场景计时
references/layers-and-order.md堆叠图层,控制 z 轴顺序,在同一个时间段内重叠两个场景
references/props-and-schemas.md声明 props,编写 Zod schema,连接 defaultProps 和 calculateMetadata
references/media.md放置 <Video> / <OffthreadVideo> / <Audio> / <Img>,裁剪,设置音量,使用 staticFile
references/determinism-rules.md保持渲染可寻址和可重现;禁止项;通过 delayRender 实现的异步资源加载
references/editing-recipes.md裁剪/修整/重新排序/重新计时/冻结/相机/遮罩/交叉淡入淡出/音频操作及其限制
references/legacy-html-contract.md识别并迁移仍基于旧 HTML + data-* 合约的项目
references/tailwind.md在 Tailwind v4 项目中工作
references/storyboard-format.md编写 STORYBOARD.md 计划(+ 解析后的清单)
references/review-loop.md在活板子上运行计划 → 草图 → 构建审查流程
references/production-loop.md将已批准的计划转化为交付的视频
references/brief-contract.md简要的规则:模式推导、共享字段登记、问题不变性
references/brief-format.md编写 BRIEF.md
references/script-format.md编写可选的 SCRIPT.md 锁定旁白
references/subagent-dispatch.md将子代理调度动词映射到你的 harness
references/frame-worker-core.md共享的帧工作角色合约

关于动画细节(弹簧配置、缓动函数、运行时适配器),请参考 hyperframes-animation。

构建合成

项目的形状

package.json          # remotion, react, react-dom;studio/render 的脚本
remotion.config.ts    # 渲染时配置(编解码器、图像格式、Tailwind/webpack 覆盖)
tsconfig.json
public/               # staticFile() 解析的所有内容
src/
  index.ts            # registerRoot(Root)
  Root.tsx            # 每个 <Composition> 都位于此处
  <名称>/
    index.tsx         # 合成的顶层组件
    scenes/*.tsx      # 每个场景一个组件
    schema.ts         # Zod schema + 推断的 props 类型

src/index.ts 是入口点,仅做一件事:

import { registerRoot } from "remotion";
import { Root } from "./Root";

registerRoot(Root);

注册合成

每个可渲染的东西都是 Root.tsx 中的一个 <Composition>。id 是 CLI 按名称渲染的内容。

import { Composition } from "remotion";
import { LaunchVideo } from "./LaunchVideo";
import { launchSchema } from "./LaunchVideo/schema";

const FPS = 30;

export const Root: React.FC = () => (
  <>
    <Composition
      id="launch"
      component={LaunchVideo}
      durationInFrames={45 * FPS}
      fps={FPS}
      width={1920}
      height={1080}
      schema={launchSchema}
      defaultProps={{ productName: "Acme", accent: "#5B8CFF" }}
    />
  </>
);

durationInFrames 是渲染长度。它是 帧,而非秒,弄错这一点是最常见的创作错误。从命名的 FPS 常量派生,而不是直接写 1350。

帧是唯一的时钟

每个动画值都是 useCurrentFrame() 的纯函数。这是使渲染可寻址的合约:渲染器跳转到第 812 帧并必须获得与逐帧播放相同的像素。

import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate, spring } from "remotion";

export const Title: React.FC<{ text: string }> = ({ text }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const enter = spring({ frame, fps, config: { damping: 18 } });
  const y = interpolate(enter, [0, 1], [40, 0]);

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ opacity: enter, transform: `translateY(${y}px)` }}>{text}</h1>
    </AbsoluteFill>
  );
};

始终对映射帧范围的 interpolate 进行钳制,否则值会超出范围继续外推,导致淡入变成不透明度 4:

const opacity = interpolate(frame, [0, 15], [0, 1], {
  extrapolateLeft: "clamp",
  extrapolateRight: "clamp",
});

时间控制是 <Sequence>

<Sequence> 对其子组件进行时间偏移:在其内部,useCurrentFrame() 在序列自己的起始处返回 0。这种局部基准重算正是关键所在,因为场景组件永远不需要知道它在主时间轴上的位置。

<AbsoluteFill>
  <Sequence durationInFrames={90}>
    <Hook />
  </Sequence>
  <Sequence from={90} durationInFrames={150}>
    <Feature />
  </Sequence>
  <Sequence from={240} durationInFrames={120}>
    <Close />
  </Sequence>
</AbsoluteFill>

对于连续的背靠背场景, <Series> 会自动计算偏移量,这样修改一个场景的持续时间就不会级联到手动修复后面所有的 from:

<Series>
  <Series.Sequence durationInFrames={90}><Hook /></Series.Sequence>
  <Series.Sequence durationInFrames={150}><Feature /></Series.Sequence>
  <Series.Sequence durationInFrames={120}><Close /></Series.Sequence>
</Series>

<Series.Sequence offset={-15}> 将场景提前以重叠其前一个场景,这是无需算术即可获得交叉淡入淡出时间段的方法。完整细节以及用于基于演示的转场的 <TransitionSeries>,请参考 references/timing.md。

图层替代轨道

没有轨道索引。堆叠顺序是 <AbsoluteFill> 内的 DOM 顺序:后面的兄弟元素绘制在上面。一个画外音轨道、一个背景音乐和三个视觉场景就是五个兄弟元素。

<AbsoluteFill>
  <Audio src={staticFile("music.mp3")} volume={0.18} />
  <Audio src={staticFile("vo.mp3")} />
  <Sequence durationInFrames={90}><Hook /></Sequence>
  <Sequence from={90}><Feature /></Sequence>
  <Overlay />                {/* 绘制在所有上述内容之上 */}
</AbsoluteFill>

<Sequence layout="none"> 会丢弃隐式的 <AbsoluteFill> 包装器。当子元素必须参与父元素的 flex 或 grid 布局而不是绝对定位时使用它。

媒体属于 Remotion

永远不要使用原生的 <video>、<audio> 或 <img> 标签。Remotion 的组件才能让渲染器确定性地进行寻址和提取帧。

需求使用
渲染中的视频<OffthreadVideo src>(优先使用)
需要 DOM 级别控制的视频<Video src>
音频<Audio src volume trimBefore trimAfter>
静态图像<Img src>
嵌入页面<IFrame src>
public/ 下的任何文件staticFile("dir/name.ext")

<OffthreadVideo> 使用 FFmpeg 在浏览器外提取帧,对于渲染来说既更快也更准确;仅在需要真实元素时才使用 <Video>(例如,根据其 currentTime 驱动某些东西)。staticFile() 对于本地资源是强制性的。裸的 "/music.mp3" 字符串在 Studio 中有效,但在 Lambda 渲染中会失效。裁剪、音量渐变和播放速率详见 references/media.md。

Props 和 schema

合成输入是 React props,由 Zod schema 进行类型化,这样 Studio 可以为它们渲染可编辑控件,并且错误的 --props 负载会大声报错而不是渲染出错误结果。

import { z } from "zod";
import { zColor } from "@remotion/zod-types";

export const launchSchema = z.object({
  productName: z.string(),
  accent: zColor(),
  features: z.array(z.object({ title: z.string(), body: z.string() })),
});

export type LaunchProps = z.infer<typeof launchSchema>;

当持续时间取决于 props 时(一个长度未知的特性列表,一个长度未知的音频文件),在 calculateMetadata 中计算它,而不是硬编码一个猜测值。参见 references/props-and-schemas.md。

不可协商的规则

类型检查无法捕获的静默错误。完整理由见 references/determinism-rules.md。

  • 禁止墙钟。 不得使用 Date.now()、new Date()、performance.now()。时间来自 useCurrentFrame()。
  • 禁止非种子随机性。 Math.random() 每帧给出一个不同的值,这会导致闪烁。使用 Remotion 的 random(seed):相同的种子,相同的值,每帧和每次渲染都一致。
  • 禁止状态驱动动画。 useState / useReducer / useEffect 不得驱动任何视觉内容。渲染器会乱序并在并行工作进程中挂载帧;通过正向播放累积的状态不存在。应改为从 frame 派生。
  • 禁止 CSS 动画、过渡或 requestAnimationFrame。 它们运行在浏览器自己的时钟上,而渲染器不会推进该时钟。所有这些都会渲染成冻结的第一帧。
  • 使用 delayRender 等待异步工作。 对于 fetch、字体、测量布局:在之前调用 delayRender(),在之后调用 continueRender(handle),否则帧会在工作完成前被捕获。
  • 钳制你的插值。 未钳制的 interpolate 会在输入范围之外进行外推。
  • 对任何动画内容使用绝对定位。 在正常流中移动的转换元素会拖动其兄弟元素。

编辑现有合成

  • 首先读取文件。保留无关的时间、props、id 和资源路径。
  • 匹配现有的 Composition id。CLI、任何渲染脚本和 CI 都通过 id 寻址合成。重命名它是一个破坏性变更。
  • 添加场景:优先使用 <Series> 以便偏移量自动重新计算。在手写偏移量的 <Sequence> 列表中,修正后面所有的 from。
  • 更改持续时间:同时检查 <Composition> 上的 durationInFrames。超过合成长度的场景会被静默截断。
  • 添加组件:保持它是 props 和 frame 的纯函数。

验证

命令详情见 hyperframes-cli。

  • npx tsc --noEmit,确保 schema 和 prop 类型实际匹配
  • 在几个场景中间点执行 npx remotion still <id> out/probe.png --frame <n>,检查每个图像
  • 执行 npx remotion studio 供审查,以便用户自行擦洗和调整 props
  • 仅在用户批准后执行 npx remotion render <id>

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

Drive the Remotion CLI development loop: scaffold, studio, type-check, compositions, still probes, single and batch render, bundle, Lambda and Cloud Run rendering, benchmark, versions, upgrade, and GPU checks. Also use when diagnosing a build or render failure, or when looking for a capability the retired HyperFrames CLI used to own.

相关技能