用途:用于创建 HyperFrames HTML 视频合成。当需要制作视频、构建动画、创建合成或添加标题卡时使用。HTML 是视频的源文件:合成是一个带 data-* 时序属性的 HTML 文件,以 GSAP 时间线做动画、CSS 做外观,框架负责片段可见性、媒体播放与时间线同步。
主要能力:支持顶层与子合成(外部 HTML 通过 data-composition-src 加载,用 <template> 包裹);片段属性含 id、data-start(秒或片段 ID 引用如 "intro + 2")、data-duration、data-track-index、data-media-start、data-volume;合成属性含 data-composition-id、data-width/data-height(如 1920x1080 或 1080x1920)、data-composition-src。data-track-index 不影响视觉层叠,层叠用 CSS z-index。
使用方式:每个合成需自带 GSAP 脚本并注册时间线:window.__timelines["my-comp"] = tl;时间线须以 { paused: true } 创建,由播放器控制;时长取自 data-duration 而非 GSAP 时间线长度;子时间线由框架自动嵌套,不需手动添加。视频需 muted playsinline,音频始终用单独 <audio> 元素。每个合成需自行加载字体(@import 或 @font-face),本地字体用 font-display: block,外部媒体加 crossorigin="anonymous";所有媒体与字体文件置于项目根目录,子合成用 ../ 引用。GSAP 脚本地址为 https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js。
限制:必须确定性,禁止 Math.random()、Date.now() 或基于时间的逻辑;GSAP 只能动画视觉属性(opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、transforms),不得动画 visibility、display,也不得调用 video.play()/audio.play(),不得对媒体执行 play/pause/seek。禁止在多个时间线上同时动画同一元素的同一属性,否则无头渲染会闪烁。同一轨道片段不可重叠。其他禁止:忘记注册 window.__timelines、用 video 播放音频、把 video 嵌套在带时序的 div 中、使用 data-layer 或 data-end、动画 video 元素尺寸(应动画包装 div)、缺少 data-composition-id 的顶层容器。文本最小可读字号:横屏 20px、竖屏 18px。编辑已有合成时应先通读全文、匹配既有字体与动画模式,只改被要求的部分。未提供视觉样式或动画方向时,按 house-style.md 的动效默认值、尺寸与配色执行。