Communitygithub.com

MattiaIppoliti/tia-skills

用於建構一個可渲染的 Remotion 專案的組合合約。涵蓋專案結構、<Composition> 註冊、<Sequence> 時間控制、圖層/軌道排序、場景組件、props 與 schema、框架自有媒體播放、確定性渲染規則及驗證。也包含 Tailwind 專案與 STORYBOARD.md / SCRIPT.md 計劃格式。在撰寫組合程式碼前請先閱讀。

tia-skills 是什麼?

此技能定義了 HyperFrames 核心組合合約,以 Remotion 作為輸出框架,規範如何建構一個可渲染的專案。它強制要求每個可渲染項目必須透過 <Composition> 註冊,並以 useCurrentFrame() 作為唯一時間來源,確保渲染的可尋址性。技能涵蓋使用 <Sequence> 和 <Series> 進行時間偏移、以 DOM 順序取代傳統軌道來管理圖層、以及透過 OffthreadVideo 和 Audio 等 Remotion 組件處理媒體。此外,它還規定了嚴格的確定性規則,禁止使用牆上時鐘、未播種的隨機性、狀態驅動動畫、CSS 動畫或 requestAnimationFrame,以保證渲染結果可重複。此技能支援所有 Remotion 專案,並提供詳細的參考文件,包括專案結構、時間控制、props 與 schema、媒體處理、Tailwind 整合、以及故事板和腳本的計劃格式,是開發者在撰寫組合程式碼前必須閱讀的核心合約。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames Core

輸出框架為 Remotion。 組合(composition)是一個透過 <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/,將場景拆分為組件,決定整體式 vs 模組化
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.mdbrief 的基本規則:模式推導、共享欄位註冊、問題不變量
references/brief-format.md編寫 BRIEF.md
references/script-format.md編寫可選的 SCRIPT.md 鎖定旁白
references/subagent-dispatch.md將子代理分發動詞對應到您的工具
references/frame-worker-core.md共享的 frame-worker 角色合約

關於動畫細節(spring 設定、緩動函數、執行時期配接器)請前往 hyperframes-animation。

建構組合

專案結構

package.json          # remotion, react, react-dom; studio/render 的腳本
remotion.config.ts    # 渲染時期設定(codec, 圖片格式, Tailwind/webpack 覆寫)
tsconfig.json
public/               # staticFile() 解析的所有檔案
src/
  index.ts            # registerRoot(Root)
  Root.tsx            # 所有 <Composition> 都放在這裡
  <Name>/
    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 提取影格,這對於渲染來說更快且更準確;僅當您需要真實元素(例如驅動某物根據其 currentTime)時才使用 <Video>。對於本地資源,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 不得驅動任何視覺元素。渲染器會以不按順序且並行 worker 的方式掛載影格;透過向前播放累積的狀態不存在。請改為從 frame 推導。
  • 無 CSS 動畫、轉場或 requestAnimationFrame。 它們在瀏覽器自己的時鐘上運行,渲染器不會推進這個時鐘。每個都會渲染為凍結的第一個影格。
  • 使用 delayRender 等待非同步工作。 擷取、字型、測量佈局:在之前呼叫 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.

相關技能