Communitygithub.com

delorenj/skills

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

skills 是什麼?

這個技能讓 AI 代理能夠使用 HyperFrames 框架,以 HTML 作為影片的單一事實來源來創作影片。它涵蓋了完整的影片製作工作流程,從最初的概念探索和設計系統設定,到 prompt 擴展、規劃,最後實作佈局和動畫。該技能強調在套用任何 GSAP 動畫之前,先建立一個「英雄影格」作為最終佈局,以確保精確的定位並防止非預期的重疊。它支援參數化合成,允許在渲染時動態覆蓋文字、顏色和其他內容,而無需修改底層的 HTML。該技能可與 Claude Code、Cursor 或任何支援 CLI 的 AI 編碼代理一起使用,並依賴於專案檔案,如 `design.md`、`house-style.md` 和位於 `references/` 目錄中的各種參考文件。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/hyperframes-upstream-hyperframes

在你喜歡的 AI 中提問

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

說明文件

HyperFrames

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

方法

探索(僅限探索性請求)

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

  • 觀眾 — 誰在看?開發人員?主管?一般消費者?
  • 平台 — 在哪裡播放?社交媒體(15 秒)、網站主視覺、產品示範、內部使用?
  • 優先級 — 最重要的是什麼?動畫品質?內容準確性?品牌忠實度?速度?
  • 變體 — 使用者想要多個選項,還是單一最佳方案?

對於具體請求(「加入一個標題卡」、「修正場景 3 的 timing」),則跳過探索。

對於探索性請求,考慮提供 2-3 個有實質差異的變體——不只是顏色調換,而是不同的節奏、能量水平或結構方法。一個是安全/符合預期的,一個是具野心的。不要強制要求——這只是一個在合適時使用的工具。

步驟 1:設計系統

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

如果它指定了本地找不到的字型(沒有 fonts/ 目錄包含 .woff2 檔案,也不是內建字型),請在編寫 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:Prompt 擴展

每次合成時都執行此步驟(單一場景片段和簡單編輯除外)。此步驟根據 design.md 和 house-style.md 來具體化使用者的意圖,並產生一個一致的、所有下游代理都能以相同方式讀取的中間產物。

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

步驟 3:規劃

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

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

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

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

先佈局再動畫

將每個元素放在它最顯眼的時刻應該在的位置——那個它完全進入、正確放置、且尚未退出的影格。首先將其寫成靜態 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 位置是基本事實;補間動畫描述了到達那裡的路徑。(在透過 data-composition-src 載入的子合成中,偏好使用 gsap.fromTo()——請參閱 references/motion-principles.md 中的負載 GSAP 規則。)
  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 位置。時間軸順序保證它們永遠不會在視覺上共存——但如果你跳過佈局步驟,你將不會發現它們因 timing 錯誤而意外重疊的情況。

什麼算是故意重疊

分層效果(文字後面的光暈、陰影元素、背景圖案)和 Z 軸堆疊設計(卡片堆疊、深度層)是故意的。佈局步驟的目的是為了發現非故意的重疊——兩個標題疊在一起、一個統計數字蓋住標籤、內容溢出畫框。

資料屬性

所有片段

屬性必要值
id是唯一識別碼
data-start是秒數或片段 ID 參考 ("el-1", "intro + 2")
data-duration圖片/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-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":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'
>
  <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 Report","theme":"dark"}' --output q4.mp4

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

子合成每個實例的值: 相同的 getVariables() 在透過 data-composition-src 載入的子合成內部也能工作。每個主機元素傳遞其自己的值:

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


…

[因篇幅關係已截斷]

Individual skills in this repo

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

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

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 (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

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.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

相關技能