# videocu

**Repository Path**: techwolf/videocu

## Basic Information

- **Project Name**: videocu
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-31
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Video Content Extractor (VideoCU)

视频内容提取系统 - 专为教学视频、会议视频等内容提供高效的文字提取服务。

## 📋 项目简介

VideoCU 是一个基于AI的视频内容提取系统，能够自动分析视频文件，提取其中的关键帧并进行OCR文字识别。通过先进的预处理算法（场景检测、图像裁剪、感知哈希去重），大幅提升提取准确率和效率。

## ✨ 核心特性

- 🚀 **高效预处理**: 场景变化检测 + 中心裁剪 + 感知哈希去重
- 🤖 **双模式 OCR**:
  - **外部 API** (默认): 通过 HTTP API 调用高性能 OCR 服务
  - **本地引擎**: 集成 PaddleOCR，支持离线识别
- 📁 **批量处理**: 支持单文件上传和目录批量处理
- ⚡ **异步处理**: 基于内存队列的轻量级异步任务系统
- 💾 **本地存储**: SQLite数据库 + 本地文件存储，无外部依赖
- 🖥️ **跨平台**: 专为Windows环境优化，支持简单部署

## 🛠️ 技术栈

- **视频处理**: OpenCV
- **图像处理**: PIL, NumPy
- **哈希算法**: ImageHash (pHash/dHash/aHash)
- **OCR引擎**: PaddleOCR (支持中英文、多语言)
- **运行环境**: Python 3.8+ (跨平台)

## 📋 系统要求

- Python 3.8 或更高版本
- 至少 4GB RAM (GPU 加速推荐 8GB+)
- PaddleOCR 依赖 (自动安装)

## 🚀 快速开始

### 1. 安装依赖

```bash
# 克隆项目
git clone <repository-url>
cd videocu

# 安装 Python 依赖 (包括 PaddleOCR)
pip install -r requirements.txt

# 可选: 如果需要 GPU 加速，安装 CUDA 版本的 PaddlePaddle
# pip install paddlepaddle-gpu
```

### 2. 基本使用

#### 快速启动（使用外部 OCR API - 推荐）

```bash
# 使用快速启动脚本（默认外部OCR）
./quick_start_external_ocr.sh test/Agent-Skills.mp4

# 指定输出目录
./quick_start_external_ocr.sh test/Agent-Skills.mp4 my_output
```

#### 命令行使用

```bash
# 基本用法 - 启用外部 OCR（默认）
python main.py video.mp4 --ocr

# 指定输出目录
python main.py video.mp4 --ocr -o output_dir

# 使用本地 PaddleOCR
python main.py video.mp4 --ocr --ocr-engine local

# 自定义外部 OCR API 地址
python main.py video.mp4 --ocr --ocr-api-url http://192.168.10.91:8181

# 使用 Zoom 会议预设
python main.py video.mp4 --ocr --preset zoom

# 自定义参数
python main.py video.mp4 --ocr --scene-threshold 0.8 --hash-threshold 6

# 使用本地 OCR + GPU 加速
python main.py video.mp4 --ocr --ocr-engine local --ocr-use-gpu

# 使用英文 OCR
python main.py video.mp4 --ocr --ocr-engine local --ocr-lang en
```

### 3. Python API 使用

```python
from src.pipeline import VideoPipeline
from src.config import Config

# 使用默认配置（外部 OCR API）
config = Config()
pipeline = VideoPipeline(config, enable_ocr=True)
stats = pipeline.process_video('meeting.mp4', 'output')

# 使用本地 PaddleOCR
config = Config()
config.OCR_ENGINE = 'local'
config.OCR_LANG = 'ch'  # 中英文
config.OCR_USE_GPU = False  # CPU 处理

pipeline = VideoPipeline(config, enable_ocr=True)
stats = pipeline.process_video('meeting.mp4', 'output')

# 自定义外部 OCR API 地址
config = Config()
config.OCR_ENGINE = 'external'
config.EXTERNAL_OCR_API_URL = 'http://192.168.10.91:8181'
config.EXTERNAL_OCR_MODEL = 'NexaAI/paddleocr-npu'

pipeline = VideoPipeline(config, enable_ocr=True)
stats = pipeline.process_video('meeting.mp4', 'output')
```

## 📖 使用指南

### 命令行参数

```
必需参数:
  video                 输入视频文件路径

可选参数:
  -o, --output         输出目录 (默认: output)
  --preset             预设配置 (general/zoom/tencent/teams/none)

场景检测:
  --scene-threshold    场景检测阈值 (0-1, 默认: 0.85)
  --sample-interval    采样间隔（帧数，默认: 10）

图像裁剪:
  --crop-mode          裁剪模式 (center/custom, 默认: center)
  --crop-ratio         中心裁剪比例 (0-1, 默认: 0.8)
  --margins            自定义裁剪边距 (4个值: 上 下 左 右)

感知哈希:
  --hash-algorithm     Hash 算法 (phash/dhash/ahash, 默认: phash)
  --hash-threshold     Hash 距离阈值 (默认: 5)

OCR 配置:
  --ocr                启用 OCR 文字识别（默认不启用）
  --ocr-engine         OCR 引擎类型 (external=外部API, local=本地PaddleOCR, 默认: external)
  --ocr-api-url        外部 OCR API 地址 (默认: http://192.168.10.91:8181)
  --ocr-lang           本地 OCR 语言 (ch=中英文, en=英文, 默认: ch)
  --ocr-use-gpu        使用 GPU 加速本地 OCR (需要 GPU 支持)
  --ocr-show-log       显示 OCR 处理日志
```

### 预设配置说明

| 预设名称 | 适用场景 | 裁剪策略 |
|---------|---------|---------|
| `general` | 通用 PPT 录屏 | 中心裁剪 90% |
| `zoom` | Zoom 会议录屏 | 自定义裁剪，去除底部和右侧 |
| `tencent` | 腾讯会议录屏 | 自定义裁剪，去除底部和右侧 |
| `teams` | Microsoft Teams | 自定义裁剪，去除底部和右侧 |
| `none` | 无裁剪 | 保留完整画面 |

## 🔧 配置参数

### 参数调优建议

#### 场景检测阈值 (scene-threshold)
- **0.7-0.8**: 敏感模式，适合 PPT 变化较小的场景
- **0.85**: 默认值，平衡模式
- **0.9-0.95**: 宽松模式，适合 PPT 变化较大的场景

#### Hash 距离阈值 (hash-threshold)
- **3-4**: 严格去重，可能漏掉相似 PPT
- **5**: 默认值，推荐使用
- **6-8**: 宽松去重，适合有轻微抖动的视频

#### 裁剪模式选择
- **center**: 适合全屏 PPT 录屏
- **custom**: 适合会议软件录屏（Zoom/Teams/腾讯会议）

## 📁 项目结构

```
videocu/
├── src/                    # 源代码目录
│   ├── __init__.py
│   ├── config.py          # 配置管理
│   ├── scene_detector.py  # 场景检测模块
│   ├── image_cropper.py   # 图像裁剪模块
│   ├── perceptual_hash.py # 感知哈希模块
│   ├── ocr_engine.py      # 本地 OCR 识别模块 (PaddleOCR)
│   ├── external_ocr.py    # 外部 OCR API 模块
│   └── pipeline.py        # 流水线处理模块
├── docs/                   # 文档目录
│   ├── 系统详细设计.md     # 系统设计文档
│   ├── 设计方案.md        # 算法设计方案
│   └── 外部OCR接口使用指南.md  # 外部 OCR 接口文档
├── main.py                # 命令行入口
├── quick_start_external_ocr.sh  # 外部 OCR 快速启动脚本
├── test_external_ocr.py   # 外部 OCR 测试脚本（基础版）
├── test_external_ocr_advanced.py  # 外部 OCR 测试脚本（高级版）
├── examples.py            # 示例代码
├── tests.py               # 单元测试
├── requirements.txt       # Python依赖
└── README.md              # 项目说明
```

## 🔍 模块说明

### 1. 场景检测模块 (scene_detector.py)
- 使用 HSV 直方图计算帧间相似度
- 支持流式处理和批量处理
- 可配置采样间隔和阈值

### 2. 图像裁剪模块 (image_cropper.py)
- 中心裁剪：保留画面中心区域
- 自定义裁剪：针对非对称布局
- 预设配置：常见会议软件布局

### 3. 感知哈希模块 (perceptual_hash.py)
- 支持 pHash、dHash、aHash 算法
- 基于汉明距离的相似度判断
- 自动去重和历史记录管理

### 4. OCR 识别模块

#### 外部 OCR API (external_ocr.py) - 默认
- 通过 HTTP API 调用远程 OCR 服务
- 使用 Base64 + data URI 格式传输图像
- 默认使用 NexaAI/paddleocr-npu 模型
- 支持自定义 API 地址和超时设置

#### 本地 OCR (ocr_engine.py)
- 基于 PaddleOCR 引擎
- 自动检测文字方向
- 支持中英文及多语言识别
- 可选 GPU 加速
- 输出 JSON 和 TXT 格式

### 5. 流水线模块 (pipeline.py)
- 整合所有处理步骤
- 进度显示和统计信息
- 错误处理和日志记录

## 🔍 处理流程

```
视频输入 (30 FPS)
    ↓
[第一层] 场景检测 (直方图差异法)
    ↓ 100,000 帧 → 500 候选帧
[第二层] 中心裁剪 (去除边缘干扰)
    ↓
[第三层] 感知哈希去重 (pHash)
    ↓ 500 候选帧 → 50-80 关键帧
[第四层] OCR 文字识别
    ↓
输出结果 (图片 + 文本)
```

## 📊 性能指标

在典型的 1 小时会议视频（30 FPS）上：

- **输入**: 108,000 帧
- **场景检测后**: ~500 候选帧
- **去重后**: ~50-80 关键帧
- **压缩比**: ~1500x
- **处理时间**: 5-10 分钟（取决于硬件）

## 🧪 运行测试

```bash
# 运行所有测试
python tests.py

# 运行特定测试
python tests.py TestSceneDetector
python tests.py TestPerceptualHasher
```

## 📝 示例

查看 `examples.py` 文件获取更多使用示例：

```bash
python examples.py
```

## 🐛 故障排除

### 常见问题

**PaddleOCR 无法初始化**
- 确保已正确安装: `pip install paddlepaddle paddleocr`
- 第一次使用时会自动下载模型文件 (~150MB)，请确保网络连接和磁盘空间充足
- 可设置离线模式: `OCR_SHOW_LOG=False` 减少日志输出

**ImportError: No module named 'paddleocr'**
- 重新安装依赖: `pip install -r requirements.txt`
- 检查 Python 版本 >= 3.8

**OCR 识别慢**
- 尝试使用 GPU 加速: `python main.py video.mp4 --ocr-use-gpu`
- 需要安装 CUDA 版本 PaddlePaddle: `pip install paddlepaddle-gpu`

**内存不足**
- 降低视频分辨率
- 增加采样间隔 `--sample-interval 20`
- 处理较短的视频片段

**显存不足 (GPU 模式)**
- 关闭 GPU 加速: `--ocr-use-gpu` 移除此参数
- 或增加 GPU 显存


## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) - 优秀的 OCR 引擎
- [OpenCV](https://opencv.org/) - 计算机视觉库
- [ImageHash](https://github.com/JohannesBuchner/imagehash) - 感知哈希库

## 📞 联系方式

如有问题或建议，请提交 Issue 或联系开发团队。

---

**VideoCU** - 让视频内容提取变得简单高效！ 🚀