Video Recap Skills

Video Recap Skills

把一段或几段视频做成中文解说成片：六个技能装进你正在用的编程 Agent，本地只要 ffmpeg，远程只要一个小米 MiMo key，成片还能一键导成剪映草稿接着改。

项目主页  ·  安装  ·  看看它的输出  ·  English

上面这条 59 秒横屏解说《这一秒过火》，是从四集短剧里选段、剪辑、写稿、配音、混音、包装并经多轮看片修改后的最终交付； 它的全部创作产物（故事计划、声音分工、旁白、时间线、QC 报告、看片修改记录、Remotion 包装源码）都在 examples/guohuo-60s/，下文的节选全部来自这些文件。

这是什么

六个技能装进 Claude Code、Codex CLI、OpenCode 或 OpenClaw，你用自然语言给出视频路径和想要的成片，Agent 负责理解画面与对白、 决定故事与视听方案、剪辑、写稿、配音、混音和字幕。支持 .mp4 / .mov / .mkv / .webm。

• 一个 key，本地只要 ffmpeg。 ASR、VLM、TTS 都走小米 MiMo，本地只用 Python 标准库和 ffmpeg，不需要 GPU，不需要 pip install，也不下载模型。配音可以换成 Fish Audio，只替换配音这一段。
• 先做创作决定，再分配声音。 Agent 先比较剪辑假设，把观众承诺、POV、戏剧问题和"发生了什么变化"的 beat 写进 recap_story_plan.json，再给每一拍指定画面任务和声音归属：旁白只在有明确任务时整块配音，强对白、动作声或沉默可以完整主导一拍。
• 先剪后配，时间轴天然对齐。 剪辑模式先把长视频剪成成片，再对着成片写解说；一次可以传多个视频，按 source_id 选段剪成一条主线；每个视频的分析沉淀成文件系统素材库，下次直接复用。
• 成片之外还能继续改。 多轨时间线 timeline.json 可一键导出剪映草稿，原片、解说、BGM、字幕、图片叠层都可编辑；自带一份准确字幕文件就会被当作原声字幕的首选来源。
• 每一步都留下可核对的记录。 旁白 lint、组装 QC、交付 QC 和看片修改日志都是机器可读文件；可选的 MiMo 成片顾问只给建议，缺 key、限流或超时都不会阻断出片。

安装

前提：Python 3.10 或更新版本，PATH 上有带 libass 的 ffmpeg（默认烧录字幕），以及一个小米 MiMo API Key。

brew install ffmpeg                        # macOS；Debian/Ubuntu 用 apt，Windows 用 choco / scoop / winget
export MIMO_API_KEY=your-mimo-key          # Windows PowerShell：$env:MIMO_API_KEY="your-mimo-key"
export MIMO_TOKEN_PLAN_CLUSTER=cn          # 仅 tp-* Token Plan key 需要：cn | sgp | ams

MiMo 不需要订阅，sk-* key 按量付费；本项目实测一条完整视频约 1.3 元，费用随视频时长和调用量变化。

在 Claude Code 里执行：

/plugin marketplace add zenstory-ai/video-recap-skills
/plugin install video-recap-skills@video-recap

也可以直接说一句话（支持导入 GitHub 仓库的 Agent 都适用）：

安装这个插件：https://github.com/zenstory-ai/video-recap-skills

Codex CLI、OpenCode、OpenClaw

Codex CLI

codex plugin marketplace add zenstory-ai/video-recap-skills
codex plugin add video-recap-skills@video-recap

OpenCode：按官方 Agent Skills 文档，项目级技能放在 .opencode/skills/ /SKILL.md。克隆仓库后从仓库目录启动：

git clone https://github.com/zenstory-ai/video-recap-skills.git
cd video-recap-skills
mkdir -p .opencode
ln -s ../skills .opencode/skills             # Windows 把 skills\* 复制到 .opencode\skills\
opencode debug skill                         # 应列出全部 6 个技能

OpenClaw：克隆后导入 Claude 插件包：

openclaw plugins install ./video-recap-skills
openclaw skills list

同一份技能只注册到一个发现目录，否则会重名或重复触发。

可选：用 Fish Audio 配音

export TTS_PROVIDER=fish-audio
export FISH_API_KEY=your-fish-key
export FISH_TTS_REFERENCE_ID=your-voice-model-id  # 可选；默认内置"娱乐扒妹"解说音色

默认模型 s2.1-pro-free，默认音色"娱乐扒妹"（reference ID 5653cea4ac83480aaf2bf45406556185），计费以 Fish Audio 官方为准。ASR 和 VLM 仍走 MiMo；本地参考音频克隆（--voice-ref）只在 MiMo 路径可用。

装好后让 Agent 自检一次：

检查 video-recap 的运行环境，告诉我 Python、ffmpeg/libass 和 MiMo 配置是否就绪。

> 变更见 CHANGELOG.md 与 Releases。仓库已从 worldwonderer/video-recap-skills 迁到 zenstory-ai/video-recap-skills，按旧地址安装的用户请重新指向新仓库。

看看它的输出

下面每一段都摘自 examples/guohuo-60s/ 里的真实文件，省略处用"…"标出。案例的输入是《这一秒过火》第 2、3、6、21 集，仓库只收录结构化产物，不含原剧音视频。

故事计划先写清"观众承诺"，再写每一拍的变化

Agent 在剪任何一刀之前先写 recap_story_plan.json。导演意图是四个问题的答案：承诺什么、跟谁的视角、观众带着什么问题看、什么信息留到最后：

"director_intent": {
  "viewer_promise": "60秒看懂死而复生的白月光为什么让男主一秒破防，并用三个名场面把关系推到婚服送嫁。",
  "pov": "跟随慕容清峄的认知与反应，让观众和他一起从震惊、发疯走到确认她仍会护他。",
  "dramatic_question": "她既然装作陌生人，为什么眼神、亲吻和保护都在暴露旧情？",
  "emotional_start": "荒诞吃瓜式震惊",
  "emotional_end": "抓马又上头的未完待续",
  "ending_aftertaste": "明明相爱却要嫁给哥哥的强悬念",
  "withhold_reveal": "前8秒先揭示准大嫂身份；中段以洗手台和护夫逐步证明旧情；最后才亮婚服。"
},

每个 beat 记的不是场景摘要，而是"发生了什么变化"、观众带着哪个问题进来、带着哪个问题出去，以及必须保住的具体时刻和证据来源（10 拍节选 1 拍）：

{
  "beat_id": "b03",
  "source_id": "episode-03",
  "source_start": 1292.0,
  "source_end": 1305.5,
  "function": "escalation",
  "event": "男主堵住女主说出日日夜夜想她与挫骨扬灰",
  "change": "power: 女主回避→男主逼问",
  "audience_question_in": "男主会忍吗",
  "audience_question_out": "狠话里全是想念",
  "character_focus": "慕容清峄",
  "must_keep_moment": "完整原声“我日日夜夜地想你…挫骨扬灰”",
  "evidence": ["asr", "vlm", "hard_subtitle"]
},

这一拍在 clip_plan.json 里变成一条带理由的选段，剪辑模式据此先剪出成片，再写旁白。

旁白让位给原声：谁主导这一拍是写在文件里的

visual_audio_board.json 给每一拍指定 audio_owner。上面那一拍由原声主导，旁白任务是 none，播放速度锁定 1.0（10 拍节选 1 拍）：

{
  "beat_id": "b03",
  "source_id": "episode-03",
  "source_start": 1292.0,
  "source_end": 1305.24,
  "output_start": 9.206666,
  "output_end": 22.446666,
  "picture_job": "performance",
  "preferred_moment": "完整原声“我日日夜夜地想你…挫骨扬灰”",
  "entry_reason": "尽量晚进到信息/动作将发生前",
  "exit_reason": "台词、动作或反应完整落地后立即离开",
  "audio_owner": "original_dialogue",
  "original_audio_anchor": "完整原声“我日日夜夜地想你…挫骨扬灰”",
  "narration_job": "none",
  "handoff": "旁白先补关系，原声/动作发生时完全让位；下一拍承接人物反应。",
  "playback_speed": 1.0
},

于是 narration.json 全片只有 7 个旁白块，第二块在 10.2 秒停下，第三块到 23.047 秒才进来，中间 13 秒完整留给那句原声：

{
  "start": 5.773,
  "end": 10.2,
  "narration": "她改名方牧兰，嘴上装作不认识，一个眼神就把三年前的旧情全招了。",
  "pause_after_ms": 80,
  "overlaps_speech": true,
  "emotion": "调侃"
},
{
  "start": 23.047,
  "end": 26.5,
  "narration": "天呐，狠话还没落地，下一秒两个人直接亲上了。",
  "pause_after_ms": 50,
  "overlaps_speech": true,
  "emotion": "吃瓜、上头"
},

三段被保护的原声由 Agent 校对后写进 original_subtitles.json，在留白处烧成「」字幕：

[
  { "start": 4.133, "end": 5.053, "text": "大嫂。" },
  { "start": 11.127, "end": 21.027, "text": "我好想你，日日夜夜地想你，想把你抽筋扒皮，挫骨扬灰。" },
  { "start": 35.673, "end": 37.473, "text": "有我在，你别怕。" }
]

组装时 timeline.json 的原声轨在每个旁白块处自动压低、块后恢复；这份时间线就是剪映草稿导出的来源。

看片之后怎么改，改了什么、冻结了什么，都有账

案例经历了四轮修改，每轮在 revision-log.json 里写成三项：改什么、冻结什么、怎么验证。最后一轮只解冻画面：

{
  "baseline": "final_picture_conform",
  "scope": "picture_conform",
  "change_set": [
    "remove the visible tail-frame pause near 42.08 seconds",
    "restore continuous source movement around 46.24 seconds"
  ],
  "frozen_set": [
    "story and narration",
    "all audio",
    "caption timing and typography",
    "title and accent graphics"
  ],
  "verification": [
    "normal-speed full watch",
    "join playback around both change points",
    "freeze detection as supporting evidence",
    "audio stream-copy verification",
…

edit-map.json 记下 46 秒那处跳接是怎么修的：不是加溶解或闪白遮掩，而是把原片被删掉的 2001–2004 秒那段同一运动补回来：

{
  "name": "wedding_corridor_continuous_motion",
  "beat_ids": ["b07", "b08"],
  "output_frames": [1052, 1288],
  "output_seconds": [42.08, 51.52],
  "asset_id": "episode-21",
  "source_seconds": [1996.0, 2010.32],
  "speed": 1.516949153,
  "repair": "Restored the omitted 2001-2004 source interval instead of hiding the jump with a transition."
},