hyperframes-compose

合成视频

HTML 是视频的事实来源。合成是一个 HTML 文件，其中包含用于计时的 data-* 属性、用于动画的 GSAP 时间线，以及用于外观的 CSS。框架会处理片段的可见性、媒体播放和时间线同步。

方法

编写 HTML 之前，先从高层次进行思考：

1. 内容 — 观众应该体验什么？明确叙事弧线、关键时刻和情绪起伏。
2. 结构 — 需要多少个合成，哪些是子合成，哪些是内联内容，哪些轨道承载什么内容（视频、音频、叠加层、字幕）。
3. 时序 — 哪些片段决定时长，转场落在哪些位置，节奏如何安排。
4. 执行 — 然后按照以下规则实现。

对于小幅修改（修正颜色、调整时序、添加一个元素），可直接按以下规则操作。

如果没有提供 visual-style.md 或动画方向，请遵循 house-style.md 中关于运动默认值、尺寸和调色板的说明。

数据属性

所有片段

属性	必填	值
id	是	唯一标识符
data-start	是	秒数或片段 ID 引用（"el-1"、"intro + 2"）
data-duration	img/div/合成必填	秒数。视频/音频默认使用媒体时长。
data-track-index	是	整数。同一轨道上的片段不能重叠。
data-media-start	否	源媒体中的剪辑偏移量（秒）
data-volume	否	0-1（默认值为 1）

data-track-index 不会影响视觉层级——请使用 CSS z-index。

合成片段

属性	必填	值
data-composition-id	是	唯一合成 ID
data-duration	是	优先于 GSAP 时间线时长
data-width / data-height	是	像素尺寸（1920x1080 或 1080x1920）
data-composition-src	否	外部 HTML 文件的路径

合成结构

每个合成都由一个 <template> 包裹，其中包含一个带有 data-composition-id 的 <div>。每个合成都必须包含自己的 GSAP 脚本并注册时间线：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </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 });
      // tweens...
      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() 或基于时间的逻辑。渲染器每次都必须生成完全相同的输出。

GSAP： 仅对视觉属性进行动画处理（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、变换）。不要对 visibility、display 进行动画处理，也不要调用 video.play()/audio.play()。

动画冲突： 绝不要在多个时间轴中同时对同一元素的同一属性进行动画处理——这会导致无头渲染时出现闪烁。

绝不要：

1. 忘记注册 window.__timelines
2. 使用视频播放音频——始终使用静音视频，并配合单独的 <audio>
3. 将视频嵌套在计时 div 中——应使用非计时包装元素
4. 使用 data-layer（应使用 data-track-index）或 data-end（应使用 data-duration）
5. 对视频元素的尺寸进行动画处理——应对包装 div 进行动画处理
6. 对媒体调用播放/暂停/跳转——播放由框架管理
7. 创建不带 data-composition-id 的顶层容器

编辑现有合成

• 首先阅读完整的合成内容——匹配现有字体、颜色和动画模式
• 只修改所要求的内容——不要重写未改动的部分
• 小改动不要重写整个文件
• 保留无关片段的时间安排

排版和资源

• 每个合成都应加载自己的字体（在 <style> 中使用 @import 或 @font-face）
• 本地字体使用 font-display: block——渲染器需要在捕获前加载字体
• 从外部 URL 加载媒体时，添加 crossorigin="anonymous"
• 最小可读字号：横屏 20px，竖屏 18px
• 对于可能溢出容器的动态文本，使用 window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight }) 计算能在单行内显示的最大字号。返回 { fontSize, fits }。选项：baseFontSize（默认值为 78）、minFontSize（默认值为 42）、step（默认值为 2）。fontFamily 和 fontWeight 必须与应用于元素的 CSS 相匹配。
• 所有文件（视频、音频、字体、图片）都应放在项目根目录，与 index.html 同级
• 在子合成中，使用 ../ 引用根目录中的文件

PiP、标题卡和幻灯片模式请参阅 patterns.md。 数据、统计和信息图表请参阅 data-in-motion.md。 打字机文本和其他 GSAP 动画效果请参阅 gsap-effects skill。 由音频驱动的动画（节拍同步、发光、脉冲）请参阅 audio-reactive skill。

输出检查清单

• 每个顶层容器都具有 data-composition-id
• 每个合成都具有 data-width、data-height、data-duration
• 每个合成都位于独立的 HTML 文件中，并通过 data-composition-src 加载
• 子合成使用 <template> 包装
• 为每个合成都注册了 window.__timelines
• 完全确定——不使用随机性
• 每个合成都包含 GSAP：<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
• npx hyperframes lint 通过，且错误数为 0
• npx hyperframes validate 通过，且错误数为 0（打开 studio 前运行这两个命令）