graphic-overlays

Graphic Overlays（视频图形包装贴片）

Graphic Overlays 能够接收一段完整播放的本地视频，并根据视频语音内容，在画面上按时间轴叠加一系列设计精美的图形卡片——包含标题、人名条（Lower-thirds）、数据标注、金句引用、侧边面板以及画中画（PiP）。Agent 会直接在对话中设计卡片（时间轴 + 内容）并撰写每张卡片的 HTML 代码，接着组装为单页合成 HTML，最后通过 hyperframes 渲染导出为 MP4 视频。本 Skill 没有固定的样式模板列表，也不强制卡片结构——所有的图形贴片均根据逐字稿实际表达的内容自然生成。

构建前请先确认路由。 本 Skill 适用于对现有的口播/真人片段叠加设计感图形卡片（标题、人名条、数据标注、金句、侧边栏、画中画）。如果用户需要的是纯字幕（将说话内容显示为文本） → 请使用 /embedded-captions；如果只需要单个简短无配音的动画元素（如单一 Logo 演绎 / 人名条片头） → 请使用 /motion-graphics。源视频片段本身保持原样播放——重剪时间、调色、裁剪画面、重排顺序或调整音频属于 NLE 非线性剪辑范畴，超出本 Skill 范围。如果需要从 URL / 话题 / PR 文章直接生成视频 → 请使用创建类工作流（creation workflows）。若不确定该用图形贴片还是字幕？请先阅读 /hyperframes。

与 embedded-captions 同属视频包装姐妹 Skill。 Subtitles/Captions 专注于把说话文本作为可读字幕呈现；而本 Skill 则是在播放的视频之上添加设计感图形贴片。纯字幕 → embedded-captions。从零构建全新视频 → 创建类工作流（product-launch-video / faceless-explainer / …）。

工作目录中可供检查的中间文件：

• metadata.json — 视频时长 / 宽度 / 高度 / 帧率（fps）
• audio.mp3 — 提取出的音频文件
• transcript.json — 扁平化词级数组 [{ text, start, end }, …]（Whisper 生成；无 segments 嵌套，无 words 外层包裹）
• storyboard.json — 简易卡片大纲（Agent 的规划产物）
• public/cards/card-XX.html — 每张卡片对应的 HTML 片段文件
• public/index.html — 最终组装完成的合成页面
• output.mp4 — 渲染导出的视频

CLI 指令

# hyperframes — 语音转写（本地 Whisper）+ 将组装好的 HTML 渲染导出为 MP4
npx hyperframes --help

本 Skill 完全依赖 hyperframes CLI 以及系统原生的 ffmpeg / ffprobe 运行。
语音转写通过 hyperframes transcribe 在本地运行 Whisper ——无需依赖第三方服务、API Key 或限流代理。

工作流

1. 检查环境

npx hyperframes doctor          # 检查 ffmpeg、无头浏览器及渲染依赖
# 确认随 Skill 内置的静态资源：
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

必需项：

• ffmpeg / ffprobe（系统原生）
• <SKILL_DIR>/assets/fonts/*.woff2、<SKILL_DIR>/assets/vendor/gsap.min.js（内置于本 Skill 中，将在第 9 步暂存至工作目录）

语音转写无需密钥 —— hyperframes transcribe 会在本地直接运行 Whisper（第 4 步）。

在 macOS 上运行 hyperframes render 时，强烈建议配置：

export PRODUCER_BROWSER_GPU_MODE=hardware

2. 创建工作目录

所有产物均存放于 videos/<project-name>/ 下 —— 与其他视频工作流（product-launch-video / faceless-explainer / pr-to-video）保持一致的命名规范。保持当前工作目录（cwd）在工作区根节点；后续所有文件均写入该子目录下。

VIDEO_PATH="/absolute/path/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. 提取音频与元数据

# 元数据 — 时长 / 宽度 / 高度 / 帧率 (fps)
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# 音频提取
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

输出产物：metadata.json（可读取 width/height/duration；帧率 fps 为求值后的 r_frame_rate 分数，例如 30000/1001 → 29.97）+ audio.mp3。

4. 语音转写

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

本地 Whisper 运行 —— 无 API Key，无代理，无需担心速率限制。命令会将词级 transcript.json 写入工作目录（包含每个词的 text 以及 start / end 时间戳）。
在第 6 步中可通过读取该文件获取精确到词/句的时间戳来驱动卡片出现时间；如果需要句级片段，可以按标点符号/停顿自行将词组合为句子。

锁定媒体总时长限制。 Whisper 返回的最后一个词的 end 时间可能会略微超过视频实际长度 —— 务必将每张卡片的 endSec 以及 composition.durationSeconds 限制（clamp）在 metadata.json 记录的总时长内，否则渲染尾部会出现黑屏。

5. 校验并修正逐字稿

transcript.json 是一个扁平的词对象数组 —— [{ "text": "...", "start": s, "end": s }, …]（没有 segments 数组，也没有外层 words 包裹；每个词的文本键名为 text）。读取并修正明显的 ASR 转写错误：

• 同音异形字、专有名词/产品名、技术术语、标点符号
• 直接原地修改词的 text 字段；保留其原始的 start / end 时间戳
• 文件中没有预先分组的 segments 数组 —— 当你需要句级片段来设定卡片时间轴时，请自行将词按句分组（根据句末标点/停顿切分）

6. 起草简易分镜脚本（在对话中完成）

此步骤无需调用 CLI。 直接读取 transcript.json + metadata.json 并在对话中设计卡片。storyboard.json 是 Agent 内部的规划产物 —— CLI 命令不会直接读取它；它的作用是帮助你在编写每张卡片的 HTML 之前，清晰地构思好时间轴与内容。请保持数据结构与下方示例一致，以便第 9 步编写合成方案时可以直接复用：

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "Hook with the speaker's anxious midnight question",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "AN HONEST QUESTION",
        "title": "The soul-searching question at 11 PM",
        "detail": "Client's 60-second voice message: 'If the RMB appreciates, does that mean my USD policy is a terrible loss?'"
      }
    }
  ]
}

Card 对象的必填字段：

字段	类型	用途
id	string	在卡片 HTML 和 GSAP 选择器中使用的唯一静态 ID
intent	string	自然语言描述；用于卡片内容合成时的意图引导
startSec / endSec	number	出现/消失的秒数时间轴（必须满足 endSec > startSec）
accentIndex	0 | 1 | 2 | 3 | 4	抽取主题 5 种强调色中的哪一种
zone	enum（详见下文）	卡片在画布上的显示区域位置
contentHints	object	自由格式对象；Agent 可在此放置 kicker（引子）/ title（标题）/ detail（详情）/ data（数据）/ quote（金句）
archetype（可选）	string	自由标记标签，用于记忆卡片模式；不填默认为自由格式（free-form）
transition（可选）	enum: cut | fade | slide | wipe	声明式的卡片间切换过渡方式

zone 的 5 种取值：

zone 区域	解析后的像素边界	适用场景
fullscreen	覆盖整个画布	高光时刻、超大数字、核心金句
whiteboard-area	内缩 40px 边距（或竖屏高度的 45%）	密集数据展示 / 带标注的内容
lower-third	底部 30% 区域	在可见视频画面上方叠加标注信息
side-panel	右侧 42%（横屏）或底部 40%（竖屏）	一侧显示数据，另一侧留给视频
video-overlay	覆盖全画布，预期卡片大部分背景透明	在全屏无缝视频上叠加标注贴片

当你在第 9 步组装合成页面时，请按照上表将每张卡片的 zone 解析为卡片容器（card-host wrapper）的具体像素边界（pixel bounds）。
视频尺寸边界在合成页面层级仅设置一次（videoTrack.bounds）；如果想实现视频在“不同卡片间平移/缩放”的效果，可在合成页面的 <script> 中针对 #video-wrap 编写 GSAP 补间动画（tweens）（参见第 9 步）。

不设固定的卡片角色，不设固定的叙事结构。 卡片的呈现完全取决于视频实际讲述的内容 —— 可以全篇都是金句，也可以全是数据分析；可以从数字开场，也可以从故事切入。让逐字稿的内容来主导节奏。

该提炼多少个卡片节点？—— 根据时长 + 信息密度自动推导。 无固定上限。首先根据视频时长选定基础节奏（base pace），再根据**信息密度（information density）**进行微调。仅设定兜底下限：至少 5 张卡片，确保即便短视频也能拥有丰富充实的视觉节奏。

步骤 1 — 根据时长确定基础节奏（中等信息密度下的自然 秒数/卡片）：

视频时长	基础节奏（每张卡片持续秒数）	设定依据
< 60秒（短视频）	6–8秒	短视频观众期望更快的切频与视觉冲击
60秒 – 3分钟	8–12秒	常见的社媒短视频节奏
3 – 10分钟	12–20秒	给予画面呼吸感；每张卡片承载更多信息
10 – 30分钟	20–35秒	适用于长视频演讲 / 访谈类节奏
> 30分钟	30–60秒	类似于分集/章节级别的卡片节奏

步骤 2 — 信息密度系数（对基础节奏进行乘积微调）：

逐字稿中的信号特征	调整系数	效果
高密度 — 密集的数据数字、独立观点频繁、节奏明快、列表式举例、每 1–2 句话就是一个新观点	× 0.7	切换节奏加快