Practical guide · 实用指南

Turn a local video into a source-grounded Chinese narration recap

怎样把本地视频做成有画面与原声依据的中文解说

Source checked 2026-09-12 · 源码核对日期

Video Recap Skills separates a Chinese-narration recap into understanding, editorial planning, narration, voiceover and assembly. Starting from an authorized local video, it builds a scene/speech/frame evidence index, chooses a viewer promise and POV, and writes only claims that evidence or supplied context supports. It can deliver a rendered MP4 or an editable draft—not merely a summary over footage.

Video Recap Skills 把中文视频解说拆成理解、编导、写稿、配音与合成。先从你有权使用的本地视频提取场景、对白和画面证据，再确定一条观众承诺与主视角，只写素材或已提供背景能够支持的内容。最终可交付解说 MP4，也可另导出可编辑草稿，而不是给原片随意铺一层摘要。

Video Recap Skills Source on GitHub

Before you start · 开始之前

Install Video Recap Skills in a supported agent host using the current route on the project page, then open the authorized video’s workspace. In manual commands, /ABS/video-recap-skills means the installed checkout’s absolute path—not a system path.
A local .mp4, .mov, .mkv or .webm that you own or may process, plus Python 3.10+, ffmpeg on PATH and space for frames, WAV files and renders. Burned subtitles require ffmpeg’s libass/subtitles filter.
A Xiaomi MiMo API key for remote ASR, VLM and default TTS. Fish Audio can replace TTS only and needs another key; ASR/VLM still use MiMo. This is not fully offline. Check provider privacy, region and billing terms before sending authorized material.

先在受支持的 Agent 宿主中安装并配置 Video Recap Skills；按项目页选择当前宿主的安装方式，再用该宿主打开获准视频所在工作区。下文手工命令中的 /ABS/video-recap-skills，指已安装 skill 仓库的绝对路径，不是系统自带目录。
一个你拥有或获准处理的本地 .mp4、.mov、.mkv 或 .webm，以及 Python 3.10+、PATH 中的 ffmpeg 和足够的中间文件空间。烧录字幕需要 ffmpeg 的 libass/subtitles filter。
远程 ASR、VLM 与默认 TTS 需要 Xiaomi MiMo API key。Fish Audio 只能替换 TTS，并需要独立 key；ASR/VLM 仍用 MiMo。这不是全离线流程，发送获准素材前应查看服务商当前的隐私、地区与计费条款。

Steps · 操作步骤

Choose the edit shape Primary route: invoke the installed video-recap skill in its configured host (for hosts exposing that slash name, /video-recap) with a natural-language brief. Use full to retain the source timeline; use cut for a shorter story rendered before narration. State audience, duration, context, subtitles and material that must survive.
Build an evidence index Understanding detects scenes, extracts frames, transcribes speech, finds quiet windows and writes timeline_fusion.json plus agent_narration_brief.md. It observes rather than invents: facts and inference remain separate. Script-first entry: python3 /ABS/video-recap-skills/skills/video-understanding/scripts/understand.py /ABS/input.mp4 --work-dir /ABS/work.
Choose an angle before writing Read the brief, contact sheet, frame facts and ASR. Decide the viewer promise, POV, dramatic question, emotional endpoint and delayed information. For a new recap, compare viable story shapes; for a directed request, honor that direction. Record the spine and change-based beats in recap_story_plan.json.
Assign picture, original sound and narration In visual_audio_board.json, give every beat a picture task, preferred reaction, in/out reason, original-audio anchor and audio owner. Strong dialogue, action sound or silence may carry a beat alone. In cut mode, create clip_plan.json first; after edited_source.mp4 exists, recheck its storyboard and write on output time.
Write source-grounded Chinese narration A narration.json block needs a job: context, causal link, foreshadowing, interpretation or transition. Do not restate visible action. Names, motives, relationships and outcomes must trace to visual evidence, ASR, reliable research or user context; never disguise background knowledge as an on-screen fact. Write complete spoken thoughts and preserve dialogue boundaries.
Review, voice and assemble Ask whether every beat changes knowledge, power, goal, relationship, emotion or risk, and whether any claim lacks support. To review before TTS, take the stage route: after video-understanding, invoke video-script, inspect its plans/narration, then run python3 /ABS/video-recap-skills/skills/video-script/scripts/validate.py --work-dir /ABS/work --mode full. Only then run voiceover.py and assemble.py from their skill directories. Cut validation uses the orchestrator’s output-timeline mode.
Resume from real artifacts The installed skill normally handles internal handoffs. For script-level cut control, start with python3 /ABS/video-recap-skills/skills/video-recap/scripts/recap.py /ABS/input.mp4 --work-dir /ABS/work --edit-mode cut --target-duration 6m. It exits after analysis for an agent/script handoff, not default human approval. After the required clip plan or narration exists, rerun that exact command; the manifest rejects mismatched source/settings. If you chose stage review, wait before rerunning. After timeline.json exists, use the draft export guide.

先选成片形态 主入口是在已配置宿主中调用安装好的 video-recap skill（宿主若暴露该 slash 名，则用 /video-recap），再提交自然语言简报。原片时间线保持完整、只在合适位置加旁白用 full；长素材要收成短故事用 cut，它先剪片，再按剪后时间轴写稿。说明受众、时长、背景、字幕和必须保留的素材。
建立视听证据索引 理解阶段检测场景、抽取代表帧、转写对白、寻找静音窗，并融合为 timeline_fusion.json 与 agent_narration_brief.md。它负责观察，不负责编故事：事实与推断分开，证据不足就保留不确定。脚本优先入口：python3 /ABS/video-recap-skills/skills/video-understanding/scripts/understand.py /ABS/input.mp4 --work-dir /ABS/work。
先定角度，再写开场 阅读 brief、contact sheet、frame facts 与 ASR，确定观众承诺、POV、戏剧问题、情绪终点和暂缓揭示的信息。首次创作比较可成立的故事结构；用户已给方向时忠实落实。把选定主线和“发生了什么变化”的 beats 写进 recap_story_plan.json。
分配画面、原声与旁白 在 visual_audio_board.json 中为每个 beat 记录画面任务、关键反应或表演、入出点理由、原声锚点和 audio_owner。强对白、动作声或沉默可以独占一拍，不必强铺旁白。cut 模式先写 clip_plan.json；edited_source.mp4 生成后，再看剪后故事板并按输出时间写稿。
写有证据的中文解说 只有一段旁白承担 context、causal_link、foreshadow、interpretation 或 transition 时才写。画面已经说清楚的事不要复述。人物名、动机、关系和结果必须来自画面、ASR、可靠背景或用户上下文，不能把背景资料伪装成当前镜头事实。每段写成可连续朗读的完整意思，并保住原声句界。
短审文案，再配音合成 复核每个 beat 是否改变认知、权力、目标、关系、情绪或风险，只听声音能否懂主线，以及有没有无依据断言。想在 TTS 前人工审阅，就走阶段入口：video-understanding 后调用 video-script，检查计划与旁白，再执行 python3 /ABS/video-recap-skills/skills/video-script/scripts/validate.py --work-dir /ABS/work --mode full；通过后才运行各 skill 目录中的 voiceover.py 与 assemble.py。cut 的输出时间轴校验由编排器选择对应模式。
从真实产物继续 通常由已安装 skill 处理内部交接。若要用脚本明确控制 cut 流程，先执行 python3 /ABS/video-recap-skills/skills/video-recap/scripts/recap.py /ABS/input.mp4 --work-dir /ABS/work --edit-mode cut --target-duration 6m。它在分析后退出，把产物交给 Agent/写稿阶段；这不表示默认流程会请求人工批准。所需 clip plan 或 narration 写好后原样重跑该命令，manifest 会拒绝不匹配的源视频或设置。若选择了阶段审阅，就先保持停止。已有 timeline.json 后再看草稿导出指南。

Example · 示例

For a host exposing this slash name (otherwise select video-recap), this is an original suggested brief—not recorded output, a benchmark or an executed provider run. Its path and timestamps are illustrative placeholders:

/video-recap
Create a six-minute Chinese recap from /ABS/interview.mov in cut mode. I may use it. Show how the guest’s launch claim changes after the failed demonstration. Follow the guest’s POV until failure, then the engineer’s reaction. Preserve the full 18:40–19:05 exchange without narration. Use visible action, transcribed speech and my context; mark uncertain identities. Build the evidence and story/audio plan before concise spoken Chinese. Burn subtitles and retain timeline.json for draft export.

若宿主把已安装 skill 暴露为这个 slash 名（否则在宿主中选择或点名 video-recap），下面是原创建议简报，不是已记录输出、基准结果或执行过的服务商调用。路径与时间戳只是示意占位，不是来自真实文件的证据：

/video-recap
把 /ABS/interview.mov 用 cut 模式做成约六分钟中文解说。我已获准使用录像。让观众看清嘉宾自信的发布承诺怎样在演示失败后变化。失败前跟随嘉宾视角，之后转向工程师反应。完整保留 18:40–19:05 原声，不铺旁白。只使用可见动作、转写对白和我的背景；身份不确定就标明。先建立证据索引与故事/声音方案，再写简洁口语。成片烧录字幕，并保留 timeline.json 以便之后导出草稿。

Expected files · 预期文件

Understanding: scenes.json, asr_result.json, vlm_analysis.json, silence_periods.json, timeline_fusion.json and agent_narration_brief.md.
Editorial: recap_story_plan.json, visual_audio_board.json, optional style_card.json, narration.json and, for cut, clip_plan.json plus edited_source.mp4.
Delivery: TTS WAV/metadata, recap_<name>.mp4, subtitles.srt/.ass and timeline.json; editable-draft export is separate.
For a concrete edit decision, see original sound versus narration: an original five-beat radio scene shows when dialogue, action sound or a pause should lead, and why audio-owner labels alone do not control the mix.

理解产物：scenes.json、asr_result.json、vlm_analysis.json、silence_periods.json、timeline_fusion.json 与 agent_narration_brief.md。
编导交接：recap_story_plan.json、visual_audio_board.json、可选 style_card.json、narration.json；cut 模式另有 clip_plan.json 与 edited_source.mp4。
交付产物：TTS WAV 分段与元数据、recap_<name>.mp4、subtitles.srt/.ass 和 timeline.json；可编辑草稿是独立的可选导出。
需要具体剪辑判断时，可读原声与旁白怎样分工：原创收音机五拍示例说明何时让对白、动作声或停顿主导，以及为什么只写声音职责标签不能直接控制混音。

Verify the result · 验证结果与边界

Before TTS, spot-check names, actions, quoted speech and causal claims against frames/ASR; read narration aloud for complete thoughts and usable pauses.
Before delivery, watch the actual final file once, listen once without looking, and inspect joins around preserved dialogue. Reports locate candidates; they do not replace playback.

配音前抽查人名、动作、引用对白和因果是否能对回画面与 ASR，并朗读一遍旁白，确认意思完整、停顿可说。
交付前以正常速度完整看一次实际成片，再只听声音一次，并检查保留原声前后的接点。自动报告只能定位候选问题，不能替代播放。