Communitygithub.com

GanQiao1990/skills_2026

在 HyperFrames HTML 中建立影片合成、動畫、標題卡、疊加層、字幕、旁白、音頻反應視覺效果和場景轉場。用於建構任何基於 HTML 的影片內容、添加與音頻同步的字幕、生成文字轉語音旁白、創建音頻反應動畫及場景轉場。

skills_2026 是什麼?

此技能為 HyperFrames 影片製作工作流程的核心,涵蓋合成結構、時間軸、動畫、視覺識別、字幕、音頻反應視覺效果及專業場景建構。使用者可透過 HTML、CSS 和 GSAP 時間軸定義影片內容,利用 `data-*` 屬性控制片段時序與播放。該技能強制要求在建構任何合成前先定義視覺識別,提供「先佈局後動畫」的方法,以避免非預期的元素重疊,並強制執行嚴格規則:時間軸必須同步建構、禁止無限重複動畫、以及必須使用場景轉場。支援獨立 HTML 合成與透過 `data-composition-src` 載入的子合成,可處理影片、音頻、圖片與動畫文字。對於多場景作品,強制要求使用轉場效果,避免跳接剪輯。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanQiao1990/skills_2026/tree/HEAD/openclaw-imports/hyperframes

在你喜歡的 AI 中提問

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

預覽

來自技能 README

說明文件

HyperFrames

HTML 是影片的唯一真理來源。一個合成是一個 HTML 檔案,帶有控制時序的 data-* 屬性、一個用於動畫的 GSAP 時間軸,以及控制外觀的 CSS。框架負責處理片段的可見性、媒體播放和時間軸同步。

範疇與吸納的狹隘工作流程

此技能是 HyperFrames 創作的類別級總綱。它涵蓋合成結構、時序、動畫、視覺識別、字幕、音頻反應視覺效果以及製作級場景建構。命令參考請使用 hyperframes-cli 技能,當來源素材是現有網站時,請使用 website-to-hyperframes 技能。狹隘的一次性製作/除錯筆記已降級為此處的支援參考。

子章節:製作工作流程陷阱

歷史上的製作筆記強調了一些仍然有用的環境陷阱:

  • 渲染時盡量使用僅 ASCII 的專案/輸出路徑;非 ASCII 路徑可能會導致無頭 Chrome 或渲染器子程序崩潰。
  • 如果 MP4 編碼在 Conda FFmpeg 下失敗,請使用 export PATH=/usr/bin:$PATH 強制使用系統 FFmpeg,或將 WebM 作為備用渲染格式。
  • 當使用自訂時間軸物件而非 GSAP 時,它們必須公開與 GSAP 相容的 duration()、pause() 和 seek(time) 方法。
  • 如果最終影片看起來是黑色或空白,首先檢查是否一個有時間設定的 .clip 容器被隱藏,而只有它的子元素被動畫化。在場景包裝器上使用像 .hidden { display: none; } 這樣的實用類別會產生經典的失敗模式:音頻渲染了,背景渲染了,但任何文字/卡片從未出現,因為父場景從未進入佈局/繪製。對於有時間設定的場景包裝器,使用 opacity: 0 或時間軸控制的透明度來隱藏,而不是 display: none。
  • 對於關鍵的運行時 JavaScript,例如 GSAP,建議在專案中放置本地副本(例如 assets/gsap.min.js),而不是在渲染期間依賴於即時 CDN 擷取。
  • 在獨立合成中加入 <link rel="icon" href="data:,">,以抑制當專案中沒有 favicon 時無頭瀏覽器的 favicon 404 錯誤訊息。
  • 透過使用 FFmpeg 提取影格並檢查螢幕截圖來進行視覺驗證,而不僅僅是信任成功的渲染退出碼。

降級的支援參考

  • references/hyperframes-video-production.md
  • references/hyperframes-workflow.md

方法

在編寫 HTML 之前,先從高層次思考:

  1. 什麼 — 觀眾應該體驗到什麼?確定敘事弧線、關鍵時刻和情感節拍。
  2. 結構 — 需要多少個合成,哪些是子合成與內聯合成,哪些音軌承載什麼(影片、音頻、疊加層、字幕)。
  3. 時序 — 哪些片段驅動持續時間,轉場發生在哪裡,節奏如何。
  4. 佈局 — 先建立最終狀態。請參閱下面的「先佈局後動畫」。
  5. 動畫 — 然後使用下面的規則添加動作。

對於小修改(修正顏色、調整時序、添加一個元素),可以直接跳到規則部分。

視覺識別閘門

請依下列順序檢查:

  1. 專案中存在 DESIGN.md? → 讀取它。使用其精確的顏色、字體、動畫規則以及「禁止事項」約束。
  2. 存在 visual-style.md? → 讀取它。套用其 style_prompt_full 和結構化欄位。(注意:visual-style.md 是專案特定的檔案。visual-styles.md 是包含 8 個命名預設的樣式庫 — 是不同的檔案。)
  3. 使用者指定了樣式名稱(例如,「Swiss Pulse」、「dark and techy」、「luxury brand」)? → 讀取 visual-styles.md 中的 8 個命名預設。產生一個最小化的 DESIGN.md,包含:## 樣式提示(一段落)、## 顏色(3-5 個帶有角色的十六進位值)、## 字體排版(1-2 個字體家族)、## 禁止事項(3-5 個反模式)。
  4. 以上皆非? → 在編寫任何 HTML 之前,先問 3 個問題:
    • 情緒是什麼?(震撼 / 電影感 / 流暢 / 技術感 / 混亂 / 溫暖)
    • 淺色還是深色畫布?
    • 有任何特定的品牌顏色、字體或視覺參考嗎? 然後根據答案產生一個最小化的 DESIGN.md。

每個合成必須將其調色板和字體排版追溯回 DESIGN.md、visual-style.md 或使用者的明確指示。如果你正打算使用 #333、#3b82f6 或 Roboto — 你跳過了這一步。

對於動畫預設、尺寸、進場模式和緩動 — 請遵循 house-style.md。house style 處理事物如何移動。DESIGN.md 處理事物看起來如何。

先佈局後動畫

將每個元素放置在其最顯眼的時刻應在的位置 — 也就是它完全進入、正確放置且尚未退出的影格。先將其編寫為靜態 HTML+CSS。暫時不要使用 GSAP。

為什麼這很重要: 如果你將元素定位在它們的動畫起始狀態(畫面外、縮放到 0、透明度 0),然後補間到你認為它們應該落定的位置,你是在猜測最終佈局。重疊問題在影片渲染之前是看不見的。透過先建立最終狀態,你可以在添加任何動畫之前看到並修復佈局問題。

過程

  1. 為每個場景確定主角影格 — 大多數元素同時可見的時刻。這就是你要建立的佈局。
  2. 為該影格編寫靜態 CSS。.scene-content 容器必須使用 width: 100%; height: 100%; padding: Npx; 並配合 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 來填滿整個場景。使用 padding 將內容向內推 — 絕對不要在內容容器上使用 position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。將 position: absolute 保留給裝飾性元素。
  3. 使用 gsap.from() 添加進場動畫 — 從畫面外/不可見動畫到 CSS 位置。CSS 位置是事實依據;補間描述了到達那裡的路徑。
  4. 使用 gsap.to() 添加退場動畫 — 從 CSS 位置動畫到畫面外/不可見。

範例

/* scene-content 填滿場景,padding 定位內容 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* 容器填滿任何場景尺寸(1920x1080、1080x1920 等)。
   Padding 定位內容。Flex + gap 處理間距。 */

錯誤 — 硬編碼尺寸和絕對定位:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}
// 步驟 3:動畫進入這些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 步驟 4:從這些位置動畫退出
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

當元素隨時間共享空間時

如果元素 A 在元素 B 進入同一區域之前退出,那麼兩者都應該在其各自的主角影格中擁有正確的 CSS 位置。時間軸順序保證它們從未在視覺上共存 — 但如果你跳過佈局步驟,你將無法發現它們因時序錯誤而意外重疊的情況。

什麼是故意重疊

分層效果(文字後方的光暈、陰影元素、背景圖案)和 Z 軸堆疊設計(卡片堆疊、深度層次)是故意的。佈局步驟的目的是捕捉非故意的重疊 — 兩個標題落在彼此上方、一個統計數據覆蓋標籤、內容溢出影格。

資料屬性

所有片段

屬性必要值
id是唯一識別碼
data-start是秒數或片段 ID 參考("el-1"、"intro + 2")
data-duration對於 img/div/合成 為必要秒數。影片/音頻預設為媒體持續時間。
data-track-index是整數。相同音軌的片段不能重疊。
data-media-start否來源的修剪偏移量(秒)
data-volume否0-1(預設 1)

data-track-index 不影響視覺層級 — 請使用 CSS z-index。

合成片段

屬性必要值
data-composition-id是唯一合成 ID
data-start是開始時間(根合成:使用 "0")
data-duration是優先於 GSAP 時間軸持續時間
data-width / data-height是像素尺寸(1920x1080 或 1080x1920)
data-composition-src否外部 HTML 檔案的路徑

合成結構

透過 data-composition-src 載入的子合成使用 <template> 包裝器。獨立合成(主要的 index.html)不使用 <template> — 它們將 data-composition-id 的 div 直接放在 <body> 中。在獨立檔案上使用 <template> 會對瀏覽器隱藏所有內容並破壞渲染。

子合成結構:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- content -->
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根合成中載入:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

影片與音頻

影片必須設定 muted playsinline。音頻始終是一個獨立的 <audio> 元素:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

時間軸合約

  • 所有時間軸都以 { paused: true } 開始 — 播放器控制播放
  • 註冊每個時間軸:window.__timelines["<composition-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 或 Promise 內部建構時間軸。捕捉引擎在頁面載入後同步讀取 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. 非同步建構時間軸(在 async、setTimeout、Promise 內部)
  10. 在後續場景的片段元素上使用 gsap.set() — 它們在頁面載入時不存在於 DOM 中。請在時間軸內部在或晚於該片段的 data-start 時間處使用 tl.set(selector, vars, timePosition)。
  11. 在內容文字中使用 <br> — 強制換行無法考慮實際渲染的字體寬度。自然換行的文字加上 <br> 會產生一個額外的不需要的換行,導致重疊。請讓文字透過 max-width 來換行。例外情況:簡短的顯示標題,其中每個單字刻意放在單獨的一行(例如,130px 大小的 "THE\nIMMORTAL\nGAME")。

場景轉場(不可協商)

每個多場景合成都必須遵循所有這些規則。違反其中任何一條都會導致合成失敗。

  1. 始終在場景之間使用轉場。無跳接剪輯。無例外。
  2. 始終在每個場景上使用進場動畫。每個元素都透過 gsap.from() 動畫進入。沒有任何元素可以完整地出現。如果一個場景

…

[翻譯時已截斷]

相關技能