把视频分析为结构化理解索引：场景检测、ASR 转写、逐场景 VLM 观察、静音窗口、融合时间线和写作 brief。用于理解、索引或总结视频，也作为后续创作前的分析阶段。
输入视频文件；输出 scenes.json、 asr_result.json、vlm_analysis.json、silence_periods.json、timeline_fusion.json、agent_narration_brief.md。
触发词：视频理解、视频分析、视频索引、video understanding、analyze video、看懂视频。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
本技能把源视频转成 Agent 与下游阶段可读取的理解索引。它的创作角色是素材观察员 / 场记，不是导演：
scenes.json，包含切点、时长和废片段过滤结果。mimo-v2.5-asr 写粗分段对白 asr_result.json，并写
asr_timing_evidence.json 说明可用性、有限时间精度与文本修正来源。silence_periods.json，标注安静窗口与 has_speech。vlm_analysis.json，包含场景描述、深层分析和 frame_facts。timeline_fusion.json、asr_writing_chunks.json 和 agent_narration_brief.md。各阶段只有在输出产物与 provenance sidecar 同时匹配当前视频及影响结果的设置时才会复用；--force 强制重算。
# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***
ASR 使用 mimo-v2.5-asr；VLM 使用 mimo-v2.5。--skip-asr 可跳过对白转写，但完整理解仍需要 MIMO_API_KEY 运行 VLM。--mimo-video-overview 可开启按场景块的视频概览。未设置 key 时重跑会复用已缓存的转写、画面分析、概览与故事索引（key 决定的默认 endpoint 不参与比对）；需要请求模型的 consolidation 记为 skipped_no_key，不发请求。缓存对不上（例如复制 work_dir 时没保留文件时间）而已有转写时，运行停下并保留转写：用 cp -p / cp -Rp / rsync -t 保留时间重新复制，或设置 key 后重跑（会重新转写）。不要用 --skip-asr 绕过，它会把现有转写替换成 []。
若 work_dir/background_research.json 存在，本技能会把剧情梗概和角色名折入 VLM 上下文；--context 可补充一条简短提示。
下面的 scripts/... 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
python3 scripts/understand.py <video> --work-dir <work_dir> [选项]
| 选项 | 默认 | 作用 |
|---|---|---|
<video> | 必填 | 源视频 |
--work-dir | 必填 | 产物目录；不存在时创建 |
--context "..." | 空 | 补充给 VLM 的简短上下文（节目名、角色名），与 background_research.json 合并 |
--scene-threshold | 0.1 | 场景检测阈值 |
--style | 纪录片 | 写进创作简报的解说风格 |
--edit-mode full|cut | 不设 | 写进简报的 recap 模式；cut 时按剪后时长估算旁白预算，已有 edited_source.mp4 时句末锚点改用剪后时间 |
--target-duration | 不设 | 写进简报的 cut 目标时长；尚无 clip_plan_validated.json 时用它估算旁白预算 |
--skip-asr | 关 | 不转写对白，把 asr_result.json 写成 []（已有转写会被覆盖），ASR 证据标为显式跳过 |
--mimo-video-overview | 关 | 按场景块运行 MiMo 视频概览，并作为逐场景主描述 |
--force | 关 | 忽略缓存，全部重算 |
--brief-only | 关 | 只用现有产物重建 agent_narration_brief.md，不抽帧、不调 API |
--edited-storyboard-only | 关 | 只按 clip_plan_validated.json 写剪后时间线 storyboard/edited_storyboard.*，并在已有的 agent_narration_brief.md 顶部加 storyboard 指引；多源计划（带 sources）从各来源 source_work_dir 的 frames/ 按其 frames_manifest.json 的 fps 取帧，tile 标 S1/S2…；不抽帧、不调 API，故事板生成失败只记日志。与 --brief-only 互斥 |
--consolidate / --no-consolidate | 开 | 生成全局故事索引 understanding_index.* |
--consolidate-asr | 关 | 另外清洗 ASR 文本，写 asr_clean.json |
默认运行写出下表产物；各阶段产物旁的 *.meta.json 是缓存 provenance sidecar。
| 文件 | 内容 |
|---|---|
frames/frame_*.jpg、frames_manifest.json | 按 fps 抽出的帧及其清单 |
scenes.json | 场景切点、起止时间与时长 |
audio.wav | 16 kHz 单声道音频，供 ASR、静音检测与句末锚点使用 |
asr_result.json | [{start, end, text}] 时间戳对白 |
asr_timing_evidence.json | ASR 可用性状态、粗窗口精度、glossary 前后文本，以及它所描述的源视频/音频/结果文件（路径存在性 + size/mtime） |
silence_periods.json | [{start, end, duration, has_speech}] 安静窗口 |
speech_boundary_anchors.json | ASR 句末标点对齐到短停顿的句末锚点；缺音频或 ASR 时 status: unavailable |
vlm_analysis.json | 逐场景描述、深层分析与 frame_facts |
mimo_video_overview.status.json | 视频概览状态（未启用时为 disabled）；启用成功另写 mimo_video_overview.json |
understanding_index.json、understanding_index.md | 全局故事索引（--no-consolidate 时不写） |
consolidation.status.json | 故事索引与 ASR 清洗的运行状态 |
storyboard/source_storyboard.{json,jpg} | 原片时间线联系表（超页时续写 _001.jpg 等）；已有 clip_plan_validated.json 时另写 edited_storyboard.*；STORYBOARD=0 关闭 |
timeline_fusion.json | VLM、ASR 与静音信息的统一时间线 |
asr_writing_chunks.json | 按句界和场景切分的 ASR 写作块 |
agent_narration_brief.md | Agent 首先阅读的创作简报 |
后续写作阶段根据创作简报与索引制定方案并写 narration.json。
references/research-guide.md，产出 background_research.json。references/data-schema.md。start/end 是固定分片形成的粗窗口，不是词级对齐；空文本只表示原因未知，
不能当作已证实静音。asr_timing_evidence.json 的状态字段见 references/data-schema.md。まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录， 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置； 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。
日本語の概要は準備中です。原文の説明を表示しています。
把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频， 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。支持单视频与多视频（sources manifest）拼剪， 本工具不读取、不映射旁白。 触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
日本語の概要は準備中です。原文の説明を表示しています。
从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 → Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、 视频 recap、video recap、voiceover、narration、auto-dub、recap。
日本語の概要は準備中です。原文の説明を表示しています。
按需把一部成片拆成可复用的制作参考：测镜头节奏与响度，标注段落与音轨分工，把原片事实与可迁移方法分开， 导出不含原片人名台词的 production_reference.json 供下次制作参考。不在默认生产路径上。 触发词：拆片、拆解成片、制作参考、参考模板、production reference。
日本語の概要は準備中です。原文の説明を表示しています。
对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验；也处理已有短片的 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的 agent_narration_brief.md 与 vlm_analysis.json；文案返修输入当前成片的工程与内容证据。策划输出 recap_story_plan.json、visual_audio_board.json、 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json；仅宣发文案任务交付提案或回填既有包装计划。 外发说明：只有建议型评审 review.py 联网，它把旁白稿全文与理解证据、策划文件的文字摘录发到 MiMo chat 接口 （MIMO_API_KEY / MIMO_API_URL，不发视频、图片或音频）；单独使用时只在显式执行时运行，端到端编排默认在 TTS 前运行一次， 可用 --no-review-narration / REVIEW_NARRATION=0 关闭（严格评审开启时除外）；validate.py 与 lint 仅在本地运行。 触发词：解说词、写解说、视频旁白、宣发标题、花字修订、文案回填、 narration script、写稿、解说文案、剪辑思路、导演思路。
日本語の概要は準備中です。原文の説明を表示しています。
把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或 Fish Audio（s2.1-pro-free）或显式配置的通用 IndexTTS HTTP 服务逐段生成语音， 按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。 外发说明：每段旁白文字会发给所选 TTS 服务（MiMo / Fish Audio / 用户自托管的 IndexTTS），--voice-ref 的参考音频会发给 MiMo。 另含实验性的英译中 dub 路径：只在显式选择 dub 模式并传 --confirm-voice-rights 时运行，会把源视频音频发到 MiMo ASR， 并以原说话人的声音为参考经 MiMo voiceclone 克隆配音；只可用于用户有权使用、且说话人同意被克隆声音的内容。 触发词：配音、语音合成、TTS、解说配音、 voiceover、text to speech、旁白配音。
日本語の概要は準備中です。原文の説明を表示しています。