HyperFrames
HTML 是影片的唯一真相來源。一個合成就是一個 HTML 檔案,包含用於時間控制的 data-* 屬性、用於動畫的 GSAP 時間軸,以及用於外觀的 CSS。框架負責處理剪輯可見性、媒體播放和時間軸同步。
屬性 API、合成/模板結構、變數和媒體規則: references/authoring.md。在一個工作階段中撰寫第一個合成 HTML 之前,請先閱讀它。
方法
探索(僅限開放式請求)
對於開放式請求(「幫我做一個產品發布影片」),在使用者尚未確定方向時,應先了解意圖再選擇顏色:目標觀眾、平台、優先級(動畫品質 vs 準確性 vs 速度),以及他們是否需要不同版本。如果需要不同版本,提供 2-3 個在節奏或結構上有所不同的選項——一個安全、一個大膽——而不是單純的顏色互換。
對於具體請求(「添加一個標題卡」、「修正場景 3 的時間」),則跳過探索步驟。
步驟 1:設計系統
如果存在 design.md 或 DESIGN.md,請先讀取它(兩種大小寫——在 Linux 上是不同的檔案)。它是品牌顏色、字體和限制條件的唯一真相來源——請使用其精確值。如果它指定的字體在 fonts/ 中沒有對應的 .woff2 檔案,且沒有內建的匹配項,請在撰寫 HTML 前警告使用者。
如果沒有 design.md,請提供一個選擇:
- 使用者指定了風格或情緒? 讀取 visual-styles.md(8 個具名預設),選擇最接近的。
- 想視覺化瀏覽? 執行設計選取器——references/design-picker.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:規劃
- 是什麼 - 敘事弧線、關鍵時刻、情緒節奏。
- 結構 - 多少個合成、子合成 vs 內聯、哪些軌道承載什麼。
- 節奏 - 在實現之前宣告場景節奏(快-快-慢-快-著色器-停頓)。模板:references/beat-direction.md。
- 時間 - 哪些剪輯驅動時長,過渡落在哪裡。
- 佈局 - 先構建最終狀態(下一節)。
- 動畫 - 然後添加運動。
只構建被要求的內容。 「一個標題卡」不是「一個標題卡 + 3 個輔助場景 + 音樂 + 字幕」。可以提議額外的元素,但不要擅自添加。
對於小型編輯,直接跳到規則。
先佈局後動畫
將每個元素放置在其最顯眼的時刻應在的位置——完全進入、正確放置、尚未退場。先將其編寫為靜態的 HTML+CSS。先不要加入 GSAP。
原因:如果你將元素放置在它們動畫的起始狀態(螢幕外、不透明度為 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(當內容增長時它會溢出)。保留絕對定位給裝飾性元素使用。 - 使用
gsap.from()製作進場效果——從螢幕外動畫到 CSS 位置。CSS 是基本事實,補間是旅程。(透過data-composition-src載入的子合成:偏好使用gsap.fromTo()——請參考 references/motion-principles.md。) - 僅限最後一個場景:使用
gsap.to()製作退場效果。 所有其他場景以完全可見的狀態結束——過渡本身就是退場(以下的過渡規則 3)。
如果元素 A 在元素 B 進入同一區域之前退場,則為兩者在其各自的關鍵影格賦予正確的 CSS 位置——時間軸會阻止它們同時存在,而佈局步驟會捕捉到由於時序錯誤導致的意外重疊。有意的分層(文字後的光暈、卡片堆疊)是可以的;此步驟的目的是捕捉非故意的重疊——兩個標題撞在一起、一個統計數據遮住標籤、內容跑出影格。
時間軸合約
- 所有時間軸都以
{ paused: true }開始——播放器控制播放 - 註冊每個時間軸:
window.__timelines["<合成-id>"] = tl - 框架會自動嵌套子時間軸——請勿手動添加它們
- 時長來自
data-duration,而非 GSAP 時間軸長度 - 永遠不要為了設定時長而創建空的補間
規則(不可協商)
確定性: 沒有 Math.random()、Date.now() 或基於時間的邏輯。使用種子式 PRNG(例如 mulberry32)來實現偽隨機。
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 - 非同步構建時間軸
- 在後續場景的剪輯元素上使用
gsap.set()——它們在頁面載入時不存在於 DOM 中。應在剪輯的data-start時刻或之後使用tl.set(selector, vars, timePosition)。 - 在內容文字中使用
<br>——它會與自然換行疊加並導致重疊;應改用max-width。例外:刻意每行一個單詞的短顯示標題。
場景轉場(不可協商)
每個多場景合成都必須遵循以下所有四條。違反任何一條都會導致合成損壞。
- 始終在場景之間使用轉場。 不能有跳切。
- 始終透過
gsap.from()動畫化每個元素的進場。沒有元素是憑空出現的。五個元素意味著五個進場補間。 - 永遠不要使用退場動畫,除了最後一個場景。不要在轉場前使用
gsap.to()來淡出不透明度、移出螢幕或縮小到 0——轉場本身就是退場,而當轉場觸發時,正在退出的場景必須是完全可見的。在轉場之前的退場補間會給轉場提供一個空影格。 - 僅限最後一個場景可以淡出元素。
轉場選擇和實現:references/transitions.md。
動畫護欄
- 將第一個動畫偏移 0.1-0.3 秒(不要從 t=0 開始)
- 變化緩動函數——每個場景至少使用 3 種不同的緩動函數,同一個場景內不要重複入場模式
- 避免在深色背景上使用全螢幕線性漸變(H.264 條帶問題)——使用徑向或純色加上局部光暈
- 標題 60px 以上,正文 20px 以上,資料標籤 16px 以上
- 在數字欄上使用
font-variant-numeric: tabular-nums
編輯現有合成
- 讀取實際檔案,不要猜測。 合成就是規範——從原始碼中提取確切的十六進制顏色、字體和緩動模式,而不是靠記憶。
- 只更改被要求的內容;保留不相關剪輯的時間。
輸出檢查清單
快速(立即執行,等待結果):
-
npx hyperframes lint和npx hyperframes validate都通過 - 如果存在 design.md,則驗證了設計符合性
慢速(在展示預覽的同時並行執行):
-
npx hyperframes inspect通過,或所有報告的溢出都已有意地標記 - 對比度警告已處理
- 動畫編排已驗證(動畫對映腳本)
如何執行和修復每個檢查:references/quality-checks.md。
參考索引
任何新的合成都必須閱讀:
| 檔案 | 涵蓋內容 |
|---|---|
| references/authoring.md | data 屬性、模板結構、變數、影片/音頻、字體/資產 |
| references/video-composition.md | 影片媒體規則——這些會覆蓋網頁本能 |
| references/typography.md | 字體搭配、OpenType、深色背景調整 |
| references/motion-principles.md | 運動設計、圖片運動、承重 GSAP 規則 |
多場景合成也必須閱讀:
| 檔案 | 涵蓋內容 |
|---|---|
| references/beat-direction.md | 節奏模板、編排動詞、深度圖層 |
| references/transitions.md | 轉場選擇;目錄 指向實現;著色器轉場位於 @hyperframes/shader-transitions npm 套件中(在 node_modules 中閱讀其原始碼) |
當任務需要時閱讀:
| 檔案 | 何時閱讀 |
|---|---|
| references/quality-checks.md | 執行 inspect/contrast/design/animation-map 檢查時 |
| references/cli.md | 任何 CLI 命令;建構/渲染故障排除 |
| references/captions.md | 任何與音頻時間同步的文字 |
| references/transcript-guide.md | 字幕側的轉錄處理(CLI 調用方式在 media.md 中) |
| references/dynamic-techniques.md | 動態字幕動畫(卡拉OK、重擊、散開) |
| references/audio-reactive.md | 對音樂/人聲做出反應的視覺效果 |
| references/css-patterns.md | 標記高亮(高亮、圓圈、爆發、塗鴉) |
| references/techniques.md | 每個節拍的規劃技巧(11 種模式及程式碼) |
| references/narration.md | 語音旁白/TTS 的節奏和腳本結構 |
| references/media.md | TTS(Kokoro)、轉錄(Whisper)、去背 |
| references/prompt-expansion.md | 方法的步驟 2 |
| references/design-picker.md | 以視覺化方式創建 design.md |
| references/from-website.md | 將網站轉換為影片 |
| references/registry.md | 安裝/貢獻註冊表區塊(hyperframes add) |
| visual-styles.md | 使用者指定風格時使用;生成 design.md |
| house-style.md | 沒有 design.md 時的美學預設值 |
| patterns.md | 畫中畫、標題卡、幻燈片 |
| data-in-motion.md | 數據、統計、資訊圖表 |
運行時適配器(當合成使用該運行時而非 GSAP 時閱讀):waapi、lottie、three、animejs、css-animations、typegpu。