video-to-markdown

从视频中提取关键帧和字幕文本，将二者一并发送至 Claude Vision 模型进行分析，最终生成结构化的 Markdown 文档，完整记录视频所传授的所有内容——包括屏幕上呈现但未通过语音充分解释的信息。

快速参考

python scripts/video_analyzer.py "" [--output DIR] [--max-frames N] [--cookies FILE] [--whisper]

输出：在指定输出目录中生成一个 .md 文件。

分步操作指南

1. 获取视频 URL

向用户确认目标视频的 URL。支持平台：YouTube、Facebook、Instagram（以及 yt-dlp 支持的绝大多数其他网站）。

2. 检查依赖项

运行预检命令：

ffmpeg -version && yt-dlp --version && python3 -c "import anthropic, PIL; print('deps OK')"

若任一命令失败，请执行：

bash scripts/setup.sh

同时确认环境变量 ANTHROPIC_API_KEY 已正确设置：

echo $ANTHROPIC_API_KEY

如未设置，请执行：

export ANTHROPIC_API_KEY=your_key_here

3. 运行分析器

标准模式（YouTube，含可用字幕）：

python scripts/video_analyzer.py "" --output ./output

交易类 / 图表密集型内容（提取更多关键帧，启用 Whisper 提升转录精度）：

python scripts/video_analyzer.py "" --max-frames 80 --whisper --output ./output

出镜讲解 / 讲座类内容（关键帧数量较少，字幕已足够）：

python scripts/video_analyzer.py "" --max-frames 20 --output ./output

Facebook 或 Instagram（需提供 cookies 文件）：

python scripts/video_analyzer.py "" --cookies /path/to/cookies.txt --output ./output

最高质量模式（使用 Opus 模型 + 大型 Whisper 模型 + 更多关键帧）：

python scripts/video_analyzer.py "" 
  --model claude-opus-4-20250514 
  --whisper --whisper-model large-v3 
  --max-frames 80 
  --output ./output

4. 查看并呈现输出结果

脚本执行完毕后，最后一行将打印输出文件的完整路径。请读取该文件，并将内容呈现给用户：

cat ./output/.md

参数说明

费用估算（基于 claude-sonnet-4-20250514）

若对分析质量要求不高，可使用 --model claude-haiku-4-5-20251001 以降低约 5 倍成本。

平台特异性说明

关于 Facebook 和 Instagram 的 cookie 配置详情，请参阅 references/platforms.md。

简要总结如下：

• YouTube：在住宅 IP 上无需身份认证即可运行；在云服务器 IP 上通常需要 cookies
• Instagram：必须提供 cookies；即使 cookies 有效，行为仍可能不稳定
• Facebook：必须提供 cookies 且 启用浏览器伪装（由脚本自动处理）

Cookie 来源：仅支持 Firefox（Chrome 自 v127 起已对 cookies 加密）。请在与运行脚本相同的网络出口 IP 上，使用已登录的 Firefox 会话导出 cookies。

输出格式

每次运行均生成一个 .md 文件，内容结构如下：

YAML 前置元数据（frontmatter）：

• 原始 URL、所属平台、视频标题
• 分析时间戳、实际分析的关键帧数量、字幕来源、所用模型

正文主体：

• 概述
• 视觉内容摘要
• 章节分解（按主题分别列出“语音提及”与“画面呈现”的内容）
• 关键视觉元素解析
• 核心要点总结
• 术语与概念说明
• 视觉–叙述差异（Visual–Narration Gaps）← 此节是本工具的核心价值所在

故障排查

“未提取到任何关键帧” → 检查 ffmpeg 是否已安装，并确认视频是否成功下载至临时目录。建议先尝试对一段简短的公开 YouTube 视频运行 --max-frames 10 进行验证。

“未找到字幕”（且未启用 Whisper） → 对于本身无字幕的视频属正常现象。可安装 faster-whisper 并添加 --whisper 参数；若不启用，则分析将仅基于关键帧继续执行。

Facebook 报错 “Cannot parse data” → 可能因 cookies 过期或来自不同 IP。请立即在相同网络环境下，使用 Firefox 重新导出 cookies。

Instagram 使用 cookies 后仍失败 → 行为具有间歇性。建议等待几分钟后重试；若持续失败，可尝试更换账号。

输出内容过短 / 缺失视觉信息 → 增加 --max-frames 值，或升级至 --model claude-opus-4-20250514 模型。

费用过高 → 将 --max-frames 降至 20–30。出镜讲解类内容通常不超过 20 帧即已足够。