talking-head-recut

Talking Head Recut

Talking Head Recut 技能专门对完整播放的本地视频进行后期包装。它能够根据口播内容的时间轴，在视频上方叠加一系列精心设计的动态图文卡片（包括标题、下三分之一花字/人名条、数据高亮、名言金句、侧边栏、画中画等）。Agent 会在对话中实时设计卡片（控制时间轴与内容）并直接编写每张卡片的 HTML 格式，随后将其拼合成一份完整的 HTML 组合文件，最后调用 hyperframes 将其渲染导出为 MP4 视频。本技能没有任何固定的卡片样式套路，也不限制卡片结构——所有的图文包装均根据逐字稿的实际内容因地制宜、即兴生成。

制作前请先确认工作流路线。 本 Skill 适用于对现有的口播/访谈视频进行图文卡片包装（标题、人名条/花字、数据卡片、金句、侧边栏、画中画）。如果你只需要纯字幕 / 逐字字幕（将口播语音转为文本字幕） → 请使用 /embedded-captions；如果只需要制作单个简短且无配音的元素（如单个 Logo 片头/人名条动画） → 请使用 /motion-graphics。原视频会保持完整原样播放——对原视频进行裁剪重新对齐、剪辑调色、重构构图、重新排序或音轨处理属于 NLE 剪辑范畴，不在本技能处理范围内。如果是基于 URL / 话题 / PR 文稿从零生成视频 → 请走 creation 创作成片工作流。如果不确定该选图文包装还是字幕 → 请先阅读 /hyperframes。

embedded-captions 的姐妹包装技能。 字幕技能添加的是口播语音的逐字字幕；而本技能是在播放的视频上叠加设计感图文视觉。纯字幕 → 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 — 最终组装的合成页面 HTML
• output.mp4 — 最终渲染生成的视频文件

CLI 命令解析

# hyperframes — 语音转文字（本地 Whisper）+ 将组装好的 HTML 渲染为 MP4 视频
npx hyperframes --help

本 Skill 完全依赖 hyperframes CLI 以及系统自带的 ffmpeg / ffprobe 运行。语音转文字通过 hyperframes transcribe 在本地运行 Whisper 完成——无需调用第三方服务、无需 API Key，也没有频率限制（Rate Limit）。

工作流步骤

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. 语音转文字（Transcribe）

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

纯本地 Whisper 转写——无 API 密钥、无代理需求、无速率限制。转写完成后会在工作目录生成按词划分的 transcript.json（包含单词 text 及 start / end 时间戳）。在步骤 6 中读取该文件获取单词/句子的时间轴，以便精准控制卡片出现的时机；如果需要句子级别的文本块，可根据标点符号或停顿自行对单词进行分句组装。

防超长截断处理（Clamp）。 Whisper 偶尔返回的最后一个词的 end 时间戳会略微超出视频实际时长——请务必将每张卡片的 endSec 以及 composition.durationSeconds 限制在 metadata.json 的实际 duration 之内，否则渲染出的视频结尾会出现黑屏。

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 吸睛",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "AN HONEST QUESTION",
        "title": "深夜 11 点的灵魂拷问",
        "detail": "客户发来 60 秒语音：'如果人民币升值，是不是意味着我的美元保单亏惨了？'"
      }
    }
  ]
}

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	自由标签，标记该卡片的设计套路/模式；未提供即为默认的自由形式
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 补间动画（详见步骤 9）。

不设死卡片角色，不设死叙事结构。 卡片的呈现形式完全取决于视频口播的实际内容——既可以全是金句，也可以全是数据；既可以由数字开场，也可以由故事开场。让逐字稿本身决定节奏。

卡片数量判定：根据视频时长 + 信息密度自动推算。 不设上限。先按视频时长确定基础节奏，再根据信息密度进行微调。唯一固定的是下限：最少 5 张卡片，确保即便是短视频也能拥有视听节奏感。

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

视频时长	基础节奏（每张卡片持续秒数）	设计依据
< 60s（短视频/Reel）	6–8s	短视频受众期望密集的快切节奏
60s – 3 分钟	8–12s	正常的社交媒体视频节奏
3 – 10 分钟	12–20s	留出呼吸空间；每张卡片承载更多信息
10 – 30 分钟	20–35s	长视频讲座 / 深度访谈节奏
> 30 分钟	30–60s	单元剧 / 接近章节切割的节奏

步骤 2 — 信息密度系数（乘以基础节奏）：

逐字稿中的特征信号	系数	效果
高密度 — 很多数字、清晰的论点、断句紧凑、清单式列举、每 1–2 句话就是一个新观点	× 0.7	快切