Communitygithub.com

delorenj/skills

在HyperFrames HTML中创建视频合成、动画、标题卡、叠加层、字幕、配音、音频响应式视觉和场景过渡。

skills 是什么?

该技能专为HyperFrames框架设计,用于生成基于HTML的视频合成内容,支持完整的视频制作工作流程。它涵盖了从设计系统管理(包括品牌色彩、字体和约束)到视频组成、动画、场景过渡、音频响应式视觉、字幕同步以及文本转语音叙述的所有方面。技能强调以HTML为视频的“唯一真相源”,利用`data-*`属性进行时序控制、GSAP时间线进行动画制作,以及CSS进行样式定义。它提供了详细的步骤指导,包括设计系统发现、提示扩展、布局优先于动画的方法,以及变量驱动的参数化合成,使开发者能够高效地创建动态视频内容。该技能支持多种平台,如Claude Code和Cursor,并与其他HyperFrames技能(如`hyperframes-cli`用于命令行操作,`hyperframes-media`用于资产预处理)协同工作。

兼容平台~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 的时序”),跳过探索阶段。

对于探索性请求,考虑提供 2-3 个有实质差异的变体——不仅仅是颜色替换,而是不同的节奏、能量水平或结构方法。一个稳妥/常规,一个雄心勃勃。不要强制这样做——这是一个在适当时可用的工具。

步骤 1:设计系统

如果项目中存在 design.md 或 DESIGN.md 文件,请首先读取它(请检查两种大小写——它们在 Linux 上是不同的文件)。它是品牌颜色、字体和约束的唯一真实来源。使用其确切的值——不要发明颜色或替换字体。任何格式都可以(YAML 前置元数据、散文、表格——只需提取值)。

如果其中命名的字体在本地找不到(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。在适当的视频比例下使用品牌颜色——而不是在 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图片/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":"标题","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

子合成每个实例的值: 相同的 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"
  data-variable-values='{"title":"企业版","price":"联系销售"}'
></div>

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.

相关技能