VideoNote-Mcp 把「视频链接 → 多格式笔记」整条流水线打包成 MCP Server + Claude Code Skill：给 agent 一个链接，它自动完成 下载 → 语音转写 → 画面理解 → 弹幕/评论 → AI 总结，交回一篇带截图、可整体搬迁的便携笔记。

仓库：HuangYincan/VideoNote-MCP。

本项目既可端到端使用（一条链接 → 一篇笔记），也可解耦：流水线每一阶段（下载 / 转写 / 抽帧 / 评论 / 总结 / 导出 / 增强 / 清理）都是独立 MCP 工具，想只用某一步、或只想了解视频内容，都能满足。无需启动任何后端服务。

⚡ 快速开始

# 1) 一条命令装好 Skill + MCP（插件 marketplace，uvx 自动更新）
claude plugin marketplace add HuangYincan/VideoNote-MCP
claude plugin install videonote@videonote

# 2) 安装时 Claude Code 会逐项提示默认值（风格/转写引擎/视频理解/评论等）；
#    装完在会话里跑配置向导收尾：
/videonote-setup

# 3) （可选）LLM-Key/B 站扫码/CLI向导
# ! videonote setup

# 4) 重启会话，对 agent 说「帮我给这个视频做笔记」+ 链接

Related MCP server: tldw-mcp

📚 文档

安装 / 配置 / 使用 / 环境变量 / 更新 / 安全等完整说明已归档到 docs/（README 只保留概览）：

• 📇 文档索引

• 🏗️ 架构设计

• 📖 使用手册 —— 安装（4 种方式）· 配置（setup 向导 + CLI）· 环境变量 · 更新 · 安全

• 📜 更新日志

🎬 真实案例

两个端到端真实案例：一个走 AGENT 直接生成并输出 LaTeX mathnote PDF，一个走 全自动 LLM 生成产出便携 Markdown。

案例一 · agent_direct + LaTeX mathnote（DeepSeek-V4 视频）

来源：【闪客】深入解读 DeepSeek V1~V4！男女老少都听得懂～

一条视频 + 四类外部资料（论文 / 技术报告 / 公众号官宣 / 开源集合）→ AGENT 直接生成精修笔记，并输出 LaTeX mathnote PDF（中文楷体模板）：

亮点：agent_direct 全流程（无 LLM key，Agent 读转写 + 帧图 + 评论自写笔记）· 多源交叉整合（视频 × 论文 × 技术报告 × 开源清单）· 精修保留原稿（note.md / note_original.md 双份）· LaTeX mathnote PDF（自适应修复字体缺失 / 断行溢出 / 引用去重）。完整过程记录见 examples/agent-direct-deepseek-v4-mathnote/README.md。

案例二 · 全自动 LLM 生成 + 便携 Markdown（多视频并行）

极简 Prompt（3 个 B 站链接 + 输出目录，一个参数都没说明）→ 全自动跑完 环境检查 → 链接识别 → 供应商/模型发现 → 参数确认 → 多视频并行 → 生成后基于字幕精修，产出 3 份精修便携笔记（note.md + Assets/ 截图 + 「观众观点」章节，并保留 note_original.md 供对比）。

• 雅思：破误区 + 听/读/写/口语四科拆解 + 179 高频考点词 + 15 句逻辑框架

• 法医：从业 43 年法医「拉片」对比影视与现实，精修扩为 12 节

• Transformer：自注意力机制详解，18 张截图按讲课时间线分布

完整过程记录见 examples/note-generation-example/README.md。

🗺️ 流水线地图

flowchart LR
    A["视频链接"] --> B["下载音视频<br/>+ 平台字幕"]
    B --> C["语音转写<br/>或直接用平台字幕"]
    B -. 可选 .-> D["逐帧画面理解<br/>关键帧 → 网格图"]
    B -. 可选 .-> E["弹幕 + 评论区"]
    C --> F["素材包<br/>转写 · 帧 · 评论"]
    D -.-> F
    E -.-> F
    F --> G["AI 总结 → Markdown 底稿<br/>正文 + 截图 + 「观众观点」"]
    G --> O1["便携笔记<br/>note.md + Assets/"]
    G --> O2["字幕导出<br/>SRT · VTT · JSON"]
    G -. Agent 生成 .-> O3["创意格式<br/>思维导图 · 闪卡 · LaTeX · typst"]
    G -. 可选 .-> O4["基于完整字幕精修<br/>保留原版对比"]

0 🔄 端到端全流程

端到端模式只给一条链接即可：generate_note 异步跑完整条流水线并返回 task_id；用轻量 get_task_status 快照轮询到 SUCCESS/FAILED/CANCELLED（单进程最多 3 个进行中任务，不要在同一消息里并行提交）。cancel_note 协作式取消。「AGENT 直接生成」走 prepare_note_material —— 只准备素材包、不调用配置 LLM，由 agent 自己读转写、看图、写笔记。

1 📥 下载与平台解析

inspect_video 识别平台（bilibili / youtube / douyin / tiktok / kuaishou / local；内置 6 平台之外返回 platform:"generic" 自动走 yt-dlp 通用提取覆盖 1800+ 站点）+ 检查链接有效性（无效直接给原因）+ 把 B 站分 P / YouTube 播放列表拆成每集可独立提交的 url（不下载）。平台 Cookie 走 ! videonote login bilibili / ! videonote setup，不要经 MCP 传入。平台字幕（含 B 站 AI 字幕）由 generate_note 内部优先使用，无独立工具。

2 🎙 语音转写（ASR）

语音转写（ASR）由 generate_note 内部完成：优先平台字幕（含 B 站 AI 字幕），无字幕则转写。引擎可选：fast-whisper（本地）/ groq / bcut / kuaishou（云端）/ mlx-whisper（macOS Apple Silicon GPU）/ funasr（中文最优，VAD + 自动标点）。引擎与模型管理走 CLI：! videonote transcriber set/download；状态查看 get_config()。

3 🖼️ 视频画面理解（抽帧）

generate_note 直接支持视频理解参数：video_understanding=True + video_interval（默认 6s）+ grid_size（默认 [3,3]），把网格图发给多模态 LLM「看」画面。

4 💬 弹幕与评论

generate_note 加 include_comments=True + comments_limit（默认 20）会把弹幕刷屏与评论区高频观点整理进笔记，新增「观众观点」章节（需 B 站 SESSDATA；抓取失败不阻断任务）。

5 ✍️ AI 总结与笔记

支持 9 种风格：minimal / detailed / academic / tutorial / xiaohongshu / life_journal / task_oriented / business / meeting_minutes；format=["screenshot"] 产出便携笔记（note.md + Assets/，相对引用可整体搬迁）。供应商/模型/转写器配置一律走 CLI（! videonote providers set / ! videonote transcriber set），只读查看 get_config()。agent_direct 由 AGENT 直接生成。

6 📤 多格式导出

机械格式用 export_transcript（srt / vtt / json）—— 确定性渲染（时间轴换算），不耗 LLM，返回 file:// 路径。创意格式（思维导图 / 闪卡 / LaTeX / typst / 用户自定义模板）由 Agent 基于 MD 底稿 + SKILL 模板生成（LaTeX 内置 Math Note / English Article 模板：数学/理工科笔记风、英文文稿/演讲大纲风；typst 内置 zju-lab 模板：理工科笔记/实验报告/论文风、带 ZJU 校徽）。

7 🎛️ 音频增强

merge_audio 把多段录音 / 会议分段 / 多个本地视频合并为 16kHz mono wav 再转写。音频预处理（16kHz 归一 + 超长 >1800s 自动分块，可选降噪）默认关、零硬依赖。diarize_media 做说话人分离（pyannote 可选重依赖，需 HF_TOKEN + 模型授权）。

8 🗂️ 任务管理与清理

每任务一个文件夹 note_results/{task_id}/：raw/（下载媒体）+ gen/（转写/笔记/帧/导出）+ 控制文件；全局任务索引在 SQLite video_tasks 表（含语义标题）。list_tasks 枚举全部任务（按语义标题识别）、cleanup_note(dry_run=True) 先查后清、cleanup_note / cleanup_all 按任务 / 全局清理（默认保留配置与模型）、health_check 检查 FFmpeg / 数据库 / whisper 就绪。

flowchart TB
    DATA["data/ 数据根"] --> R["note_results/ 任务目录"]
    DATA --> DB[("video_note.db<br/>SQLite 全局任务索引")]
    R --> T1["任务 A<br/>note_results/{task_id}/"]
    R --> T2["任务 B<br/>…"]
    R --> T3["任务 C<br/>…"]
    T1 --> RAW["raw/ 原始材料<br/>音视频 · 封面"]
    T1 --> GEN["gen/ 生成材料"]
    T1 --> CTRL["status.json · result.json · manifest.json"]
    GEN --> T1A["transcript.json 转写全文"]
    GEN --> T1B["note.md 成稿笔记"]
    GEN --> T1C["Assets/ 笔记内截图"]
    GEN --> T1D["frames/ 关键帧原图"]
    GEN --> T1E["srt / vtt / json 字幕导出"]
    DB -. 索引 .-> T1

🏆 最佳实践

• 学习备考：端到端 + 视频理解 + 基于字幕的后续优化，把课程讲透。

• 会议纪要：merge_audio 合并分段录音 → diarize_media 说话人分离 → meeting_minutes 风格。

• 讲座精读：端到端生成后，agent 基于完整字幕精修、按章节补齐细节。

• 视频赏析：开启弹幕 + 评论整合，笔记含「观众观点」章节。

• 端到端：一条链接用 generate_note（下载/转写/总结/评论全流程内部完成）；只准备素材用 prepare_note_material。

• 真实案例：完整案例过程记录见 examples。

🤝 如何贡献

• 功能分支 → PR → dev（CI 冒烟必须绿）；dev 稳定后 PR → main（保护分支，需 review）。

• 流程、分支命名与提交前自查见 CONTRIBUTING.md。

🙏 致谢

感谢社区与所有贡献者，感谢 Glama 对 MCP server 的收录，以及所有开源依赖与上游流水线项目的启发。