HyperFrames
HTML 是影片的單一事實來源。一段合成(Composition)就是一個 HTML 檔案,其中包含用於時間設定的 data-* 屬性、用於動畫的 GSAP 時間軸,以及用於外觀的 CSS。框架會處理片段可見性、媒體播放和時間軸同步。
方法
探索(僅限探索性請求)
對於開放式請求(「幫我做一支產品發表影片」、「為我們的品牌創作一些東西」),當使用者尚未確定方向時,請先瞭解意圖,再挑選顏色:
- 觀眾(Audience) — 誰會觀看這支影片?開發者?高階主管?一般消費者?
- 平台(Platform) — 影片要在哪裡播放?社群媒體(15 秒)、網站主視覺、產品示範、內部使用?
- 優先級(Priority) — 什麼最重要?動畫品質?內容準確性?品牌忠實度?速度?
- 變體(Variations) — 使用者想要多個選項,還是只要一個最好的方案?
對於具體請求(「加個標題卡」、「調整場景 3 的時間」),請跳過探索步驟。
對於探索性請求,可以考慮提供 2-3 個有實質差異的變體,而不僅僅是換顏色——例如不同的節奏、能量水準或結構方法。一個安全/符合預期,一個大膽創新。這不是強制性的——是在合適時可用的工具。
步驟 1:設計系統
如果專案中存在 design.md 或 DESIGN.md 檔案,請先讀取它(檢查兩種大小寫——在 Linux 上是不同的檔案)。這是品牌顏色、字型和限制條件的單一事實來源。使用其中的確切數值——不要發明顏色或替換字型。任何格式都可以(YAML 前置元資料、散文、表格——只需提取數值)。
如果它指定的字型在本地找不到(沒有包含 .woff2 檔案的 fonts/ 目錄,也不是內建字型),請在撰寫 HTML 之前警告使用者:「design.md 指定了 [字型名稱] 但找不到字型檔案。請將 .woff2 檔案新增到 fonts/,否則我將回退到 [最接近的內建替代方案]。」
如果沒有 design.md 存在,請給使用者提供一個選擇:
- 使用者提到了風格或氛圍? → 閱讀 visual-styles.md 中的 8 個命名預設。選擇最接近的。
- 想要視覺化瀏覽選項? → 執行設計選擇器:閱讀 references/design-picker.md 以瞭解完整工作流程。這會提供一個視覺選擇器頁面。使用者在瀏覽器中配置氛圍、調色板、排版和動畫,然後複製生成的 design.md 並將其貼回對話中。
- 想跳過步驟快速進行? → 詢問:氛圍、淺色或深色、是否有任何品牌顏色/字型?然後從 house-style.md 中選擇一個調色板。
design.md 定義品牌。它不定義影片合成規則。 這些規則來自 references/video-composition.md 和 house-style.md。以適合影片的規模使用品牌顏色——而不是像網頁 UI 那樣的透明度。
步驟 2:提示擴展
始終對每個合成執行此步驟(單場景片段和簡單編輯除外)。這一步驟會根據 design.md 和 house-style.md 來鞏固使用者的意圖,並產生一個一致的、所有下游代理都能以相同方式讀取的中間產物。
閱讀 references/prompt-expansion.md 以瞭解完整的流程和輸出格式。
步驟 3:規劃
在撰寫 HTML 之前,先從高層次思考:
- 內容(What) — 觀眾應該體驗到什麼?識別敘事弧線、關鍵時刻和情感節拍。
- 結構(Structure) — 有多少個合成,哪些是子合成(sub-composition)與內聯合成(inline),哪些軌道承載什麼內容(影片、音訊、疊加層、字幕)。
- 節奏(Rhythm) — 在實施之前宣告你的場景節奏。哪些場景是快速切換,哪些是停留,著色器出現在哪裡,能量高峰在哪裡。命名模式:快-快-慢-快-著色器-停留。閱讀 references/beat-direction.md 以瞭解節奏模板。
- 時間(Timing) — 哪些片段驅動持續時間,轉場發生在哪裡,節奏如何。
- 佈局(Layout) — 先構建最終狀態。請參閱下面的「先佈局後動畫」。
- 動畫(Animate) — 然後使用下方的規則加入動畫。
只構建被要求的東西。 「一個標題卡」的請求不是「一個標題卡 + 3 個輔助場景 + 背景音樂 + 字幕」的請求。每個場景、每個元素、每個補間動畫都應有其存在的理由。如果額外的場景或元素能真正改善作品,請提出建議——但不要擅自加入。
對於小型編輯(修正顏色、調整時間、加入一個元素),直接跳到規則。
先佈局後動畫
將每個元素放置在其最顯眼的時刻——也就是它完全進入、正確定位、且尚未退出的幀。先將其寫成靜態的 HTML+CSS。此時還不需要 GSAP。
為什麼這很重要: 如果你將元素定位在它們的動畫起始狀態(畫面外、縮放到 0、透明度 0),然後補間到你認為它們最終應該到達的位置,你只是在猜測最終佈局。重疊問題在影片渲染之前是看不見的。透過先構建最終狀態,你可以在加入任何動畫之前看到並修復佈局問題。
過程
- 為每個場景識別主要幀(hero frame) — 即大部分元素同時可見的時刻。這就是你要構建的佈局。
- 為該幀撰寫靜態 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 位置是基本事實;補間描述了到達該位置的過程。(在透過data-composition-src載入的子合成中,偏好使用gsap.fromTo()——請參閱 references/motion-principles.md 中的載荷 GSAP 規則。) - 使用
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 軸堆疊設計(卡片堆疊、深度層次)是有意的。佈局步驟的目的是捕捉無意的重疊——兩個標題落在彼此上方、一個統計數字覆蓋了標籤、內容超出畫面。
資料屬性
所有片段
| 屬性 (Attribute) | 必要 (Required) | 值 (Values) |
|---|---|---|
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。
合成片段
| 屬性 (Attribute) | 必要 | 值 |
|---|---|---|
data-composition-id | 是 | 唯一的合成 ID |
data-start | 是 | 開始時間(根合成:使用 "0") |
data-duration | 是 | 優先於 GSAP 時間軸持續時間 |
data-width / data-height | 是 | 像素尺寸 (1920x1080 或 1080x1920) |
data-composition-src | 否 | 外部 HTML 檔案的路徑 |
data-variable-values | 否 | 子合成主機上每個實例變數覆蓋的 JSON 物件 |
在根 <html> 元素上:
| 屬性 (Attribute) | 必要 | 值 |
|---|---|---|
data-composition-variables | 否 | 已宣告變數的 JSON 陣列 (id/type/label/default) — 驅動 Studio 編輯 UI 並為 getVariables() 提供預設值 |
合成結構
透過 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>
變數(參數化合成)
使用不同的內容渲染同一個合成——標題、主題顏色、價格、字幕——而無需編輯原始 HTML。
三步驟模式:
- 宣告 合成
<html>根元素上的變數,使用data-composition-variables。每個條目需要id、type(string、number、color、boolean、enum之一)、label和default。列舉條目還需要options: [{value, label}, ...]。 - 讀取 合成內腳本中的解析值,使用
window.__hyperframes.getVariables()。返回宣告的預設值 + 每個實例的覆蓋值 + CLI 覆蓋值的合併結果。 - 覆蓋 在渲染時使用
npx hyperframes render --variables '{...}'(頂層)或使用主機元素上的data-variable-values='{...}'(子合成的每個實例)。
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"Title","default":"Hello"},
{"id":"theme","type":"enum","label":"Theme","default":"light","options":[
{"value":"light","label":"Light"},
{"value":"dark","label":"Dark"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# 開發預覽使用宣告的預設值
npx hyperframes preview
# 使用覆蓋值渲染
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4
# 或從 JSON 檔案讀取
npx hyperframes render --variables-file ./vars.json
子合成每個實例的值: 相同的 getVariables() 在透過 data-composition-src 載入的子合成內部也可以運作。每個主機元素傳遞其自己的值:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
…