graphic-overlays

Graphic Overlays

Graphic Overlays 能够处理一段完整播放的本地影片，并在影片上叠加一系列精心设计且对齐口播内容（逐字稿）的动态图卡（graphic cards） — 包含标题、下三分之一字卡（lower-thirds）、数据突显、引言、侧边栏、子母画面等。Agent 会设计这些图卡（时间点 + 内容）并在对话中直接撰写每张图卡的 HTML，随后将其拼装成单页组合 HTML，并透过 hyperframes 算图汇出为 MP4。这里没有固定的原型列表，也没有预设的卡片结构 — 所有的叠加图卡都是根据逐字稿的实际口播内容即兴设计出来的。

开始制作前，请先确认路线。 本 Skill 旨在为现有口播影片加工，叠加上精美设计的图卡（标题、lower-thirds、数据卡片、引言、侧边栏、子母画面）。如果使用者只是需要一般文字字幕（将口播语音转为可读字幕） → 请改用 /embedded-captions；如果只需要单一简短且无配音的元素（如单颗 Logo 片头 / 下三分之一字幕条） → 请改用 /motion-graphics。原始剪辑片段会保持原样播放 — 任何重新对时、调色、重新裁切（reframing）、调整顺序或音讯处理，都属于非线性剪辑（NLE）范畴，超出本 Skill 的处理范围。若是想根据 URL / 主题 / PR 简报从头制作影片 → 请使用 creation 创作流程。若不确定该用 overlays 还是 captions？请先阅读 /hyperframes。

与 embedded-captions 并列的动态包装 Skill。 Captions 是把 口播文字 加上去作为可读字幕；而本 Skill 则是为播放中的影片叠加 设计好的动态图卡。一般纯字幕 → embedded-captions。从零开始制作影片 → 使用 creation 创作流程（如 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，亦无 API 速率限制（rate limit）。

工作流程

1. 检查环境

npx hyperframes doctor          # ffmpeg, headless browser, render deps
# 确认内建静态资源：
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 部署至工作目录）

语音转写无须 Key — 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. 提取音讯与元资料（Metadata）

# 元资料 — 片长 / 宽度 / 高度 / 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. 语音转写（Transcribe）

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. 在对话中起草轻量级分镜脚本（Storyboard）

不涉及 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?'"
      }
    }
  ]
}

卡片必要栏位：

栏位	型别	用途
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	自由标签，可用来记录卡片模式；省略则预设为自由模式
transition（可选）	enum: cut | fade | slide | wipe	声明式的卡片间转场效果

五种 zone 数值：

zone	对应逻辑范围	适用时机
fullscreen	覆盖整个画布	核心高光时刻、大数字、金句总结
whiteboard-area	留出 40px 边距（或直式高度的 45%）	密集数据 / 带有标注的内容
lower-third	底部 30% 区域	在可看清的影片画面上压字标注
side-panel	右侧 42%（横式）或底部 40%（直式）	一侧放置数据，另一侧保留影片
video-overlay	全画布，预期卡片大部分为透明	在全萤幕影片上置入标注叠加层

在步骤 9 拼装组合页面时，请参照上表将每张卡片的 zone 解析为卡片容器（card-host wrapper）上的像素范围。
影片范围在组合设定中仅设定一次（videoTrack.bounds）；若想让影片看起来在「卡片间移动」，请在组合页面的 <script> 中针对 #video-wrap 撰写 GSAP 补帧动效（tween）（参见步骤 9）。

无预设卡片角色，无预设叙事结构。 卡片的形式完全取决于影片实际口播内容 — 可以全都是引言或全都是数据，可以由数字开场也可以由故事开场。让逐字稿决定节奏。

该提炼多少个重点？— 根据片长 + 密度自动推断。 没有固定的上限。根据影片片长设定基础节奏，再根据资讯密度进行微调。只有下限是固定的：最少 5 张卡片，确保即使是短影片也有视觉节奏感。

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

影片片长	基础节奏（每张卡片秒数）	说明
< 60 秒（Short/Reel 短影音）	6–8 秒	观众期望短影音有更快的节奏切换
60 秒 – 3 分钟	8–12 秒	一般社群影片的常见节奏
3 – 10 分钟	12–20 秒	给予喘息空间；每张卡片承载更多内容
10 – 30 分钟	20–35 秒	长影片演讲 / 访谈的流畅节奏
> 30 分钟	30–60 秒	单元化、接近章节划分的感觉

步骤 2 — 资讯密度乘数（与基础节奏相乘）：

逐字稿中的特征信号	乘数	效果
高密度 — 包含大量数字、独立观点、断续节奏、清单列举，每 1–2 句话就是一个新观点	× 0.7	切换更快

<!-- truncated for translation batch; full body continues in source -->