video-analyzer

KO | EN

gitlite — search

#hacktoberfest #deep-learning #linux #docker #java #windows #awesome #kubernetes #vue #security #pytorch #mcp #ios #openai

(★ 14)

🎬 Video Analyzer skill for agent: Whisper transcription + scene detection + Claude Vision analysis

video-analyzer 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Video Analyzer

Video Analyzer 可以把一个视频先转成文字，再按台词片段切分镜，并为每个片段截取一张关键帧图片。

脚本会生成：

- `transcript.json`：完整转录文本和时间戳
- `shots.json`：按台词切出来的分镜数据
- `shots/*.jpg`：每个分镜的关键帧截图

注意：脚本本身不做图片理解，也不内置视觉大模型。它只负责把视频变成“文字 + 分镜 + 关键帧”。后续分镜画面分析要看你在哪个 Agent 或模型环境里使用。

## 第一次使用

下面步骤适合第一次从 GitHub 拉取项目、还没有安装 Whisper 的用户。

### 1. 准备电脑环境

需要先安装：

- Python 3.9 或更高版本
- FFmpeg

macOS 推荐用 Homebrew 安装 FFmpeg：

```bash
brew install ffmpeg
```

Ubuntu / Debian：

```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

如果不确定电脑有没有 Python，可以运行：

```bash
python3 --version
```

能看到版本号就可以继续。

### 2. 下载项目

```bash
git clone https://github.com/duxj4520/openclaw-video-analyzer.git
cd video-analyzer
```

如果你已经下载好了项目，只需要进入项目目录：

```bash
cd video-analyzer
```

### 3. 安装 Python 依赖

```bash
python3 -m pip install -r requirements.txt
```

这一步会安装 `openai-whisper`。第一次安装可能需要几分钟。

### 4. 检查是否安装成功

```bash
python3 scripts/analyze.py --check
```

看到下面提示就说明环境准备好了：

```text
✅ 依赖检查通过，可以开始分析视频
```

如果失败，按终端里显示的错误提示补装缺失内容。

### 5. 可选：准备视觉模型 API Key

如果你只需要转录、按台词分镜、截关键帧，这一步可以跳过。

如果你的 Agent 不能直接读取图片，但你想自动分析每个分镜画面，需要准备阿里云百炼 API Key，并在运行前设置：

```bash
export DASHSCOPE_API_KEY="你的百炼 API Key"
```

不要把 API Key 写进代码，也不要提交到 GitHub。这个 Key 只用于后面的通义千问视觉模型分析，会产生 API 调用成本。

### 6. 分析第一个视频

把 `/path/to/video.mp4` 换成你自己的视频路径：

```bash
python3 scripts/analyze.py \
  --video /path/to/video.mp4 \
  --output analysis/
```

运行完成后，会在 `analysis/` 目录看到：

```text
analysis/
├── transcript.json
├── shots.json
└── shots/
    ├── shot_001.jpg
    ├── shot_002.jpg
    └── ...
```

## 在 Claude Code 里使用

在 Claude Code 中触发这个 Skill 时，流程是：

1. 运行脚本生成 `transcript.json`、`shots.json` 和关键帧截图。
2. Claude 读取 `shots.json`。
3. Claude 逐张查看关键帧图片。
4. Claude 生成完整视频分析报告：
   - `analysis.json`
   - `analysis.md`

也就是说，脚本负责“提取素材”，Claude 负责“看图分析和写报告”。

## 分镜分析用什么模型？

这个项目分成两层：

- 本地脚本层：使用 `openai-whisper` 做语音转录，使用 `ffmpeg / ffprobe` 读取视频和截关键帧。
- 视觉分析层：不由脚本固定，取决于你使用的 Agent 或外部视觉模型。

### 方案 A：Agent 内置模型可以读图

适合 Claude Code 这类能直接读取本地图片的环境。

流程：

1. 运行脚本生成 `shots.json` 和 `shots/*.jpg`。
2. Agent 读取 `shots.json`。
3. Agent 打开每个 `keyframe` 图片。
4. Agent 按固定字段写出 `analysis.json` 和 `analysis.md`。

推荐每个镜头输出这些字段：

```json
{
  "content": "画面主体描述",
  "visual_elements": {
    "colors": ["主要颜色"],
    "composition": "构图方式",
    "atmosphere": "画面氛围"
  },
  "text_in_frame": "画面中的文字，没有则为空",
  "sentiment": "积极/消极/中性",
  "quality_score": 8,
  "keywords": ["关键词1", "关键词2"]
}
```

### 方案 B：Agent 不能读图

适合普通命令行、自建 Agent、或只能处理文本的模型环境。

这种情况下，脚本仍然可以正常工作，但只能生成：

- `transcript.json`
- `shots.json`
- `shots/*.jpg`

后续有三种选择：

- 人工查看 `shots/*.jpg`，手动补充画面分析。
- 把 `shots/*.jpg` 上传到支持图片理解的模型，再把结果合并回 `analysis.json`。
- 暂时只做文本侧分析，比如台词结构、时长节奏、Hook、关键词、分镜数量。

如果没有图片理解能力，不应该声称已经完成“画面内容分析”“画面质量评分”或“画面文字识别”。这些字段只能留空、标记为 `未分析`，或者只基于台词做推断。

#### 备选项：用通义千问视觉模型分析关键帧

如果当前 Agent 不能读图，但你有阿里云百炼 API Key，可以用项目里的可选脚本分析关键帧。

这个脚本使用通义千问视觉模型，默认模型是 `qwen-vl-plus`，通过阿里云百炼 DashScope 兼容接口调用。本脚本只使用 Python 标准库，不需要额外安装 SDK。

设置 API Key：

```bash
export DASHSCOPE_API_KEY="你的百炼 API Key"
```

先运行原始视频预处理：

```bash
python3 scripts/analyze.py \
  --video /path/to/video.mp4 \
  --output analysis/
```

再分析关键帧：

```bash
python3 scripts/analyze_frames_qwen.py \
  --shots analysis/shots.json \
  --output analysis/visual_analysis.qwen.json
```

也可以指定其他通义千问视觉模型：

```bash
python3 scripts/analyze_frames_qwen.py \
  --shots analysis/shots.json \
  --model qwen-vl-max
```

如果只是先试效果，可以只分析前 5 个分镜：

```bash
python3 scripts/analyze_frames_qwen.py \
  --shots analysis/shots.json \
  --limit 5
```

输出文件：

```text
analysis/visual_analysis.qwen.json
```

这个文件包含每个分镜的 `visual_analysis` 字段，可以再交给 Agent 合并成最终的 `analysis.json` 和 `analysis.md`。

注意：

- 这个步骤会把关键帧图片发送到阿里云百炼 DashScope API。
- 会产生 API 调用成本，分镜越多成本越高。
- 可以用 `--limit 5` 先测试前 5 个分镜，确认效果后再跑全量。

### 其他国内可选模型

后续也可以按同样方式扩展更多国内视觉模型：

- 智谱 GLM-4V / GLM-4.5V / GLM-4.6V：支持图片、视频、文件等多模态输入。
- 火山方舟豆包视觉模型：支持视觉理解请求，部分接口支持图片 URL 或 Base64。
- Kimi 视觉模型：支持视觉内容理解，适合已有 Moonshot/Kimi API 账号的用户。

当前项目先接通义千问视觉模型，是因为它对本地关键帧场景比较直接：官方接口支持 Base64 Data URL，本地截图不用先上传到公网。

### 开放给多人使用时要注意

- 文档要明确区分“脚本输出”和“视觉模型输出”。
- 不要把 `analysis.json / analysis.md` 描述成脚本一定会生成的文件。
- 如果 Agent 不能读图，就只能完成转录、分镜和关键帧提取。
- 如果接外部视觉模型，需要说明图片会被发送到第三方模型，涉及隐私和成本。
- 不同模型的输出风格会有差异，最好固定 JSON 字段，方便后续比较多个视频。
- 大量分镜会增加模型调用次数；建议先限制分镜数量，或分批分析。

## 常见问题

### 提示缺少 openai-whisper

运行：

```bash
python3 -m pip install -r requirements.txt
```

### 提示缺少 ffmpeg 或 ffprobe

macOS：

```bash
brew install ffmpeg
```

Ubuntu / Debian：

```bash
sudo apt-get install ffmpeg
```

### 提示视频文件不存在

说明 `--video` 后面的路径不对。可以把视频文件拖进终端窗口，系统通常会自动填入完整路径。

### 第一次转录很慢

Whisper 第一次运行时可能会下载模型文件。下载完成后，后续会快一些。

## 适合的使用场景

- 分析口播类短视频
- 按台词节奏拆分视频结构
- 提取爆款视频的开场、节奏、主题和画面素材
- 为后续支持图片理解的 Agent 或模型准备关键帧

video-analyzer

video-analyzer 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

video-analyzer

video-analyzer 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README