video-note

video-note 是一个本地优先的 Agent Skill：从 Bilibili、YouTube、抖音、快手等视频获取字幕或执行本地转录，再由 Codex 等支持 Agent Skills 的 Agent 生成带时间戳、关键帧和证据文件的 Obsidian Markdown 笔记。

English

特点

• 字幕优先：尽量避免下载完整音视频。
• 本地回退：无字幕时可使用 faster-whisper，不要求额外 LLM API Key。
• 多平台：支持 Bilibili、YouTube，以及由 yt-dlp 处理的抖音、快手等平台。
• 深度笔记：支持课程、教程、研究报告、项目讲解、访谈等模板。
• 长视频：语义分块、逐块覆盖和可恢复的精修包。
• 视觉证据：关键帧筛选、封面、可选 OCR 和 Obsidian 图片引用。
• 质量门禁：检查章节覆盖、时间戳、图片、MathJax 和详细笔记结构。
• 可追溯：保存 transcript、metadata、manifest、质量报告和版本历史。

项目状态

首个公开版本定位为 Windows-first beta。字幕接口和视频网站访问策略可能随平台变化；抖音、快手及部分受限内容可能需要用户自己的登录 Cookie。请只处理你有权访问和使用的内容。

目录

skills/video-note/
├── SKILL.md
├── agents/openai.yaml
├── scripts/
├── references/
├── config.example.json
├── requirements.txt
├── requirements-whisper.txt
├── LICENSE
└── THIRD_PARTY_NOTICES.md

仓库级 README、许可证、CI 和测试与实际 Skill 分离。安装时只需要 skills/video-note/。

环境要求

• Python 3.11+
• FFmpeg：关键帧和音频处理需要
• yt-dlp：多平台元数据、字幕和音频回退需要
• faster-whisper：无字幕时的本地转录，可选
• Tesseract：关键帧 OCR，可选

安装核心依赖：

python -m pip install -r skills/video-note/requirements.txt

启用本地 Whisper 回退：

python -m pip install -r skills/video-note/requirements-whisper.txt

FFmpeg 和 Tesseract 是系统级可执行文件，不由上述 requirements 安装。

安装 Skill

下载或克隆仓库后，将 skills/video-note 复制到 Agent 的全局 Skill 目录。

Codex（PowerShell）：

Copy-Item -Recurse -Force .\skills\video-note "$env:USERPROFILE\.codex\skills\video-note"

Claude Code（PowerShell）：

Copy-Item -Recurse -Force .\skills\video-note "$env:USERPROFILE\.claude\skills\video-note"

macOS/Linux：

cp -R ./skills/video-note ~/.codex/skills/video-note

重启对应 Agent，使其重新发现 Skill。

使用

安装后直接向 Agent 提供视频链接，例如：

请用 $video-note 把这个视频整理成详细的 Obsidian 学习笔记：<视频链接>

也可以直接运行一键脚本：

python skills/video-note/scripts/generate_note.py "<视频链接>" --vault "<Obsidian Vault>" --keyframes

脚本生成初稿、附件和 manifest；精修流程由 SKILL.md 指导 Agent 读取 transcript 与关键帧后完成。默认不会覆盖已有笔记。

Obsidian 落盘

所有 Vault 使用同一套默认规则，不根据 Vault 名称或相邻目录猜测用户的文件结构：

• 笔记写入 <Vault>/VideoNotes/
• 每篇笔记的附件写入同级 <笔记名>.assets/
• 运行中间文件写入系统临时目录下的 video-note/runs/
• transcript 缓存写入系统用户缓存目录

可分别使用 --notes-dir、--attachments-dir、--work-dir 和 --cache-dir 覆盖这些目录。

Cookie 与隐私

公开内容优先无 Cookie 访问。确实需要登录态时，复制示例配置并只在本地填写：

不同平台和浏览器的 Cookie 获取方式不同，请自行搜索“<平台> <浏览器> 导出 Cookie”等关键词。本项目不提供 Cookie 获取教程，也不推荐来源不明的浏览器扩展或脚本。

Copy-Item skills\video-note\config.example.json skills\video-note\config.local.json

推荐通过标准输入保存，避免 Cookie 进入 shell 历史：

Get-Clipboard | python skills\video-note\scripts\save_cookies.py bilibili --stdin

config.local.json、缓存、字幕、音视频、关键帧和生成笔记都已被 .gitignore 排除。发布前仍应运行敏感信息扫描，不要只依赖忽略规则。

测试

运行离线单元测试：

python -m unittest discover tests -v

检查 Python 语法：

python -m compileall -q skills/video-note/scripts tests

在线平台回归默认关闭。只有在明确接受联网访问、速率限制和平台差异时才运行：

python skills/video-note/scripts/run_platform_regression.py --out-dir ./regression-output --live

与 BiliNote 的关系

本项目参考了 JefferyHcool/BiliNote 的平台识别、字幕优先和失败回退思路，但不运行其 FastAPI 后端，也不调用其模型供应商生成链路。本项目不是 BiliNote 官方项目。

具体归属和许可证见 THIRD_PARTY_NOTICES.md。Skill 安装包内也保留了相同的许可证与第三方声明。

许可证与合规

项目采用 MIT License。视频、字幕、封面和关键帧可能受平台条款及内容版权保护；本仓库不提供这些内容。使用者应自行确认访问、转录、保存与再利用行为合法合规。