🎬 Video Expert Analyzer

🌐 Language / 语言
English | 中文

🎬 Video Expert Analyzer

AI-powered professional video analysis tool based on Walter Murch's Six Rules of Editing, with real multimodal AI vision scoring (Gemini 3.0 / Kimi 2.5 / Claude).

✨ Features

🤖 Real AI Vision Scoring — Multimodal models (Gemini/Kimi/GPT-4o) analyze actual frame content
🔀 Dual Scoring Paths — Agent mode (IDE AI reads frames) + API mode (remote API calls)
🎯 Dynamic Weighting — Weights auto-adjust based on scene type (Hook/Narrative/Aesthetic/Commercial)
🎬 Scene Detection — PySceneDetect detect-content for accurate scene splitting
🎤 Smart Subtitle Extraction — 4-tier fallback: Bilibili API → Embedded → RapidOCR → FunASR
⭐ Best Shots — Auto-copy top-rated clips to best_shots/
📊 5D Scoring — Aesthetic, Credibility, Impact, Memorability, Fun/Interest
🌐 Bilingual — All terminology with Chinese translations

📱 Supported Platforms

Platform	Status	Notes
Bilibili	✅ Full Support	yt-dlp download + Bilibili API subtitles
YouTube	✅ Full Support	yt-dlp download
Douyin (抖音)	✅ Full Support	Dedicated downloader (public/share links do not need browser cookies)
Xiaohongshu (小红书)	✅ Full Support	Dedicated downloader
Others	⚠️ May Work	Depends on yt-dlp support

🤖 Model Compatibility

Model	Agent Mode	API Mode	Notes
Gemini 3.0 Flash	✅ Recommended	✅ Recommended	Fast, strong vision
Gemini 3.0 Pro	✅ Recommended	✅ Supported	Best visual understanding
Kimi 2.5	✅ Supported	✅ Supported	Excellent for Chinese
Claude (Sonnet/Opus)	✅ Supported	❌ No	Has vision but no OpenAI-compatible API
Text-only models	❌ No	❌ No	Cannot score without vision

Agent Mode = AI assistant in IDE views frame images directly
API Mode = CLI calls vision model via OpenAI-compatible API

🚀 Quick Start

Prerequisites

# System dependencies
brew install ffmpeg  # macOS

# Install all Python dependencies
pip3 install -r requirements.txt

# Check environment
python3 scripts/check_environment.py

One-Command Analysis

# Setup (first time only)
python3 scripts/pipeline_enhanced.py --setup

# Analyze any video
python3 scripts/pipeline_enhanced.py https://www.bilibili.com/video/BV1xxxxx
python3 scripts/pipeline_enhanced.py "https://www.douyin.com/video/xxxxx"

# AI scoring (choose one)
# Option A: Agent mode (in IDE, AI assistant scores visually)
# Option B: API mode
export VIDEO_ANALYZER_API_KEY="your-key"
python3 scripts/ai_analyzer.py scene_scores.json --mode api

📊 Scoring System

Five Dimensions

Dimension	Weight	Description
Aesthetic Beauty 美感	20%	Composition, lighting, color harmony
Credibility 可信度	20%	Authenticity, natural performance
Impact 冲击力	20%	Visual saliency, attention-grabbing
Memorability 记忆度	20%	Uniqueness, Von Restorff Effect
Fun/Interest 趣味度	20%	Engagement, entertainment, social currency

Scene Types & Dynamic Weights

Type	Primary Weights	Use Cases
TYPE-A Hook	Impact 40% + Memorability 30%	Opening hooks, high-energy moments
TYPE-B Narrative	Credibility 40% + Memorability 30%	Story segments, emotional scenes
TYPE-C Aesthetic	Aesthetics 50% + Sync 30%	B-roll, atmosphere shots
TYPE-D Commercial	Credibility 40% + Memorability 40%	Product showcases, ads

Selection Levels

Level	Criteria	Usage
🌟 MUST KEEP	Score ≥ 8.5 or any dimension = 10	Core material
📁 USABLE	7.0 ≤ Score < 8.5	Supporting shots
🗑️ DISCARD	Score < 7.0	Not recommended

📁 Output Structure

output-directory/
├── {video_id}.mp4              # Full video
├── {video_id}.m4a              # Audio
├── {video_id}.srt              # Subtitles (smart extraction)
├── scene_scores.json           # ⭐ AI scoring data
├── *_complete_analysis.md      # ⭐ Full analysis report
├── scenes/                     # Scene clips
│   └── best_shots/             # ⭐ Top-rated clips (auto-copied)
└── frames/                     # Preview frames

🔧 Configuration

Pipeline Options

Option	Description
`--setup`	Configure output directory
`--scene-threshold`	Scene detection sensitivity (default: 27)
`--best-threshold`	Best shots threshold (default: 7.5)
`-o, --output`	Output directory

API Environment Variables

Variable	Description
`VIDEO_ANALYZER_API_KEY`	Vision model API key (required for API mode)
`VIDEO_ANALYZER_BASE_URL`	API endpoint (default: Gemini)
`VIDEO_ANALYZER_MODEL`	Model name (default: `gemini-2.0-flash`)

📚 Theory Background

Based on Walter Murch's Six Rules:

Emotion > Story > Rhythm > Eye-trace > 2D Plane > 3D Space

A shot with genuine emotion but slight shake is better than a perfect but empty frame.

🙏 Credits

Built with:

yt-dlp — Video download
FunASR — Chinese speech recognition
PySceneDetect — Scene detection
FFmpeg — Media processing
RapidOCR — Burned subtitle OCR

📖 References

Core Theory

Murch, W. (2001). In the Blink of an Eye (2nd ed.). Silman-James Press.
Murch, W. (1995). The Conversations. Knopf.

Psychology & Cognitive Science

Von Restorff, H. (1933). Psychologische Forschung, 18(1), 299-342.
Itti, L., & Koch, C. (2001). Nature Reviews Neuroscience, 2(3), 194-203.
Kahneman, D. (2011). Thinking, Fast and Slow. Farrar, Straus and Giroux.

Social Media & Virality

Berger, J. (2013). Contagious. Simon & Schuster.
Berger, J., & Milkman, K. L. (2012). Journal of Marketing Research, 49(2), 192-205.

Video & Film Analysis

Bordwell, D., & Thompson, K. (2012). Film Art (10th ed.). McGraw-Hill.
Katz, S. D. (1991). Film Directing Shot by Shot. Michael Wiese Productions.
Brown, B. (2016). Cinematography: Theory and Practice (3rd ed.). Routledge.

🎬 视频专家分析器

基于 Walter Murch 剪辑六法则 和 真实 AI 视觉评分 的专业视频分析工具

✨ 核心特性

🤖 真实 AI 视觉评分 — 多模态大模型（Gemini/Kimi/GPT-4o）分析真实画面内容
🔀 双路径评分 — Agent 模式（IDE 中 AI 直接看图）+ API 模式（远程 API 调用）
🎯 动态权重系统 — 根据场景类型自动调整权重（Hook/叙事/氛围/商业）
🎬 场景检测 — PySceneDetect detect-content 精准场景分割
🎤 智能字幕提取 — 四级降级：B站API → 内嵌字幕 → RapidOCR → FunASR
⭐ 精选片段 — 自动复制高分片段到 best_shots/
📊 五维评分 — 美感、可信度、冲击力、记忆度、趣味度
🌐 中英双语 — 所有专业术语附中文释义

📱 支持平台

平台	支持状态	说明
Bilibili	✅ 完全支持	yt-dlp 下载 + B站API字幕
YouTube	✅ 完全支持	yt-dlp 下载
抖音 (Douyin)	✅ 完全支持	专用下载器（公开/分享链接无需浏览器 cookie）
小红书 (Xiaohongshu)	✅ 完全支持	专用下载器
其他平台	⚠️ 可能支持	取决于 yt-dlp

🤖 模型兼容性

模型	Agent 模式	API 模式	说明
Gemini 3.0 Flash	✅ 推荐	✅ 推荐	速度快、视觉能力强
Gemini 3.0 Pro	✅ 推荐	✅ 支持	最强视觉理解
Kimi 2.5	✅ 支持	✅ 支持	中文语境优秀
Claude (Sonnet/Opus)	✅ 支持	❌ 不支持	有视觉能力但无 OpenAI 兼容 API
纯文本模型	❌ 不可用	❌ 不可用	无视觉能力

🚀 快速开始

环境准备

# 系统依赖
brew install ffmpeg

# 一键安装所有依赖
pip3 install -r requirements.txt

# 检查环境
python3 scripts/check_environment.py

一键分析

# 首次配置
python3 scripts/pipeline_enhanced.py --setup

# 分析视频
python3 scripts/pipeline_enhanced.py https://www.bilibili.com/video/BV1xxxxx
python3 scripts/pipeline_enhanced.py "https://www.douyin.com/video/xxxxx"

# AI 评分（二选一）
# 方式 A：Agent 模式（IDE 中 AI 助手直接看图评分）
# 方式 B：API 模式
export VIDEO_ANALYZER_API_KEY="your-key"
python3 scripts/ai_analyzer.py scene_scores.json --mode api

抖音链接说明

公开可访问的抖音链接，优先直接交给本地脚本处理，不要先尝试网页登录或浏览器 cookie
推荐命令：

python3 scripts/pipeline_enhanced.py "<抖音链接>"
# 或只下载视频
python3 scripts/download_douyin.py "<抖音链接>" ./video.mp4

如果在 WSL、远程容器或无桌面浏览器环境里看到“cookie 无法读取”的报错，说明走错路线了，应切回上面的本地脚本
优先使用从抖音 App 复制的 https://v.douyin.com/... 分享短链；长链同样支持

📊 评分体系

五维评分维度

维度	权重	评估要点
美感 (Aesthetic)	20%	构图(三分法)、光影质感、色彩和谐度
可信度 (Credibility)	20%	表演自然度、物理逻辑、无出戏感
冲击力 (Impact)	20%	视觉显著性、动态张力、第一眼吸引力
记忆度 (Memorability)	20%	独特视觉符号、冯·雷斯托夫效应
趣味度 (Fun)	20%	参与感、娱乐价值、社交货币潜力

筛选等级

等级	标准	用途
🌟 MUST KEEP	加权总分 ≥ 8.5 或单项 = 10	核心素材
📁 USABLE	7.0 ≤ 加权总分 < 8.5	辅助素材
🗑️ DISCARD	加权总分 < 7.0	建议舍弃

📁 输出结构

输出目录/
├── {video_id}.mp4              # 完整视频
├── {video_id}.m4a              # 音频
├── {video_id}.srt              # 字幕（智能提取）
├── scene_scores.json           # ⭐ AI 评分数据
├── *_complete_analysis.md      # ⭐ 完整分析报告
├── scenes/                     # 场景片段
│   └── best_shots/             # ⭐ 精选片段（自动复制）
└── frames/                     # 预览帧

🔧 配置选项

选项	说明
`--setup`	配置输出目录
`--scene-threshold`	场景检测阈值 (默认: 27)
`--best-threshold`	精选阈值 (默认: 7.5)

📚 理论背景

基于 Walter Murch 剪辑六法则：

情感 > 故事 > 节奏 > 视线追踪 > 2D平面 > 3D空间

一个情感真挚但画面略抖的镜头，优于一个画面完美但内容空洞的镜头。

🙏 致谢

yt-dlp — 视频下载
FunASR — 中文语音识别
PySceneDetect — 场景检测
FFmpeg — 媒体处理
RapidOCR — 烧录字幕识别

📜 License

MIT License - 自由使用和修改

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
scripts		scripts
templates		templates
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
RELEASE_v2.1.0.md		RELEASE_v2.1.0.md
SKILL.md		SKILL.md
SUMMARY.md		SUMMARY.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🎬 Video Expert Analyzer

✨ Features

📱 Supported Platforms

🤖 Model Compatibility

🚀 Quick Start

Prerequisites

One-Command Analysis

📊 Scoring System

Five Dimensions

Scene Types & Dynamic Weights

Selection Levels

📁 Output Structure

🔧 Configuration

Pipeline Options

API Environment Variables

📚 Theory Background

🙏 Credits

📖 References

Core Theory

Psychology & Cognitive Science

Social Media & Virality

Video & Film Analysis

🎬 视频专家分析器

✨ 核心特性

📱 支持平台

🤖 模型兼容性

🚀 快速开始

环境准备

一键分析

抖音链接说明

📊 评分体系

五维评分维度

筛选等级

📁 输出结构

🔧 配置选项

📚 理论背景

🙏 致谢

📜 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages