Communitygithub.com

HyperFrames 核心技能

HyperFrames 組合合約——建立一個可渲染的專案。用於組合結構、`data-*` 時間屬性、`class="clip"`、軌道、子組合、變數、框架擁有的媒體播放、確定性渲染規則和驗證。在撰寫組合 HTML 之前請先閱讀。

HyperFrames 核心技能 是什麼?

HyperFrames Core 是一個全面的技術技能,用於定義和操作 HyperFrames 組合合約。HyperFrames 是一個獨特的框架,可將 HTML 文件渲染成影片,其中 DOM 結構透過 `data-*` 屬性宣告時間,動畫執行階段是可搜尋的,且媒體播放由框架擁有。此技能對於任何使用 HyperFrames 建立可渲染專案的人都至關重要,並支援包括 Claude Code、Cursor 和 Codex 在內的 AI 代理平台。此技能涵蓋了建立組合的完整技術合約,從基本結構和子組合到軌道、剪輯和變數等高級主題。它提供了詳細的參考資料(位於 `references/`),以獲取特定主題的指導,例如最小組合模式和確定性規則。此技能還包括廣泛的 Lint 規則和不可協商的規則,以確保組合正確且可預測地渲染,避免常見錯誤,例如 CSS 和 GSAP 屬性衝突或不正確的媒體放置。此技能與其他 HyperFrames 領域技能(如 `hyperframes-animation` 和 `hyperframes-creative`)協同工作,並包含用於驗證和預覽的 CLI 命令。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/hyperframes-core

在你喜歡的 AI 中提問

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

說明文件

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 與 screenshot、GPU 模式、階段時間。Linux 上的 screenshot + 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-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。

一個暫停的時間線

每個組合註冊恰好一個 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-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

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check (aspect ratio correction), prompt engineering, avatar resolution, and voice selection. Required for any HeyGen video generation. Replaces deprecated endpoints with v3. Use when: (1) generating any HeyGen video (via API or otherwise), (2) sending a personalized video message (outreach, update, announcement, pitch, knowledge), (3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face, (4) "make a video of me saying...", "send a video to my leads", "record an update for my team", "create a video pitch", "make a loom-style message", "I want to appear in this video", "generate a HeyGen video", "make a talking head video". Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter. Returns video share URL + HeyGen session URL for iteration. Chain signal: when the user wants to create/design an avatar AND make a video in the same request, run heygen-avatar f...

Zuhair-01/claude-skills-and-systems

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

相關技能