Communitygithub.com

govindgoel2001/video-editing-toolkit

建立影片合成、動畫、標題卡、疊加層、字幕、旁白、音訊反應視覺效果和場景轉場,使用 HyperFrames HTML。

video-editing-toolkit 是什麼?

這是一個專為 AI 代理設計的影片編輯工具包,基於 HyperFrames 框架,使用 HTML 作為影片的單一事實來源。它支援完整的影片製作工作流程,包括合成創作、動畫、標題卡、疊加層、字幕、語音旁白(TTS)、音訊反應視覺效果(節奏同步、發光、脈衝)以及場景轉場(淡入淡出、擦除、揭示、著色器轉場)。該工具包與 Claude Code、Cursor 和 Codex 等平台相容,並強調透過強制執行視覺標識閘道(確保使用 DESIGN.md 或 visual-style.md 定義顏色、字型和動態規則)和佈局優先動畫方法(先以 CSS 建立最終狀態,再使用 GSAP 新增進入/退出動畫)來避免常見錯誤。它還包含嚴格規則,例如使用確定性邏輯(無 Math.random())、有限重複次數(無 repeat: -1)、同步時間軸建構以及強制使用場景轉場(禁止跳躍剪接)。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/hyperframes

在你喜歡的 AI 中提問

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

預覽

來自技能 README

說明文件

HyperFrames

HTML 是影片的唯一事實來源。合成是一個帶有 data-* 屬性(用於時序)、一個 GSAP 時間軸(用於動畫)和 CSS(用於外觀)的 HTML 檔案。該框架負責處理剪輯的可見性、媒體播放和時間軸同步。

方法

在編寫 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,包含:## Style Prompt(一段)、## Colors(3-5 個十六進位值及其角色)、## Typography(1-2 個字型家族)、## What NOT to Do(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 來填滿整個場景。使用內邊距將內容向內推 — 永遠不要在內容容器上使用 position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。僅對裝飾性元素保留 position: absolute。
  3. 使用 gsap.from() 添加進入動畫 — 從畫面外/不可見狀態動畫到 CSS 位置。CSS 位置是基準事實;補間描述了到達那裡的路徑。
  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:動畫到這些位置
const tl = gsap.timeline({ paused: true });
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-durationimg/div/composition 需要秒數。Video/audio 預設為媒體持續時間。
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">
    <!-- 內容 -->
    <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>

影片和音訊

影片必須設定為 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 中。應使用時間軸內的 tl.set(selector, vars, timePosition),參數為剪輯的 data-start 時間或之後的位置。
  11. 在內容文字中使用 <br> — 強制換行無法考慮實際渲染的字型寬度。自然換行的文字加上 <br> 會產生額外的不需要的換行,導致重疊。讓文字透過 max-width 換行。例外:簡短的顯示標題,其中每個詞有意位於自己的行上(例如,130px 的 "THE\nIMMORTAL\nGAME")。

場景轉場(不可協商)

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

  1. 始終在場景之間使用轉場。 無跳躍剪接。無例外。
  2. 始終在每個場景上使用進入動畫。 每個元素都透過 gsap.from() 動畫進入。沒有元素可以完全成形地出現。如果一個場景有 5 個元素,則需要 5 個進入補間。
  3. 除了最終場景外,永遠不要使用退出動畫。 這意味著:在轉場觸發之前,不允許使用 gsap.to() 將不透明度動畫到 0、將 Y 軸移出畫面、將縮放動畫到 0 或任何其他「離開」動畫。轉場本身就是退出。退出場景的內容在轉場開始時必須完全可見。
  4. 僅限最終場景: 最後一個場景可以淡出元素(例如,淡出到黑色)。這是唯一允許使用 gsap.to(..., { opacity: 0 }) 的場景。

錯誤 — 在轉場前使用退出動畫:

// 禁止 — 這會在轉場可以使用場景之前清空它
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 轉場在空影格上觸發

正確 — 僅進入動畫,轉場處理退出:

// 場景 1 進入動畫
const tl = gsap.timeline({ paused: true });
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// 無退出補間 — 7.2 秒處的轉場處理場景更改
// 場景 2 進入動畫
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

動畫防護欄

  • 將第一個動畫偏移 0.1-0.3 秒(不要從 t=0 開始)
  • 在進入補間之間變化緩動函數 — 每個場景至少使用 3 種不同的緩動函數
  • 不要在一個場景內重複使用相同的進入模式
  • 避免在深色背景上使用全螢幕線性漸層(H.264 條帶效應 — 使用徑向漸層或純色搭配局部發光)
  • 渲染影片中,標題使用 60px+,正文使用 20px+,數據標籤使用 16px+
  • 在數字欄上使用 font-variant-numeric: tabular-nums

當未提供 visual-style.md 或動畫方向時,請遵循 house-style.md 以獲得美學預設值。

字型和資源

  • 字型: 直接在 CSS 中編寫你想要的 font-family — 編譯器會自動嵌入支援的字型。如果不支援某個字型,編譯器會發出警告。
  • 為外部媒體添加 crossorigin="anonymous"
  • 對於...

Individual skills in this repo

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

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

govindgoel2001/video-editing-toolkit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

相關技能