- name
SKILL.md
Tệp skill vẫn nằm trong kho mã của nhà phát hành.
Dán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add zenstory-ai/video-recap-skills --skill video-recap -a cursor -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add zenstory-ai/video-recap-skills --skill video-recap -a claude-code -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add zenstory-ai/video-recap-skills --skill video-recap -a codex -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add zenstory-ai/video-recap-skills --skill video-recap -a grok -yGửi tin nhắn đã sao chép trong cuộc trò chuyện Grok Bot. Bot sẽ lấy tệp SKILL.md này từ GitHub và thêm vào bộ skill mà mọi Bot của bạn dùng chung.
Install this skill: https://github.com/zenstory-ai/video-recap-skills/tree/HEAD/skills/video-recapTừ nhà phát hành
本技能是自包含的视频解说与剪辑生产技能,将视频理解、故事立意、画面剪辑、旁白撰稿、配音合成与音画混音放在同一工作目录 work_dir 下串联完成:
understand.py(视频理解)─▶ Agent 制定故事/声画方案并写 clip_plan.json 或 narration.json ─▶ [cut.py(剪辑与重出简报)] ─▶ validate.py(本地底线校验)─▶ voiceover.py(TTS 配音)─▶ assemble.py(混音与字幕渲染)
日常使用可直接运行总入口 scripts/recap.py 串联全流程并在创作节点自动暂停,也可按需单独调用 scripts/ 下的单阶段脚本(understand.py、cut.py、validate.py、voiceover.py、assemble.py)。
把外部成片拆解为制作参考(production_reference.json)不在默认生产链上。当用户要求拆片学习时:先对样片跑 understand.py(建议设 ASR_SEGMENT_SECONDS=5),再用独立的拆片技能执行测量、标注、校验与导出,将导出的 production_reference.json 放入下一轮运行的 work_dir,或登记为资源库里的 production_reference 模板并经 --project 绑定。主流程不会自动拆片,也不拿新成片与参考片做机械打分比对。
全流程支持断点续跑:写完 clip_plan.json 或 narration.json 后重跑同一条 recap.py 命令即可继续。续跑时脚本会核对 recap_run_manifest.json 记录的源视频身份与参数,若工作目录来自其他视频或不同参数组合会拒绝复用;暂停时终端打印的续跑命令已将路径转为绝对路径并补齐 --work-dir。
画面流程 --edit-mode full|cut 与声音策略 --audio-mode narration|source-mix 相互独立,支持以下五条路线(其余组合启动即报错):
创作判断由 Agent 负责。动笔前先区分本轮的创作控制模式(CREATE 新建创作 / DIRECTED 按指定方案执行 / REVISION 定稿返修,与 --edit-mode 独立),并在配音渲染前完成五项判断:
控制模式分工、REVISION 锁定规则、剪辑与口播细则,以及 recap_story_plan.json、visual_audio_board.json、style_card.json 的结构详见 references/creative-editing-playbook.md。
# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***
同一个 MIMO_API_KEY 即可驱动默认全链路。涉及远程网络请求的环节如下:
understand.py):将切分后的音频窗口发往 MiMo ASR(mimo-v2.5-asr),将抽帧 JPEG 连同 background_research.json 摘要发往 MiMo VLM(默认 mimo-v2.6-flash,可通过 MIMO_MODEL 切换 mimo-v2.6-pro 等)。若工作目录已有完整分析产物,传 --brief-only 或 --edited-storyboard-only 则纯本地运行、不发起网络请求。voiceover.py):按 --tts-provider(默认 auto 优先选已配置的 MiMo,其次 Fish Audio,不自动选 index-tts)将解说文本发往对应 TTS 服务:
mimo-tts:发往 MiMo TTS(mimo-v2.5-tts);若显式传了 --voice-ref <audio>,还会将该参考音频切片发往 mimo-v2.5-tts-voiceclone(使用前请确认已获声音授权)。fish-audio:需配置 FISH_API_KEY,将每段解说文本与 FISH_TTS_REFERENCE_ID 发往 FISH_TTS_API_URL(默认 https://api.fish.audio/v1/tts)。index-tts:仅在显式指定 --tts-provider index-tts 时启用,将文本与 INDEX_TTS_VOICE 发往用户自建的 INDEX_TTS_ENDPOINT(详见 references/index-tts.md)。validate.py)、视频剪辑(cut.py、shot_review.py)与音画合成(assemble.py):纯本地确定性逻辑与 ffmpeg / ffprobe 调用,不发起网络请求。以 tp- 开头的 Token Plan 密钥默认发往中国区集群,可通过 MIMO_TOKEN_PLAN_CLUSTER 切换集群。配置项见 references/config-playbook.md,产物格式见 references/data-schema.md。下文 scripts/... 均相对于本技能目录。
只要能从文件名或用户说明识别出片名、剧集名或科普主题,开跑前先按 references/research-guide.md 核实人物关系与前情,写入 work_dir/background_research.json(多视频连剪写在项目根 work_dir,脚本会自动同步到 sources/<source_id>/)。
随后启动编排入口:
python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
脚本完成音频提取、静音与句末停顿锚点检测(speech_boundary_anchors.json)、场景切分、VLM 帧分析与 ASR 转写后,生成故事板拼图 storyboard/storyboard_*.jpg 与创作简报 agent_narration_brief.md 并暂停。
阅读 agent_narration_brief.md 并查看故事板抽帧后,先写 recap_story_plan.json(CREATE 主线清晰时写 1 个选定方案即可,仅在源片存在多角度取舍时比较 2–3 个候选假设)与 visual_audio_board.json(逐拍明确画面瞬间、进出理由、原声锚点与声音主导方)。
在 cut 模式第一阶段,编写基于**源片时间轴(SOURCE)**的 work_dir/clip_plan.json(本阶段不写 narration.json):
{
"target_duration": "3m",
"clips": [
{
"start": 12.0,
"end": 38.0,
"reason": "b01 (hook):沈曼推门撞见未婚夫与千金谈联姻,入点卡推门看清两人动作,出点卡转身攥紧户口本"
}
],
"required_evidence": {
"nodes": [
{"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
],
"before": []
}
}
选镜与切点规则:
reason):用自然中文写清该段承担的节拍作用(hook | setup | turn | escalation | payoff)与入出点画面/声音依据,无需拼固定段数的竖线模板。required_evidence):不可丢失的关键动作、反应或原声问答可登记在 required_evidence;若边界吸附裁掉必保区间或颠倒 before 顺序,脚本会报错拦截。0.30s 气口且不跨硬切点,单段最短 >= 0.8s,片尾最后一拍留出表情或动作落定的余韵。切进台词中途会报 unsafe_clip_sentence_boundary(若同时引发闪帧与切词冲突则报 shot_speech_conflict)。cut.py 渲染 edited_source.mp4 后会自动运行 shot_review.py 生成 shot_review.json,拦截 <= 0.20s 的极短残镜闪帧(flash_slivers)。遇到动作戏或密集反打时,也可运行 ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - 或 scripts/shot_review.py(见 references/shot-review.md)检查切点,区分原片切点与拼接切点——将原片自带的无关短镜头整段删除或把边界移到快切簇外侧;对由本次拼接制造的切点(如硬切边缘残留几帧邻镜),外扩入出点或合并同源相邻段,不用转场遮掩坏接点。写好 clip_plan.json 后重跑 recap.py,脚本完成边界吸附、渲染恒定帧率 edited_source.mp4 并重映射输出时间轴证据(speech_boundary_anchors_output.json、storyboard/edited_storyboard.*),随后暂停等待写解说词。
进入写稿阶段后,先查看剪后故事板、补齐 visual_audio_board.json 的成片输出时间并按需编写 style_card.json,再写 work_dir/narration.json:
[
{
"start": 0.2,
"end": 5.0,
"narration": "相恋五年揣着户口本去求婚,沈曼推开门,却撞见未婚夫正搂着千金谈联姻。",
"pause_after_ms": 250,
"overlaps_speech": true
}
]
编排 cut 模式下,narration.json 直接填写剪后成片的 OUTPUT 时间戳(0 .. 成片总时长)(单独调校验器传 validate.py --mode cut_output)。核心写作要求(细则与正反例见 references/creative-editing-playbook.md):
overlaps_speech: true)须对齐句末锚点或静音窗(违者报 interrupts_source_sentence / unsafe_source_handoff),释放原声同样避免落在角色半句话中途(对白区间内后续 3s 无锚点时给出 unsafe_source_release 复核提示,合成端做 bounded_release 平滑回升)。incomplete_sentence),靠精炼字数匹配窗口(full 模式超预算 1.25 倍报 over_budget,不静默删字)。写连贯自然的口语长短句,不写阅读理解式升华套话;结局交给画面与原声演完,兑现后不再补总结旁白。BGM_PATH)只用纯器乐,原片已有高音量人声插曲时不叠外部配乐。传入 --subtitle-y-top/--subtitle-y-bot 默认仅在旁白区间开启 1.0 不透明像素带遮罩(留白段继续露出原片自带硬字幕);若原片无硬字幕,或额外设置 SOURCE_SUBTITLE_MASK_TIMING=all(或同时设 MASK_SOURCE_SUBTITLES=true + SOURCE_SUBTITLE_MASK_TIMING=all + SUBTITLE_MASK_OPACITY=1.0)开启全片不透明遮罩并保留了原声对白,可在 work_dir/original_subtitles.json 按成片时间写入校对后的原声字幕(若留白段原片硬字幕仍可见,合成器会自动跳过以免叠字)。references/promotional-copy.md 写入 work_dir/promo_copy.json;成片画布视觉包装按 references/packaging.md 写入 work_dir/packaging_plan.json。写好 narration.json 后重跑同一条 recap.py 命令:
validate.py):输出 narration_lint.json。对时间重叠/越界、残句、抢断原话、full 模式超预算与模板占位符泄漏做硬阻断(errors);对原声释放点无邻近锚点(unsafe_source_release)、开场留白偏长(weak_cold_open_silence)、长段无声留白(excessive_dead_air)、外貌泛称(generic_character_label)与评论套话(editorial_commentary_tone)给出非阻断提示(warnings)。voiceover.py):逐段合成语音写入 tts_segments/ 与 tts_meta.json,缓存按文本、音色、模型与参考音频指纹命中;若实测语速低于下限(TTS_MIN_SPEECH_RATE,即合成音频异常拖长)疑似异常合成,会自动重试并将异常音频另存为 *.rejected.wav。assemble.py):将画面、逐段旁白、动态闪避与句末回升后的原声、可选 BGM、可选音效(work_dir/sfx_plan.json 或 packaging_plan.json.sfx)、画布包装(work_dir/packaging_plan.json 或 packaging_layers.json,见 references/packaging.md)与片尾音频淡出合成为最终 MP4,自动抽帧导出 work_dir/cover.jpg(若 promo_copy.json 指定了封面秒数则优先采用),并输出 timeline.json(传 --export-jianying 可将视频、旁白、BGM、字幕与包装图片导出为剪映草稿)。若旁白在微加速上限内仍装不进可用时间窗,直接报 no_safe_fit 阻断,不截断尾音。声音模式与路由规则见 references/audio-modes.md。多视频输入仅支持 cut 模式,项目级简报会列出各片源的 source_id,clip_plan.json 中每条片段均须填写 source_id:
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
可通过 --material-library-dir .video-materials --save-materials 与 --use-materials 跨集复用单源理解缓存;同一库根目录下还可登记配乐、音效、音色、字体、贴图及可复用模板(subtitle_style、packaging、production_reference),用 scripts/library.py check|list|show 查询并通过 --project recap_project.json 绑定,合成后自动生成 work_dir/resource_lock.json(详见 references/resource-library.md)。测量原片硬字幕纵向遮罩区间可查看抽帧图片,或在源码仓库下运行 tools/measure_subtitle.py <video> 后传入 --subtitle-y-top 与 --subtitle-y-bot。
交付前必须直接打开最终成片文件完成视听复核:
final_qc.json 检查:REVISION 模式确认修改项已落实且冻结项未回退;核对 final_qc.json 的解码、时长与规格结果,若 metadata.warnings 非空(如 partial_tts 或缺少 libass 导致 subtitle_burn_degraded 降级为外挂 .srt),须如实告知用户。# 对当前整段输入直接混音合成;不隐式跑理解、ASR 或 TTS
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# 按 cut 流程生成剪辑计划,剪完直接合成原声成片,不再暂停等待 narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix
source-mix 同样执行原声响度归一、可选 BGM 混音、片尾淡出与音频重编码;切换音频模式须换用新工作目录。详见 references/audio-modes.md。
python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
doctor.py 检查本机 ffmpeg / ffprobe、字幕滤镜与远程服务密钥配置;dashboard_server.py 在本地 127.0.0.1 启动只读审片台(仅响应 GET 与 HEAD),浏览 --root 下的成片目录、解说时间轴与素材库。
核心交付物:
recap_<video>.mp4:最终解说或原声成片。subtitles.srt / subtitles.ass:生成的字幕文件。work_dir/:中间分析、创作计划与校验产物,字段契约见 references/data-schema.md。work_dir/recap_story_plan.json 与 visual_audio_board.json:Agent 编写的故事规划与分镜声画表。命令行参数以 python3 scripts/recap.py --help 及各阶段脚本 --help 为准;--style 作为自由文本原样传给写稿 Agent,不映射为固定枚举。
full 模式字数硬上限、超长削尾、必保画面丢失、占位符泄漏、解码与封装规格)作为硬门禁运行。references/creative-editing-playbook.md 自主把控并经成片视听复核确认。从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm,并要求剪辑、添加旁白、配音、总结或制作短剧/电视剧/电影/纪录片/科普解说时使用。在同一个自包含技能内完成视频理解、导演立意与选镜剪辑、解说撰稿与校验、TTS 配音及音画混音合成。触发词:视频解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narrati
---name: video-recapdescription: 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv /…---# skills/video-recap/SKILL.mdTổng quan
从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm,并要求剪辑、添加旁白、配音、总结或制作短剧/电视剧/电影/纪录片/科普解说时使用。在同一个自包含技能内完成视频理解、导演立意与选镜剪辑、解说撰稿与校验、TTS 配音及音画混音合成。触发词:视频解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
Câu hỏi thường gặp
Tải skills/video-recap/SKILL.md từ nhà phát hành, hoặc sao chép đường dẫn và mở kho mã. PlugMCP chỉ liệt kê skill và không lưu trữ tệp này.
Nhà phát hành duy trì nó tại https://github.com/zenstory-ai/video-recap-skills.
Claude, Cursor, Codex và Grok Build có thể đọc tệp SKILL.md mà bạn thêm từ kho mã của nhà phát hành. Grok Bot cài đặt skill khi bạn gửi liên kết thư mục GitHub của skill trong cuộc trò chuyện.