heygen-com/hyperframes

插件安裝： 在執行設定或新鮮度指令之前，請先遵循插件執行規則（若此技能位於 HyperFrames 插件內）。獨立安裝則保留下方的更新說明。

HyperFrames 核心

代理陷阱（請先閱讀）：

• 中心化請使用 flex/inset，而不是在一個你隨後會用 GSAP x/y 操作的節點上使用 CSS transform: translate(-50%,-50%)。Lint 規則：gsap_css_transform_conflict。請改用 fromTo 或 xPercent/yPercent。
• 不要為場景退出添加 tl.set(..., {visibility:"hidden"})。執行環境已經會隱藏計時的剪輯。在內部節點上做透明度淡入淡出（或是在 .clip 上使用 opacity）就已足夠。字幕的硬性終止是另一套規則。
• window.__timelines["id"] 必須與根元素的 data-composition-id 相符。
• 在 render 之後，閱讀摘要的第二行：beginframe vs screenshot、GPU 模式、階段時間。screenshot 加上 Linux 上的 software gpu 是較慢的路徑。

HyperFrames 從 HTML 渲染影片。一個組合是一個 HTML 檔案，其 DOM 使用 data-* 屬性宣告時間，其動畫執行環境是可搜尋的，且其媒體播放由框架擁有。

此技能是技術合約 — 說明如何建構一個 hyperframes 專案。以下內容為建置指南；各主題的詳細資訊位於 references/（索引見下），請按需求閱讀。流程文件（簡報、分鏡、審查、製作、調度、幀處理）位於 /hyperframes → references/。其他相關議題位於同級領域技能中 — hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力對應圖會說明每個技能涵蓋的範圍。

參考資料

檔案	閱讀目的…
references/minimal-composition.md	從最小的可渲染組合骨架開始
references/composition-patterns.md	選擇整體式 vs 模組化；結構化一個模組化 index.html；選擇一個子組合原型
references/data-attributes.md	查詢任何 data-*（根 / 剪輯 / 子組合宿主 / 舊名稱別名）；使用 class="clip"
references/tracks-and-clips.md	了解 data-track-index 的作用（以及不作用）範圍、z 索引、相對於另一個剪輯的時間；使用 npx hyperframes timeline 列出每個軌道和剪輯
references/creator-editing-recipes.md	複製真實的剪下/修剪/重新排序/重新計時/凍結/鏡頭/遮罩/交叉淡入淡出/音訊編輯配方及其限制
references/sub-compositions.md	連接一個子組合（宿主屬性、<template>、每個實例的變數）並在其中製作動畫
references/variables-and-media.md	宣告變數；放置 <video>/<audio>、設定音量、修剪
references/determinism-rules.md	建構可搜尋的時間線；確定性禁止事項；佈局 / 文字適應
references/full-screen-motion.md	使用共享背景創建全幀運動
references/tailwind.md	在 Tailwind v4 專案中工作（init --tailwind；執行環境合約與 Studio 的 v3 不同）

動畫執行環境的具體資訊（GSAP API、Lottie、Three.js 等）請前往 hyperframes-animation → adapters/<runtime>.md。

建構一個組合

兩種根形式（不可互換）

• 獨立（頂層 index.html）：根元素 <div data-composition-id="…"> 直接位於 <body> 中，沒有 <template> 包裹。包裹獨立根元素會隱藏所有內容，且 lint 會拒絕它（standalone_composition_wrapped_in_template，錯誤）。
• 子組合（透過 data-composition-src 載入）：將根元素包裹在 <template> 中。這是建議撰寫的形式：載入器也接受純完整的文件並回退到其 <body>，但範例和工具假設的是模板化形式。

⚠ 傳輸規則：對於模板化的子組合，組裝器會丟棄檔案自身的 <head> <style>/<script>（packages/core/src/compiler/compositionAssembly.ts，hasTemplate 閘門），因此請將 <style>/<script> 放在模板內部。<link> 無論如何都會被提升。 ⚠ 宿主 ID 慣例：給予宿主插槽、內部模板和 window.__timelines["<id>"] 鍵相同的 ID。支援不同的本地 ID（組裝器會回退到檔案中的第一個根元素），但不匹配是靜默的，因此除非有理由不這樣做，否則請保持一致。

檔案結構、宿主連接和預渲染檢查清單 → references/sub-compositions.md。

根元素必須設定尺寸（靜默的佈局錯誤）

獨立根元素需要撰寫 width/height: 100%。畫布尺寸是 data-width/data-height。執行環境會將這些像素值套用到組合根元素上。不要在 #root 上硬編碼 1920px/1080px。骨架 → references/minimal-composition.md。

一個暫停的時間線

每個組合註冊恰好一個 gsap.timeline({ paused: true }) 在 window.__timelines["<id>"]（鍵 = 根元素的 data-composition-id）。在非同步回呼（document.fonts.ready）內部建構它是被支援的；重要的是你只在建構完成後註冊。渲染長度是根元素的 data-duration，而非時間線的長度：一個超過它的時間線會被截斷，而一個提前結束的時間線則會保持其最後一幀。省略根元素的 data-duration，長度將改為推斷（時間線、媒體視窗或適配器）。你不需要 window.__timelines = window.__timelines || {}：執行環境在你的內嵌腳本執行前就已創建註冊表，且 lint 不再要求它。不要手動將子時間線嵌套到宿主中；執行環境會自動嵌套已註冊的子時間線。完整合約（包括非 GSAP 執行環境） → references/determinism-rules.md + hyperframes-animation/adapters/。

首次 lint 陷阱（保證首次建構失敗）

lint 確實會捕捉的規則，但僅在事後。請在首次就正確撰寫：

• 永遠不要將 CSS 初始 transform 與 GSAP 對相同屬性的補間動畫配對 — CSS 值和補間動畫的起始值會衝突，且 lint 會以 gsap_css_transform_conflict 拒絕它。請使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在補間動畫內部設定初始狀態，而不是使用 CSS transform: translateX(-40px)。
• 永遠不要在 <video>/<audio> 上放置 crossorigin。lint 會無條件以 media_crossorigin_breaks_preview（錯誤）拒絕它，包括用於 canvas/WebGL/WebAudio 回讀。沒有抑制方法。
• 永遠不要讓一個 <video data-start> 有一個同時攜帶 data-start 的祖先。lint 會以 video_nested_in_timed_element（錯誤）拒絕它。請在包裝器或影片上設定時間，而非兩者。
• 每個 <audio> 都需要一個 id。lint 會以 media_missing_id 拒絕它，且沒有 id 的 <audio> 永遠不會被混音器拾取，因此渲染將會是靜音的。
• 永遠不要使用 autoAlpha 或 visibility 對 .clip 進行補間動畫 — lint 會以 gsap_animates_clip_element 拒絕它。請改為為子元素製作動畫。
• 一個命名的 CSS font-family 需要一個指向已提供本地檔案的 @font-face，否則 lint 會觸發 font_family_without_font_face。
• 子組合的 #root 使用 width/height: 100%（或 inset: 0），而不是硬編碼的 1920px/1080px。畫布尺寸是 data-width/data-height。

lint 錯誤也會關閉佈局和對比度稽核：check 接著會報告 0 sample(s) 和 0/0 text checks，這看起來像是一個乾淨的檔案，但實際上什麼也沒執行。在信任這些數字之前，請先清除 lint 錯誤。

不可協商的規則（自動化閘門可能遺漏的靜默錯誤）

在此列出；完整的理由在連結的參考資料中。請勿違反：

• 沒有渲染時間時鐘 / 未播種的 Math.random / 網路 / 輸入狀態；沒有 repeat: -1（請使用有限次數）。 → determinism-rules.md
• 永遠不要在 .clip 元素上補間 display、visibility 或 autoAlpha。框架擁有剪輯的可見性，且 lint 會拒絕它（gsap_animates_clip_element）。請改為為子元素製作動畫。 → determinism-rules.md
• 正文中沒有 <br>；轉換後的元素必須是區塊級別且有尺寸；脈動的絕對定位裝飾元素需要有間距餘裕。 → determinism-rules.md
• <video>/<audio> 是透過扁平的文件查詢找到的，因此框架可以在任何嵌套深度（包括在子組合 <template> 或包裝器內部）搜尋和解碼它們。一個硬性限制：如果一個 <video data-start> 位於另一個也帶有 data-start 的普通元素內部，lint 會報錯，且這是一個真實的失敗（錯誤的來源幀，然後剪輯在時間槽中間消失），因此請將時間設定在包裝器或影片上，絕不能兩者都設。子組合宿主除外：子組合內部的媒體可以正確渲染。另一個注意事項是時間線，而非放置位置：子組合時間線無法為宿主根元素製作動畫。 → variables-and-media.md
• 在組裝後的頁面上保持每個 id 唯一（為子組合 ID 加上組合 ID 前綴，例如 #<id>-hero），以便你自身的 #id CSS 和 getElementById 呼叫能夠正確解析。框架注入不再依賴於此：編譯器會在所有 video[src]/audio[src]/img[src] 上標記一個文件唯一的 data-hf-render-id。使用 <source> 子元素而非 src 屬性的媒體不會被標記，因此唯一 ID 在那裡仍然重要。 → composition-patterns.md
• 在組合根元素上進行全螢幕填充在正常渲染下是沒問題的。僅在分層合成路徑（HDR 內容，或使用著色器轉場的組合）上會被丟棄，此時引擎會強制每個組合根元素透明，以便底層顯示出來。如果你的組合使用著色器轉場或 HDR 媒體，請將填充放在一個全出血的子元素上（position:absolute; inset:0）。 → composition-patterns.md

編輯現有組合

• 先閱讀檔案。保留不相關的時間、軌道、ID、變數、媒體路徑。
• 要知道專案時間線上有什麼（軌道、剪輯、開始、結束、播放內容），請執行 npx hyperframes timeline [--json]，而不是閱讀 index.html 和每個子組合檔案。
• 比對現有的組合 ID 和時間線鍵值。
• 添加一個剪輯：根據周圍的剪輯，有目的地設定其 data-start/data-duration。data-track-index 是 Studio 的顯示車道，而非時間約束，因此不需要是空的。
• 一個在根元素 data-duration 之後結束的剪輯會被截斷：在同一編輯中將根元素 data-duration 延伸到剪輯的結束點（lint 會發出 clip_ends_past_root_duration 警告）。
• 任何組合元素上的 data-hidden 會同時在預覽和渲染中隱藏它，覆蓋其時間視窗；它是非破壞性/可逆的，並由 Studio 時間線的眼睛圖示切換。
• 添加一個子組合：在連接宿主之前驗證其內部的 data-composition-id。

驗證

指令詳細資訊請使用 hyperframes-cli

• npx hyperframes check 通過（lint、執行環境、佈局、動畫和對比度共 0 個發現）
• 包含子組合的專案：npx hyperframes snapshot --at <midpoints> 並目視檢查每個幀
• 用於審查的 npx hyperframes preview --background（使用者可以在 Studio 的時間線中編輯任何內容，且伺服器在執行指令後保持存活）
• 僅在使用者批准後執行 npx hyperframes render