星冉 · 视频分析 · Video Analyzer

> 星冉出品（主理人：Astra）— 基于 OpenCV + K-Means + 场景化投放诊断方法论的全链路视频分析 Skill。
> 不仅提取技术指标，更结合具体投放平台与目标，帮助用户看清视频的问题、亮点与改进方向。

⚠️ 核心工作流：分析前必须先询问客户

这是本 Skill 的第一原则。 每个平台对视频的要求规范不同，同一视频在不同平台的结论也不同。
因此，在启动任何分析之前，必须先向客户确认以下 6 件事，再据此组织场景化分析：

必问清单（6 问）

> 若客户未明确某几项，可按合理假设补全（如默认「付费投放」「全平台」「带货转化」），
> 并在分析结论中明确标注假设，避免误导。

场景化分析原则

• 只分析客户指定的平台，不用一套通用逻辑套所有平台；
• 每个平台用它自己的审核红线、内容偏好、流量分发机制逐条核对；
• 分析侧重点随目标而变（如「带货」重点看 CTA/利益点/时长，「涨粉」重点看垂直度/关注引导）；
• 每个问题带严重程度分级（致命/高危/中危/低危）与可定位时间点。

快速开始

单视频分析（场景化）

# 基础分析（本地文件）
python -m scripts.pipeline /path/to/video.mp4 --output-dir ./output

# 场景化分析（指定平台 + 目标 + 行业 + 受众）
python -m scripts.pipeline video.mp4 --report \
  --platforms douyin,wechat_channels \
  --goal conversion \
  --industry 宠物食品 \
  --audience 宝妈

# 自然发布（非付费）分析
python -m scripts.pipeline video.mp4 --report --organic --goal breakout

# URL 分析
python -m scripts.pipeline "https://v.douyin.com/xxx" --report

# 已有帧图目录分析（浏览器捕获的帧）
python -m scripts.pipeline ./frames_dir/ --mode pre-extracted --output-dir ./output

批量处理

python -m scripts.batch_processor ./videos/ --output-dir ./batch_output
python -m scripts.batch_processor ./videos/ --incremental --cache-dir ./cache

核心能力矩阵

八维度诊断体系

对每个视频，从 8 个维度逐一诊断，每个维度输出 评分(0-100)、等级、问题、亮点、改进建议：

逐帧分析维度（带时间点定位）

在 8 维度与场景化投放诊断之外，逐帧分析输出带时间点的结论，整合进问题清单与修改建议：

> 音画同步为启发式检测（字幕帧 vs 音频能量），精确口型对齐需 ASR。

场景化投放诊断体系（抖音·快手·视频号·百度）

从「通用规则引擎」升级为「按平台逐条分析」。每个平台独立输出：
适配分 + 问题清单（严重程度分级）+ 修改建议 + 内容偏好/流量机制适配说明，并附跨平台对比总览。

严重程度分级

四平台审核与推荐要点

> 四平台完整审核红线与推荐机制见 references/ad-platform-guidelines.md，代码化规则见 scripts/platforms.py。

调用接口

CLI 调用

python -m scripts.pipeline <INPUT> [OPTIONS]

Python API

from scripts.pipeline import VideoAnalysisPipeline, AnalysisConfig
from scripts.ad_diagnostics import AnalysisScenario

config = AnalysisConfig(sample_interval_sec=2.0, max_frames=30, enable_ocr=True, enable_report=True)

# 构造投放场景（分析前先向客户确认）
scenario = AnalysisScenario(
    platforms=["douyin", "wechat_channels"],  # 发布平台
    goal="conversion",                         # 带货转化
    industry="宠物食品",                        # 行业
    audience="宝妈",                            # 受众
    is_paid=True,                              # 付费投放
    is_original=True,                          # 原创
    has_logo=True,                             # 含品牌Logo
)

pipeline = VideoAnalysisPipeline(config)
result = pipeline.analyze("/path/to/video.mp4", output_dir="./output", scenario=scenario)

# 8 维度诊断
print(result.summary["overall_score"], result.summary["overall_grade"])
for d in result.dimension_reports:
    print(d["name"], d["score"], d["grade"], d["problems"])

# 场景化投放诊断（每平台独立报告）
ad = result.ad_diagnostics
print("场景:", ad["scenario"])
for p in ad["platform_reports"]:               # 指定平台逐条分析
    print(f"{p['icon']} {p['platform']}: {p['fit_score']} ({p['fit_grade']}) {p['verdict']}")
    for i in p["issues"]:                       # 问题清单（严重程度分级）
        print(f"  [{i['severity_label']}] {i['title']} @{i['timestamp']}")
        print(f"     建议: {i['suggestion']}")
for c in ad["platform_comparison"]:             # 跨平台对比
    print(c["platform"], c["fit_score"], c["tag"], c["top_issue"])

# 逐帧分析
fa = result.frame_analysis
for v in fa["violation_timeline"]:              # 违规风险点时间线
    print(f"违规: {v['time']} 「{v['keyword']}」({v['severity_label']})")

输出数据结构

output/
├── data.json              # 完整结构化数据（含维度诊断 + 场景化投放诊断 + 逐帧分析）
├── frames/                # 关键帧图像
├── report.html            # 可视化诊断报告（--report时）
└── cache.json             # 分析缓存

data.json 顶层结构：

{
  "schema_version": "2.4.0",
  "metadata": {...},             # 视频元数据
  "frames": [...],               # 逐帧分析（含运动强度）
  "scenes": [...],               # 场景列表
  "global_colors": {...},        # 全局色彩
  "global_composition": {...},   # 全局构图
  "audio": {...},                # 音频分析（含能量时间线）
  "motion": {...},               # 运动/节奏分析
  "title_cover": {...},          # 标题封面分析
  "ocr_all_text": "...",         # OCR 全文
  "dimension_reports": [...],    # ★ 8维度诊断报告
  "summary": {...},              # ★ 综合评分总览
  "frame_analysis": {...},       # ★ 逐帧分析（画面/字幕/音画同步/违规时间线/完播风险）
  "ad_diagnostics": {...},       # ★ 场景化投放诊断（每平台独立报告+对比总览）
  "pipeline_status": {...}       # 各步骤执行状态
}

完整 Schema 见 references/output-schema.md。

依赖

pip install -r requirements.txt

必需: opencv-python-headless, numpy, Pillow
推荐: jinja2（HTML报告）
可选: yt-dlp（URL下载）, paddleocr（中文OCR）, pytesseract（OCR兜底）
系统: ffmpeg（音频分析，需加入 PATH）

可扩展性

• 新增平台：在 scripts/platforms.py 的 PLATFORMS 中新增 PlatformProfile（规则 + 偏好 + 流量机制），并在 PLATFORM_ORDER 注册。
• 新增投放目标：在 platforms.py 的 GOALS 中新增目标定义，在 ad_diagnostics.py 的 _check_goal 中补充目标导向检查。
• 新增行业红线：在 platforms.py 的 INDUSTRY_RULES 中新增行业合规规则。
• 新增分析维度：在 analyzers.py 新建分析器，在 dimensions.py 注册新维度评估器。
• 新增逐帧检测：在 frame_analysis.py 的 FrameAnalyzer 中扩展检测方法。

版权声明

© 星冉 Astra（艺名）出品。本技能全部内容著作权归作者个人所有，非公司共同财产。权利人身份以 LICENSE 文件及作品登记证书为准；授权公司及团队在 WorkBuddy 内部使用。未经书面许可，禁止对外公开分发、转售、再授权或移除本声明。