Video Deconstructor

把本地视频或视频链接转换成一份可复核的内容研究包：时间轴关键帧、语音稿、结构化解构、原创变体提示词和 HTML 报告。

它不是“输入链接就稳定搬运任意平台视频”的爬虫，也不承诺绕过平台风控。下载失败时会明确降级，已经得到的页面上下文、关键帧和提示词仍会保留。

输出什么

视频文件 / URL
  -> yt-dlp 下载（可选 Cookie）
  -> 本地浏览器 CDP 兜底（可选）
  -> FFmpeg 按完整时间轴抽帧
  -> Whisper 转写（可选）
  -> OpenAI-compatible 多模态模型
  -> report.html + report.md + prompt.md + transcript.txt + metadata.json

功能

• 本地视频与 HTTP/HTTPS 视频链接
• 按完整时长均匀抽取关键帧，并保存每帧时间戳
• summary、deconstruct、remix、xiaohongshu 四种模式
• 可选 Whisper 本地转写
• OpenAI-compatible 多模态模型接口
• yt-dlp Cookie 与浏览器 Cookie 支持
• Edge/Chrome CDP 页面媒体兜底
• Markdown、HTML、提示词、转写和元数据同时落盘
• 模型失败时保留已有中间产物，不把部分成功伪装成完整成功

安装

需要 Python 3.10+，并确保 ffmpeg 与 ffprobe 已加入 PATH。

git clone https://github.com/lantianbaicai/video-deconstructor.git
cd video-deconstructor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

需要本地语音转写时再安装较重的 Whisper/Torch 依赖：

python -m pip install -e ".[whisper]"

配置

Copy-Item .env.example .env

在 .env 中配置：

VIDEO_DECONSTRUCTOR_API_KEY=
VIDEO_DECONSTRUCTOR_MODEL=doubao-seed-2-0-pro-260215
VIDEO_DECONSTRUCTOR_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
WHISPER_MODEL_SIZE=base

.env、Cookie 和生成输出均被 Git 忽略。旧版的 VIDEO_ANALYZER_* 环境变量仍可兼容读取。

使用

分析本地视频：

video-deconstructor "E:\videos\demo.mp4" --mode deconstruct

不安装 Whisper，先验证画面链路：

video-deconstructor "E:\videos\demo.mp4" --skip-transcript --prompt-only

分析普通视频链接：

video-deconstructor "https://example.com/video.mp4" --mode summary

需要登录态的平台可以显式提供 Cookie：

video-deconstructor "https://example.com/post" --cookies cookies.txt
video-deconstructor "https://example.com/post" --cookies-from-browser edge

浏览器兜底要求本地 Edge/Chrome 以远程调试模式运行，默认端点为 http://127.0.0.1:9333。它只读取当前页面可见信息和媒体资源，不保证平台页面始终可解析。

输出目录

默认写入当前目录的 video-deconstructor-output/：

video-deconstructor-output/<video>_<timestamp>/
|-- frames/
|-- report.html
|-- report.md
|-- prompt.md
|-- transcript.txt
`-- metadata.json

URL 输入还可能包含 download/ 与 page_media.json。

项目结构

video_deconstructor/
|-- cli.py           # 下载、抽帧、转写与任务编排
|-- timeline.py      # 时间轴与安全路径
|-- prompts.py       # 四种分析模式
|-- model_client.py  # 多模态模型请求
`-- types.py         # 共享数据类型
tests/
examples/
docs/

边界

• 仅分析你有权访问和研究的内容。
• 不要高频抓取，不要把主账号 Cookie 提交到仓库。
• “页面可见价、标题或评论”不等于平台内部真实成交数据。
• 模型生成的改写方向应继续人工审核，避免照搬原视频的文案、镜头和角色资产。
• 平台页面、Cookie 和风控策略变化后，下载能力可能需要维护。

验证

python -m unittest discover -s tests -v
python -m video_deconstructor --help

当前版本是公开 Alpha，重点是让输入、降级状态和产物边界可观察，而不是宣称支持所有平台。