---
name: kb-ocr-processor
description: 视频OCR识别 - 从视频帧中提取文字
---

# KB OCR Processor Skill

**kb-ocr-processor** - 从视频帧中提取文字，作为语音识别的补充或替代方案。

## 什么时候使用

- kb-workflow 步骤 4 的降级方案：当 Whisper 语音识别效果不佳时
- 音频质量差、有背景音乐干扰、多种语言混合等情况

## 功能

- 视频截帧：直接从视频文件截取帧图片
- 批量处理：支持处理帧目录
- 双引擎：EasyOCR / Tesseract
- 置信度评分：每帧识别结果带置信度
- 文本合并：自动合并所有帧的识别结果

## 命令

```bash
# 方式1: 直接从视频截帧并 OCR（推荐）
python3 ocr_processor.py --video ./video.mp4 --output ocr.json

# 方式2: 处理已截取的帧目录
python3 ocr_processor.py --input ./frames/ --output ocr.json

# 指定截帧帧率（默认1帧/秒）
python3 ocr_processor.py --video ./video.mp4 --fps 2 --output ocr.json

# 同时生成合并的文本文件
python3 ocr_processor.py --video ./video.mp4 --output ocr.json --merge

# 使用 Tesseract 引擎
python3 ocr_processor.py --input ./frames/ --engine tesseract --output ocr.json
```

## 输出格式 Schema

### 必需字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否识别成功 |
| `engine` | string | 使用的 OCR 引擎 |
| `total_frames` | number | 处理的总帧数 |

### 可选字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `results` | array | 每帧的识别结果 |
| `merged_text` | string | 合并后的文本 |
| `output_file` | string | 输出文件路径 |
| `error` | string | 错误信息 |

## 成功示例

```json
{
  "success": true,
  "engine": "easyocr",
  "total_frames": 619,
  "output_file": "content/bilibili_BV1xx411c7mD_ocr.json",
  "results": [
    {
      "source": "0001.jpg",
      "text": "字幕文字",
      "confidence": 0.95
    },
    {
      "source": "0002.jpg",
      "text": "更多字幕文字",
      "confidence": 0.92
    }
  ],
  "merged_text": "字幕文字\n更多字幕文字\n..."
}
```

## 错误示例

### 视频文件不存在

```json
{
  "success": false,
  "error": "视频文件不存在",
  "video": "./missing.mp4"
}
```

### ffmpeg 未安装

```json
{
  "success": false,
  "error": "ffmpeg 未安装",
  "suggestion": "请运行: sudo apt-get install ffmpeg"
}
```

### 内存不足

```json
{
  "success": false,
  "error": "内存不足",
  "suggestion": "尝试降低帧率或处理较短的片段"
}
```

## 安装

```bash
cp -r kb-ocr-processor/ ~/.openclaw/skills/
pip install easyocr pytesseract Pillow

# 系统依赖
sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng
```

## 在 kb-workflow 中的使用

```bash
# 步骤 4 的降级方案（当 Whisper 效果不佳时）
python3 ~/.openclaw/skills/kb-ocr-processor/ocr_processor.py \
    --video "content/downloads/bilibili_BV1xx411c7mD.mp4" \
    --output "content/bilibili_BV1xx411c7mD_ocr.json" \
    --merge

# 输出：
# - bilibili_BV1xx411c7mD_ocr.json (完整结果)
# - bilibili_BV1xx411c7mD_ocr.txt (合并文本)
```

## 注意事项

- **耗时操作**：OCR 处理需要截帧和识别，可能较慢
- **帧率选择**：1帧/秒适合大多数场景，更高帧率增加精度但耗时更长
- **引擎选择**：EasyOCR 精度较高，Tesseract 速度较快
- **适用场景**：音频质量差、背景音乐干扰、多语言混合时使用