Airsc is free for everyone. If it helps you, support it with $2–$20.

Support
VISign in
PluginSafeImages, video & audioSome setup

video-recap-skills

zenstory-ai · zenstory-ai/video-recap-skills

Enables Claude Code/Codex to create Chinese narrated video recaps using scene detection, ASR, VLM, script generation, TTS, and FFmpeg assembly.

Claude Code / Codex skills that turn a video into a Chinese narration recap (视频解说): scene detection, ASR, VLM, script, TTS, ffmpeg assembly, optional editable JianYing / CapCut draft export (剪映草稿导出). Local ffmpeg + one MiMo key, no GPU. | 用 Claude Code skills 把视频做成中文解说成片，可选一键导出可编辑剪映草稿。

550 stars103License: MITUpdated 14 days ago0 opens

Preview

▍

What you can do with it

  • Transform multiple raw video clips into a single Chinese narrated short video recap.
  • Generate a script, voiceover, and subtitles for a video without manual editing.
  • Export a video recap project to CapCut/JianYing for further manual refinement.

Safety check

Safe

No risky patterns found in the files we scanned.

Automated scan of the repo files. Always review code you run.

From the README

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 和看片修改日志都是机器可读文件。

安装

ClawHub

ClawHub 分发由仓库中的 显式发布清单 管理，并通过 ClawHub 提供发现入口。具体 skill 链接只有在发布者、版本和匿名访问均验证后才会写入本文档，避免把尚不存在的条目当成已上架。

前提：Python 3.10 或更新版本，PATH 上有 ffmpeg，以及一个小米 MiMo API Key。默认把字幕烧录进画面，这需要带 libass 的 ffmpeg；Homebrew 自带的 ffmpeg 没有 libass，这时默认运行不烧录，在成片旁输出同名 .srt 外挂字幕并在 final_qc.json 里记一条警告（显式传 --burn-subtitles 则在开跑前报错）。旁白里写了画面文字叠加（visual_overlays）时还需要带 drawtext 的 ffmpeg，缺了会在配音前报错。要在 macOS 上烧录字幕，可用 brew install ffmpeg-full（keg-only，需把它的 bin 放到 PATH 前面）。

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/<name>/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                         # 应列出全部 7 个技能

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,
  "overla
View source on GitHub