zarazhangrui/youtube-to-ebook · 上手攻略

仓库：zarazhangrui/youtube-to-ebook
链接：https://github.com/zarazhangrui/youtube-to-ebook
分类：ai-tooling · content-pipeline
作者：Tom
更新：2026-08-13

是什么

youtube-to-ebook 是一个将 YouTube 频道视频自动转成 EPUB 电子书的 Python 工具链。它的工作流是：抓频道最新视频 → 提取字幕 → 丢给 Claude 改写成杂志风文章 → 打包成 EPUB → 可选邮件推送。作为 Claude Code Skill 使用时，对话中一句"Set up YouTube to ebook for me"就能触发安装引导。

核心架构为四段管道：get_videos.py（YouTube Data API v3 拉频道最新视频，自动过滤 Shorts）→ get_transcripts.py（YouTubeTranscriptApi 抓字幕）→ write_articles.py（Claude API 改写为可读文章）→ send_email.py（ebooklib 生成 EPUB，可选 Gmail 推送）。另有 dashboard.py 提供 Streamlit 可视化面板。

解决什么问题

手动整理 YouTube 学习资料费时费力——频道多了之后，追踪每个频道更新、一个个复制字幕、再手动排版成可阅读格式，重复劳动极多。该工具把这条链路自动化：配置一次频道列表（channels.txt），每周定时运行，得到一本结构清晰的电子书合集，推到 Kindle 或任意阅读器。

对 Claude Code 用户来说，Skill 格式让它变成了对话式工具，不需要记住命令，开口就能触发。

快速安装

环境要求：Python 3.8+，需要 YouTube Data API v3 密钥（免费）+ Anthropic API 密钥（Claude 调用费用）。

# 克隆仓库
git clone https://github.com/zarazhangrui/youtube-to-ebook.git
cd youtube-to-ebook

# 安装依赖
pip install -r requirements.txt

# 复制环境变量模板
cp .env.example .env

配置 API 密钥（编辑 .env）：

YOUTUBE_API_KEY=your_google_cloud_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GMAIL_ADDRESS=your@gmail.com        # 可选，邮件推送
GMAIL_APP_PASSWORD=your-app-password # 可选

获取 YouTube Data API v3 密钥（免费）： 1. 访问 Google Cloud Console，新建项目 2. 启用「YouTube Data API v3」 3. 创建凭证 → API Key，填入 .env

添加频道（编辑 channels.txt，每行一个频道 Handle）：

@mkbhd
@veritasium
@3blue1brown

首次运行：

python main.py

启动 Web 面板（可选）：

pip install streamlit
python -m streamlit run dashboard.py

核心用法

完整管道（生成电子书）

python main.py

只编辑频道列表

python main.py --channels

Streamlit 可视化面板

streamlit run dashboard.py
# 默认端口 8501，打开 http://localhost:8501

修改文章风格

编辑 write_articles.py 中的 prompt 可切换语气：

Magazine style（默认）
Academic summary（学术摘要）
Casual blog post（轻博客风）
Technical documentation（技术文档）

定时自动运行（macOS launchd）

<!-- ~/Library/LaunchAgents/com.youtube.ebook.plist -->
<plist version="1.0">
<dict>
  <key>Label</key><string>com.youtube.ebook</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/python3</string>
    <string>/path/to/main.py</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Weekday</key><integer>3</integer>
    <key>Hour</key><integer>7</integer>
  </dict>
</dict>
</plist>

cp com.youtube.ebook.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.youtube.ebook.plist

⚠️ 注意：python3 路径可能与包安装的 Python 不一致。运行 which python3 确认路径，或在 plist 中填入完整路径如 /Library/Frameworks/Python.framework/Versions/3.11/bin/python3。

典型适用场景

个人知识管理：追更喜欢的教育类 YouTube 频道（3Blue1Brown、Veritasium 等），定期把新视频整理成合集在 Kindle 上阅读
研究文献追踪：学术类频道的定期简报生成，用于文献综述前期资料积累
内容创作者素材库：将同类主题视频转文字，便于二次创作参考
离线学习：没有稳定网络的场景，预先打包一期 EPUB 带上路

坑与注意

问题	原因	解决方案
Shorts 未被过滤	YouTube API 按时长过滤不可靠	使用 `/shorts/` URL 模式检测：`/shorts/` 出现在重定向 URL 中则跳过
搜索结果不按时间排序	YouTube Search API 本身非严格时序	改用频道的「Uploads 播放列表」ID，通过 `playlistItems` API 拉取（严格时序）
`get_transcript()` 报错	YouTubeTranscriptApi 语法变更	使用实例方法：`ytt_api = YouTubeTranscriptApi()`，`transcript = ytt_api.fetch(video_id)`
字幕提取触发限速	并发请求过多	每次请求间隔 2 秒：`time.sleep(2)`
字幕中人名/术语拼写错误	自动字幕识别局限	将视频标题和描述一并传给 Claude，利用其中的正确拼写纠错
GitHub Actions / 云服务器抓不到字幕	YouTube 对数据中心 IP 有反爬	本地 macOS/Linux 运行，不要用 GitHub Actions
文章截断	`max_tokens` 不足	在 `write_articles.py` 中增大 `max_tokens` 参数

Python 路径陷阱：系统可能存在多个 Python 安装。自动化脚本用 python3，但包可能装在另一个 Python 下。必须在 run_newsletter.sh 和 dashboard.py 中填入完整路径。

与同类对比

工具	定位	优点	缺点
youtube-to-ebook（本工具）	频道 → Claude 改写 → EPUB	自动过滤 Shorts、Claude 改写质量高、支持邮件推送	依赖 Claude API 费用、无中文优化
yt-dlp + 手动处理	纯下载	灵活、支持任何平台	无法自动改写、无 EPUB 生成
ToGetherTube 等在线工具	在线观看	无需安装	无自动化、无改写、无 EPUB
YouTube Summary 等浏览器插件	单视频摘要	开箱即用	无法批量、无 EPUB、无定时

youtube-to-ebook 的核心差异在于 Claude 改写这一步：把生字幕转化成结构化文章，而非简单拼接时间戳。这让输出的电子书真正可读，而非字幕流水账。

一句话推荐结论

如果你在追多个 YouTube 学习频道，想把更新自动整理成可管理的电子书，youtube-to-ebook 是目前最顺滑的「零门槛 Claude + YouTube → EPUB」方案——配置一次，每周自动推送，Kindle 上看完就是赚到。

原始仓库：https://github.com/zarazhangrui/youtube-to-ebook · MIT License