video-ocr-to-text — 视频画面文本提取（本地 OCR，零 token）
概述
本技能提供一套纯本地的视频画面文字提取流水线：给定视频链接或本地视频文件，自动下载（仅链接场景）→ 均匀抽帧 → 本地 OCR（tesseract）→ 输出逐帧文本与去重清单。
核心特性：
- 多平台链接支持：抖音（含短链 v.douyin.com/xxx）、快手、B站、YouTube 等。抖音走专用解析；其余平台走 yt-dlp。
- 本地视频支持：直接传入 .mp4/.mkv/.mov 等本地路径，跳过下载。
- 零 token 消耗：全程仅调用本地二进制（ffmpeg / tesseract）与本地 Python 库（opencv / numpy / pytesseract），不调用任何大模型、视觉 API 或云端转录服务。
- 公式友好：对帧做放大 + Otsu 二值化，并对公式密集区补做多 PSM 模式识别，适合提取数学/量化表达式。
适用场景
- 提取短视频/网课中烧录在画面上的字幕、公式、PPT 文字（抖音知识类视频常见）。
- 提取图表、表格、成绩单等画面标注文字。
- 需要批量把视频帧转为可检索文本，且不允许产生 API 费用 / token 消耗。
> 注意：本技能只提取画面可见文字。若视频仅有"语音口播"而无烧录字幕，需改用本地语音识别（见 references/advanced.md 的 Whisper 扩展），那同样零 token，但不在本技能默认流程内。
依赖项
运行环境需具备以下本地工具/库（均为免费、开源、离线可用）：
| 依赖 | 用途 | macOS 安装 | Ubuntu 安装 |
|---|---|---|---|
ffmpeg |
下载视频 / 抽帧 | brew install ffmpeg |
apt install ffmpeg |
tesseract (>=5) |
OCR 引擎 | brew install tesseract |
apt install tesseract-ocr |
tesseract-lang |
中文等语言包 | brew install tesseract-lang |
apt install tesseract-ocr-chi-sim tesseract-ocr-chi-tra |
| Python 3.10+ | 运行脚本 | 系统自带 / brew install python |
系统自带 |
opencv-python-headless |
视频解码 / 图像处理 | pip install opencv-python-headless |
同左 |
numpy |
数组运算 | pip install numpy |
同左 |
pytesseract |
tesseract 的 Python 封装 | pip install pytesseract |
同左 |
yt-dlp（可选） |
非抖音平台链接下载 | brew install yt-dlp |
pip install yt-dlp |
安装示例（macOS，使用 WorkBuddy 管理的 Python venv）：
brew install ffmpeg tesseract tesseract-lang yt-dlp
/Users/kimbalhuang/.workbuddy/binaries/python/versions/3.13.12/bin/python3 -m venv /Users/kimbalhuang/.workbuddy/binaries/python/envs/video-ocr
/Users/kimbalhuang/.workbuddy/binaries/python/envs/video-ocr/bin/pip install opencv-python-headless numpy pytesseract
> 校验：tesseract --list-langs 应能看到 chi_sim；python -c "import cv2,pytesseract" 不应报错。
Token 消耗说明（重要）
| 步骤 | 调用对象 | 是否消耗 token / 费用 |
|---|---|---|
| 解析视频直链 | 本地 curl / ffmpeg |
否（仅网络流量） |
| 抽帧 | 本地 opencv |
否 |
| OCR 识别 | 本地 tesseract |
否（CPU 计算，零费用） |
| 文本汇总 | 本地 Python | 否 |
- 本技能完整流程全程零 token、零 API 费用。 唯一的"成本"是本地 CPU 时间与磁盘 IO。
- OCR 对希腊字母（μ/σ/Σ/λ/α/β）、上下标、数学符号常有误读，需人工或后续脚本校正（见下）。
- 若你额外用 LLM 对 OCR 结果做清洗、纠错或把语音转写，那一步会产生 token——但那属于可选增强，不在本技能默认范围内，文档中明确标注。
用法
方式 A：作为 Skill 被调用
当用户给出视频链接或本地视频并希望"提取画面文字 / 公式 / 字幕"时，加载本技能，然后执行 scripts/extract_text.py。
方式 B：直接命令行
# 1) 抖音短链
python scripts/extract_text.py --input "https://v.douyin.com/9xc6Ca5fxz4/" \
--lang chi_sim+eng --out ./output
# 2) 其他平台链接（走 yt-dlp）
python scripts/extract_text.py --input "https://www.bilibili.com/video/BVxxxx" \
--lang chi_sim+eng --out ./output
# 3) 本地视频文件
python scripts/extract_text.py --input "./lecture.mp4" --out ./output
参数说明：
| 参数 | 默认值 | 说明 |
|---|---|---|
--input |
必填 | 视频 URL 或本地文件路径 |
--lang |
chi_sim+eng |
tesseract 语言包，如 eng / chi_sim+eng / jpn |
--interval |
0.7 |
抽帧间隔（秒），越小帧越密、越慢 |
--upscale |
2 |
帧放大倍数，公式密集建议 3 |
--out |
当前目录 | 输出目录，生成 <stem>.ocr.json 与 <stem>.ocr.md |
--keep-video |
关 | 保留下载的视频（默认下载后处理完即删） |
输出格式
在 --out 目录生成两个文件：
<stem>.ocr.json：结构化结果，含meta（fps/帧数/时长）、frames（逐帧 OCR 文本）、lines（去重后的全部文本行，带时间戳）。<stem>.ocr.md：可读报告，含逐帧文本与去重清单，便于人工校正与归档。
局限与优化建议
- 画面公式：tesseract 对数学符号识别弱。建议
--upscale 3并对失败片段用references/advanced.md的多 PSM 补识别脚本。 - 纯语音视频：画面无文字时输出为空，需接本地 Whisper（见 advanced.md）。
- 平台防盗链：抖音链接偶发短期失效；B站/YouTube 需
yt-dlp最新版。 - 长视频：
--interval调大以减少帧数；或先ffmpeg截取关键时间段再传入。
排错
tesseract is not installed→ 安装 tesseract 并确认在 PATH。chi_sim不可用 → 安装tesseract-lang（macOS）或tesseract-ocr-chi-sim（Ubuntu）。- 抖音解析报
ROUTER_DATA缺失 → 链接失效或被限流，换用桌面端分享链接或手动传本地文件。 - 其他平台下载失败 → 确认
yt-dlp已装且为最新：yt-dlp -U。
