Video Analyzer

视频分析处理 — video-analyzer

概述

将视频"反编译"为结构化分析报告的本地工具，全程离线，无需联网。

核心能力：

• 🎙️ 语音转文字（精确到每个字的时间戳，含说话人分离）
• 🎬 场景边界切割与章节切片
• 🔍 视觉物体与画面文字识别
• 📊 多模态时空对齐（声音 ↔ 画面 ↔ 文字）
• ✨ 带时间戳的精华摘要
• ✂️ 视频章节切片 + 独立SRT字幕
• 🗣️ 说话人分离标注
• 📱 短视频平台适配（抖音/快手/B站/视频号，自动识别链接+下载+平台分析）
• 🎬 自动剪辑建议（高光检测/冗余标记/时间线生成/EDL导出/字幕样式）
• 📄 交互报告输出（HTML + JSON + Markdown）

快速开始

第一次使用前

⚠️ 模型下载提醒：首次运行会自动下载语音识别模型。v4.1 起默认使用 tiny 模型（约 75MB），如需更高精度可加 --model small 切换到 small 模型（约 466MB）。国内用户建议先执行以下命令加速：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

下载完成后后续使用无需重复下载。

基本用法

python main.py --input "视频路径或URL" --output "./output"

使用场景示例

输出示例

output/
├── report.html              # 交互式 HTML 报告（主报告，用浏览器打开）
├── data.json                # 完整结构化 JSON 数据
├── script.md                # 剧本格式 Markdown
├── scenes/                  # 场景关键帧缩略图
│   ├── scene_001.jpg
│   ├── scene_002.jpg
│   └── ...
├── chapters/              # 章节切片（--slice-chapters 时生成）
│   ├── chapter_001.mp4
│   ├── chapter_001.srt
│   ├── chapter_001.vtt
│   ├── chapter_002.mp4
│   ├── chapter_002.srt
│   └── chapters_index.json
├── summary/               # 时间戳摘要
│   ├── timestamped_summary.md
│   └── timestamped_summary.json
├── speakers.srt           # 说话人字幕（--diarize 时生成）
├── platform/              # 平台分析（--platform 时生成）
│   ├── platform_metadata.json
│   └── short_video_analysis.json
├── edl/                   # EDL 时间线（--export-edl 时生成）
│   ├── timeline.cmx3600
│   └── ffmpeg_commands.sh
├── subtitles/             # 字幕文件（--editing-suggest 时生成）
│   └── subtitle.ass
└── assets/
    ├── waveform.svg       # 音频波形图
    └── timeline.svg       # 时间轴可视化

参数说明

功能说明

短视频平台适配（--platform）

自动识别并处理抖音/快手/B站/视频号视频链接：

• 链接解析：支持分享链接、短链接、BV号等多种格式
• 视频下载：基于 yt-dlp 的多平台视频下载
• 元数据提取：标题、作者、点赞/评论/分享/收藏数、BGM信息等
• 黄金前3秒分析：检测开场hook类型（视觉冲击/画面变化/平稳开场）
• 完播率因素分析：视频时长评分、内容密度、行动号召检测、悬念检测
• 带货分析：促销关键词识别、价格提取、行动号召检测
• 节奏分析：场景切换频率、节奏类型判定

自动剪辑建议（--editing-suggest）

基于AI分析自动生成剪辑建议：

• 高光检测：综合视觉活跃度、音频能量、语音情感、画面内容四维度评分
• 冗余标记：检测静音片段、填充词、语速异常、画面静止、重复内容
• 时间线生成：智能排列高光片段，跳过冗余，生成优化剪辑顺序
• EDL导出：支持CMX3600（Premiere Pro/DaVinci Resolve兼容）/CSV/JSON格式
• 字幕样式：抖音风格/B站风格/电影风格/简洁风格，支持SRT/ASS/VTT格式 按场景边界自动将视频切割为多个短视频片段，每段生成独立的 SRT 字幕文件和 WebVTT 字幕文件。
• 使用 ffmpeg 流复制模式（极速，不重新编码）
• 每个章节含 .mp4 + .srt + .vtt 三个文件
• 自动生成 chapters_index.json 索引文件

说话人分离（--diarize）

多人对话场景下，分离出不同说话人的对话段落。

• 基于 MFCC + 频谱特征 + GMM 聚类
• 完全离线，无需网络
• 以不同颜色标注不同说话人（A-F）
• 生成独立的 speakers.srt 字幕文件

时间戳摘要

每次运行自动生成带时间戳的精华摘要列表。

• [MM:SS] 格式时间戳
• Markdown + JSON 双格式输出
• 标注精华评分和标签

硬件自适应

启动时自动检测硬件配置，动态调整处理参数：

控制策略（不影响用户体验）：

• 低配电脑（< 8GB 内存）：自动降低优先级（nice=10），使用 tiny/small 模型
• 运行时监控：实时检测内存使用，接近上限时主动降速
• 处理时间预估：分析前显示预估等待时间

安全提示

• 所有处理均在本地完成，无上传
• 输入视频需经用户路径合法性验证
• OCR 识别结果仅供参考
• 生成的 HTML 报告可在浏览器中离线查看
• v3.0 新增：文件类型黑名单拦截，禁止危险文件输入

输入文件类型限制

为保障安全，以下文件类型被禁止作为输入：

能力边界与限制

不支持的场景

识别准确率说明

以上数据仅供参考，不同视频类型差异较大。

反模式 / 千万别这样用

以下操作会导致工具报错或输出错误结果，请务必避免：

• ❌ 输入损坏的视频文件：工具会直接报错退出。可用 ffmpeg -i input.mp4 -c copy fixed.mp4 尝试修复后再分析。
• ❌ 输入纯音频文件（如 MP3、WAV）：工具不支持，请先转成视频或用专业语音转文字工具。
• ❌ 超长视频不设 --max-memory：2小时以上大视频建议加 --max-memory 2 --no-visual 防止内存溢出。
• ❌ 小内存电脑选大模型：4GB 内存选 medium 或 large-v3 会极其缓慢甚至卡死。用 --model tiny 或 --model small。
• ❌ 重复分析使用旧缓存：加 --force 重新分析，避免读过期缓存。
• ❌ 用 IE 打开 HTML 报告：请用 Chrome/Edge/Firefox。
• ❌ 窄带网络下分析在线视频：先下载到本地再分析，网络不稳定容易失败。
• ❌ 跳过 ffmpeg 安装直接用：ffmpeg 是硬性依赖，必须先安装。
• ❌ 输入 .ps1 .exe 等可执行文件：文件类型黑名单会直接拒绝，本工具只处理视频。

常见问题（FAQ）

安装与配置

Q: ffmpeg 安装后仍提示找不到？ A: 需要让 ffmpeg 在系统 PATH 中。Windows 用户可用 scoop install ffmpeg 或下载后解压并将 bin 目录加入 PATH；macOS 用 brew install ffmpeg；Ubuntu 用 sudo apt install ffmpeg。安装后新开一个终端窗口，运行 ffmpeg -version 验证。

Q: pip install 时 whisper 下载模型很慢？ A: whisper 首次运行时会自动下载模型文件（small 约 466MB），国内用户建议设置镜像：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Q: paddleocr 安装失败？ A: paddleocr 是可选依赖，不安装也能使用语音转文字和场景检测。如需 OCR，先确认 Python 版本 ≤ 3.11，再 pip install paddlepaddle paddleocr。

Q: 说话人分离不准确怎么办？ A: 说话人分离基于声音特征聚类，如果说话人声音相似或环境噪音大，准确率会下降。可以：① 安装 librosa 和 scikit-learn 提升特征提取能力；② 用 --diarize 后手动编辑生成的 speakers.srt 文件。

Q: 为什么提示"禁止的文件类型"？ A: 工具内置了文件类型黑名单，所有非视频文件（如 .exe .ps1 .zip .docx 等）都会被拒绝输入。请确认输入的是 .mp4/.mkv/.avi/.mov 等视频文件。

Q: 抖音/快手/B站视频无法下载？ A: 短视频平台下载依赖 yt-dlp，请先安装：pip install yt-dlp。部分视频可能需要配置 cookies 才能下载。如果仍然失败，请确认链接可访问且网络稳定。

Q: 自动剪辑建议的高光检测准确吗？ A: 高光检测基于视觉活跃度、音频能量、语音情感、画面内容四维度综合评分，准确率约 70-85%。建议将结果作为参考，人工微调后导出 EDL 到 Premiere Pro 或 DaVinci Resolve 进一步编辑。

Q: EDL 文件如何导入到剪辑软件？ A: CMX3600 格式兼容 Premiere Pro / DaVinci Resolve / Final Cut Pro。在 Premiere Pro 中：文件 → 导入 → 选择 .edl 文件。在 DaVinci Resolve 中：文件 → 导入时间线 → 导入 EDL。

Q: 字幕样式可以自定义吗？ A: 可以在 config.yaml 的 editing.subtitle 部分自定义字体、大小、颜色等参数。也支持在命令行用 --subtitle-style 选择预设模板。

运行错误

Q: 运行中提示 "No space left on device"？ A: 缓存目录占满了磁盘。用 --temp-dir 指定其他目录，或删除旧缓存 rm -rf .cache/。也可在 config.yaml 中减小 max_memory_gb。

Q: 下载在线视频失败？ A: 工具内置 3 次重试机制。如果仍然失败，请确认 URL 可访问且网络稳定；YouTube/B站等需安装 yt-dlp：pip install yt-dlp。

Q: 语音识别结果有漏字或错字？ A: 语音识别准确率约 85-95%。提高准确率方法：① 用更大的模型 --model medium；② 确保视频音频清晰无背景噪音；③ 方言视频选 --lang zh 指定中文。

Q: 场景切分不准，渐变画面漏切？ A: HSV 直方图差分对快速跳切准确度高（90%+），渐变过渡可能漏切。需要更精确的场景检测建议用 --scenes-only 导出后手动编辑 JSON。

Q: 处理大视频时电脑变卡？ A: 低配电脑请加 --nice 15 --max-memory 4。工具会自动降低进程优先级并限制内存使用。若仍卡顿，可加 --no-visual --no-ocr 只跑语音转文字。v3.0 版新增了实时资源监控，会自动防止内存溢出。

输出相关

Q: HTML 报告打开是乱码？ A: 请用现代浏览器（Chrome/Edge/Firefox）打开，不要用 IE。报告内已设 UTF-8 编码。

Q: 输出的 JSON 太大怎么查看？ A: 建议用 VS Code 或 jq 命令行工具：jq '.transcript.segments[0:3]' data.json 查看前 3 段。

Q: 章节切片的视频无法播放？ A: 章节切片使用 ffmpeg 流复制模式（-c copy），切割点必须在关键帧上。如果某些章节无法播放，可在 config.yaml 中设置 force_reencode: true 使用重新编码模式（稍慢但兼容性好）。

Q: 说话人分离结果全是同一人？ A: 请确认安装了可选依赖：pip install librosa scikit-learn。如果没有这些库，会回退到基于时间间隔的简单猜测策略，准确率较低。v4.1 新增质量评分（--quality-score），可量化评估分离结果可信度。

Q: 说话人分离质量评分怎么使用？ A: 运行 --diarize --quality-score，会输出 0-100 分数和等级（高/中/低）。≥ 80 分可信，≥ 60 分基本可用，< 60 分建议手动调整。评分基于声纹距离和重叠率两个维度。

Q: 剪映 draft.json 怎么用？ A: 运行 --editing-suggest --jianying 生成 draft.json 文件。打开剪映专业版 → 导入 → 选择 draft.json 即可加载时间线和字幕。

Q: tiny 模型和 small 模型有什么区别？ A: tiny 模型（75MB）识别速度更快但准确率略低；small 模型（466MB）准确率更高但速度慢。v4.1 默认 tiny 优先体验，如需要更高精度可用 --model small 切换。

Q: 为什么优先推荐 tiny 模型？ A: v4.1 新增 tiny 模型优先体验（75MB），首次使用门槛从 466MB 降至 75MB。低配电脑也会自动使用 tiny 模型。如需更高精度，可手动切换 --model small/medium。

更新提醒

启动时会自动检查 GitHub 上的新版本，发现更新时会显示提醒。使用 --no-update-check 可跳过此检查。

联系方式

如有更好建议：njskills@agent.qq.com

更新日志

| v4.3.0 | 2026-08-24 | 增加：纯音频输入（mp3/m4a/wav 播客与录音，ffmpeg 探测后直接转 16k 单声道 wav 进 ASR，跳过场景切分与 OCR，报告复用纪要版）；增加：批量队列（SQLite 任务表 + 硬件档位并发控制：low=1/mid=2/high=4，支持中断后续跑）；增加：GPU 自动加速（启动时探测 CUDA，命中则加载 Whisper CT2 int8 量化模型，失败自动回退 CPU tiny）；优化：ASR 配置统一（Whisper/Paraformer/SenseVoice 分散配置合并为 --asr-engine 单参数，auto 沿用现有自动选择逻辑）；增加：--dir / --hardware-tier / --download-ct2-model 参数 |

历史版本

v4.2.0

• 合并：场景检测+章节切片为「场景管理」模块（detect→slice 一条链）
• 增加：短视频爆款预测（多模态特征+爆款样本对比，概率评分+改进建议）
• 增加：实时直播分析（流式ASR+滑动窗口+敏感词检测+实时告警）
• 增加：--scene-management / --viral-predict / --live-analyze 参数
• 优化：HTML/JSON/Markdown 报告新增爆款预测和直播分析板块
• 增加：tiny 模型优先体验（75MB 低门槛，首次使用从 466MB 降至 75MB）
• 增加：说话人分离质量评分（声纹距离 + 重叠率，0-100 分 + 高/中/低等级）
• 增加：剪映 draft.json 导出（可直接导入剪映专业版）
• 增加：--jianying / --quality-score 参数
• 优化：硬件自适应默认 tiny 模型，低配电脑友好

历史版本

v2.2.0

• 增加：使用场景示例表格（7个常见场景 + 对应命令）
• 增加：反模式 / 千万别这样用警告（7条）
• 增加：识别准确率说明表格（4个模块）
• 增加：首次使用前模型下载提醒（加速镜像命令）
• 增加：场景切分不准、文字识别漏字的原因说明
• 优化：触发方式 -> 使用场景示例，附场景+命令速查表
• 优化：文档结构新增前置提示
• 优化：准确率自检列表现已内置

v2.1.0

• 增加：网络下载 3 次自动重试机制
• 增加：能力边界与限制表格
• 增加：FAQ 常见问题（安装/运行/输出三类）
• 优化：错误提示改为中文，附带修复建议
• 优化：网络不稳定时自动重试，不再直接退出

v2.0.0

• 增加：硬件自适应（自动检测 CPU/内存/GPU，动态调整并行参数）
• 增加：进程优先级控制（nice_level），低配电脑自动降低优先级
• 增加：缓存自动清理（限制缓存目录大小，防 OOM）
• 增加：--max-memory、--nice、--no-adaptive 参数
• 修复：scene_tags/scene_types 拼写错误
• 修复：highlights 类型不匹配问题

v1.0.0

• 首个稳定版本
• 支持本地视频和 HTTP URL 输入
• HTML/JSON/Markdown 三格式输出
• 模块化设计，便于扩展