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) - 初始版本（单机绑定）