mizorewww/course2md · 上手攻略
- 仓库：mizorewww/course2md
- 链接：https://github.com/mizorewww/course2md
- 分类：工具 · 视频笔记 · ASR · 本地 AI
- 作者：Tom
- 更新：2026-09-03
它是什么
course2md 是一个将 YouTube、Bilibili 或本地视频（网课、录屏、会议录像）转换为带截图的图文 Markdown / HTML 讲义的命令行工具。核心流程：下载视频 → 按画面变化采样关键帧截图 → 语音识别转文字 → 自动对齐文字与截图 → 输出结构化笔记。最新版本 v0.7.0（2026） 新增断点续传与 LLM 字幕润色功能。
解决什么问题
看视频学习时，手动截屏 + 整理笔记费时费力；纯文字记录又丢失了幻灯片/白板/代码演示等视觉信息。course2md 用 ASR（自动语音识别）+ 画面检测算法自动完成这整套流程，输出可直接阅读的 Markdown 或 HTML讲义，适合：
- 备考复习：快速生成有图有文的课程笔记，支持 Ctrl+F 搜索
- 会议记录：将录像转成可编辑的文字材料
- 知识沉淀：把 B 站/YouTube 教程永久存档为本地笔记
- 多语言场景：内置中文理解优势显著的 Qwen3-ASR 模型
快速安装
macOS（Homebrew，推荐 Apple Silicon）
brew install mizorewww/tap/course2md
⚠️ 要求 macOS 15（Sequoia）及以上。Apple Silicon 默认使用 CoreML 后端（ANE 加速，零外部依赖）；Intel Mac 自动回退到 gpu/cpu 后端。
Linux
# 方式一：install.sh 预编译版
curl -fsSL https://raw.githubusercontent.com/mizorewww/course2md/main/install.sh | bash
# 方式二：AUR（Arch Linux）
yay -S course2md-bin
# 方式三：从源码构建（需 Rust 工具链）
cargo install --path .
Windows
# 安装依赖
winget install --id Gyan.FFmpeg -e
winget install --id yt-dlp.yt-dlp -e
winget install --id ggml.llamacpp -e
# 下载 release 二进制，重命名为 course2md.exe 并加入 PATH
通用依赖（所有平台）
ffmpeg&ffprobe：音视频抽取与画面采样yt-dlp：在线视频解析（处理 URL 时需要）llama-server（llama.cpp）：gpu / cpu 识别后端需要；macOS coreml 与云端 api 模式无需安装
⚠️ 首次运行时会弹出交互式配置向导，引导选择本地或云端 ASR 后端并下载相应模型（约 1~2.4 GB）。网络受限先设
export HF_ENDPOINT=https://hf-mirror.com，或直接course2md --provider api跳过本地模型。
核心用法
基本命令
# 解析 B 站视频
course2md https://www.bilibili.com/video/BV1pb8o6yE8f
# 解析 YouTube 视频
course2md https://youtu.be/dQw4w9WgXcQ
# 解析本地视频文件
course2md ./lecture.mp4
输出默认保存在 ./out/<平台>/<标题>/<编号>/，包含：
| 文件 | 说明 |
|---|---|
course.md |
图文混排 Markdown 讲义（默认生成） |
course.html |
独立排版 HTML 页面（默认生成） |
frames/ |
关键帧截图目录（slide_0001.jpg 等） |
audio.wav |
提取的 16kHz 单声道音频 |
timeline.jsonl |
带时间戳的原始识别序列 |
meta.json |
视频标题、作者、时长等元数据 |
structured.json |
结构化数据（--formats 包含 json 时生成） |
media.mp4 |
下载的视频（本地输入不复制；默认转换完自动删除） |
ASR 后端选择
通过 --provider <backend> 指定，或写入 ~/.config/course2md/config.toml 永久生效：
| 后端 | 适用平台 | 推荐场景 |
|---|---|---|
coreml |
macOS Apple Silicon（默认） | 离线、低功耗、中文最准；ANE 加速，无需 llama-server |
gpu |
Linux / Windows / Intel Mac | CUDA/Metal/Vulkan 加速，需 llama-server，约 2.4 GB 模型 |
npu |
Linux / Windows（Intel Core Ultra） | OpenVINO Whisper，极低功耗（比 CPU 快 6 倍） |
cpu |
通用兜底 | 纯 CPU，兼容性最高，需 llama-server |
api |
任意平台 | OpenAI 兼容端点（OpenRouter 等），免本地模型；音频上传云端 |
# 切换到云端 API（需设置 API key）
course2md https://www.bilibili.com/video/BV1pb8o6yE8f \
--provider api \
--llm-base-url https://openrouter.ai/api/v1 \
--llm-api-key sk-or-v1-xxxx
# macOS Apple Silicon 切换 ASR 模型
course2md ./lecture.mp4 --provider coreml --asr-model qwen3-0.6b
⚠️ Qwen3-ASR 1.7B 中文/中英混合专业词汇识别优于 Whisper large-v3-turbo；Whisper 在纯英文或多语种场景仍有优势。模型选择见下表：
| 模型 | 推荐度 | 显存占用 | 核心优势 | 注意事项 |
|---|---|---|---|---|
| Qwen3-ASR 1.7B | ★★★★★ | 1.7~2.7 GB | 中文技术词准、标点完整、句子完整度高 | MLX 路径走 GPU（非 ANE 低功耗） |
| Qwen3-ASR 0.6B | ★★★★ | 600 MB~1.4 GB | ANE 极低功耗（约 375 J / 3 分钟），零外部依赖 | 复杂生僻技术词略逊于 1.7B |
| Whisper large-v3-turbo | ★★★ | 800 MB~1.5 GB | 纯英文/小语种优秀，NPU 上 12× 实时加速 | 中文标点欠缺，技术词音近误判率高 |
| Whisper Tiny/Base | ★ | <200 MB | 极速（39× 实时） | 严重音近幻觉，不建议正式使用 |
LLM 润色（v0.7.0+）
# 开启 LLM 润色（一键设置，支持任意 OpenAI 兼容端点）
course2md llm setup
# 转换时启用/禁用
course2md ./lecture.mp4 --llm
course2md ./lecture.mp4 --no-llm
⚠️ LLM 润色默认关闭。需自行配置 OpenAI 兼容端点的 API key（支持 OpenRouter 等）。关闭后会有开启提示，可用
--no-llm-hint关闭提示。
配置管理
# 初始化生成带完整注释的配置模板
course2md config init
# 查看当前生效配置
course2md config show
优先级：命令行参数 > ~/.config/course2md/config.toml > 内置默认值。
关键配置项（~/.config/course2md/config.toml）：
[defaults]
out = "out" # 输出根目录
similarity = 0.85 # 画面 SSIM 相似度阈值（越高截图越多）
sample_interval = 1.0 # 画面采样间隔（秒）
cooldown = 10.0 # 新截图触发冷却防抖（秒）
# provider = "coreml" # 默认 ASR 后端
# asr_model = "qwen3-1.7b" # 默认 ASR 模型
断点续传（v0.7.0+）
长课程中断后，重新运行相同命令会自动从中断处继续，无需从头开始。
典型适用场景
场景一：B 站网课 → 本地 Markdown 笔记
# 直接丢链接，5 分钟后得到完整讲义
course2md https://www.bilibili.com/video/BV1pb8o6yE8f
# 输出：./out/bilibili/<视频标题>/<avid>/course.md + course.html + frames/
场景二：本地会议录像 → 可编辑文字记录
# 会议录屏 → 带时间线的结构化笔记
course2md ./team-meeting-2026-09-03.mp4
# timeline.jsonl 可直接导入笔记软件做时间线导航
场景三：预下载模型，离线批量处理
# 预先下载模型（避免首次转换时等待）
course2md models download
# 批量处理（结合 shell 循环）
for url in $(cat urls.txt); do
course2md "$url"
done
坑与注意
-
macOS 版本门槛：CoreML 后端要求 macOS 15+（Sequoia）。旧系统只能用 gpu/cpu 后端，需要安装 llama-server。⚠️ Intel Mac 不支持 CoreML，始终回退到 llama-server 后端。
-
首次运行模型下载：首次识别会自动下载 1~2.3 GB 模型到
~/Library/Caches/qwen3-speech/（macOS）或~/.cache/course2md/models/（Linux）。网络慢先设HF_ENDPOINT镜像。 -
yt-dlp 依赖：处理在线视频（YouTube/Bilibili）时必须安装 yt-dlp；处理本地文件不需要。
-
llama-server 版本：gpu/cpu 后端依赖 llama-server，部分平台需要从源码编译（见 Linux 安装步骤）。⚠️ 慢盘/纯 CPU 场景下 llama-server 启动超时从 120s 调整到 300s，但仍可能超时。
-
中文标点差异：Whisper 模型中文标点缺失严重，推荐使用 Qwen3-ASR 系列。README 明确指出 Whisper 对 "NeoVim"、"Altair 8800" 等技术词存在音近误判。
-
API 模式隐私：使用
--provider api时音频切片会上传至云端处理，涉及敏感内容请注意隐私风险。 -
Windows 路径：Windows 下配置文件路径为
%APPDATA%\course2md\config.toml，模型缓存为%LOCALAPPDATA%\course2md\models\。 -
Rust 源码构建：需要 Rust 稳定版工具链。macOS Apple Silicon 构建 CoreML 支持需要 Xcode 16+（Swift 6）。不需要 CoreML 时可设
COURSE2MD_NO_APPLE=1 cargo build --release跳过。
与同类对比
| 工具 | 视频平台支持 | ASR 模型 | 输出格式 | 离线能力 | 特色 |
|---|---|---|---|---|---|
| course2md | YouTube / Bilibili / 本地 | Qwen3-ASR（中文强项）+ Whisper | Markdown + HTML + JSON | 完整离线（coreml/gpu/cpu） | 中文技术词识别最优；多后端自动回落 |
| yt-dlp + whisper | YouTube / Bilibili 等 | Whisper（需自行组装） | 纯文字字幕 | 可离线（需本地 Whisper） | 无截图、无自动排版，需手动拼接 |
| Netizen / Bilibili 字幕导出 | 仅 Bilibili | 平台自带 | SRT 字幕 | 依赖平台字幕 | 无截图，仅导出已有字幕 |
| LectureSight | YouTube / 本地 | Vosk / Whisper | Markdown | 可离线 | 侧重学术讲座，截图逻辑不同 |
核心差异：course2md 的护城河在于（1）内置 Qwen3-ASR 对中文技术词汇的显著优势；（2）CoreML 后端在 Apple Silicon 上的极低功耗（~375 J / 3 分钟）；（3）多 ASR 后端自动回落机制；（4）一键配置 + 模型缓存管理。相比手动组装 yt-dlp + whisper 流程，开箱即用且输出质量更高。
一句话推荐结论
中文网课/技术视频首选 course2md：macOS Apple Silicon 用户零依赖开箱即用，其他平台 Homebrew/AUR 一行安装，Qwen3-ASR 中文识别精度是市面最高水平，输出 Markdown + HTML 双格式可直接导入任意笔记工具。⚠️ 非 Apple Silicon Linux/Windows 需配置 llama-server 略有一定门槛，但一次性配置后体验完整。
Sources: GitHub README (https://github.com/mizorewww/course2md) · v0.7.0 Releases (https://github.com/mizorewww/course2md/releases) · 中文 README (https://github.com/mizorewww/course2md/blob/main/readme.zh.md)