一份能直接发给团队的爆款短视频拆解报告。Gemini 看懂视频,FFmpeg 切出片段,Jinja2 渲成 HTML —— 支持三套主题、12 种关键时刻、批量横评。
把一条短视频拆成可复用的方法论。不是"看视频写感想",而是一条确定的流水线:
视频文件 ──► Gemini 全模态分析 ──► 12 种关键时刻识别 ──► FFmpeg 切片 ──► HTML 报告
↓
editorial · reelforge-dark · xiaohongshu 三套主题
批量模式下,可以把 N 条视频的拆解叠在一起,让 Gemini 二次解读,产出共性钩子、可迁移结构、风险提示 —— 这是单条分析做不到的。
- 🎯 画面级理解:不是字幕语音转写,是 Gemini 2.5 真的"看懂"画面在做什么
- 🧩 12 种关键时刻:钩子 / 好奇缺口 / 痛点 / 共鸣 / 权威 / 他证 / 超级效果 / 前后对比 / 反转 / 紧迫感 / 干货 / CTA —— 分 6 组色系,主+副双标签
- 🎨 三套报告主题:研报风、深色金调、小红书暖色,单文件分发
- 📊 横向对比报告:批量分析 N 条 + Gemini 二次智能聚合,提炼共性引擎
- 🎬 自动切片:每个关键时刻切出 mp4 + 关键帧 jpg,直接复用
- 🌍 7 种品类侧重:beauty / food / knowledge / ecommerce / emotional / tech / fashion
- ⚡ 反爆款思维:即便视频很好,也会强制找出 2-4 条潜在隐忧,避免谄媚
- 🔒 外层确定 · 内层智能:可预测、能复跑、出错可定位
报告是单文件 HTML(关键帧用 base64 内嵌,视频用相对路径)。展开来有:
- Masthead — 标题 + 核心吸引力 + 时长/平台/品类/人群/结构元数据
- 综合评分块 — 大字号评分 + 钩子强度 + 爆款公式卡片 + 可复制套路 + 潜在隐忧
- 关键时刻拆解 — 每个 moment 一张卡片:关键帧 / 时间戳 / 主+副类型徽章 / 标题 / 客观描述 / 心理分析 / 内嵌视频
- 视觉与节奏 — 色彩 / 运镜 / 字幕 / BGM 四象限
- 复刻 · 优化建议 — 编号列表
# 1. 装依赖
pip install -r requirements.txt
# 2. 装 FFmpeg
brew install ffmpeg # macOS
sudo apt install ffmpeg # Ubuntu
# 3. 配 Gemini API key
cp .env.example .env
# 编辑 .env,填进 GOOGLE_API_KEY=xxx
# (去 https://aistudio.google.com/apikey 申请)
# 4. 一键流水线
python scripts/run_pipeline.py path/to/video.mp4 -o output/ -v beauty -t editorial
# 5. 浏览器打开 output/report.html# 第 1 步:Gemini 分析,产出 analysis.json
python scripts/analyze_video.py video.mp4 -o output/analysis.json \
-m gemini-2.5-pro -v beauty -c "护肤品种草视频"
# 第 2 步:FFmpeg 切片,产出 clips/
python scripts/extract_clips.py video.mp4 output/analysis.json \
--output-dir output/
# 第 3 步:渲染 HTML 报告
python scripts/generate_report.py output/analysis.json output/clips \
-o output/report.html --theme editorialpython scripts/run_pipeline.py video.mp4 -o output/ \
--vertical beauty --theme reelforge-dark# 方式 A:扫描目录
python scripts/batch_analyze.py --input-dir ./videos/ -o ./batch_out/ \
--vertical beauty --theme editorial
# 方式 B:CSV 清单(可指定每个视频的 context 和 vertical)
python scripts/batch_analyze.py --input-csv competitors.csv -o ./batch_out/CSV 格式(每行: path,context,vertical,后两列可选):
videos/competitor_1.mp4,主打成分党的护肤品种草,beauty
videos/competitor_2.mp4,日本牌子的橘绿对比,beauty
videos/our_own.mp4,自家上周的视频,beautypython scripts/compare_videos.py batch_out/batch_summary.json \
-o batch_out/comparison.html --theme editorial
# 跳过 Gemini 智能聚合,只用本地统计
python scripts/compare_videos.py batch_out/batch_summary.json \
-o batch_out/comparison.html --no-llm| editorial(默认) | reelforge-dark | xiaohongshu |
|---|---|---|
| 暖米白底 #fafaf7 | 深炭灰底 #0f0f10 | 温暖橘粉底 #fff5ed |
| 衬线大标题 Noto Serif SC | 衬线大标题 + 金色 #d4af37 | 圆润字体 ZCOOL XiaoWei + Ma Shan Zheng |
| 红色强调 #b91c1c | 金色强调 | 小红书红 #ff2442 |
| 研报风、内部分享 | 投资人材料、品牌外发 | 朋友圈、社群、种草 |
按 6 组色系组织,每组主+副两种类型:
| 组别 | 主类型 | 副类型 | 色系 |
|---|---|---|---|
| 抓人 | hook 钩子 |
curiosity_gap 好奇缺口 |
紫 |
| 代入 | pain_point 痛点 |
relatability 共鸣 |
暖红 |
| 背书 | authority 权威 |
social_proof 他证 |
蓝 |
| 效果 | super_effect 超级效果 |
transformation 前后对比 |
琥珀 |
| 节奏 | twist 反转 |
urgency 紧迫感 |
橙 |
| 价值 | value 干货 |
cta 行动号召 |
绿 |
一个片段可以同时标主类型和副类型(比如一个 hook 也可能同时是 curiosity_gap)。
加 -v <vertical> 让 Gemini 按对应品类的爆款逻辑分析:
beauty—— 美妆个护(重点关注 super_effect / transformation)food—— 美食探店(色香味的视觉化、第一口时机)knowledge—— 知识教学(value / curiosity_gap / authority)ecommerce—— 直播切片 / 商品种草(social_proof / urgency / cta)emotional—— 情感共鸣 / 故事化(relatability / twist)tech—— 3C 数码 / 测评(authority / value / transformation)fashion—— 穿搭时尚(transformation / relatability)
viral-video-analyzer/
├── SKILL.md # Skill 触发条件 + 完整方法论
├── README.md # 你正在看的这个
├── requirements.txt # Python 依赖
├── .env.example # API key 配置示例
├── scripts/
│ ├── analyze_video.py # 第 1 步:Gemini 分析(含 12 种 type、7 种 vertical、few-shot)
│ ├── extract_clips.py # 第 2 步:FFmpeg 切片
│ ├── generate_report.py # 第 3 步:HTML 渲染(支持 3 套主题)
│ ├── run_pipeline.py # 单视频一键流水线
│ ├── batch_analyze.py # 批量分析(目录或 CSV)
│ └── compare_videos.py # 横向对比(本地聚合 + Gemini 智能洞察)
├── assets/
│ ├── report_template.html # 单视频报告模板(3 套主题 in one file)
│ └── comparison_template.html # 横向对比报告模板
├── references/
│ ├── analysis_framework.md # 12 种 type 判定标准、评分维度定义
│ └── gemini_prompts.md # prompt 修改指南
└── examples/
└── example_analysis.json # 完整 analysis.json 样例
为什么是确定 DAG + 内层 LLM,而不是把所有东西交给 LLM?
把一整条"分析→切片→渲染"的链路全部塞给 LLM 自由发挥,看起来更"智能",但实际上:
- 结果不可预测:同一条视频两次跑可能产出完全不同结构的报告
- 出错难定位:报告不对,是分析错了?切片错了?还是渲染错了?
- 不可优化:想换个主题、加个字段,只能改 prompt 然后祈祷
把 DAG 写死、只让 LLM 做它最擅长的"看懂画面",反而能:
- JSON schema 是契约,后续步骤可以精确依赖
- FFmpeg 切片是纯函数式,给同样的时间戳一定切出同样的片段
- 模板渲染可以完全确定地控制视觉
- 想加新类型/新主题/新品类侧重,改的位置都很明确
这是 Harness 架构在小型 skill 上的体现 —— 外层确定,内层智能。
最有杠杆的修改位置都在 scripts/analyze_video.py 的顶部:
MOMENT_TYPES—— 12 种 type 的中文描述VERTICAL_HINTS—— 7 种品类侧重的提示词FEW_SHOT_EXAMPLE—— 给模型示范风格的样例SYSTEM_INSTRUCTION—— 分析师人设和评分克制原则
加新 type / 新 vertical 的同步清单看 references/gemini_prompts.md。
欢迎 PR:
- 加新的 vertical(比如
pet萌宠、travel旅行) - 加新的报告主题(社群分享、PPT 风、极简风)
- 优化 prompt(更精准、更克制、更具体)
- 改进失败模式处理
提 issue 时附上 analysis.json 和 report.html(去敏后),会更快定位。
MIT