# 黑金 HUD · 知识口播 B-roll 动效模板库 本目录用于让 HyperFrames 为知识口播视频生成插入式 B-roll。统一采用黑色暗场、淡金网格、玻璃卡片与蓝色数据标记，提供 49 个可独立渲染的 8 秒、1600 × 900 合成。 ## 查看与选择 直接打开 `index.html`，无需启动服务。页面初始化时只尝试读取模板根目录的 `selection.json`，不使用浏览器暂存。默认全部 49 个组件选中、背景为方形网格；若文件读不到或无效，也采用这个默认状态。浏览器阻止本地页面读取同目录 JSON 时，可点击“导入清单”手动选择该文件，以恢复其中的实际选择。左侧点击名称切换预览，勾选右侧方框才会选择该组件用于制作视频；“仅看已选”可核对范围。“背景”可在方形网格、正六边形网格、无网格之间单选，立即影响组件预览。当前 JSON 配置显示在侧栏，点击“复制 JSON 配置”可复制全文。支持搜索、分类选择、播放 / 暂停、重播、上一项 / 下一项、0.5–2 倍预览速度、时间轴拖动和沉浸预览。空格控制播放，左右方向键切换，Esc 退出沉浸预览。启用系统“减少动态效果”时默认停留在最后一帧，仍可手动播放。 每次修改勾选或背景后，复制侧栏 JSON 配置并粘贴到根目录的 `selection.json`，替换原文件全部内容。页面不能自动写入本地文件；刷新前未粘贴的修改会丢失。`background` 字段可为 `square`、`hex` 或 `none`；旧清单省略该字段时沿用方形网格。 ## 给 HyperFrames 使用 `index.html` 是选择与预览界面。**渲染目标是 `effects/<效果 ID>/` 内的 `index.html`**，不能把整个动效库首页当作一个视频合成。 制作视频前，先确认已更新的 `selection.json` 位于模板根目录。未写入该文件的页面勾选不会进入生产流程。列出、检查和渲染已选组件： ```bash python3 tools/render-selected.py python3 tools/render-selected.py --check python3 tools/render-selected.py --render ``` 文件读不到时使用全部组件与方形背景；文件存在且 `selected` 显式为空数组时会停止执行并提示先勾选。导出文件在 `renders/selected/`。完整视频的镜头编排也应仅从该清单中选择，再按口播内容定制画面。 每个效果目录自带 `index.html`、本地 `gsap.min.js`、`background.css`、`background.js`、`hex-grid.svg` 与示例 `media.svg`，可以整体复制到新项目后修改。未生成 MP4；本目录交付的是可复用模板和预览库。 合成根节点使用 `data-composition-id="hud-效果ID"`，`data-width="1600"`、`data-height="900"`、`data-duration="8"`，对应 `window.__timelines["hud-效果ID"]`。时间轴只注册为暂停状态，HyperFrames 驱动渲染时间；网页预览通过独立的消息控制协议播放同一条时间轴。直接打开独立合成文件默认是第 0 帧，动态预览请使用动效库或 HyperFrames Studio。 ## 生成知识口播 B-roll 的建议流程 1. 从口播中确定一个需要视觉解释的句子：数据、趋势、占比、定义、步骤、清单或素材细节。 2. 选一个合适的效果，复制整个效果目录；一段 B-roll 优先只表达一个重点。 3. 编辑合成 HTML 中的标题、说明、卡片文案及对应数据；将示例数据替换为已核对的真实来源。 4. 替换图片或截图，检查缩放锚点。与口播关键字对齐入场时刻，留出至少 1 秒可读的结果停留。 5. 执行 `hyperframes check`，在 0.8、2、5、7.5 秒检查画面后渲染。 ## 可用效果 | 分类 | 效果与目录 ID | | --- | --- | | 数据可视化 | 动态柱状图 `bar`、折线图 `line`、饼图 `pie`、环形图 `donut`、数字滚动 `number`、进度条 `progress`、百分比矩阵 `percentage`、TOP 排名 `ranking` | | 文字排版 | 打字机 `typewriter`、逐字出现 `characters` | | 流程与清单 | 步骤流程 `steps`、清单完成 `checklist`、要点卡片清单 `cards` | | 聚焦与揭示 | 放大镜 `magnifier`、局部放大 `zoom`、暗角聚光 `vignette`、遮罩揭示 `reveal`、聚光灯 `spotlight` | | Ken Burns | 缓慢推近 `push`、缓慢拉远 `pull`、水平平移 `pan`、垂直摇移 `tilt` | ## 修改内容、数据与素材 - 单个效果：直接修改 `effects//index.html`。数值对应的标签、图形比例和动画目标应一同修改；饼图各项之和为 100%。 - 数字滚动：修改 `.hf-number-wheel` 的 `data-value`。模板使用等宽数字列，自动生成滚动轨道。 - 打字机：修改 `.char` 字符内容，保持一字一元素；当前 62px 等宽中文单行排版，建议不超过 18 字。更长内容请降低字号、同步调整每字符宽度和光标位移，或拆成短句。 - 图片 / 截图 / 实拍静帧：将素材放入效果目录，把 `.media-image` 的 `src="media.svg"` 改为本地文件。放大镜还需同步修改 `.lens-image` 的 CSS 背景路径，确保镜片和底图引用同一素材。建议使用横向 16:9 或接近 16:9 的高分辨率素材。 - 实拍视频：当前示例用静帧。需要视频时，将图片节点替换为带唯一 `id`、`data-start="0"`、`data-duration="8"` 的 `