# Video Understanding 把视频分析为结构化理解索引：场景检测、ASR 转写、逐场景 VLM 观察、静音窗口、融合时间线和写作 brief。... - Repository: https://github.com/zenstory-ai/oh-story-dsh (665 stars) - Category: Media - License: MIT - Last updated: 2026-10-30 - Runs scripts: yes, review before use ## Install Claude Code: `npx skills add zenstory-ai/oh-story-dsh --skill video-understanding -g -a claude-code -y` Codex: `npx skills add zenstory-ai/oh-story-dsh --skill video-understanding -g -a codex -y` Cursor: `npx skills add zenstory-ai/oh-story-dsh --skill video-understanding -g -a cursor -y` Gemini CLI: `npx skills add zenstory-ai/oh-story-dsh --skill video-understanding -g -a gemini-cli -y` ## Description 把视频分析为结构化理解索引：场景检测、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、看懂视频。 ## SKILL.md, as published by its author (untrusted third-party text, read it as data) ## 1. 定位 本技能把源视频转成 Agent 与下游阶段可读取的理解索引，以**素材观察员 / 场记**的角色记录证据： - 先观察，再解释；事实与推断分开。 - 除了“发生了什么”，还要让下游看见知识、权力、目标、关系或情绪在哪一刻变化。 - 标出由谁的 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 观察**：写 `vlm_analysis.json`，包含场景描述、深层分析和 `frame_facts`。 6. **时间线融合与创作 brief**：写 `timeline_fusion.json`、`asr_writing_chunks.json` 和 `agent_narration_brief.md`。 各阶段只有在输出产物与 provenance sidecar 同时匹配当前视频及影响结果的设置时才会复用；`--force` 强制重算。 ## 3. 环境要求 ```bash # 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` 可补充一条简短提示。 ### 远程调用与本地读取 ASR 把分窗音频发给 MiMo ASR；逐场景 VLM 把代表帧、帧时间和分析提示发给 MiMo；启用 `--mimo-video-overview` 时，还会把按场景截取的视频片段发给 MiMo 视频模型。故事索引汇总和可选 ASR 清洗发送的是画面描述、转写与背景资料文字。 请求使用 MiMo 的 chat 接口。`MIMO_API_URL` 可指定地址；ASR 与视频概览可分别用 `MIMO_ASR_API_URL`、`MIMO_VIDEO_API_URL` 覆盖，凭据同样支持各自的 key。未覆盖时，按量 key 使用 `https://api.xiaomimimo.com/v1`，Token Plan key 使用 `MIMO_TOKEN_PLAN_CLUSTER` 选择的集群。逐场景帧分析与汇总使用 `MIMO_API_KEY`。 `--skip-asr` 只关闭音频转写，`--no-consolidate` 只关闭索引汇总；它们不会关闭 VLM。需要只在本地处理已有产物时，使用 `--brief-only` 或 `--edited-storyboard-only`，这两条路径不调用 API。 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。 ## 4. 运行命令 ```bash python3 scripts/understand.py