HyperFrames
HTML 是影片的單一事實來源。一個合成是一個帶有 data-* 屬性(用於時間控制)、GSAP 時間軸(用於動畫)和 CSS(用於外觀)的 HTML 檔案。該框架負責處理剪輯能見度、媒體播放和時間軸同步。
方法
探索(僅限探索性請求)
對於開放式請求(「幫我做一支產品發布影片」、「為我們的品牌創作一些內容」),在使用者尚未確定方向時,應先了解意圖,再選擇顏色:
- 受眾 — 誰在看?開發者?高層?一般消費者?
- 平台 — 在哪裡播放?社群媒體(15秒)、網站英雄區、產品展示、內部使用?
- 優先級 — 最重要的是什麼?動作品質?內容準確性?品牌忠實度?速度?
- 變體 — 使用者想要多個選項,還是單一最佳成品?
對於特定請求(「加入一個標題卡」、「修正場景3的時間」),則跳過探索步驟。
對於探索性請求,可以考慮提供 2-3 個有意義差異的變體——不僅是顏色更換,而是不同的節奏、能量水平或結構方法。一個是安全/預期的,一個是雄心勃勃的。不要強制要求——這只是在適當時機可用的工具。
步驟 1:設計系統
如果專案中存在 design.md 或 DESIGN.md,請先讀取它(檢查兩種大小寫——在 Linux 上是不同的檔案)。它是品牌顏色、字型和限制的單一事實來源。使用其確切的值——不要發明顏色或替換字型。任何格式皆可(YAML frontmatter、散文、表格——只需提取數值)。
如果它指定了本地找不到的字型(沒有包含 .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 之前,先在較高層次思考:
- 什麼 — 觀眾應該體驗到什麼?識別敘事弧線、關鍵時刻和情感節拍。
- 結構 — 有多少個合成,哪些是子合成與內聯合成,哪些音軌承載什麼(影片、音頻、疊加層、字幕)。
- 節奏 — 在實作之前宣布你的場景節奏。哪些場景是快速節奏,哪些是停留,著色器落在哪裡,能量高峰在哪裡。命名模式:快-快-慢-快-著色器-停留。閱讀 references/beat-direction.md 以了解節奏模板。
- 時間 — 哪些剪輯驅動持續時間,轉場落在哪裡,節奏是什麼。
- 佈局 — 首先建立最終狀態。請參閱下方的「佈局優先於動畫」。
- 動畫 — 然後使用下方規則加入動態。
只建立被要求的內容。 「一個標題卡」的請求不是「一個標題卡 + 3 個輔助場景 + 背景音樂 + 字幕」的請求。每個場景、每個元素、每個補間都應該有其存在的理由。如果額外的場景或元素能真正改善作品,可以提出建議——但不要擅自加入。
對於小型編輯(修正顏色、調整時間、加入一個元素),直接跳到規則。
佈局優先於動畫
將每個元素放置在其最顯眼的時刻應在的位置——也就是它完全進入、正確放置且尚未退出的影格。首先將其撰寫為靜態 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 位置是地面真相;補間描述了到達那裡的過程。(在透過data-composition-src載入的子合成中,建議使用gsap.fromTo()——請參閱 references/motion-principles.md 中的關鍵 GSAP 規則。) - 使用
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:動畫到那些位置
從(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
從(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
從(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// 步驟 4:從那些位置動畫退出
到(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
到(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
到(".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/合成必需 | 秒數。影片/音頻預設為媒體持續時間。 |
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>
影片和音頻
影片必須使用 muted playsinline。音頻始終使用獨立的 <audio> 元素:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
時間軸協定
- 所有時間軸都以
{ paused: true }開頭——播放器控制播放 - 註冊每個時間軸:
window.__timelines["<composition-id>"] = tl - 框架會自動巢狀化子時間軸——不要手動加入它們
- 持續時間來自
data-duration,而不是來自 GSAP 時間軸長度 - 永遠不要為了設定持續時間而建立空的補間
規則(不可協商)
確定性: 不要使用 Math.random()、Date.now() 或基於時間的邏輯。如果需要虛擬隨機值(例如 mulberry32),請使用種子化 PRNG。
GSAP: 只能動畫視覺屬性(opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、變換)。不要動畫 visibility、display,或呼叫 video.play()/audio.play()。
動畫衝突: 永遠不要同時從多個時間軸對同一元素動畫同一屬性。
不允許 repeat: -1: 無限重複的時間軸會破壞捕捉引擎。根據合成持續時間計算精確的重複次數:repeat: Math.ceil(duration / cycleDuration) - 1。
同步時間軸建構: 永遠不要在 async/await、setTimeout 或在 Promises 內部建構時間軸。捕捉引擎在頁面載入後同步讀取 window.__timelines。字型由編譯器嵌入,因此立即可用——無需等待字型載入。
絕對不要做:
- 忘記
window.__timelines註冊 - 使用影片作為音頻——始終使用靜音影片 + 獨立的
<audio> - 將影片巢狀在計時 div 內——使用非計時包裝器
- 使用
data-layer(使用data-track-index)或data-end(使用data-duration) - 動畫影片元素尺寸——動畫一個包裝 div
- 對媒體呼叫 play/pause/seek——框架擁有播放控制
- 建立沒有
data-composition-id的頂層容器 - 在任何時間軸或補間上使用
repeat: -1——始終使用有限重複 - 非同步建構時間軸(在
async、setTimeout、Promise內部) - 對來自後續場景的剪輯元素使用
gsap.set()——它們在頁面載入時不存在於 DOM 中。請在時間軸內部於或晚於剪輯的data-start時間使用tl.set(selector, vars, timePosition)。 - 在內容文字中使用
<br>——強制換行不考慮實際渲染的字型寬度。自然換行的文字加上<br>會產生額外的不需要的換行,導致重疊。請改用max-width讓文字換行。例外:簡短的顯示標題,其中每個單詞刻意位於自己的行上(例如 "THE\nIMMORTAL\nGAME" 大小為 130px)。
場景轉場(不可協商)
每個多場景合成都必須遵循以下所有規則。違反任一規則即為損壞的合成。
- **
… [內容已截斷以利翻譯]