# ocr-portable

**Repository Path**: lvqb/ocr-portable

## Basic Information

- **Project Name**: ocr-portable
- **Description**: 视频字幕提取
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本地离线 OCR 服务（视频画面文字 / 硬字幕提取）

自包含绿色包：内置 Python 3.12、RapidOCR（ONNX Runtime / PP-OCRv6）、ffmpeg 与模型文件。
**不需要安装 Python，不需要联网，解压即可运行。**

## 一、目录结构

```
ocr-portable/
├── start-ocr.bat          双击启动（端口 8124）
├── server.py              服务主程序
├── py312/                 内嵌 Python 3.12 + 全部依赖
├── models/                OCR 模型（det / rec / cls，约 30MB）
├── ffmpeg/ffmpeg.exe      抽帧用的 ffmpeg（约 220MB）
├── test-sub.mp4           带硬字幕的测试视频
└── README.md
```

## 二、启动

1. 解压到**纯英文、无空格**的路径（如 `D:\ocr-portable`）
2. 双击 `start-ocr.bat`
3. 看到 `Uvicorn running on http://0.0.0.0:8124` 即成功
4. 浏览器访问 `http://127.0.0.1:8124/health` 验证

修改端口：编辑 `start-ocr.bat` 最后一行的 `--port 8124`。
改完记得同步后端配置 `ai.ocr` 里的端口。

## 三、接口

### GET /health
```json
{"status":"ok","engine":"rapidocr/onnxruntime","model_loaded":true,"ffmpeg":"...\\ffmpeg.exe"}
```

### POST /ocr

multipart/form-data 上传，视频或图片均可。

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `file` | file | 必填 | 视频（mp4/mov/mkv/avi/flv/webm…）或图片（jpg/png/bmp/webp） |
| `fps` | float | 2 | 抽帧频率，每秒识别几帧。字幕停留一般 ≥1 秒，2 足够；追求速度可用 1 |
| `crop` | string | 空 | 只看画面局部，格式 `x,y,w,h`（0~1 比例），如 `0.1,0.65,0.8,0.3` 表示下三分之一 |
| `min_score` | float | 0.5 | 置信度下限，低于该值的文字丢弃 |
| `format` | query | json | `json` 返回结构化结果；`srt` 只返回 SRT 文本 |

返回（format=json）：
```json
{
  "text": "第一句字幕\n第二句字幕",
  "segments": [
    {"start": 0.5, "end": 3.0, "text": "你好世界 这是第一句字幕"},
    {"start": 3.0, "end": 5.5, "text": "第二句 画面文字提取测试"}
  ],
  "frames": 17,
  "fps": 2.0,
  "duration": 8.0,
  "elapsed": 11.67,
  "srt": "1\n00:00:00,500 --> 00:00:03,000\n...   "
}
```

`start` / `end` 单位为**秒**（浮点），与 FunASR 服务一致，后端乘 1000 转毫秒即可。

### 调用示例

```bash
# 整个画面识别，输出 JSON
curl -X POST http://127.0.0.1:8124/ocr -F "file=@视频.mp4" -F "fps=2"

# 只识别下方字幕条，直接拿 SRT
curl -X POST "http://127.0.0.1:8124/ocr?format=srt" \
     -F "file=@视频.mp4" -F "crop=0.1,0.65,0.8,0.3" -F "fps=1"
```

## 四、性能

| 场景 | 实测（本机 CPU） |
| --- | --- |
| 单张 1280x720 图片 | 0.54 秒 |
| 8.5 秒视频（fps=2，17 帧） | 11.7 秒 |
| 8.5 秒视频（fps=1，9 帧） | 12.6 秒（含模型冷启动） |

粗略估算：1 小时视频按 fps=2 处理约 1.5~2 小时；用 `crop` 缩小区域 + `fps=1` 可显著加速。

## 五、与后端（RuoYi）对接

新增配置项（与 `ai.funasr` 同级）：
```yaml
ai:
    ocr: ${ai.url}:8124/ocr
```

Java 侧用 RestTemplate 上传 multipart，参数 `file` + `fps` + `crop`，
解析 `segments` 得到 `startTime/endTime`（毫秒）与 `text`，与 FunASR 输出的字幕结构一致。

> Docker 部署时 `ai.url` 要指向宿主机可达地址（见 application-prod.yml 注释），
> 且 `start-ocr.bat` 已绑定 `0.0.0.0`，容器可访问。

## 六、注意事项

1. **不要用中文目录**：ffmpeg 与 Python 子进程在中文路径下可能出错。
2. **防火墙**：机房部署需放行 8124 入站（仅容器访问时只放行本机即可）。
3. **字幕位置**：默认全画面识别，画面里的台标/水印也会被识别出来。字幕位置固定时建议用 `crop` 限定区域，既快又准。
4. **竖排/艺术字**：PP-OCRv6 small 对常规横排字幕效果好；艺术字、极低分辨率会掉准确率，
   可换 medium 模型（需另行下载）。
5. **并发**：内部串行执行（CPU 推理，加锁），多个视频请排队调用，不要并发压满。
6. **临时文件**：每次请求在系统临时目录建工作目录，处理完自动删除。

## 七、与 FunASR 包的区别

| | funasr-portable | ocr-portable |
| --- | --- | --- |
| 识别对象 | 声音（语音转字幕） | 画面（印在画面上的文字） |
| 端口 | 8123 | 8124 |
| 接口 | `POST /v1/audio/transcriptions`（OpenAI 兼容） | `POST /ocr` |
| 输出 | 语音字幕 | 画面文字字幕 |

两者可同时运行，互不干扰。