video-to-notes
将视频自动转录并整理为结构化笔记的跨平台技能。
首次使用
1. 环境检测
python3 scripts/check_env.py
根据输出安装缺失的工具。
2. 配置
cp config.example.json config.json
# 编辑 config.json，填写你的路径
必填项：
- obsidian_vault — Obsidian 库绝对路径（不使用 Obsidian 可留空）
- whisper_model — 推荐值：small（平衡）/ medium（高精度）/ tiny（快速测试）
可选项：
- extra_paths — 手动指定工具路径（留空则自动从 PATH 检测）
- note_format — obsidian（默认）或 file（保存到 temp_dir）
依赖
| 工具 | 用途 | 安装方式 |
|---|---|---|
| Python 3.8+ | 运行脚本 | python.org |
| openai-whisper | 音频转录 | pip install openai-whisper |
| yt-dlp | 视频下载 | pip install yt-dlp |
| ffmpeg | 音频提取 | ffmpeg.org |
| PyTorch CUDA（可选） | GPU 加速 | pytorch.org |
工作流
Step 1: 获取视频信息
B 站视频：
curl -s "https://api.bilibili.com/x/web-interface/view?bvid=BV1xxxxx"
提取字段：title、duration（秒）、owner.name、subtitle.list
决策：
- 有字幕 → 直接获取字幕文本（跳过 Step 2-4）
- 无字幕 → 进入 Whisper 转录流程
Step 2: 下载视频
python3 scripts/download.py "https://www.bilibili.com/video/BV1xxxxx"
也支持 BV 号简写：
python3 scripts/download.py BV1xxxxx
手动方式：
yt-dlp -o "_temp/video.%(ext)s" --no-playlist "URL"
Step 3: 提取音频
python3 scripts/extract_audio.py "_temp/video.mp4"
支持格式：mp3（默认）、wav、flac、m4a
手动方式：
ffmpeg -i "_temp/video.mp4" -vn -acodec libmp3lame -q:a 2 "_temp/audio.mp3"
Step 4: Whisper 转录
python3 scripts/transcribe.py "_temp/audio.mp3"
指定模型和语言：
python3 scripts/transcribe.py "_temp/audio.mp3" -m medium -l zh
手动方式：
python3 -c "
import whisper
model = whisper.load_model('small')
result = model.transcribe('_temp/audio.mp3', language='zh')
with open('_temp/transcript.txt', 'w', encoding='utf-8') as f:
f.write(result['text'].strip())
"
模型选择指南：
| 模型 | VRAM | 速度 | 精度 | 推荐场景 |
|---|---|---|---|---|
| tiny | ~1 GB | 极快 | 低 | 测试 / 短视频（<5 分钟） |
| small | ~2 GB | 快 | 中 | 日常使用（推荐） |
| medium | ~5 GB | 中 | 高 | 长视频 / 专业内容 |
| large | ~10 GB | 慢 | 很高 | 最高精度需求 |
| turbo | ~5 GB | 快 | 高 | 速度与精度平衡 |
脚本自动检测 GPU（CUDA），无 GPU 自动回退 CPU。
Step 5: 整理笔记
读取转录文本后，按以下模板结构化整理：
# [视频标题]
> 视频来源：[UP 主 / 作者]
> 原视频：[链接]
> 整理时间：[YYYY-MM-DD]（基于 Whisper 转录）
---
## 核心内容
### 要点 1：[标题]
[整理后的内容]
### 要点 2：[标题]
[整理后的内容]
---
## 核心洞察
- 洞察 1
- 洞察 2
---
## 实践建议
1. 建议 1
2. 建议 2
---
**笔记整理自：** [作者]《[视频标题]》
**视频链接：** [URL]
**整理日期：** [YYYY-MM-DD]
Whisper 中文常见识别错误修正：
| 错误 | 正确 | 错误 | 正确 | |
|---|---|---|---|---|
| 温馨 | 文献 | 断路 | 段落 | |
| 文件 | 文献 | 单脸 | 单独 | |
| 战线 | 展示 | 工与商 | 供应商 | |
| 耗尸耗利 | 耗时耗力 | 业伙 | 业务伙伴 | |
| 求实 | 权威 | 提亮 | 提炼 | |
| API | APA（格式） | GBT | GPT | |
| 军职 | 均值 | 围章 | 文章 | |
| M学者 | Markowitz | 中数 | 中文 |
整理原则：
- 先通读全文，标记明显错误
- 结合视频标题和背景知识推断正确文本
- 学术术语、人名、理论名称重点核查
- 保留原文结构，只修正错误，不擅自改写
Step 6: 保存笔记
python3 scripts/save_note.py "_temp/note.md" -t "[视频标题]"
根据 config.json 的 note_format 自动选择保存位置：
- obsidian → 保存到 obsidian_vault 指定的库
- file → 保存到 temp_dir
也可指定目标目录覆盖配置：
python3 scripts/save_note.py "_temp/note.md" -t "[标题]" -d "/自定义/路径"
Step 7: 清理临时文件
rm -rf _temp/
Windows:
Remove-Item -Recurse -Force _temp
常见问题
Q: CUDA out of memory
换更小的模型（large -> medium -> small -> tiny），或在 Python 中设置：
import torch
torch.cuda.set_per_process_memory_fraction(0.5, device=0)
Q: ffmpeg 退出码 1 但文件完整
Windows/macOS 下 ffmpeg 将进度信息输出到 stderr，可能导致非零退出码。脚本已处理：只要输出文件存在且大小 > 0 即视为成功。
Q: yt-dlp 退出码 1 但下载成功
可能是 Python 弃用警告。脚本通过 --no-playlist 减少多余输出，检查输出文件即可。
Q: 中文笔记乱码
使用 scripts/save_note.py 保存（自动 UTF-8 编码），避免直接用 shell 重定向。
Q: Whisper 识别错误太多
- 换更大模型（small -> medium）
- 中文内容建议指定
-l zh - 参考错误对照表人工修正
Q: 没有 GPU，转录很慢
- tiny 模型在 CPU 上约 1x 实时（10 分钟音频需要 10 分钟）
- small 模型在 CPU 上约 0.3x 实时（10 分钟音频需要 30 分钟）
- 建议：短视频用 small + CPU，长视频考虑租 GPU 或用云端转录 API
扩展方向
- [ ] 批量视频处理（读取 BV 号列表文件）
- [ ] 自动语言检测（中文/英文/双语）
- [ ] 集成其他转录引擎（FunASR、Paraformer）
- [ ] LLM 自动整理笔记（调用 AI 生成结构化笔记）
- [ ] YouTube / 抖音 / 油管支持
- [ ] 时间戳索引生成（带跳转链接的笔记）
版本历史
- v0.2 (2026-05-21) - 重构：跨平台、配置化、脚本化
- v0.1 (2026-05-21) - 初始版本（单机绑定）
