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 內建的腳手架,僅編輯提示實際更改的內容。「從頭開始撰寫」的路徑需要耗費數分鐘的模型輸出和無聲的聊天工具時間;而腳手架路徑只需幾秒鐘。
# 1. 選擇一個隱藏的快取槽位。點號前綴 → OD 的專案檔案列表會跳過它,
# 因此原始檔案永遠不會使聊天變得雜亂。
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. 取得一個可立即渲染的腳手架(hyperframes.json、
# meta.json、index.html,其中已包含 GSAP CDN 和
# window.__timelines.main 註冊)。這在你的 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 補間動畫。保持編輯量最少;腳手架已經是有效的 HF。
# 4. 透過 OD 守護行程調度渲染。請勿從此 shell 執行 `npx hyperframes
# render` — 守護行程會為你在非沙箱的行程中執行它。(許多代理程式 CLI,
# 尤其是 Claude Code,會將 Bash 包裝在 macOS 的 sandbox-exec 中,
# 在該環境下,puppeteer 的 Chrome 子行程在幀捕捉過程中會部分掛起。
# 守護行程是非沙箱的,因此渲染能可靠完成。)
#
# 調度器大約在 1 秒內回傳一個 {taskId};透過循環呼叫 `od media wait <taskId>`
# 來驅動渲染完成。每個呼叫最長輪詢 25 秒(遠低於 shell 工具預設的 30 秒上限),
# 並以退出碼 0/2/5 來表示完成/執行中/失敗。
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<descriptive-name>.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=$(node "$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)、節制運動。僅在使用者的提示過於模糊以致於無法選擇主題(非常罕見)時才詢問風格輸入。
何時跳過腳手架並從頭開始撰寫:僅當使用者明確要求空白範本明顯無法容納的內容時(例如,多合成時間軸、音頻反應疊加層、與已產生的 TTS 音軌同步的字幕)。對於所有其他情況,init + 編輯是預設路徑。
你仍然可以從自己的 shell 執行的較輕量 HF 子命令(它們不需要啟動 Chrome):
npx hyperframes lint "$COMP"— 在調度前驗證合成npx hyperframes transcribe <audio>— 產生字幕npx hyperframes tts <text>— 產生旁白
將守護行程調度保留給 render/inspect/preview(任何與 Chrome 綁定的操作)。
請勿 呼叫 od 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),當任務需要時,可直接從你的 shell 工具呼叫它們(例如,在合成中引用之前,先將 TTS 音頻生成到快取中)。
方法
在撰寫 HTML 之前,請從高層次思考:
- 什麼 — 觀眾應該體驗什麼?識別敘事弧線、關鍵時刻和情緒節拍。
- 結構 — 有多少個合成,哪些是子合成 vs 內聯,哪些軌道承載什麼(影片、音訊、疊加層、字幕)。
- 時間 — 哪些片段驅動持續時間,轉場落在哪裡,節奏如何。
- 佈局 — 先建立最終狀態。請參閱下面的「先佈局後動畫」。
- 動畫 — 然後使用以下規則添加運動。
對於小型編輯(修正顏色、調整時間、添加一個元素),可以直接跳到規則。
視覺身分門控
按以下順序檢查:
- 專案中存在 DESIGN.md? → 讀取它。使用其確切的顏色、字體、運動規則和「不要做的事項」約束。
- 存在 visual-style.md? → 讀取它。應用其
style_prompt_full和結構化欄位。(注意:visual-style.md是專案特定的檔案。visual-styles.md是具有 8 個命名預設的樣式庫 — 是不同的檔案。) - 使用者指定了樣式(例如「Swiss Pulse」、「dark and techy」、「luxury brand」)? → 讀取 visual-styles.md 以取得 8 個命名預設。產生一個最小的 DESIGN.md,包含:
## Style Prompt(一個段落)、## Colors(3-5 個十六進制值和角色)、## Typography(1-2 個字體家族)、## What NOT to Do(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來填滿整個場景。使用內邊距將內容向內推 — 永遠不要在內容容器上使用position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。保留position: absolute僅用於裝飾性元素。 - 使用
gsap.from()添加進入動畫 — 從螢幕外/不可見動畫到 CSS 位置。CSS 位置是基本事實;補間描述到達那裡的旅程。 - 使用
gsap.to()添加退出動畫 — 從 CSS 位置動畫到螢幕外/不可見。
範例
/* scene-content 填滿場景,內邊距定位內容 */
.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 等)。
內邊距定位內容。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/composition 需要 | 秒數。影片/音訊預設為媒體持續時間。 |
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">
<!-- 內容 -->
<style>
[data-composition-id="my-comp"] {
/* 作用域樣式 */
}
</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 });
// 補間...
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-start="0" data-duration="10" data-track-index="1"></div>
影片
…
[因翻譯而截斷]