视频理解

概述

把任意视频拆成「元数据 + 关键帧 + 音频」，再产出结构化报告：概要、场景时间线、关键事件、实体、屏幕文字、语音转写、高亮片段。默认走魔搭 API-Inference 的多模态模型，也兼容任何 OpenAI 兼容端点。

依赖

Python 3.9+，仅标准库。
ffmpeg：优先用系统 ffmpeg；没有时脚本自动回退到 pip install imageio-ffmpeg。
可选 API Key（不配也能工作，见工作流 A）。

工作流 A：无 API Key（Agent 直接看图）

适合当前对话本身具备视觉能力的情况，成本最低。

抽帧与音频：

python scripts/prepare_video.py <视频路径或URL> --out workdir --max-frames 16

读取输出里的 frames 列表，用 Read 工具查看其中的 JPEG（一次 4–6 张，不要全量读）。
需要语音时，把 workdir/audio.wav 交给任意转写工具，或跳过并在报告中注明"未做语音转写"。
按下方「输出格式」直接写报告，时间点用 manifest 里的 time 字段。

工作流 B：全自动

配置端点（三选一，按需）：

# 魔搭 API-Inference（默认）
export MODELSCOPE_API_TOKEN=ms-xxxx
# 或阿里云百炼
export VIDEO_UNDERSTANDING_API_KEY=sk-xxx
export VIDEO_UNDERSTANDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export VIDEO_UNDERSTANDING_MODEL=qwen-vl-max

一条命令产出报告：

python scripts/analyze_video.py <视频路径或URL> --out workdir --max-frames 24 --asr

产物：workdir/report.md（给人看）、workdir/report.json（给程序用）、workdir/frames/（关键帧）。

参数说明：

| 参数 | 作用 | |---|---| | --max-frames | 采样帧上限，默认 24；短视频可降到 8–12 省成本 | | --scene | 用镜头切换检测代替均匀采样，适合剪辑类视频 | | --transcript | 直接传入已有字幕/转写文本，跳过 ASR | | --asr | 调用 /audio/transcriptions 转写 audio.wav，失败自动降级 | | --dry-run | 只抽帧，不调用模型 |

输出格式

报告固定包含这些段落，缺数据时写"无"而不是删段：

概要：150 字以内，先说是什么视频，再说发生了什么。
场景时间线：起始秒 - 结束秒：画面与内容，按时间递增，不重叠。
关键事件：时间 + 重要性(high/medium/low) + 事件，只保留推动叙事的。
实体：人物、物体、屏幕文字三组。
音频：是否有人声、转写全文、环境声。
高亮片段：可剪辑/可检索的区间，说明为什么值得看。
质量说明：画质、字幕可读性、信息缺失。

JSON 字段定义见 references/report-schema.md。

长视频与成本

10 分钟：先 --max-frames 12 粗看整体，再对高亮片段单独抽帧细看。
帧数不是越多越好：单次请求 4 帧，24 帧约 6 次调用。
分辨率已压到宽 768，足够识别场景与文字；需要读小字时对该时间点单独抽原图。
纯音频、无人声视频照常处理，audio.has_speech 置 false。

注意事项

先确认视频可读：路径含空格要加引号，URL 需可被 ffmpeg 直接访问。
不要一次读几十张帧图，会挤爆上下文；按批读、按需读。
报告中的时间点必须落在 0 <= t <= duration，模型偶尔越界，写报告前校验一次。
涉及人脸、车牌、证件等敏感内容，默认做概括性描述，不逐字转录。
视频含版权素材时，高亮片段只给时间区间，不给下载地址。

资源

scripts/prepare_video.py — 元数据、抽帧、音轨提取，输出 manifest.json。
scripts/analyze_video.py — ASR + 多模态观察 + 汇总，输出 report.md / report.json。
references/report-schema.md — 报告 JSON 字段与示例。
references/providers.md — 端点配置、模型选择、常见报错。