Communitygithub.com

scott-fryxell/brayness

使用 HyperFrames HTML 创建视频合成、动画、标题卡片、叠加层、字幕、旁白、音频反应式视觉和场景过渡。适用于任何基于 HTML 的视频工作——创作合成、将字幕与音频同步、生成 TTS 旁白、运行开发循环(初始化、代码检查、预览、渲染)、预处理资源(TTS、转录、移除背景)或安装/贡献注册表块。

brayness 是什么?

该技能提供了一个完整的框架,用于在 HyperFrames 中创作基于 HTML 的视频。核心原则是“HTML 是视频的真相来源”,合成文件是具有时序属性的 HTML 文件,利用 GSAP 进行动画,CSS 控制外观。工作流程严格且分为三步:首先建立设计系统(读取或创建设计文档),然后进行提示扩展以协调设计意图,最后详细规划叙事、结构、节奏和布局。遵循“先布局后动画”的原则:先为每个场景的“英雄帧”构建静态 HTML+CSS 结束状态,然后再添加 GSAP 动画入口。框架强制执行严格的非协商规则,如确定性动画(无随机性)、同步时间线构建、场景间必须使用过渡(无跳切),以及开发者循环包括 lint、validate、inspect 和渲染。该技能支持在 macOS、Windows 和 Linux 上运行。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scott-fryxell/brayness/tree/HEAD/skills/hyperframes

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames

HTML 是视频的真相来源。一个合成文件就是一个带有 data-* 属性用于时序的 HTML 文件,使用 GSAP 时间线进行动画,CSS 控制外观。框架处理剪辑可见性、媒体播放和时间线同步。

属性 API、合成/模板结构、变量和媒体规则: references/authoring.md。在会话中编写第一个合成 HTML 之前,请先阅读它。

方法

发现(仅针对探索性请求)

对于开放式的请求(“给我做一个产品发布视频”),当用户尚未确定方向时,先了解意图再选择颜色:受众、平台、优先级(运动质量 vs. 精度 vs. 速度),以及他们是否想要变体。如果要求变体,则提供 2-3 个在节奏或结构上不同的选项——一个安全,一个有野心——而不是简单换色。

对于具体请求(“添加一个标题卡片”,“修复场景 3 的时间”),跳过发现步骤。

步骤 1:设计系统

如果存在 design.md 或 DESIGN.md,首先读取它(注意两种大小写——在 Linux 上它们是不同的文件)。它是品牌颜色、字体和约束的真相来源——使用它的确切值。如果它指定了字体,但在 fonts/ 中没有对应的 .woff2 文件,也无法内置匹配,则在编写 HTML 之前警告用户。

如果没有 design.md,提供一个选择:

  1. 用户提到了风格或情绪? 读取 visual-styles.md(8 个命名预设),选择最接近的一个。
  2. 视觉化浏览? 运行设计选取器 - references/design-picker.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:规划

  1. 什么 - 叙事弧线、关键时刻、情感节奏。
  2. 结构 - 多少个合成、子组合 vs. 内联、哪些轨道承载什么。
  3. 节奏 - 在实现之前声明场景节奏 (快-快-慢-快-着色器-停顿)。模板: references/beat-direction.md。
  4. 时序 - 哪些剪辑驱动持续时间、过渡落在哪里。
  5. 布局 - 首先构建结束状态(下一节)。
  6. 动画 - 然后添加运动。

只构建被要求的内容。 “一个标题卡片”不是“一个标题卡片 + 3 个支持场景 + 音乐 + 字幕。”建议额外内容;不要擅自添加。

对于小修改,直接跳到规则。

先布局后动画

将每个元素放置在其最可见的时刻——完全进入、正确放置、尚未退出。先将其编写为静态 HTML+CSS。尚不使用 GSAP。

原因:如果你将元素定位在动画开始状态(屏幕外、透明度 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(当内容增长时会溢出)。将绝对定位保留给装饰性元素。
  3. 使用 gsap.from() 进入——从屏幕外动画到 CSS 位置。CSS 是事实依据;补间是过程。(通过 data-composition-src 加载的子组合:优先使用 gsap.fromTo()——参见 references/motion-principles.md。)
  4. 仅最终场景:使用 gsap.to() 退出。 所有其他场景以完全可见结束——过渡本身就是退出(下面的过渡规则 3)。

如果元素 A 在元素 B 进入同一区域之前退出,为两者提供其各自英雄帧的正确 CSS 位置——时间线防止它们共存,并且布局步骤会捕获因时序错误导致的意外重叠。有意分层(文字后的辉光、卡片堆叠)是可以的;此步骤旨在捕获无意的重叠——两个标题碰撞、一个统计信息覆盖标签、内容脱离帧。

时间线契约

  • 所有时间线以 { 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. 在媒体上调用播放/暂停/搜索——框架拥有播放控制权
  7. 创建没有 data-composition-id 的顶层容器
  8. 在任何时间线或补间上使用 repeat: -1
  9. 异步构建时间线
  10. 在来自后续场景的剪辑元素上使用 gsap.set()——它们在页面加载时不存在于 DOM 中。在剪辑的 data-start 时间点或之后使用 tl.set(selector, vars, timePosition)。
  11. 在内容文本中使用 <br>——它会与自然换行堆叠并导致重叠;改用 max-width。例外:故意一行一个单词的短显示标题。

场景过渡(不可协商)

每个多场景合成必须遵守所有四条规则。违反任何一条都是无效的合成。

  1. 始终在场景之间使用过渡。 没有跳切。
  2. 始终通过 gsap.from() 动画每个元素的进入。 没有元素是完全显现的。五个元素意味着五个进入补间。
  3. 除最终场景外,切勿使用退出动画。 在过渡之前没有 gsap.to() 淡出透明度、移出屏幕或缩放到 0——过渡本身就是退出,并且当过渡触发时,离开的场景必须完全可见。过渡前的退出补间会向过渡传递一个空帧。
  4. 仅最终场景 可以淡出元素。

过渡选择与实现: references/transitions.md。

动画护栏

  • 将第一个动画偏移 0.1-0.3s(不是 t=0)
  • 变换缓动——每个场景至少 3 种不同的缓动,同一个场景内没有重复的进入模式
  • 避免深色背景上的全屏线性渐变(H.264 条带)——使用径向或纯色 + 局部辉光
  • 标题 60px+,正文 20px+,数据标签 16px+
  • 在数字列上使用 font-variant-numeric: tabular-nums

编辑现有合成

  • 读取实际文件,而不是猜测。 合成本身就是规格说明——从源代码提取确切十六进制颜色、字体和缓动模式,而不是凭借记忆。
  • 只更改被请求的内容;保留无关剪辑的时序。

输出检查清单

快速(立即运行,阻塞结果):

  • npx hyperframes lint 和 npx hyperframes validate 均通过
  • 如果存在 design.md,则验证了设计一致性

慢速(在呈现预览时并行运行):

  • npx hyperframes inspect 通过,或者每个报告的溢出都已有意标记
  • 对比度警告已处理
  • 动画编排已验证(animation-map 脚本)

如何运行和修复每个检查: references/quality-checks.md。

参考索引

对于任何新的合成,始终读取:

文件涵盖内容
references/authoring.mddata 属性、模板结构、变量、视频/音频、字体/资源
references/video-composition.md视频媒介规则——这些覆盖了网页本能
references/typography.md字体配对、OpenType、深色背景调整
references/motion-principles.md动效设计、图像运动、关键 GSAP 规则

对于多场景合成,也始终读取:

文件涵盖内容
references/beat-direction.md节奏模板、编排动词、深度层次
references/transitions.md过渡选择;目录 路由到实现;着色器过渡位于 @hyperframes/shader-transitions npm 包中(在其 node_modules 中读取源代码)

当任务需要时读取:

文件何时读取
references/quality-checks.md运行 inspect/contrast/design/animation-map 检查时
references/cli.md任何 CLI 命令;构建/渲染故障排除
references/captions.md任何与音频时序同步的文本
references/transcript-guide.md字幕端对话处理(CLI 调用位于 media.md 中)
references/dynamic-techniques.md动态字幕动画(卡拉 OK、闪现、散射)
references/audio-reactive.md响应音乐/语音的视觉
references/css-patterns.md标记高亮(高亮、圆圈、爆发、涂鸦)
references/techniques.md每个节拍的规划技术(11 种模式及代码)
references/narration.md旁白/TTS 节奏和脚本结构
references/media.mdTTS (Kokoro)、转录 (Whisper)、背景去除
references/prompt-expansion.md方法的步骤 2
references/design-picker.md可视化创建 design.md
references/from-website.md将网站转化为视频
references/registry.md安装/贡献注册表块(hyperframes add)
visual-styles.md用户指定风格;生成 design.md
house-style.md没有 design.md 时的美学默认值
patterns.md画中画、标题卡片、幻灯片
data-in-motion.md数据、统计、信息图

运行时适配器(当合成使用该运行时而非 GSAP 时读取):waapi、 lottie、 three、 animejs、 css-animations、 typegpu。

相关技能