Yueying – Let AI watch videos

yueying — 让 AI 观看视频

将 Claude、Cursor 或任何 MCP 客户端连接到视频，即可获得带时间戳的转录文本和关键帧联系表——离线运行，无需 API 密钥。 优先处理本地文件；URL（YouTube、Bilibili、Douyin、Xiaohongshu、TikTok、Vimeo 等）仅限处理你有权处理的视频，通过 yt-dlp 以 ≤720p 获取，默认在处理后删除。

中文说明 ↓

Yueying（阅影）意为“阅读视频”。一个软件包即可提供 MCP 服务、CLI 和 Agent 技能。

你将获得什么

连接了 yueying 的 Claude Desktop：粘贴链接，等待约 40 秒，即可获得视频的时间戳笔记。该视频自带字幕，因此无需运行语音识别，模型只请求了转录文本。需要查看画面时，关键帧和联系表会通过 get_frames 返回。演示视频：GitInGifs: Git Branches，由 GitLab 制作，采用 CC BY 许可。

一段 24 秒演示视频的联系表（四张应用截图，配有中文旁白）。每个画面上的黄色标签都是关键帧编号和时间戳；模型会在回复中引用这些信息。

同一视频的转录文本——使用本地语音识别，自动检测语言为中文：

[00:00] 这是阅读,一个安静的桌面小说阅读器。整本书连续滚动,按段落记住进度。
        第二个画面是桌面模式,窗口变透明,只留文字浮在桌面上。
        第三个画面是伪装皮肤,一键变成代码编辑器。
        最后是伪装成表格的样子。

（这款应用名为月读；ASR 将其同音词识别成了“阅读”。语音识别有时会把名称识错，模型会根据画面中的文字进行纠正。）

每个视频都会生成一个文件夹：

report.md          index for the model: metadata, chapters, contact sheets, keyframes, transcript
transcript.txt     paragraphs with [mm:ss] timestamps
transcript.srt     subtitles for any player
grid_01.jpg …      3x3 contact sheets, 9 keyframes each, in time order
frames/            full-size keyframes, e.g. f003_00m15s.jpg
manifest.json      machine-readable result (paths, segments, chapters, options)

为什么选择 yueying

• 优先使用字幕，仅在需要时才用 Whisper。 有平台字幕时就使用字幕；否则使用本地 faster-whisper：NVIDIA GPU 上使用 large-v3-turbo，CPU 上使用 small，并自动回退到 CPU——不会上传任何内容，也无需密钥。
• 内置 ffmpeg。 在 Windows 11 上开箱即用（imageio-ffmpeg）；无需折腾 PATH。
• 节省 token。 在场景切换处提取关键帧，剔除近似重复帧，再将其整理成带有嵌入式时间戳的 3x3 联系表。每张联系表包含九个时刻，约占 1–2K token；每份转录文本按 [mm:ss] 分段。
• 支持中文平台及其他平台。 Bilibili（分 P 视频、合集、使用浏览器登录状态访问的会员视频）、Douyin、Xiaohongshu，以及 YouTube、TikTok、Vimeo、X 和 yt-dlp 支持的所有其他网站。
• 无需 API 密钥，不收集遥测数据。 唯一的网络流量来自你指定的视频网站，以及一次 Whisper 模型下载。请参阅隐私政策。

基准测试：一段 6 分钟的 Bilibili 视频，在 RTX 5060 笔记本上约 90 秒即可生成报告；在 CPU 上使用 model=small 时，每 10 分钟语音预计耗时约 1–2 分钟。

快速开始

1. 安装 uv（无需安装 Python）：

   winget install astral-sh.uv                         # Windows
   brew install uv                                     # macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh     # Linux / macOS
   

2. 预热并进行一次全面检查（安装软件包、检测 GPU、下载语音模型、运行 2 秒冒烟测试，并打印可供粘贴的配置）：

   uvx yueying mcp --setup
   

3. 将服务添加到客户端（见下文），然后询问：“监控 C:\videos\lecture3.mp4，并将步骤整理成笔记” 或 *“这个视频关于 docker compose 说了什么：https://www.bilibili.com/video/BV…”*。

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）· ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。之后完全退出并重新打开 Claude。

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Windows 注意事项：Claude Desktop 不一定能获取你的 PATH——如果服务启动失败（“spawn uvx ENOENT”），请使用绝对路径，例如 "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe"（运行 where uvx 可查看路径）。日志：%APPDATA%\Claude\logs\mcp-server-yueying.log（macOS 上为 ~/Library/Logs/Claude/）。请保持其中的 wait_seconds 为默认值；参见运行规则。

Claude Code

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

或者将此仓库的 .mcp.json 放入项目中（其中附带 "timeout": 1800000，因此一次 watch_video 调用可以等待较长的视频）。若要全局提高 Claude Code 的工具超时时间，请在环境中设置 MCP_TOOL_TIMEOUT=1800000（毫秒）。该仓库也是一个 Claude Code 插件（.claude-plugin/plugin.json：服务 + 技能）。

Cursor

点击上方的 添加到 Cursor 徽章，或将相同的 JSON 放入 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Cline

MCP Servers → Configure（cline_mcp_settings.json）。timeout 的单位是秒；五个只读工具可以安全地设为自动批准。分步 Agent 操作说明：llms-install.md。

{
  "mcpServers": {
    "yueying": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yueying", "mcp"],
      "env": { "PYTHONUTF8": "1" },
      "timeout": 1800,
      "autoApprove": ["get_transcript", "search_transcript", "get_frames", "get_frame_at", "list_videos"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

VS Code（Copilot Agent 模式）

点击上方的 在 VS Code 中安装 徽章，或创建 .vscode/mcp.json（注意根键 servers）：

{ "servers": { "yueying": { "type": "stdio", "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

支持自定义 URL scheme 的宿主可使用以下直接链接：cursor://anysphere.cursor-deeplink/mcp/install?name=yueying&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ5dWV5aW5nIiwibWNwIl0sImVudiI6eyJQWVRIT05VVEY4IjoiMSJ9fQ== 和 vscode:mcp/install?%7B%22name%22%3A%22yueying%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22yueying%22%2C%22mcp%22%5D%2C%22env%22%3A%7B%22PYTHONUTF8%22%3A%221%22%7D%7D。

不使用 uv（pip / pipx）和 Windows 一键安装

pip install yueying            # or: pipx install yueying
yueying mcp --setup            # prints a config with the absolute path of the yueying-mcp executable

将该绝对路径用作 "command"，且不设置 args（Windows：...\Scripts\yueying-mcp.exe；也可使用 python -m yueying mcp）。没有 Python 工具的 Windows 用户可以在检出目录中双击 install.cmd：它会创建 %LOCALAPPDATA%\yueying\venv，安装 Claude Code 技能，运行 yueying mcp --setup，并打印包含正确路径的 JSON 代码块。

GPU

uvx --from "yueying[cuda]" yueying mcp     # NVIDIA: adds the CUDA runtime wheels (cuBLAS, cuDNN)
pip install "yueying[cuda]"

设备和模型会自动选择（model=auto：CUDA 上使用 large-v3-turbo，CPU 上使用 small）；如果 GPU 测试失败，识别会自动回退到 CPU。

Docker

docker build -t yueying .
docker run --rm -i -v yueying-data:/data -v "$PWD/videos:/videos:ro" yueying

该镜像仅支持 CPU（容器默认无法使用 GPU），因此默认使用 small 模型。 以只读方式挂载视频，并向工具提供容器内路径（/videos/lesson.mp4）；结果和 下载的 Whisper 权重保存在 /data 卷中。在客户端配置中，command 为 docker，args 为 ["run", "--rm", "-i", "-v", "yueying-data:/data", "-v", "/your/videos:/videos:ro", "yueying"]。

工具

工具	Agent 使用时机	返回内容	限制
watch_video(video, mode="full", language="auto", model="auto", frame_interval_seconds=None, cookies_from_browser=None, output_dir=None, refresh=False, wait_seconds=45, max_chars=12000)	任何视频的首次调用：传入本地绝对路径或 URL。mode：full（转录文本 + 关键帧）、transcript、frames。	DONE 概览：标题、来源、时长、文本来源、文件夹、文件、章节、联系表范围、以 [mm:ss] 分段的文本；或者返回带阶段/百分比/预计时间的 RUNNING，或带通俗易懂提示的 ERROR。	最多阻塞 wait_seconds（0–1500）秒。转录文本达到 max_chars 后会截断，并提供 get_transcript 的起始时间。按视频缓存；refresh=true 会重新处理。
get_transcript(video, start="0", end=None, format="paragraphs", max_chars=8000)	概览被截断、需要指定时间范围，或要导出字幕（format="srt"）时使用。	标题 + [mm:ss] 段落 / [mm:ss-mm:ss] 片段 / SRT 区块；截断时显示 TRUNCATED — next_start="…"。	max_chars 为 1000–100000。时间格式：秒、mm:ss、h:mm:ss。
search_transcript(video, query, context_seconds=15, limit=10)	“他什么时候提到 X？”	命中结果，包含时间、周围的句子、最近的关键帧编号和联系表编号。	以空格分隔的词语，匹配任意词；匹配词越多，排名越高；limit ≤ 50。
get_frames(video, kind="grids", start=1, count=2, max_width=1280)	查看屏幕内容：先看联系表（grids），仅在需要查看细节时使用单张关键帧（frames）。	每张图像的绝对路径 + JPEG，按时间顺序排列；还有更多图像时显示 Next: get_frames(start=…)。	每次调用 ≤ 3 张图像（默认 2 张，在 Claude Desktop 中保持 ≤ 2 张）；1280 px 时每张联系表约 150 KB。
get_frame_at(video, time, max_width=960)	查看某一时刻的代码、幻灯片、图表或 UI。	精确帧（本地文件仍存在时从源文件提取）或最近的缓存关键帧，以及该时刻前后说出的段落。	一张图像，960 px 时约 100 KB。
list_videos(limit=20)	用户提到之前的视频，或需要检查磁盘使用情况时使用。	表格：video_id、标题、时长、文本来源、日期、大小、文件夹；正在运行的任务。	即时返回，只读。

读取工具中的 video 可接受 watch_video/list_videos 返回的 video_id、结果文件夹，或传给 watch_video 的相同路径/URL。

RUNNING 规则

处理可能需要几分钟，而大多数主机将工具调用时长限制在约一分钟。因此，watch_video 最多等待 wait_seconds，然后返回 RUNNING video_id=… · stage 2/4 speech recognition 40% · elapsed 46 s · est. ~1 min remaining。Agent 只需使用相同的 video 再次调用 watch_video——它会重新连接到同一任务（任务运行期间会忽略选项；refresh=true 会重新启动）。建议的 wait_seconds：

主机	wait_seconds	原因
Claude Desktop	45（默认值）	客户端硬性超时约为 60 s
Cursor	45（默认值）	60–120 s
Claude Code	最多 1500	配合 .mcp.json timeout / MCP_TOOL_TIMEOUT = 1800000 ms
Cline	最多 1500	配合 "timeout": 1800（s）

对于支持显示进度通知的主机，每 1.5 s 发送一次通知。每个服务一次处理一个视频；额外请求会排队。

**首次运行：**首次进行语音识别时会下载一次 Whisper 模型（CPU 上 small 约 480 MB，GPU 上 large-v3-turbo 约 1.6 GB）。uvx yueying mcp --setup 会提前完成此操作；否则 RUNNING 行会显示“首次运行将下载约 …，可能需要几分钟”。

文件存放位置

根目录：如果设置了 $YUEYING_OUT_DIR，则使用该目录；否则为 ~/yueying_out。每个视频对应一个条目，命名为 <slug>-<video_id>（yt-<id>、bili-<BV> 或文件名）——绝不重命名；标题保存在 manifest.json 中。

~/yueying_out/
└── bili-BV1xx-3f9a2c1e/
    ├── report.md  transcript.txt  transcript.srt  manifest.json
    ├── grid_01.jpg … grid_07.jpg
    ├── frames/            f001_00m02s.jpg …   (+ frames/extra/ for get_frame_at)
    ├── .job               only while a job runs
    └── _download/         only with YUEYING_KEEP_SOURCE=1

环境变量	含义	默认值
YUEYING_OUT_DIR	结果根目录（绝对路径，允许使用 ~）	~/yueying_out
YUEYING_MODEL	model 参数的默认值	auto
YUEYING_DEVICE	auto / cuda / cpu	auto
YUEYING_LANG	服务写入的 report.md 的语言（en/zh）	en
YUEYING_COOKIES_FROM_BROWSER	Cookie 的默认来源浏览器（chrome、edge、firefox 等）	未设置
YUEYING_KEEP_SOURCE	设为 1 时保留下载的 ≤720p 源文件到 _download/（为 URL 启用精确时刻截图）	未设置
YUEYING_MAX_JOBS	每个服务同时运行的流水线数量	1
YUEYING_JOB_TIMEOUT	每个视频的硬性时限，单位为秒	7200
HF_HOME	Hugging Face 缓存目录（Whisper 权重存放于此）	HF 默认值
HF_ENDPOINT	镜像，例如 https://hf-mirror.com	huggingface.co
PYTHONUTF8	在 Windows 上设为 1，避免乱码	—

磁盘空间：每小时视频约占 25 MB；设置 YUEYING_KEEP_SOURCE=1 后，每小时额外占用 300–600 MB。文件不会自动删除——list_videos 会显示大小；删除文件夹即可释放空间；watch_video(refresh=true) 会重新处理一个视频。编辑本地文件会改变其大小/修改时间，因此会创建一个新条目。

支持的来源

• 本地文件： ffmpeg 可读取的所有格式——mp4、mkv、mov、webm、avi、flv、ts，以及音频格式（mp3、m4a、wav 等）。仅音频输入会生成不含画面的转录文本。
• URL： yt-dlp 支持的所有网站。以 ≤720p 下载，处理后删除，除非设置了 YUEYING_KEEP_SOURCE=1。
• Bilibili： 未登录时，Bilibili 提供 480p 视频，足以查看幻灯片和代码。若需高清或会员专享视频，请传入 cookies_from_browser="chrome"（或 edge、firefox、brave、chromium、safari）；在 Windows 上请先关闭 Chrome，否则它会锁定 Cookie 数据库。多分段视频和合集：p= 链接会作为独立条目处理；CLI 的 --all 会处理全部内容。
• 不支持： 直播流或图片。短链接（b23.tv、v.douyin.com）会被处理，但不会与其长链接去重（服务本身不会解析 URL）。

还有 CLI 和 Agent 技能

yueying video.mp4
yueying "https://www.bilibili.com/video/BVxxxx" --ui-lang en
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying lesson1.mp4 lesson2.mp4 "https://www.bilibili.com/video/BVyyyy"   # several at once, one folder each + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # every part of a multi-part video / collection
yueying --install-skill                                                    # Claude Code skill -> ~/.claude/skills/yueying

默认输出：./yueying_out/<name>/（多个输入时为父文件夹）。CLI 日志行和 report.md 默认使用中文（英文请使用 --ui-lang en）；0.3 版本会将默认语言改为英文。

标记	含义
--out DIR	输出文件夹（默认 ./yueying_out/<name>；多个输入时为父文件夹）
--all	当 URL 是 Bilibili 多段视频／合集／播放列表时，处理所有条目（默认：仅处理第一条）
--lang zh	语音语言代码（zh、en、ja……）；默认自动检测
--model auto	Whisper 模型：auto / tiny / base / small / medium / large-v3 / large-v3-turbo（CLI 默认值）。auto = NVIDIA GPU 上使用 large-v3-turbo，CPU 上使用 small
--device cpu	强制使用 CPU（auto / cuda / cpu）
--interval 3	大约每 N 秒提取一张关键帧。默认值按时长决定：少于 1 分钟时为 2 秒，少于 3 分钟时为 3 秒，少于 10 分钟时为 6 秒，少于 30 分钟时为 12 秒，超过时为 20 秒
--frames 30	关键帧数量上限（默认值按时长决定，上限为 150；使用 --interval 时为 300）
--scene 0.2	场景变化灵敏度 0–1，数值越低越灵敏（默认 0.3）
--no-dedupe	保留与前一帧几乎相同的帧（默认会删除：缩略图像素变化小于 2 %）
--no-asr	即使没有字幕也不进行语音识别（仅处理画面）
--no-frames	不提取关键帧（仅处理文本）
--force-asr	即使存在字幕也运行语音识别
--cookies-from-browser chrome	使用浏览器登录信息下载（Bilibili 高清／会员视频、需要登录的 YouTube 视频）
--keep	保留下载的源视频
--ui-lang en	report.md 标题和标签的语言：zh（默认）或 en
--json	结束时打印一行清单 JSON（供脚本使用）
--install-skill	将 Agent 技能安装到 ~/.claude/skills/yueying
mcp	运行 MCP 服务（mcp --setup、mcp --check、mcp --version）

技能文件（src/yueying/skill/SKILL.md）会指导编码 Agent 优先使用可用的 MCP 工具，否则运行 CLI 并阅读 report.md 和联系表。支持 Agent Skills 标准的工具可以将 ~/.claude/skills/yueying/SKILL.md 复制到自己的技能文件夹中。

与类似项目的对比（2026 年 9 月）

	yueying	claude-video	claude-real-video	mcp-video-analyzer
MCP 服务	是	否（仅技能）	否（技能）	是（Node）
离线语音识别	是——优先使用字幕，否则使用本地 faster-whisper	云端 Whisper 备用方案	优先使用 ASR	需单独安装 whisper
GPU 自动检测 + CPU 回退	是	–	–	–
内置 ffmpeg	是	–	–	–
已在 Windows 上测试	是（Windows 11）	–	–	–
联系表（3x3）	是	–	–	–
帧上嵌入时间戳	是	–	–	–
Bilibili / Douyin / Xiaohongshu	是	–	–	–

“–”表示我们查看时该项目未宣传此功能；请查看其 README，项目可能已有更新。

隐私政策

yueying 不收集任何数据，也没有遥测、分析、崩溃报告或更新检查。所有处理都在本地进行。唯一的网络连接是：(1) 通过 yt-dlp 连接到你提供的 URL 所属视频网站；(2) 连接到 Hugging Face（或 HF_ENDPOINT）以下载一次 Whisper 模型。输出会保存在你的文件夹中，直到你将其删除。字幕文本和你请求的任何帧只会发送给你的 MCP 客户端配置使用的模型——此类传输受客户端和服务提供商的条款约束，而非 yueying 的条款。问题请提交至：GitHub issues。完整内容：docs/privacy.md。

故障排查 / 常见问题

• Claude Desktop 中显示“No result received”。 将 wait_seconds 保持为 45（此时 Agent 会再次调用 watch_video），并运行一次 uvx yueying mcp --setup，避免首次调用同时下载模型。
• spawn uvx ENOENT / 服务无法启动。 宿主无法访问你的 PATH：将 uvx 的绝对路径（where uvx / which uvx）或 yueying-mcp 的绝对路径用作 "command"。
• Windows 上控制台窗口闪现。 更新到 0.2.0+：子进程会在不显示窗口的情况下启动。如果仍能看到窗口，说明你运行的是旧安装版本（uv cache clean yueying）。
• 标题乱码 / 显示为 ?????。 在服务配置中添加 "env": { "PYTHONUTF8": "1" }（上方所有代码片段均已包含此项）。
• Bilibili 错误 412 / "-352"。 网站要求登录：设置 cookies_from_browser="edge" 或 "chrome"（在 Windows 上先关闭 Chrome）。
• YouTube 提示“Sign in to confirm you're not a bot”。 使用相同的解决方法：设置 cookies_from_browser。也可以尝试更新 yt-dlp：uv cache clean yueying 或 pip install -U yt-dlp。
• CPU 上运行缓慢。 没有 NVIDIA GPU 时，已自动选择 model="small"；如果只需要图片，请使用 mode="frames"；如果要跳过关键帧，请使用 mode="transcript"。
• 转录文本中的名称、数字和代码有误。 任何 ASR 都可能出现这种情况——系统已告知 Agent 应以屏幕上的文字为准；请让它在对应时刻调用 get_frame_at。
• 模型下载缓慢或被阻止（中国大陆）。 在服务 env 中设置 HF_ENDPOINT=https://hf-mirror.com（无法访问 huggingface.co 时，CLI 会自动切换到镜像）。
• GPU 错误（CUDA / cuDNN / 内存不足）。 设置 model="small" 或 YUEYING_DEVICE=cpu；使用 yueying[cuda] 安装 CUDA wheel。
• 想使用不同设置重新处理。 使用 watch_video(video=…, refresh=true, …)——它会终止该视频正在运行的作业、删除对应条目并重新开始。

工作原理

video / URL ──► yt-dlp (≤720p) + platform subtitles
            ──► ffmpeg 16 kHz audio ──► faster-whisper (skipped when subtitles exist)
            ──► ffmpeg scene detection ──► keyframes (near-duplicates dropped)
            ──► Pillow: burn "#n mm:ss", pack 3x3 contact sheets
            ──► report.md · transcript.txt · transcript.srt · manifest.json

MCP client ──stdio──► mcp_server.py ──spawns──► python -m yueying.cli <video> --json --ui-lang en
                       │  parses the child's progress lines, long-polls, caches per video
                       └─► store.py (cache keys / folders) · query.py (paging, search, frames)

服务进程本身不会加载 yt-dlp、Whisper 或 CUDA；所有繁重工作都由子进程执行，且该子进程会随服务一起终止。所有文件都位于 src/yueying/ 中：

文件	职责
cli.py	命令行入口；运行处理流程；分派 mcp 子命令；--install-skill
mcp_server.py	MCP 服务：六个工具、作业运行器、进度解析、DONE/RUNNING/ERROR 渲染、--setup
store.py	输出根目录、规范 URL、每个视频的缓存键和文件夹名称、.job 标记
query.py	对清单进行操作的纯函数：转录分页、搜索、最近帧、联系表范围、图像缩小
models.py	Whisper 模型名称、大小和 Hugging Face 仓库（不导入大型依赖）
download.py	yt-dlp 下载、字幕语言选择、播放列表 / 合集列表
ffm.py	ffmpeg 封装：探测、音频提取、内嵌字幕、超时处理
subs.py	srt / vtt / Bilibili JSON 字幕解析、YouTube 自动字幕去重
asr.py	faster-whisper 转录、GPU/CPU 选择、auto 模型、回退方案
frames.py	场景检测、帧时间计算、提取、去重、烧录时间戳、联系表
report.py	report.md、转录文件、manifest.json（zh/en 标签）、清单加载
skill/SKILL.md	Agent 技能

路线图

• next — 为 Claude Desktop 提供 .mcpb 一键安装包，上架 Smithery。
• 0.3 — forget_video / prune 工具、将英语设为 CLI 默认报告语言、通过 MCP 支持 --all（播放列表）。

致谢

• faster-whisper、yt-dlp、imageio-ffmpeg、Pillow
• 联系表中烧录的时间戳参考了 video-vision-mcp；基于时长的帧间隔参考了 video-analyzer-skill

许可证

MIT — 参见 LICENSE。

---

中文说明

阅影（yueying）让 AI 看懂视频。 给 Claude Desktop、Claude Code、Cursor 等支持 MCP 的工具一个本地视频文件或视频链接（B站 / YouTube / 抖音 / 小红书 …），它就能拿到带时间戳的文字稿和关键帧九宫格：字幕优先，没有字幕就本地 faster-whisper 识别，全程离线，不上传、不要 API key。链接通过 yt-dlp 以 ≤720p 下载，处理完默认删除原视频。完整文档见上方英文部分。

安装

# 1. 装 uv（不需要先装 Python）
winget install astral-sh.uv          # Windows；macOS: brew install uv
# 2. 预热：安装、探测显卡、下载模型、跑 2 秒冒烟测试、打印配置
uvx yueying mcp --setup

不用 uv：pip install yueying（有 NVIDIA 显卡再加 pip install "yueying[cuda]"），然后 yueying mcp --setup 会打印 yueying-mcp 的绝对路径。Windows 也可以下载仓库后双击 install.cmd，它会建独立环境、装 Claude Code 技能、跑 --setup 并打印可粘贴的配置。

配置

Claude Desktop（%APPDATA%\Claude\claude_desktop_config.json，改完完全退出再打开；Windows 下 uvx 找不到就写绝对路径，如 C:\\Users\\<你>\\.local\\bin\\uvx.exe）、Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）都是同一段：

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Claude Code 一行：

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

Cline 在同一段里加 "type": "stdio"、"timeout": 1800，并把 get_transcript、search_transcript、get_frames、get_frame_at、list_videos 放进 autoApprove。VS Code 的 .vscode/mcp.json 根键是 servers 并加 "type": "stdio"。

六个工具

工具	用途
watch_video(video, mode, language, model, frame_interval_seconds, cookies_from_browser, output_dir, refresh, wait_seconds, max_chars)	看一个视频：本地绝对路径或链接。返回 DONE（概览 + 文字稿）、RUNNING（进度，用同一个 video 再调一次即可继续等）或 ERROR（英文提示）。结果按视频缓存，refresh=true 重做
get_transcript(video, start, end, format, max_chars)	按时间段读文字稿；format="srt" 导出字幕
search_transcript(video, query, context_seconds, limit)	找「哪里提到了 X」，给出时间、上下文、最近的关键帧号和九宫格号
get_frames(video, kind, start, count, max_width)	看画面：先看九宫格（grids），需要细节再看单帧（frames）；每次最多 3 张
get_frame_at(video, time, max_width)	看某一时刻：代码、PPT、图表、界面；本地文件还在就精确抽帧
list_videos(limit)	列出处理过的视频（video_id、标题、时长、文字来源、日期、大小、目录）和正在跑的任务

Claude Desktop / Cursor 里 wait_seconds 保持默认 45；Claude Code / Cline 配好 timeout 后可以给到 1500，一次调用就等到结果。第一次语音识别要下载模型（CPU 约 480 MB 的 small，显卡约 1.6 GB 的 large-v3-turbo），--setup 会提前下好。

输出目录与环境变量

结果在 ~/yueying_out/<名字>-<video_id>/（YUEYING_OUT_DIR 可改），每个视频一个文件夹：report.md、transcript.txt、transcript.srt、grid_01.jpg …、frames/、manifest.json。约每小时视频 25 MB；不会自动删，删文件夹即可。常用环境变量：YUEYING_OUT_DIR（输出根目录）、YUEYING_MODEL（默认 auto：有 NVIDIA 显卡用 large-v3-turbo，否则 small）、YUEYING_DEVICE（auto/cuda/cpu）、YUEYING_LANG（服务端 report.md 语言，默认 en，中文写 zh）、YUEYING_KEEP_SOURCE=1（保留下载的原视频）、YUEYING_JOB_TIMEOUT（单个视频上限秒数，默认 7200）、PYTHONUTF8=1（Windows 防乱码）。

B站 cookie

不登录 B站 只给 480p，看 PPT 和代码够用；高清或会员视频传 cookies_from_browser="chrome"（或 edge），Windows 下先关掉 Chrome，否则读不到 cookie 数据库。遇到 412 / -352 也是同样的处理。

国内镜像

下载模型慢或被墙：在服务器配置的 env 里加 "HF_ENDPOINT": "https://hf-mirror.com"。命令行版在 huggingface.co 连不上时会自动切到镜像。

命令行用法

yueying 视频.mp4
yueying "https://www.bilibili.com/video/BVxxxx"
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying 第1课.mp4 第2课.mp4 "https://www.bilibili.com/video/BVyyyy"   # 多个一起，各出各的文件夹 + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # B站 分 P / 合集 全部处理
yueying --install-skill                                                    # 装 Claude Code 技能

默认输出 ./yueying_out/<视频名>/，日志和 report.md 默认中文（--ui-lang en 切英文）。常用参数：--lang zh 指定语言、--model small 换小模型（auto 自动选）、--device cpu、--interval 3 抽帧间隔、--frames 30 最多帧数、--scene 0.2 场景灵敏度、--no-dedupe 不去重、--no-asr 只要画面、--no-frames 只要文字、--force-asr 有字幕也识别、--cookies-from-browser chrome、--keep 保留原视频、--json 末尾打印一行 manifest。完整说明见上方英文表格。