视频分析器
三阶段视频分析流水线：并行视觉+音频观察，然后为Bilibili发布合成元数据。
何时使用
用户说“分析这个视频”、“视频分析”、“提取视频信息”、“生成投稿元数据”
用户希望从视频文件中获取结构化内容分析
用户希望为Bilibili发布视频（标题、简介、标签、类别、封面）准备视频
Bilibili发布Playwright的上游：此技能生成的元数据用于Bilibili发布
架构
输入视频 ──────────────────────────────────────────────────────
│
│ ├── 第一阶段a：visual.py ──→ observations_visual.json
│ │ （ffmpeg提取帧 → 编码 → 视觉LLM观察）
│ 并行
│ │ ├── 第一阶段b：transcribe.py ──→ observations_audio.json
│ │ （ffmpeg提取音频 → 转录 + 结构）
│ │ │
│ │ └── 第二阶段：analyze.py ──→ metadata.json ←───────────────────┘
│ │ （合并V+A观察 → 通过LLM发布元数据）
run.sh协调：启动visual.py和transcribe.py作为后台进程（&），等待两个进程完成，然后可选地运行analyze.py。
输出目录
$OUTPUT/
├── observations_visual.json # JSON数组：每帧一个对象
├── observations_audio.json # JSON对象：转录 + 结构化信息
├── metadata.json # （可选）合成的Bilibili元数据
└── frames/ # （仅在--keep-frames时，否则自动清理）
过程
bash scripts/run.sh \
--video VIDEO_PATH --output /tmp/va-out \
--transcribe audio-llm \
--audio-llm-key KEY --audio-llm-base URL --audio-llm-model MODEL \
--vision-llm-key KEY --vision-llm-base URL --vision-llm-model MODEL \
--max-frames 15 \
--synthesize-method api \
--analyze-llm-key KEY --analyze-llm-base URL --analyze-llm-model MODEL
- 代理直接模式（无外部API — 代理直接读取帧/音频）
bash scripts/run.sh \
--video VIDEO_PATH --output /tmp/va-out --keep-frames
代理然后读取observations_visual.json（占位符帧），observations_audio.json（音频文件路径），并可选地直接读取帧图像 + 音频文件以生成元数据。
省略--synthesize-method以仅观察，然后稍后单独运行analyze.py。
每个阶段（视觉、音频、合成）可以使用不同的密钥和模型。
关键参数
参数 默认值 目的
--video PATH — 必需。输入视频文件
--output DIR — 必需。输出目录
--transcribe MODE 代理直接 本地/云/代理直接/音频LLM
--max-frames N 15 每4分钟段的最大帧数
--keep-frames false 保留提取的帧图像
--synthesize-method 方法 — API/代理/手动。省略 = 仅观察
所有
-key、-base、*-model参数遵循以下模式：--vision-llm-key、--audio-llm-key、--analyze-llm-key等。
请参阅references/REFERENCE.md以获取完整的参数表。
脚本 文件 角色
scripts/common.py 共享实用程序：HTTP重试带退避、通过ffprobe的媒体持续时间、从LLM输出解析JSON
scripts/visual.py 帧提取（自动分段、自动压缩>200KB）+ 视觉LLM观察。长视频：分段并行处理（最多4个并发）
scripts/transcribe.py 音频提取 + 转录（4种模式）。自动分块大音频带2s重叠以去重
scripts/analyze.py 观察 → 发布元数据（3种方法：API/代理/手动）。API失败的启发式回退
scripts/run.sh 协调器：并行视觉+音频，然后可选合成
输出摘要
observations_visual.json — JSON数组，每帧一个对象，包含帧、对象、描述、文本、操作、样式、封面候选、段、段开始。
observations_audio.json — 转录、发言者、关键点、语气。代理直接模式包括音频文件路径。
metadata.json — 标题（≤80个字符）、简介（≤2000个字符）、标签（≤10）、类别、子类别、封面建议（主要+原因+次要）、声明、版权声明。
陷阱
API密钥在聊天中：一些平台会截断带有...的密钥。始终通过命令行参数传递密钥，而不是通过消息。
模型能力：视觉需要image_url支持。音频LLM需要input_audio支持。检查您的提供商。
游戏录制：帧很大（~300-380KB vs ~30-80KB用于手机）。自动压缩处理此问题，但请为长视频规划速率限制。
长视频 = 并行API调用：30分钟视频 = 8段 × 15帧 = 8次视觉API调用（最多4个并发）。请考虑速率限制。
缺失凭证自动降级：省略LLM密钥 → 预处理或代理直接模式。脚本永远不会在缺失密钥时崩溃。
--interval已弃用：忽略。间隔自动根据--max-frames计算每个段。
错误处理
三层防御：HTTP重试 — 3次重试带指数退避
by