HyperFrames
HTML 是影片的唯一事實來源。合成是一個帶有 data-* 屬性(用於時間控制)、GSAP 時間軸(用於動畫)和 CSS(用於外觀)的 HTML 檔案。該框架處理剪輯的可見性、媒體播放和時間軸同步。
Open Design 整合(對此專案至關重要)
當此技能在 Open Design 環境中執行時(即已設定 $OD_PROJECT_DIR),輸出流程是固定的:只有渲染後的 .mp4 應放置在專案根目錄中。合成原始檔(hyperframes.json、meta.json、index.html、資源)應放置在隱藏的快取目錄中,以免混亂使用者的檔案檢視器或聊天的「已產生檔案」標籤。
OD 內的渲染工作流程 — 快速路徑:
對於大多數 OD 請求(「測試影片」、「5 秒產品展示」、「示範片段」),請勿從頭開始撰寫合成 HTML。使用 HyperFrames 內建的 Scaffold(骨架),僅編輯提示實際上需要的部分。「從頭開始創作」路徑會耗費數分鐘的模型輸出和無聲的聊天工具時間;而 Scaffold 路徑只需幾秒鐘。
# 1. 選擇一個隱藏的快取插槽。點前綴 → OD 的專案檔案
# 列表會跳過它,因此原始檔永遠不會混亂聊天。
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. 取得一個立即可渲染的 Scaffold(hyperframes.json、
# meta.json、帶有 GSAP CDN 和已註冊的
# window.__timelines.main 的 index.html)。這在你的 shell 中執行 — 純粹的檔案複製,
# 不需要 Chrome,除了 npx 快取之外無需網路。
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. 僅編輯 $COMP/index.html — 如果需要非預設長度,請變更根元素的 `data-duration`,
# 在 <style> 中交換預設調色板,為文字/圖像添加 1–3 個剪輯 <div>,然後在現有的
# `window.__timelines["main"] = gsap.timeline({paused:true})` 區塊內
# 附加相符的 GSAP 補間。保持編輯最小化;Scaffold 已經是有效的 HF。
# 4. 透過 OD 守護程式分派渲染。請勿從此 shell 執行 `npx hyperframes
# render` — 守護程式會在一個非沙箱化的行程中為你執行它。(許多代理 CLI,特別是 Claude Code,
# 會將 Bash 包裝在 macOS sandbox-exec 中,在該環境下,puppeteer 的 Chrome
# 子行程會在畫面捕捉過程中部分掛起。守護程式行程
# 是非沙箱化的,因此渲染可以可靠完成。)
#
# 分派器大約在 1 秒內返回一個 {taskId};透過迴圈呼叫 `"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>` 來驅動渲染完成。
# 每次呼叫最多長輪詢 25 秒(遠低於你的 shell 工具的預設 30 秒上限),並以退出碼 0/2/5 表示完成/執行中/失敗。
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<描述性名稱>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
每次 generate 和每次 wait 呼叫最多持續約 25 秒,因此代理程式 shell 工具的預設約 30 秒上限永遠不會觸發。來自 HF 的進度行(Capturing frame N/M)會在整個迴圈期間即時串流到 stderr。當渲染完成時,最後一行 stdout 是 {"file": { "name": "<output>", "size": …, "kind": "video", … }} — 在你的回覆中引用 file.name,以便使用者知道產生了什麼。
在 OD 內部跳過視覺識別閘門。 下面的「方法」部分中的 HARD-GATE(強制閘門)部分告訴你要先讀取 DESIGN.md / visual-style.md,或者停下來問 3 個關於情緒的問題,然後才能撰寫任何合成。該閘門適用於獨立的 HF 專案。OD 專案已經有自己的設計系統層 — 使用者在建立專案時選擇了他們的視覺方向。對於 OD 測試渲染,預設使用:深色畫布 (#0b0b0f)、一個暖色強調色 (#ffb76b)、一個冷色強調色 (#7da4ff)、克制的動畫。僅當使用者的提示過於模糊以至於甚至無法選擇主題時(這種情況非常罕見),才詢問風格輸入。
何時跳過 Scaffold 並從頭開始撰寫:僅當使用者明確要求一些空白範本顯然無法容納的內容時(例如,多合成時間軸、音訊反應式疊加層、與他們已產生的 TTS 音軌同步的字幕)。對於所有其他情況,init + edit 是預設路徑。
你可以直接從自己的 shell 執行的較輕量 HF 子命令(它們不需要啟動 Chrome):
npx hyperframes lint "$COMP"— 在分派前驗證合成npx hyperframes transcribe <audio>— 產生字幕npx hyperframes tts <text>— 產生配音
將守護程式分派保留給 render/inspect/preview(任何與 Chrome 相關的操作)。
請勿呼叫 "$OD_NODE_BIN" "$OD_BIN" media generate --model hyperframes-html — 該分派器路徑會有意返回 400(AGENT_RENDERED)。HyperFrames 由你直接透過 npx 渲染。
請勿將 hyperframes.json / meta.json / index.html 放置在專案根目錄中;OD 的檔案清單會遞迴掃描,使用者會看到三個不相關的檔案出現在聊天中。
對於 render 以外的 CLI 選項(lint、preview、transcribe、tts、inspect、benchmark),當任務需要時(例如,在從合成中引用之前,將 TTS 音訊產生到快取中),直接從你的 shell 工具呼叫它們。
方法
在撰寫 HTML 之前,請從高層次思考:
- 什麼 — 觀眾應該體驗到什麼?識別敘事弧線、關鍵時刻和情感節拍。
- 結構 — 有多少個合成,哪些是子合成與內聯合成,哪些音軌承載什麼內容(影片、音訊、疊加層、字幕)。
- 時間 — 哪些剪輯驅動持續時間,轉場發生在哪裡,節奏是什麼。
- 佈局 — 首先建立結束狀態。請參閱下面的「佈局先於動畫」。
- 製作動畫 — 然後使用下面的規則添加運動。
對於小型編輯(修正顏色、調整時間、添加一個元素),請直接跳到規則。
視覺識別閘門
<強制閘門> 在撰寫任何合成 HTML 之前,你必須定義視覺識別。請勿使用預設或通用顏色來撰寫合成。
按此順序檢查:
- 專案中存在 DESIGN.md? → 讀取它。使用其確切顏色、字體、運動規則和「禁止事項」限制。
- 存在 visual-style.md? → 讀取它。應用其
style_prompt_full和結構化欄位。(注意:visual-style.md是一個專案特定的檔案。visual-styles.md是包含 8 個命名預設風格的風格庫 — 是不同的檔案。) - 使用者命名了一種風格(例如,「Swiss Pulse」、「暗色科技風」、「奢華品牌」)? → 讀取 visual-styles.md 以取得 8 個命名預設風格。產生一個最小化的 DESIGN.md,包含:
## 風格提示(一個段落)、## 顏色(3-5 個十六進位值及其角色)、## 字體排印學(1-2 個字體家族)、## 禁止事項(3-5 個反模式)。 - 以上皆非? → 在撰寫任何 HTML 之前問 3 個問題:
- 情緒是什麼?(爆炸性 / 電影感 / 流暢 / 技術性 / 混亂 / 溫暖)
- 亮色還是暗色畫布?
- 有沒有特定的品牌顏色、字體或視覺參考? 然後根據答案產生一個最小化的 DESIGN.md。
每個合成必須將其調色板和字體排印學追溯到 DESIGN.md、visual-style.md 或使用者的明確指示。如果你正要使用 #333、#3b82f6 或 Roboto — 你跳過了這一步。
</強制閘門>
關於運動預設值、尺寸、入場模式和緩動 — 請遵循 house-style.md。室內風格處理物體如何移動。DESIGN.md 處理物體的外觀。
佈局先於動畫
將每個元素放置在其最顯眼的時刻應該在的位置 — 即它完全進入、正確放置且尚未退出的影格。首先將其撰寫為靜態 HTML+CSS。暫時不要使用 GSAP。
為什麼這很重要: 如果你將元素放置在它們的動畫起始狀態(在畫面外、縮放為 0、透明度為 0),然後將它們補間到你認為它們應該落定的位置,你是在猜測最終的佈局。重疊在影片渲染之前是不可見的。透過首先建立結束狀態,你可以在添加任何運動之前看到並修正佈局問題。
過程
- 為每個場景識別主要影格 — 大多數元素同時可見的時刻。這就是你要建立的佈局。
- 為該影格撰寫靜態 CSS。
.scene-content容器必須使用width: 100%; height: 100%; padding: Npx; display: flex; flex-direction: column; gap: Npx; box-sizing: border-box來填滿整個場景。使用 padding 將內容向內推 — 永遠不要在內容容器上使用position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。保留position: absolute僅用於裝飾性元素。 - 使用
gsap.from()添加入場 — 從畫面外/不可見動畫到 CSS 位置。CSS 位置是基本事實;補間描述了到達那裡的路徑。 - 使用
gsap.to()添加退場 — 從 CSS 位置動畫到畫面外/不可見。
範例
/* scene-content 填滿場景,padding 定位內容 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* 容器填滿任何場景大小(1920x1080、1080x1920 等)。
Padding 定位內容。Flex + gap 處理間距。 */
錯誤 — 硬編碼尺寸和絕對定位:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// 步驟 3:動畫到這些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// 步驟 4:從這些位置動畫退出
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
當元素隨時間共享空間時
如果元素 A 在元素 B 進入同一區域之前退出,則兩者都應具有其各自主要影格的正確 CSS 位置。時間軸排序保證了它們永遠不會在視覺上共存 — 但是如果你跳過了佈局步驟,你將不會捕捉到由於時間錯誤而意外重疊的情況。
什麼算是故意重疊
分層效果(文字後方的發光、陰影元素、背景圖案)和 Z 軸堆疊設計(卡片堆疊、深度層次)是故意的。佈局步驟的目的是捕捉非故意的重疊 — 兩個標題互相重疊、一個統計數字覆蓋標籤、內容溢出畫面邊界。
資料屬性
所有剪輯
| 屬性 | 必要 | 值 |
|---|---|---|
id | 是 | 唯一識別碼 |
data-start | 是 | 秒數或剪輯 ID 引用("el-1"、"intro + 2") |
data-duration | img/div/compositions 需要 | 秒數。影片/音訊預設為媒體持續時間。 |
data-track-index | 是 | 整數。相同音軌的剪輯不能重疊。 |
data-media-start | 否 | 從來源裁剪的偏移量(秒) |
data-volume | 否 | 0-1(預設 1) |
data-track-index 不影響視覺分層 — 請使用 CSS z-index。
合成剪輯
| 屬性 | 必要 | 值 |
|---|---|---|
data-composition-id | 是 | 唯一合成 ID |
data-start | 是 | 開始時間(根合成:使用 "0") |
data-duration | 是 | 優先於 GSAP 時間軸持續時間 |
data-width / data-height | 是 | 像素尺寸(1920x1080 或 1080x1920) |
data-composition-src | 否 | 外部 HTML 檔案的路徑 |
合成結構
透過 data-composition-src 載入的子合成使用 <template> 包裝器。獨立合成(主 index.html)不使用 <template> — 它們將 data-composition-id div 直接放在 <body> 中。在獨立的檔案上使用 <template> 會對瀏覽器隱藏所有內容並破壞渲染。
子合成結構:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- content -->
<style>
[data-composition-id="my-comp"] {
/* scoped styles */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
在根元素中載入:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-star…