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）

依赖

工作流

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())
"

模型选择指南：

脚本自动检测 GPU（CUDA），无 GPU 自动回退 CPU。

Step 5: 整理笔记

读取转录文本后，按以下模板结构化整理：

# [视频标题]

> 视频来源：[UP 主 / 作者]
> 原视频：[链接]
> 整理时间：[YYYY-MM-DD]（基于 Whisper 转录）

---

## 核心内容

### 要点 1：[标题]

[整理后的内容]

### 要点 2：[标题]

[整理后的内容]

---

## 核心洞察

- 洞察 1
- 洞察 2

---

## 实践建议

1. 建议 1
2. 建议 2

---

**笔记整理自：** [作者]《[视频标题]》
**视频链接：** [URL]
**整理日期：** [YYYY-MM-DD]

Whisper 中文常见识别错误修正：

整理原则：

• 先通读全文，标记明显错误
• 结合视频标题和背景知识推断正确文本
• 学术术语、人名、理论名称重点核查
• 保留原文结构，只修正错误，不擅自改写

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