bilibili-obsidian-notes

bilibili-obsidian-notes

快速开始（Windows / PowerShell）

如果你在终端里看到中文乱码，优先使用 UTF-8 模式运行 Python：

# 一次性会话设置（二选一即可）
chcp 65001
$env:PYTHONUTF8 = "1"   # 或者每次运行都用 python -X utf8

python -X utf8 scripts\bili_vision_notes.py `
  --url "<Bilibili URL>" `
  --vault "<你的 Obsidian Vault 路径>" `
  --max-frames 12

输出：

• <vault>/video-notes/<title> (<id>).md
• <vault>/video-notes-images/<id>/*.png
• <vault>/.tmp/bili-vision-notes/<id>/...
• <vault>/.tmp/bili-vision-notes/<id>/timings.json（结构化阶段耗时）
• <vault>/.tmp/bili-vision-notes/<id>/retention.json（视频保留状态）

仅字幕辅助工具：

python -X utf8 scripts\bili_fetch_subtitle.py `
  --url "<Bilibili URL>" `
  --out ".\\subtitle.json" `
  --login

二维码登录（推荐用于付费视频或需要登录的视频）：

python -X utf8 scripts\bili_qr_login.py

登录后，bili_fetch_subtitle.py / bili_vision_notes.py 会自动尝试将 BBDown.data 用作 Cookie 备用来源。 字幕优先级：UP 主中文字幕、UP 主其他字幕、中文字幕 AI 字幕，然后是其他语言的 AI 字幕。

快照辅助工具（支持跳转 URL，例如 ?t=501.16 或 #t=08:21.17）：

python -X utf8 scripts\bili_snapshot.py `
  --url "https://www.bilibili.com/video/BV1cL411n7KV/?t=501.165719#t=08:21.17" `
  --vault "<你的 Obsidian Vault 路径>"

说明：

• 默认输出：<vault>/_resources/<title>PT8M21.166S.webp
• 默认最大宽度：1920（仅在宽度超过 1920 时缩小；绝不放大）
• 脚本会输出适用于 Obsidian 的嵌入行： - ![[...webp|<title> - 08:21]] [08:21](https://.../?t=501.165719#t=08:21.17)
• 使用 --clip N 仅下载 [t-N, t+N]（秒）的片段。若要“前后各 1 秒”，使用 --clip 1。需要许多截图时，建议完整下载（不使用 --clip）。

预览快照（低清预览图；不下载整段视频；通常仅用于备用或快速定位时间点）：

python -X utf8 scripts\bili_snapshot.py `
  --method preview `
  --url "https://www.bilibili.com/video/BV1cL411n7KV/?t=501.165719#t=08:21.17" `
  --vault "<你的 Obsidian Vault 路径>"

自动降级（默认未启用）：先尝试高清 video，失败后再回退到 preview：

python -X utf8 scripts\bili_snapshot.py `
  --method auto `
  --url "https://www.bilibili.com/video/BV1cL411n7KV/?t=501.165719#t=08:21.17" `
  --vault "<你的 Obsidian Vault 路径>"

常用选项

• --cookies-from-browser edge|chrome 用于需要登录的视频
• --max-frames N 笔记中的最大关键帧数
• --scene-threshold 0.0-1.0 值越低，帧数越多
• --keep-video/--no-keep-video 是否在工作目录中保留 mp4
• 保留完整视频，直到截图 QA 完成。它是场景检测和补充快照共用的本地来源。只有在不再需要后续快照时，才使用 --no-keep-video。
• --subtitle-file <path> 使用现有的 Bilibili 字幕 JSON/VTT 文件（覆盖自动获取）
• --subtitle-json-out <path> 将获取到的字幕 JSON 保存到文件（用于调试或重复使用）
• bili_snapshot.py --clip N 仅下载 t 周围的一小段时间范围

下载视频保留策略

只要笔记图片仍可能变更，就保留已下载的课程视频媒体。满足以下任一条件时，视为笔记已完成，并删除已下载的 video.<media extension> 文件：

1. 用户明确确认学习笔记已完成。
2. 距离上次讨论、检查或调整该笔记图片已过完整 7 天。

保留 Markdown 笔记、字幕、截图、联系表、元数据、timings.json 和 retention.json。如果旧工作目录没有 retention.json，绝不要仅凭文件系统修改时间将其删除。

主笔记脚本和快照脚本会刷新当前视频的图片活动时间，并清理其他符合条件的视频。讨论笔记图片时，如果没有运行这两个脚本中的任何一个，请明确刷新活动时间：

python -X utf8 scripts\bili_retention.py `
  --vault "<你的 Obsidian Vault 路径>" `
  touch --video-id "<BV id>"

用户确认完成后，立即应用既定删除策略：

python -X utf8 scripts\bili_retention.py `
  --vault "<你的 Obsidian Vault 路径>" `
  complete --video-id "<BV id>" --delete

手动检查或应用 7 天规则：

# Dry run
python -X utf8 scripts\bili_retention.py `
  --vault "<你的 Obsidian Vault 路径>" cleanup --days 7

# Delete eligible video media
python -X utf8 scripts\bili_retention.py `
  --vault "<你的 Obsidian Vault 路径>" cleanup --days 7 --write

对于含有已下载视频但没有 retention.json 的旧工作目录，使用 bootstrap 启动一个保守的 7 天宽限期。当没有活动任务时，该技能不会持续运行；规则会在下次调用主笔记/快照脚本或执行明确的清理命令时评估。

Workflow (for Codex)

1. Refresh retention activity for the current video before image discussion. The main-note and snapshot scripts do this automatically.
2. Run the script once with the full video retained to generate a note skeleton + keyframes. Inspect timings.json before optimizing; it records the automatic phases and explicitly excludes later visual review and manual note expansion.
3. Build or inspect one contact sheet first. Select supplemental timestamps in one visual review pass and reuse the retained full video for local FFmpeg extraction.
4. Use functions.view_image on each selected keyframe and extract:
   • blackboard formulas (convert to LaTeX)
   • code blocks (copy verbatim)
   • key derivation steps / pitfalls
5. Patch only the generated note file using apply_patch, then report post-main visual review, supplemental screenshot, manual expansion, and QA time separately.
6. If the user confirms completion, run bili_retention.py complete --delete. Otherwise keep the video active until seven days have elapsed since the last note-image activity.

Note style (学习笔记版，推荐默认)

目标：不是逐句转写字幕，而是把字幕内容整理成可复习的学习笔记（结构清晰、重点突出、公式排版正确），同时不遗漏“知识讲解主线”。

内容取舍

• 删除：开场寒暄、结尾点赞/关注/留言等与知识无关内容。
• 保留：定义、动机、例子、关键结论、步骤流程、注意事项（例如“为什么只执行第一个控制量”）。
• 纠错策略：仅对明显 ASR 错误做最小纠正（如 “NPC”→“MPC”），表述尽量贴近原字幕但让语句更顺。
• 避免出戏：不写“讲者用意/作者想表达什么”这类元叙事，用“学习者记录”口吻复述即可。

结构与排版（参考 PPO算法.md 的可读性）

• 标题用 ## / ### 分层组织知识点；标题不带时间。
• 用列表呈现要点；用 加粗 强调关键词；可用 callout：
  • > [!summary] 小结
  • > [!note] 备注/提醒
• 时间戳策略：不需要给每句话打时间戳；只在关键截图/关键结论处保留时间戳链接即可。

公式与代码（最容易出错，必须遵守）

• 行内数学用 $...$（例如 $e(t)=y(t)-r(t)$），不要用反引号 `...` 把数学写成代码样式。
• 公式块用独立的 $$ ... $$，并确保公式块前后各有一个空行。
• 不要把 $$ 缩进到列表里：在 Obsidian 中，缩进的 $$ 很容易被当成代码块渲染失败。
  • 推荐写法：先写一个 bullet（以冒号结尾），然后换行空一行，再写一个不缩进的 $$ ... $$ 公式块。
• 代码（代码/命令/变量名）才使用反引号或三反引号代码块；代码块内容尽量原样保留。

截图引用（只放关键板书/推导/代码）

• 截图统一保存到 <vault>/_resources（bili_snapshot.py 默认如此）。
• 笔记中引用使用脚本打印的 embed 行格式（可直接粘贴），例如： - ![[<title>PT3M10.002S.webp|<title> - 03:10]] [03:10](https://.../?t=190.001762#t=03:10.00)

Notes:

• functions.view_image 当前不支持 .webp，如果需要让 Codex 识别 bili_snapshot.py 生成的截图，可临时转为 .png 再查看（Obsidian 里仍建议引用 .webp）。