Communitygithub.com

KingBridgeSS/sakugacut

使用 HyperFrames HTML 建立影片合成、動畫、標題卡、疊加層、字幕、旁白、音訊反應視覺效果和場景轉場。在執行已確定的 SakugaCut TimelinePlan 時使用。

sakugacut 是什麼?

此技能提供一個完整的影片合成框架,以 HTML 作為影片的唯一真實來源。它透過 `data-*` 屬性管理時間軸、使用 GSAP 處理動畫、並以 CSS 控制視覺呈現,自動處理片段可見性、媒體播放和時間軸同步。此技能採用結構化的工作流程:從設計系統定義(品牌色彩、字型)開始,接著進行提示擴展以確定使用者意圖,然後制定包含場景節奏和佈局的計劃,最後才撰寫 HTML 和動畫。它支援子合成、參數化變數(可透過 `data-variable-values` 或 CLI 覆蓋)以及多種媒體類型(影片、音訊、圖片、div)。此技能在 Cursor、Claude Code 和 Codex 等 AI 代理平台中運作良好,可透過 `hyperframes-cli` 進行初始化、檢查和渲染。

相容平台~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KingBridgeSS/sakugacut/tree/HEAD/hyperframes_skills/hyperframes

在你喜歡的 AI 中提問

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

說明文件

HyperFrames

HTML 是影片的真實來源。一個合成就是一個 HTML 檔案,其中包含用於時間控制的 data-* 屬性、用於動畫的 GSAP 時間軸,以及用於外觀的 CSS。框架會處理片段可見性、媒體播放和時間軸同步。

方法

探索階段(僅限探索性請求)

對於開放式請求("幫我製作一個產品發布影片"、"為我們的品牌創作一些內容"),在使用者尚未確定方向時,請先了解意圖再選擇顏色:

  • 受眾 — 誰會觀看?開發者?高層?一般消費者?
  • 平台 — 在哪裡播放?社群媒體(15 秒)、網站首頁、產品示範、內部使用?
  • 優先順序 — 什麼最重要?動畫品質?內容準確性?品牌忠實度?速度?
  • 變化 — 使用者想要多個選項,還是單一最佳方案?

對於具體請求("加入一個標題卡"、"修正場景 3 的時間"),則跳過探索階段。

對於探索性請求,可考慮提供 2-3 個有實質差異的變化 — 不僅是顏色互換,而是不同的節奏、能量強度或結構方法。一個安全/符合預期,一個則大膽創新。不要強制要求 — 這是在適當情況下可使用的工具。

步驟 1:設計系統

如果專案中存在 design.md 或 DESIGN.md 檔案,請先閱讀它(檢查兩種大小寫 — 在 Linux 上是不同的檔案)。它是品牌色彩、字型和限制條件的真實來源。使用其中的確切值 — 不要自行發明顏色或替換字型。任何格式都可以(YAML 前置資料、散文、表格 — 只需提取數值)。

如果它指定的字型在本地找不到(沒有包含 .woff2 檔案的 fonts/ 目錄,也不是內建字型),請在撰寫 HTML 前警告使用者:「design.md 指定了 [字型名稱] 但未找到字型檔案。請將 .woff2 檔案加入 fonts/ 目錄,否則我將回退到 [最接近的內建替代字型]。」

如果沒有 design.md 存在,請提供使用者一個選擇:

  1. 使用者提到了風格或氛圍? → 閱讀 visual-styles.md 以了解 8 個命名的預設風格。選擇最接近的一個。
  2. 想要視覺化瀏覽選項? → 執行設計選擇器:閱讀 references/design-picker.md 以了解完整工作流程。這會提供一個視覺化選擇器頁面。使用者在瀏覽器中配置氛圍、調色盤、字型和動畫,然後複製產生的 design.md 並貼回對話中。
  3. 想要跳過並快速進行? → 詢問:氛圍、淺色或深色、任何品牌色彩/字型?然後從 house-style.md 中選擇一個調色盤。

design.md 定義了品牌。它不定義影片合成規則。 這些規則來自 references/video-composition.md 和 house-style.md。使用適合影片規模的品牌色彩 — 而不是以 Web UI 的不透明度使用。

步驟 2:提示擴展

每次合成都必須執行(單場景片段和簡單編輯除外)。此步驟將使用者的意圖與 design.md 和 house-style.md 對齊,並產生一個一致的中介結果,讓所有下游代理都能以相同方式讀取。

閱讀 references/prompt-expansion.md 以了解完整流程和輸出格式。

步驟 3:計畫

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

  1. 什麼 — 觀眾應該體驗到什麼?確定敘事弧、關鍵時刻和情感節拍。
  2. 結構 — 需要多少個合成,哪些是子合成與內聯合成,哪些軌道承載什麼內容(影片、音訊、疊加層、字幕)。
  3. 節奏 — 在實作之前宣告你的場景節奏。哪些場景是快速切換、哪些是停留、著色器落在哪裡、能量在哪裡達到高峰。命名模式:快-快-慢-快-著色器-停留。閱讀 references/beat-direction.md 以了解節奏模板。
  4. 時間控制 — 哪些片段驅動持續時間、轉場落在哪裡、節奏如何。
  5. 佈局 — 先建立最終狀態。請參閱下方的「先佈局後動畫」。
  6. 動畫 — 然後使用以下規則加入動畫。

只建立被要求的內容。 「一個標題卡」的請求不是「一個標題卡 + 3 個支援場景 + 背景音樂 + 字幕」的請求。每個場景、每個元素、每個補間動畫都應該有其存在的價值。如果額外的場景或元素能真正改善作品,請提出建議 — 不要直接加入。

對於小型編輯(修正顏色、調整時間、加入一個元素),直接跳到規則。

先佈局後動畫

將每個元素放置在它最顯眼的時刻所在的位置 — 也就是它完全進入、正確放置、且尚未退出的影格。先將其寫成純靜態 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 來填滿整個場景。使用內邊距將內容向內推 — 切勿在內容容器上使用 position: absolute; top: Npx。使用絕對定位的內容容器在內容高於剩餘空間時會溢出。保留 position: absolute 僅用於裝飾性元素。
  3. 使用 gsap.from() 加入入場動畫 — 從畫面外/隱藏狀態動畫到 CSS 位置。CSS 位置是真實狀態;補間則描述了到達該位置的過程。(在透過 data-composition-src 載入的子合成中,建議使用 gsap.fromTo() — 請參閱 references/motion-principles.md 中關於承載 GSAP 的規則。)
  4. 使用 gsap.to() 加入退場動畫 — 從 CSS 位置動畫到畫面外/隱藏狀態。

範例

/* scene-content 填滿場景,內邊距定位內容 */
.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 等)。
   內邊距定位內容。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是秒數。影片/音訊預設為媒體持續時間。
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-variable-values否子合成主機上每個實例變數覆蓋的 JSON 物件

在根 <html> 元素上:

屬性必要值
data-composition-variables否已宣告變數的 JSON 陣列(id/type/label/default)— 驅動 Studio 編輯 UI 並提供 getVariables() 的預設值

合成結構

透過 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">
    <!-- 內容 -->
    <style>
      [data-composition-id="my-comp"] {
        /* 作用域樣式 */
      }
    </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 });
      // 補間...
      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>

變數(參數化合成)

使用不同的內容渲染同一個合成 — 標題、主題顏色、價格、字幕 — 無需編輯原始 HTML。

三步驟模式:

  1. 宣告 在合成的 <html> 根元素上使用 data-composition-variables 宣告變數。每個條目需要 id、type(可選值:string、number、color、boolean、enum)、label 和 default。列舉條目還需要 options: [{value, label}, ...]。
  2. 讀取 在合成腳本中使用 window.__hyperframes.getVariables() 讀取已解析的值。返回已宣告預設值、每個實例覆蓋值和 CLI 覆蓋值的合併結果。
  3. 覆蓋 在渲染時使用 npx hyperframes render --variables '{...}'(頂層)或對子合成使用主機元素上的 data-variable-values='{...}'(每個實例)。
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"標題","default":"你好"},
  {"id":"theme","type":"enum","label":"主題","default":"light","options":[
    {"value":"light","label":"淺色"},
    {"value":"dark","label":"深色"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# 開發預覽使用宣告的預設值
npx hyperframes preview

# 使用覆蓋值渲染
npx hyperframes render --variables '{"title":"Q4 報告","theme":"dark"}' --output q4.mp4

# 或從 JSON 檔案渲染
npx hyperframes render --variables-file ./vars.json

子合成每個實例的值: 在透過 data-composition-src 載入的子合成中,同樣的 getVariables() 也能作用。每個主機元素傳遞自己的值:

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"專業版","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"企業版","price":"$99"}'
></div>

參考文件

此技能依賴於專案特定目錄中的數個參考文件:

CLI 使用方式

此技能可與 hyperframes-cli 搭配使用進行初始化、檢查和渲染:

# 初始化專案
npx hyperframes init

# 檢查檔案
npx hyperframes check --all

# 預覽
npx hyperframes preview

# 渲染
npx hyperframes render --output output.mp4

# 快照(用於除錯)
npx hyperframes snapshot

對於媒體預處理,請使用 hyperframes-media:

npx hyperframes-media optimize input.mp4 --output optimized.mp4

相關技能