内容
# 眼动音频 MCP
一个异步的模型上下文协议（MCP）服务器，为 AI 模型提供“眼睛和耳朵”，以处理网页视频。它从 YouTube 和其他视频平台提取字幕并捕获截图。
## 功能
- **混合字幕提取**：立即获取 YouTube 字幕，备用本地 Whisper ASR
- **按需视频截图**：在无需下载完整视频的情况下，捕获任意时间戳的帧
- **截图 OCR**：使用 Tesseract 从帧中提取可见文本（可选， `--ocr` 标志）
- **Cookie 身份验证**：通过 cookies.txt 支持年龄限制和私有视频
- **本地缓存**：处理后的视频被缓存，以便后续立即查询
- **异步架构**：非阻塞设计保持 MCP 客户端响应迅速
- **灵活输出**：剪贴板、stdout、文件或 JSON — 由您选择
## 基准测试
请参阅 [BENCHMARK.md](BENCHMARK.md) 以获取性能基准测试和与 MCP 和 CLI 生态系统中所有主要视频字幕、截图和 OCR 工具的深入竞争分析。
## 要求
- **Python 3.9+** （需要 `list[int]` 类型提示）
- **FFmpeg** （需要 yt-dlp 和 OpenCV）
- **Node.js 18+** （仅限 CLI 包装器）
- **Tesseract** （可选，仅限 `--ocr` 标志）
## 安装
### 1. 安装系统依赖项
**macOS:**
```bash
brew install ffmpeg python3
# 可选（用于 OCR）：
brew install tesseract
```
**Windows:**
```bash
choco install ffmpeg python
# 可选（用于 OCR）：
choco install tesseract
```
**Linux:**
```bash
sudo apt update && sudo apt install ffmpeg python3 python3-pip
# 可选（用于 OCR）：
sudo apt install tesseract-ocr
```
### 2. 安装 Python 包
```bash
pip install -r requirements.txt
```
或手动：
```bash
pip install mcp youtube-transcript-api yt-dlp opencv-python-headless faster-whisper requests pytesseract
```
### 3. 安装 Node.js CLI（可选）
```bash
npm install
```
## 使用
### 选项 A：MCP 服务器（推荐）
MCP 服务器为 AI 模型提供直接访问视频字幕和截图的功能。
**快速安装** — 无需安装。只需将配置添加到下面的 MCP 客户端即可。
#### Claude Desktop
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）
#### Cursor
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`.cursor/mcp.json` （项目）或 `~/.cursor/mcp.json` （全局）
#### Claude Code
```bash
claude mcp add ocular-audio-mcp -- npx ocular-audio-mcp
```
#### Codex CLI（OpenAI）
```bash
codex mcp add ocular-audio-mcp -- npx ocular-audio-mcp
```
#### Gemini CLI
```bash
gemini mcp add ocular-audio-mcp npx ocular-audio-mcp --scope user
```
#### Windsurf
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`~/.codeium/windsurf/mcp_config.json`
#### Zed
```json
{
"context_servers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`~/.config/zed/settings.json`
#### VS Code（GitHub Copilot）
```json
{
"servers": {
"ocular-audio-mcp": {
"type": "stdio",
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`.vscode/mcp.json`
#### OpenCode
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
配置：`~/.opencode/config.json`
#### Cline（VS Code 扩展）
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "npx",
"args": ["ocular-audio-mcp"]
}
}
}
```
#### 本地开发（从源代码）
```json
{
"mcpServers": {
"ocular-audio-mcp": {
"command": "python",
"args": ["/path/to/ocular_audio_mcp.py"]
}
}
}
```
### 选项 B：CLI
```bash
npx ocular-audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```
默认情况下，字幕将被打印到 stdout 并复制到剪贴板。将其粘贴到 Claude Web、ChatGPT 或任何 AI 聊天中。
#### CLI 选项
| 标志 | 描述 |
|------|-------------|
| `-h`, `--help` | 显示帮助信息 |
| `-v`, `--version` | 显示版本号 |
| `--stdout` | 仅将字幕打印到 stdout（不复制到剪贴板，不保存到文件） |
| `--no-clipboard` | 跳过复制到剪贴板 |
| `--output <file>` | 将上下文写入特定文件路径 |
| `--json` | 输出原始 JSON（元数据 + 字幕）以便编程使用 |
| `--detail <level>` | 截图捕获模式：`overview`, `balanced`, `deep`, `auto` （默认：`auto`） |
| `--ocr` | 使用 Tesseract OCR 从截图中提取文本 |
| `--force` | 绕过缓存并重新处理视频 |
| `--verbose` | 显示详细的进度信息 |
| `--quiet` | 禁止摘要和状态消息 |
| `--check` | 检查系统依赖项（Python、FFmpeg、Whisper、Tesseract） |
| `--list-cached` | 列出所有缓存的视频及其标题 |
| `--cache-info` | 显示缓存统计信息（计数、大小、最旧/最新） |
| `--clear-cache` | 删除所有缓存的字幕和截图 |
#### 示例
```bash
# 基本用法 — 打印到 stdout + 复制到剪贴板
npx ocular-audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 仅 stdout — 适用于管道传输到其他工具
npx ocular-audio --stdout "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | head -50
# 写入特定文件
npx ocular-audio --output transcript.txt "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 原始 JSON 以便编程使用
npx ocular-audio --json "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | jq .metadata.title
# 仅字幕，无截图
npx ocular-audio --detail overview "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 最大截图
npx ocular-audio --detail deep "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 不复制到剪贴板，仅打印到终端
npx ocular-audio --no-clipboard "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 截图 OCR — 从帧中提取可见文本
npx ocular-audio --ocr "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# JSON 输出与 OCR
npx ocular-audio --json --ocr "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 强制重新处理（绕过缓存）
npx ocular-audio --force "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 详细模式 — 查看所有进度详细信息
npx ocular-audio --verbose "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 静默模式 — 最小化输出
npx ocular-audio --quiet --stdout "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 检查系统功能
npx ocular-audio --check
# 列出缓存的视频
npx ocular-audio --list-cached
# 显示缓存统计信息
npx ocular-audio --cache-info
# 清除所有缓存数据
npx ocular-audio --clear-cache
```
## Cookie 设置（适用于年龄限制/私有视频）
YouTube 可能会阻止对年龄限制或私有视频的字幕访问。要解决此问题，请导出浏览器 cookie：
1. 安装浏览器扩展程序，如“Get cookies.txt LOCALLY”（Chrome/Firefox）
2. 登录 YouTube 时访问 youtube.com
3. 将 cookie 导出到名为 `cookies.txt` 的文件中
4. 将文件放在以下位置之一：
- `~/.cache/ocular_audio_mcp/cookies.txt`
- `~/.config/ocular_audio_mcp/cookies.txt`
- `./cookies.txt` （在项目目录中）
服务器将自动检测并使用 cookie 文件。
## MCP 工具
### `get_ocular_audio_capabilities`
返回系统功能和依赖状态。使用此功能检查可用功能。
**参数：** 无
**返回：** 包括 Python 版本、FFmpeg、Whisper、Tesseract、OpenCV 和 cookie 状态在内的系统信息。
### `get_ocular_audio_metadata`
仅提取视频元数据（标题、创作者、时长、浏览量、章节），无需字幕。比获取完整字幕快得多。
**参数：**
- `url` （字符串）：视频 URL
### `get_ocular_audio_transcript`
从视频中提取完整的字幕、视频章节和元数据。
**参数：**
- `url` （字符串）：视频 URL
- `use_local_whisper` （布尔值，默认：true）：如果字幕不可用，则启用 Whisper 备用
### `get_ocular_audio_chapters`
仅提取带有时间戳的视频章节。返回章节标题，起始时间以 [MM:SS] 格式显示。
**参数：**
- `url` （字符串）：视频 URL
### `get_ocular_audio_video_screenshots`
在特定时间戳捕获截图。
**参数：**
- `url` （字符串）：视频 URL
- `timestamps_secs` （整数数组）：要捕获的时间戳（例如， `[45, 120, 300]`）
- `enable_ocr` （布尔值，默认：false）：如果为 true，则对每个捕获的帧运行 OCR 以提取可见文本
### `get_ocular_audio_video_context`
一次性提取字幕、元数据和智能截图。自动分析字幕以查找视觉上重要的时刻，并在这些时间戳处捕获截图。
**参数：**
- `url` （字符串）：视频 URL
- `detail_level` （字符串，默认：“auto”）：控制截图捕获模式：
- `"auto"` - 根据视频长度和内容重要性进行适配
- `"overview"` - 仅字幕和元数据，无截图（最快）
- `"balanced"` - 仅在视觉上重要的时刻截图（强信号）
- `"deep"` - 在每个视觉上显著的时刻截图（所有信号）
- `use_local_whisper` （布尔值，默认：true）：如果字幕不可用，则启用 Whisper 备用
- `enable_ocr` （布尔值，默认：false）：如果为 true，则对捕获的截图运行 OCR 以提取可见文本
### `list_ocular_audio_cache`
列出所有缓存的视频及其元数据（标题、上传者、时长、缓存时间）。
**参数：** 无
### `clear_ocular_audio_cache`
清除缓存的视频数据。
**参数：**
- `video_id` （字符串，可选）：视频 ID，用于清除特定视频。如果为空，则清除所有缓存。
## 缓存管理
处理后的视频缓存在 `~/.cache/ocular_audio_mcp/` 中，时长为 7 天。使用 CLI 标志管理缓存：
```bash
npx ocular-audio --list-cached # 查看已缓存的内容
npx ocular-audio --cache-info # 存储统计信息
npx ocular-audio --clear-cache # 清除所有缓存
```
或手动：
```bash
rm -rf ~/.cache/ocular_audio_mcp/*.json
```
## 故障排除
### “未找到本地 ASR 引擎”
安装 Whisper 引擎：
```bash
pip install faster-whisper
```
### “音频轨道下载失败”
- 检查您的网络连接
- 对于年龄限制的视频，请添加 cookies.txt 文件（参见上面的 Cookie 设置）
- 确保 FFmpeg 已安装：`ffmpeg -version`
### “无法提取可播放的视频流”
- 视频可能是私有的或被地理封锁
- 尝试添加 cookies.txt
- 检查视频是否仍然可用
### Windows 上未找到 Python
确保 Python 在您的 PATH 中。尝试：
```bash
python --version
```
如果未找到，请从 python.org 重新安装 Python，并在安装过程中选中“将 Python 添加到 PATH”。
### MCP 服务器未连接
- 验证您的 MCP 客户端配置中的路径是否正确
- 手动测试服务器：`python /path/to/ocular_audio_mcp.py`
- 检查所有依赖项是否已安装：`pip list | grep -E "mcp|whisper|yt-dlp"`
## 许可证
MIT
