Communitygithub.com

libz-renlab-ai/TeamBrain

使用 HyperFrames HTML 建立影片合成、動畫、標題卡、疊加層、字幕、語音旁白、音頻反應視覺效果及場景轉場。當要求建立任何基於 HTML 的影片內容時即可使用。

TeamBrain 是什麼?

這個 AI 代理技能專為使用 HyperFrames 框架進行專業影片創作而設計,HyperFrames 是一種以 HTML 為影片來源真相的系統。它提供了一個完整的影片製作工作流程,包括使用 GSAP 時間軸進行合成創作、透過 `data-*` 屬性進行時間碼管理,以及使用 CSS 進行視覺樣式設定。此技能遵循嚴格的「佈局優先於動畫」方法,開發人員必須在加入任何動畫之前先建立靜態最終狀態,防止元素意外重疊和版面配置問題。它支援多種影片功能,例如音頻反應視覺效果(節拍同步、發光、脈衝)、動態文字強調(標記掃描、手繪圓圈、爆發線)、場景轉場(淡入淡出、擦除、揭露、著色器轉場)以及語音旁白。此技能適用於 Cursor、Claude Code 和 Codex 等 AI 代理平台,需要特定的專案結構,包括用於品牌識別的 `design.md`、用於設計系統的 `visual-styles.md`,以及用於一致性提示擴展的 `references/` 目錄。它嚴格強制執行非協商性規則,例如條時間軸必須同步建構、禁止 `repeat: -1` 以及確定性行為,確保在所有代理實例中都能獲得可預測、可靠的影片輸出。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/libz-renlab-ai/TeamBrain/tree/HEAD/.agents/skills/hyperframes

在你喜歡的 AI 中提問

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

預覽

來自技能 README

說明文件

HyperFrames

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

方法

探索(僅限探索性請求)

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

  • 受眾 — 誰在看?開發者?高層?一般消費者?
  • 平台 — 在哪裡播放?社群媒體(15秒)、網站英雄區、產品展示、內部使用?
  • 優先級 — 最重要的是什麼?動作品質?內容準確性?品牌忠實度?速度?
  • 變體 — 使用者想要多個選項,還是單一最佳成品?

對於特定請求(「加入一個標題卡」、「修正場景3的時間」),則跳過探索步驟。

對於探索性請求,可以考慮提供 2-3 個有意義差異的變體——不僅是顏色更換,而是不同的節奏、能量水平或結構方法。一個是安全/預期的,一個是雄心勃勃的。不要強制要求——這只是在適當時機可用的工具。

步驟 1:設計系統

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

如果它指定了本地找不到的字型(沒有包含 .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。在影片適用的規模下使用品牌顏色——而不是在網頁 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:動畫到那些位置
從(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
從(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
從(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 步驟 4:從那些位置動畫退出
到(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
到(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
到(".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/合成必需秒數。影片/音頻預設為媒體持續時間。
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() 或基於時間的邏輯。如果需要虛擬隨機值(例如 mulberry32),請使用種子化 PRNG。

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 或在 Promises 內部建構時間軸。捕捉引擎在頁面載入後同步讀取 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 讓文字換行。例外:簡短的顯示標題,其中每個單詞刻意位於自己的行上(例如 "THE\nIMMORTAL\nGAME" 大小為 130px)。

場景轉場(不可協商)

每個多場景合成都必須遵循以下所有規則。違反任一規則即為損壞的合成。

  1. **

… [內容已截斷以利翻譯]

Individual skills in this repo

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

libz-renlab-ai/TeamBrain

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

libz-renlab-ai/TeamBrain

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.

libz-renlab-ai/TeamBrain

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames — for example "port my Remotion project to HyperFrames", "convert this Remotion code to HyperFrames", "migrate from Remotion", "translate this Remotion comp", or "rewrite this as HyperFrames HTML". Do NOT use when (a) the user is authoring a NEW HyperFrames composition, even if they have or are A/B-testing a similar Remotion video; (b) the user mentions Remotion in passing without asking for migration; (c) the user shares Remotion code as reference material rather than asking for a translation; (d) the user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build. When in doubt, default to authoring a native HyperFrames composition with the `hyperframes` skill instead. Skill detects unsupported patterns (use...

libz-renlab-ai/TeamBrain

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.

libz-renlab-ai/TeamBrain

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.

相關技能