Communitygithub.com

scott-fryxell/brayness

在 HyperFrames HTML 中建立影片合成、動畫、標題卡、疊層、字幕、語音旁白、音頻反應視覺效果和場景轉場。適用於任何基於 HTML 的影片工作——編寫合成、將字幕與音頻同步、生成 TTS 旁白、執行開發循環(初始化、檢查、預覽、渲染)、預處理資產(TTS、轉錄、去背),或安裝/貢獻註冊表區塊。

brayness 是什麼?

HyperFrames 是一個以 HTML 為核心的影片創作框架。此技能(brayness)讓 AI 代理程式能夠在 HyperFrames 中處理從簡單編輯到完整動畫影片的各種任務。其核心理念是「HTML 是影片的唯一真相來源」:使用帶有 `data-*` 屬性控制時間的 HTML 文件、GSAP 時間軸進行動畫、CSS 控制外觀,框架則負責處理剪輯可見性、媒體播放和時間軸同步。對於開放式請求,代理程式會先進行探索以了解意圖,然後遵循嚴格的開發流程:先建立設計系統(從現有的設計文件或使用者偏好中提取品牌色彩和字體)、擴展提示詞、規劃敘事結構、佈局(先靜態再動畫),最後確保使用非破壞性的場景轉場。該技能強調純 CSS 佈局(先建構最終狀態再動畫)、使用 GSAP 的 `from()` 製作進場效果、嚴格的時間軸註冊(`window.__timelines`),並遵守一系列防止不確定性、動畫衝突和渲染錯誤的硬性規則。支援 Cursor、Claude Code 和 Codex 等平台。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scott-fryxell/brayness/tree/HEAD/skills/hyperframes

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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,請提供一個選擇:

  1. 使用者指定了風格或情緒? 讀取 visual-styles.md(8 個具名預設),選擇最接近的。
  2. 想視覺化瀏覽? 執行設計選取器——references/design-picker.md。
  3. 想快速進行? 詢問情緒、明/暗色調、品牌顏色/字體;從 house-style.md 中選取一個調色板。

design.md 定義的是品牌,而非影片合成規則。 這些規則來自 references/video-composition.md 和 house-style.md。品牌色彩要以影片的規模來思考,而非網頁 UI 的不透明度。

步驟 2:提示詞擴展

除單場景片段和瑣碎編輯外,每個合成都要執行此步驟——根據 design.md/house-style.md 來紮根意圖,形成一致的中間表示。流程和格式:references/prompt-expansion.md。

步驟 3:規劃

  1. 是什麼 - 敘事弧線、關鍵時刻、情緒節奏。
  2. 結構 - 多少個合成、子合成 vs 內聯、哪些軌道承載什麼。
  3. 節奏 - 在實現之前宣告場景節奏(快-快-慢-快-著色器-停頓)。模板:references/beat-direction.md。
  4. 時間 - 哪些剪輯驅動時長,過渡落在哪裡。
  5. 佈局 - 先構建最終狀態(下一節)。
  6. 動畫 - 然後添加運動。

只構建被要求的內容。 「一個標題卡」不是「一個標題卡 + 3 個輔助場景 + 音樂 + 字幕」。可以提議額外的元素,但不要擅自添加。

對於小型編輯,直接跳到規則。

先佈局後動畫

將每個元素放置在其最顯眼的時刻應在的位置——完全進入、正確放置、尚未退場。先將其編寫為靜態的 HTML+CSS。先不要加入 GSAP。

原因:如果你將元素放置在它們動畫的起始狀態(螢幕外、不透明度為 0),然後朝著你認為它們應該在的位置進行補間,你就是在猜測最終佈局,而重疊問題在渲染前會一直不可見。先構建最終狀態,佈局錯誤在運動存在之前就能被發現。

  1. 找出每個場景的關鍵影格——大部分元素同時可見的時刻。構建那個佈局。
  2. 為其編寫靜態 CSS。.scene-content 必須填滿場景:width: 100%; height: 100%; padding: Npx; 並配合 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box。內邊距將內容推向內部——絕對不要在內容容器上使用 position: absolute; top: Npx(當內容增長時它會溢出)。保留絕對定位給裝飾性元素使用。
  3. 使用 gsap.from() 製作進場效果——從螢幕外動畫到 CSS 位置。CSS 是基本事實,補間是旅程。(透過 data-composition-src 載入的子合成:偏好使用 gsap.fromTo()——請參考 references/motion-principles.md。)
  4. 僅限最後一個場景:使用 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。字體由編譯器嵌入;無需等待字體載入。

絕對禁止:

  1. 忘記註冊 window.__timelines
  2. 使用影片來播放音頻——始終使用靜音影片 + 獨立的 <audio>
  3. 將影片嵌套在計時 div 內——使用非計時的包裝器
  4. 使用 data-layer(改用 data-track-index)或 data-end(改用 data-duration)
  5. 動畫化影片元素的尺寸——動畫化一個包裝 div
  6. 在媒體元素上呼叫 play/pause/seek——框架擁有播放控制權
  7. 創建一個沒有 data-composition-id 的頂層容器
  8. 在任何時間軸或補間上使用 repeat: -1
  9. 非同步構建時間軸
  10. 在後續場景的剪輯元素上使用 gsap.set()——它們在頁面載入時不存在於 DOM 中。應在剪輯的 data-start 時刻或之後使用 tl.set(selector, vars, timePosition)。
  11. 在內容文字中使用 <br>——它會與自然換行疊加並導致重疊;應改用 max-width。例外:刻意每行一個單詞的短顯示標題。

場景轉場(不可協商)

每個多場景合成都必須遵循以下所有四條。違反任何一條都會導致合成損壞。

  1. 始終在場景之間使用轉場。 不能有跳切。
  2. 始終透過 gsap.from() 動畫化每個元素的進場。沒有元素是憑空出現的。五個元素意味著五個進場補間。
  3. 永遠不要使用退場動畫,除了最後一個場景。不要在轉場前使用 gsap.to() 來淡出不透明度、移出螢幕或縮小到 0——轉場本身就是退場,而當轉場觸發時,正在退出的場景必須是完全可見的。在轉場之前的退場補間會給轉場提供一個空影格。
  4. 僅限最後一個場景可以淡出元素。

轉場選擇和實現: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.mddata 屬性、模板結構、變數、影片/音頻、字體/資產
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.mdTTS(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。

相關技能