video-understanding

1. 役割

このスキルは、ソース動画をエージェントと後続工程が読み取れる理解インデックスに変換し、素材観察者／記録係の役割で証拠を記録します。

• まず観察し、その後に解釈します。事実と推論を分けます。
• 「何が起きたか」だけでなく、知識、権力、目標、関係、感情がどの瞬間に変化するのかを後続工程に伝えます。
• 変化を誰の POV が担うのか、どの反応や演技が代替不可能なのか、完全な台詞や動作を自然にカットできる箇所はどこかを示します。
• 証拠が不十分な場合は不確実性を保ち、ドラマチックな結論を作り出しません。

2. 処理段階

1. シーン検出：scenes.json を作成し、カット点、長さ、不要部分の除外結果を含めます。
2. フレーム抽出：視覚分析用に代表フレームを抽出します。
3. ASR：mimo-v2.5-asr を通じて粗い分割の台詞 asr_result.json を作成し、利用可否、限定的な時間精度、テキスト修正の出所を説明する asr_timing_evidence.json も作成します。
4. 無音検出：silence_periods.json を作成し、静かな区間と has_speech を記録します。
5. VLM 観察：シーンの説明、詳細な分析、frame_facts を含む vlm_analysis.json を作成します。
6. タイムライン統合とクリエイティブブリーフ：timeline_fusion.json、asr_writing_chunks.json、agent_narration_brief.md を作成します。

各段階では、出力成果物と provenance sidecar の両方が現在の動画および結果に影響する設定と一致する場合にのみ再利用します。--force を指定すると強制的に再計算します。

3. 環境要件

# 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 で台詞の文字起こしを省略できますが、動画を完全に理解するには VLM の実行に MIMO_API_KEY が必要です。--mimo-video-overview を有効にすると、シーンごとの動画概要を生成できます。キーが設定されていない場合、再実行時にはキャッシュ済みの文字起こし、画面分析、概要、ストーリーインデックスが再利用されます（キーによって決まるデフォルトの endpoint は比較対象に含まれません）。モデルへのリクエストが必要な統合処理は skipped_no_key として記録され、リクエストは送信されません。キャッシュが一致せず（たとえば、work_dir のコピー時にファイルの更新時刻が保持されなかった場合）、既存の文字起こしがあるときは、実行を停止して文字起こしを保持します。更新時刻を保持してコピーし直すには cp -p／cp -Rp／rsync -t を使用するか、キーを設定して再実行してください（文字起こしが再実行されます）。回避策として --skip-asr を使用しないでください。既存の文字起こしが [] に置き換わります。

work_dir/background_research.json が存在する場合、このスキルはあらすじと登場人物名を VLM のコンテキストに含めます。--context で短いヒントを追加できます。

リモート呼び出しとローカル読み取り

ASR は分割した音声を MiMo ASR に送信します。シーンごとの VLM は代表フレーム、フレームの時刻、分析プロンプトを MiMo に送信します。--mimo-video-overview を有効にすると、シーンごとに切り出した動画クリップも MiMo 動画モデルに送信します。ストーリーインデックスの統合と任意の ASR クリーニングで送信するのは、画面の説明、文字起こし、背景資料のテキストです。

リクエストには MiMo の chat インターフェースを使用します。MIMO_API_URL でアドレスを指定できます。ASR と動画概要は、それぞれ MIMO_ASR_API_URL、MIMO_VIDEO_API_URL で上書きでき、認証情報もそれぞれのキーに対応しています。上書きしない場合、従量課金キーでは https://api.xiaomimimo.com/v1 を使用し、Token Plan キーでは MIMO_TOKEN_PLAN_CLUSTER で選択したクラスターを使用します。シーンごとのフレーム分析と統合には MIMO_API_KEY を使用します。

--skip-asr は音声の文字起こしのみを無効にし、--no-consolidate はインデックスの統合のみを無効にします。どちらも VLM は無効にしません。既存の成果物だけをローカルで処理するには、--brief-only または --edited-storyboard-only を使用してください。これらの経路では API を呼び出しません。

以下の scripts/... はすべて、このスキルのディレクトリを基準とします。実行環境をリポジトリのルートディレクトリから起動する場合は、スクリプトのパスにこのスキルの絶対パスを付けてください。

4. 実行コマンド

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 の先頭にストーリーボードの案内を追加します。複数ソースのプラン（sources を含む）では、各ソースの source_work_dir にある frames/ から、その frames_manifest.json の fps に従ってフレームを抽出し、タイルに S1／S2…とラベルを付けます。フレーム抽出や API 呼び出しは行いません。ストーリーボードの生成に失敗した場合は、ログにのみ記録します。--brief-only とは併用できません
--consolidate / --no-consolidate	オン	グローバルストーリーインデックス understanding_index.* を生成します
--consolidate-asr	オフ	ASR テキストもクリーニングし、asr_clean.json に書き込みます

5. 输出契约

默认运行写出下表产物；各阶段产物旁的 *.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。

6. 参考资料

• 背景调研：references/research-guide.md，产出 background_research.json。
• JSON 结构：references/data-schema.md。

7. 能力边界

• 不写解说词，也不做解说评分；只负责生成理解索引与创作简报。
• 不编造信号无法支持的剧情；当 ASR / VLM 过薄时输出素材警告。
• MiMo ASR 的 start/end 是固定分片形成的粗窗口，不是词级对齐；空文本只表示原因未知， 不能当作已证实静音。asr_timing_evidence.json 的状态字段见 references/data-schema.md。