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。