quanxiel/ops/course-toolkit/README.md

course-toolkit — YouTube 课程「下载 + 转写 + 成册」工具包

把某个 YouTube 课程/播放列表，批量变成 本地视频 + 英文文稿 + 中文导读 Markdown。

组成

文件	作用
fetch_course.sh	主入口：枚举播放列表 → 并行下载+转写 → 清洗文稿
worker.sh	单个视频的下载/抽音频/转写（被主脚本并行调用）
course_util.py	子命令：manifest / clean / transcribe / build

快速开始

# 1) 下载 + 转写（默认英文，4 路并行）
./fetch_course.sh "https://www.youtube.com/playlist?list=XXXX" ~/course/我的课程
#    中文课程： MODEL=small LANG=zh ./fetch_course.sh <url> <outdir>

# 2) 生成中文导读：在 <outdir>/guides/ 下放 01.txt 02.txt ...（可直接让 AI 读 clean/NN.txt 生成）
#    然后组装成册：
python3 course_util.py build ~/course/我的课程

产物结构：

<outdir>/
├── manifest.txt        # NN|id|slug|title
├── videos/NN-slug.mp4   # 本地视频（默认 360p）
├── transcripts/         # 带时间轴文稿
├── clean/NN.txt         # 去时间轴文稿（供检索/摘要）
├── guides/NN.txt        # 中文导读（可选，人工/AI 写）
├── NN-slug.md           # 成册笔记（导读 + 全文）
├── README.md            # 目录索引
└── build.log            # 运行日志

环境变量

变量	默认	说明
PROXY	socks5://192.168.27.96:1080	访问 YouTube 的代理
MODEL	base.en	faster-whisper 模型（英文 base.en/small.en；中文 small）
LANG	en	转写语言
JOBS	4	并行数
FMT	18	yt-dlp 格式（见下）

依赖：yt-dlp、ffmpeg、faster-whisper + python3。

关键经验（踩过的坑）

1. 画质问题：YouTube 未登录下载被限，实测只有 --extractor-args "youtube:player_client=android" 能下 → 上限 360p（格式 18，渐进式、含音轨）。android_vr/tv_embedded 会列出 1080p 但下载 403；要高清需 PO token / 登录 cookie。
2. 官方字幕不稳：常遇 429 限流或该视频根本没有字幕 → 故用本地 ASR替代。
3. 模型下载：走 hf-mirror，并必须 HF_HUB_DISABLE_XET=1（否则 xet CAS 401）。
4. 速度：faster-whisper base.en + beam_size=1 + 单线程多进程并行，实测 ~28x 实时（4 并行）；19 集≈12 分钟。
5. 成册：每集 md = 中文导读 + 英文全文；文稿为自动转写，未人工校对。
6. ⚠️ 版权：视频版权归原作者，建议仅作个人学习归档，勿公开分发。

（本工具包由小五沉淀，首个用户：《Full Algorithmic Trading Using Python》19 集）