外掛安裝注意事項: 在執行設定或重新整理指令之前,請先遵循 外掛執行規則(當此技能位於 HyperFrames 外掛中時)。獨立安裝則保留下方的更新說明。
HyperFrames 核心
代理陷阱(請優先閱讀):
- 使用 flex/
inset進行居中,不要在一個節點上使用 CSStransform: translate(-50%,-50%)後又對其進行 GSAPx/y動畫。檢查事項:gsap_css_transform_conflict。請改用fromTo或xPercent/yPercent。 - 不要在場景結束時加入
tl.set(..., {visibility:"hidden"})。執行環境會自動隱藏已結束播放的剪輯。為內部節點設定透明度淡出(或為.clip設定opacity)就已足夠。字幕硬性終止則屬於不同規則。 window.__timelines["id"]必須與根元素的data-composition-id相符。- 執行
render後,請閱讀摘要的第二行:beginframe與screenshot、GPU 模式、階段時間。screenshot+software gpu在 Linux 上是較慢的路徑。
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 | 選擇單體架構或模組化架構;組織模組化 index.html;挑選子組合原型 |
references/data-attributes.md | 查詢任何 data-* 屬性(根 / 剪輯 / 子組合宿主 / 舊版別名);使用 class="clip" |
references/tracks-and-clips.md | 了解 data-track-index 的作用(與不作用)、z-index、相對於其他剪輯設定時間;使用 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。
一個暫停的時間軸
每個組合在 window.__timelines["<id>"] 註冊剛好一個 gsap.timeline({ paused: true })(鍵值等於根元素的 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 })在補間內部設定初始狀態,而不是使用 CSStransform: translateX(-40px)。 - 永遠不要在
<video>/<audio>上設定crossorigin。lint會無條件以media_crossorigin_breaks_preview(錯誤)拒絕它,即使是為了 Canvas/WebGL/WebAudio 回讀。無法繞過。 - 永遠不要讓一個有
data-start的<video>的元素也包含另一個也有data-start的祖先元素。lint會以video_nested_in_timed_element(錯誤)拒絕它。請將時間設定在外層包裝或影片上,不要兩者都設。 - 每個
<audio>都需要一個id。lint會以media_missing_id拒絕它,且沒有id的<audio>永遠不會被混音器選取,因此渲染會是靜音的。 - 永遠不要對
.clip元素進行autoAlpha或visibility的補間動畫 —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只能存在於有限根元素data-duration之下(將匯出剪輯設定到它上面 — 否則請使用有限次數)。→determinism-rules.md - 永遠不要對
.clip元素進行display、visibility或autoAlpha的補間動畫。框架擁有剪輯的可見性控制權,且lint會拒絕它(gsap_animates_clip_element)。請對其子元素進行動畫。→determinism-rules.md - 正文中不要有
<br>;經過 transform 的元素必須是區塊級別 + 已設定尺寸;脈衝式絕對定位裝飾元素需要預留峰值間距。→determinism-rules.md <video>/<audio>是透過平面的文件查詢找到的,因此框架可以在任何巢狀深度(包含在子組合<template>或包裝器內)進行搜尋和解碼。一個硬性限制:如果一個有data-start的<video>位於另一個同樣有data-start的普通元素內,lint會報錯,且失敗是真實的(錯誤的來源影格,然後剪輯在時段中間消失),因此請將時間設定在包裝器或影片上,但絕不能兩者都設。子組合宿主則例外:子組合內部的媒體可以正確渲染。另一個需要注意的是時間軸,而非位置:子組合時間軸無法動畫化宿主根元素。→variables-and-media.md- 確保在組裝後的頁面上每個
id都是唯一的(為子組合的 ID 加上組合 ID 前綴,例如#<id>-hero),以便你自己的#idCSS 和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通過(0 個發現項目,涵蓋 lint、執行時期、佈局、運動和對比度) - 包含子組合的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每個影格 -
npx hyperframes preview --background用於審查(使用者可以在 Studio 的時間軸中編輯任何內容,且伺服器在觸發指令後持續運作) - 僅在使用者批准後才執行
npx hyperframes render