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.md | brief 的基本規則:模式推導、共享欄位註冊、問題不變量 |
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 和資源路徑。
- 匹配現有的
Compositionid。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>