Bang Motion 视频图层技术详解：像 After Effects 一样把 MP4 嵌入 HTML 动画并锁定时间线的完整指南

Bang Motion 是一个让 AI 编码代理"变身动效设计师"的开源 Agent Skill，交付物是一个双击即播的index.html。它的视频图层（Video as footage layer）能力，让你把 MP4 素材嵌进 HTML 动画里，像 After Effects 的 footage 图层一样被裁剪、打掩码、调色，并精确锁定在 GSAP 时间线上——scrub 到任意一秒，画面分毫不差。

什么是"视频图层"：网页动画里的真实 footage

在 After Effects 里，footage 图层可以做这些事：裁剪 in/out 点、套遮罩、调色级、与关键帧动画的合成。过去做网页动效，视频只能靠原生<video>标签自己跑，跟动画脱节——你拖动进度条，文字飞走了，视频还在原地播。

Bang Motion 从 v1.18.0 起，在所有 starter 模板里内置了clip()辅助函数（见 CHANGELOG.md），把这个问题彻底解决：

视频内容跟随时间线的时钟：播放时自动同步（偏差超过 0.2 秒自动纠正），scrub / 暂停时逐帧 seek。禁止使用autoplay/loop，也不要自己调play()——一切都由时间线说了算。

这套机制的完整用法写在 references/techniques.md 的 §9b 章节。

时间线是唯一时钟：锁定视频的原理

视频图层能"锁得住"，根源在于 Bang Motion 的确定性架构（references/architecture.md）：

• 整个动画由一条 GSAP master timeline驱动，所有视觉元素都是tl.time()的纯函数；
• 所有动画写在绝对秒数上（比如8.10秒），而不是+=0.3这种相对偏移；
• 严禁Date.now()、Math.random()进入渲染路径。

这意味着：播放、暂停、拖动 scrub、逐帧导出 MP4，看到的画面完全一致。视频图层正是搭在这条"唯一时钟"上的——时间线走到第几秒，视频就 seek 到对应的素材帧。

一行代码把 MP4 挂上时间线：clip() 五个参数

用法非常简洁，只需两层结构：外层div做动画，内层video只负责放内容。

<div class="clipbox" id="box1"> <video id="v1" src="assets/klip.mp4" muted playsinline preload="auto"></video> </div>

// at = 时间线第几秒开始 · in/out = 素材裁切点（秒）· rate = 速度 · hold = 是否定格尾帧 clip($('#v1'), {at: 4, in: 1.5, out: 6, rate: 1, hold: false}); tl.set('#box1', {autoAlpha: 1}, 4); // 第 4 秒显示容器 tl.fromTo('#box1', {scale: .8}, {scale: 1, duration: 1, ease: 'power3.out', immediateRender: false}, 4); // 缩放入场

完整实现可参考 assets/starter-opener.html 的 FOOTAGE 区块（每个 starter 都自带）。

四种常用布局模式：设备屏、遮罩、分屏与全屏

clip()装好视频后，剩下的就是"把外层容器当普通图层玩"——位移、缩放、clip-path遮罩、mix-blend-mode调色都能用。官方推荐四种模式：

模式一：设备屏幕里的录屏

放在笔记本 / 手机 mockup 的屏幕里，镜头可以推进到屏幕内——SaaS 产品演示的杀手锏：

模式二：容器遮罩

把视频装进圆角卡片、圆形、甚至巨大的字母形状（clip-path/ mask）里，像杂志拼贴一样。

模式三：分屏对比

视频占一侧，主张文案 / 大数字占另一侧，两边各自动画但共享一条时间线。

模式四：全屏 footage + 叠加层

全屏视频上盖调色层（filter或mix-blend-mode叠上品牌色）、暗角，再在"文字安全区"里放高对比标题：

帧级同步：从 ?debug=1 预览到 MP4 导出

视频图层对导出流程也是"帧级"的，因为每个 starter 都暴露了OPENER.seekFrame(t)——它不仅 seek 时间线，还会等待视频解码器把对应帧准备好：

1. 预览：URL 加?debug=1出现 scrub 面板，拖动即可验证视频与文字的同步；
2. 抽检：scripts/snap.mjs 自动截取关键秒数，包含视频片段的秒数务必截；
3. 导出：scripts/export-frames.mjs 以 60 fps 逐帧渲染成 PNG，再用 ffmpeg 合成 MP4。因为逐帧精确 seek，导出的 MP4 和视频图层完全同步——比录屏不会掉帧。

素材建议先裁好再放入项目（无声音轨、720p–1080p、H.264yuv420p）：

ffmpeg -i 源.mov -ss 2 -t 6 -vf "scale=1920:-2" \ -c:v libx264 -pix_fmt yuv420p -crf 20 -movflags +faststart -an assets/klip.mp4

⚠️ 注意：交付物变成index.html+assets/文件夹（内含视频），交付时记得告知用户。

避坑清单：5 个高频错误

相关资源速查

一句话总结：把<video>装进容器，用一行clip()报上时间线的"户口"，剩下的——遮罩、调色、入场出场——就和在 After Effects 里拖 footage 图层一样自然。