YT Comment → Markdown / 互動式網頁

把 YouTube 頻道或影片的留言（含回覆階層）匯出成：

• 互動式網頁 (HTML) — 單檔內嵌資料，雙欄佈局，可搜尋/篩選/排序，可離線分享
• Markdown — 每影片一份（zip）或合併為單一檔

提供三步驟網頁介面與 CLI，不需 YouTube Data API key（底層使用 yt-dlp + youtube-comment-downloader）。

• 功能總覽
• 快速開始
• 系統需求
• 網頁介面操作流程
• 命令列用法
• 輸出模式
• 專案結構
• 注意事項與限制
• 開發貢獻
• License

• 🎯 三步驟流程：輸入網址 → 勾選想抓的影片 → 一鍵下載
• 📊 互動式 HTML 結果頁：跨影片搜尋（黃底高亮）、依讚數/❤️ 篩選、回覆預設折疊（仿 YouTube）
• 🔁 回覆階層：依 cid 自動重組成兩層樹狀結構
• 📺 支援多種來源：頻道（@handle、/channel/、/user/）、影片、播放清單、Shorts
• ⚡ 即時進度：抓取時透過 SSE 推送當前影片標題與進度條
• 💻 CLI + Web 雙模式：自動化批次跑 CLI、手動操作走 Web
• 🌐 完全離線分享：互動式 HTML 把資料 inline，雙擊即可看，可寄信

# 1. clone 與安裝
git clone https://github.com/dean9703111/yt-comment.git
cd yt-comment
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# 2. 啟動網頁介面（推薦）
uvicorn yt_comments.server:app --reload --port 8000
# 開瀏覽器到 http://localhost:8000

# 3. 或直接用 CLI
python -m yt_comments https://www.youtube.com/@dlcorner -n 5 --mode html

第一次跑建議先用網頁介面抓 2-3 部影片驗證行為（步驟見下方截圖）。

• Python 3.10 或更新（已在 3.10 / 3.11 / 3.12 / 3.13 / 3.14 測試）
• macOS / Linux / Windows（純 Python，無原生編譯）
• 約 200 MB 磁碟（依賴：yt-dlp、fastapi、uvicorn 等）

貼上 YouTube 頻道（如 https://www.youtube.com/@dlcorner）或影片網址，設定列出的影片數量（或勾「全部」）、是否含 Shorts，按「下一步：列出影片清單」。

頻道的影片以縮圖卡片呈現（預設全部勾選），可單獨取消或用「全選 / 取消全選」。已勾選數會即時顯示。

決定排序、是否含回覆、輸出模式（HTML / per-video zip / 單一 md），按「開始抓取已勾選的 N 部影片」（數字會跟著勾選數變動）。

透過 Server-Sent Events 推送，進度條上方顯示當前正在處理的影片標題，可清楚看到目前抓到第幾部、百分比進度。

完成訊息出現後，瀏覽器會自動觸發下載（HTML 模式為 .html、Markdown 模式為 .md 或 .zip）。

--mode html 產出的 .html 檔可直接雙擊打開，雙欄佈局：左欄影片清單、右欄留言。支援跨影片搜尋（黃底高亮）、依讚數/❤️ 篩選、回覆預設折疊（仿 YouTube）、依熱門/最新排序。

# 預設：抓 @dlcorner 頻道最新 10 部影片，每部一份 md
python -m yt_comments https://www.youtube.com/@dlcorner

# 互動式 HTML（推薦）
python -m yt_comments https://www.youtube.com/@dlcorner -n 5 --mode html --out ./output

# 限制 3 部，合併為單一 md
python -m yt_comments https://www.youtube.com/@dlcorner -n 3 --mode single --out ./mydir

# 全部影片（含 Shorts）匯出為互動式 HTML
python -m yt_comments https://www.youtube.com/@dlcorner --all --include-shorts --mode html

# 單支影片，只抓頂層留言，按最新排序
python -m yt_comments "https://www.youtube.com/watch?v=XXXX" --no-replies --sort new

全部選項：

產出一個獨立 .html 檔，資料以 JSON 內嵌，可直接雙擊打開或寄送他人。功能：

• 左欄影片清單：縮圖、留言數、發佈日；可依留言數/最新/標題排序
• 右欄留言：仿 YouTube 樣式，回覆預設折疊為「▾ 顯示 N 則回覆」
• 跨影片全文搜尋：頂部搜尋框輸入後在標題與留言中即時匹配並高亮（黃底）
• 篩選：👍 至少 N、只看 ❤️ 主回覆過的、只看有回覆的
• 排序：熱門（讚數）/ 最新 / 最舊

縮圖直接連 https://i.ytimg.com/vi/<id>/mqdefault.jpg，離線時不顯示縮圖但其餘內容完整可用。

# 影片標題

- **頻道**: @dlcorner
- **發佈日期**: 2024-01-15
- **影片網址**: https://www.youtube.com/watch?v=xxx
- **影片 ID**: `xxx`
- **留言總數**: 123（頂層 78、回覆 45）

---

## 留言

- **@user1** (`UCxxxx`) · 1 day ago · 👍 42
  > 超棒的影片！
  - **@user2** (`UCyyyy`) · 1 day ago · 👍 5
    > 同意，我也很喜歡
  - **@user1** (`UCxxxx`) · 10 hours ago
    > 謝謝大家
- **@user3** (`UCzzzz`) · 2 days ago · 👍 10
  > 學到很多

回覆以 2 個空格的縮排呈現於父留言下。

yt_comments/
├── fetcher.py        # URL 分類、頻道影片列出（含 shorts 交錯合併）、留言抓取
├── markdown.py       # 階層重組與 Markdown 格式化
├── result_html.py    # 互動式 HTML 模板（CSS/JS 內嵌、資料 JSON 注入）
├── server.py         # FastAPI: /api/preview, /api/jobs (job + SSE), /api/jobs/{id}/download
├── cli.py            # argparse 命令列入口
└── static/index.html # 三步驟前端介面（vanilla JS + EventSource）

tools/
└── snapshots.py      # 跑系統 Chrome 自動截圖 + 加紅框/編號標注，產出 docs/screenshots/
docs/screenshots/     # README 用截圖

tools/snapshots.py 會自動操作首頁、勾選影片、按下抓取、等到完成，並把六張截圖存到 docs/screenshots/。

# 1. 安裝 dev 依賴（控制系統 Chrome、加標注）
pip install playwright Pillow

# 2. 確認 server 已啟動
uvicorn yt_comments.server:app --port 8000

# 3. 跑截圖腳本（會用系統 Chrome；macOS 預設路徑 /Applications/Google Chrome.app）
python tools/snapshots.py

Chrome 執行檔路徑寫死在 tools/snapshots.py 開頭的 CHROME_PATH，Linux/Windows 請依環境修改。

• 限流：大量影片時可能被 YouTube 暫時限流；CLI / Web 都會跳過失敗影片繼續處理：
  • zip 模式內會多一份 _errors.txt
  • HTML 模式內 metadata 區會顯示失敗數
• 抓取速度：抓「全部 + Shorts」對大型頻道可能要數分鐘；Web 介面會持續推送進度。
• 建議：第一次使用先用 STEP 2 勾選 2–3 部影片驗證行為。
• 記憶體 job：網頁的 job 結果在記憶體保留 30 分鐘後自動清除，重啟 server 也會清空。
• 不適用情境：私人影片、已關閉留言、會員限定內容皆無法抓取。

歡迎提 Issue / PR。本機開發流程：

git clone https://github.com/dean9703111/yt-comment.git
cd yt-comment
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 改完碼後試跑
uvicorn yt_comments.server:app --reload --port 8000
# 或
python -m yt_comments https://www.youtube.com/@dlcorner -n 2 --mode html

目前沒有 CI 與測試套件（功能性手動驗證）。若你想加 unit test，可以先針對 markdown.py 的 build_tree、result_html.py 的 _parse_votes 起手。

MIT © 2026 dean

底層依賴：

• yt-dlp — Unlicense
• youtube-comment-downloader — MIT
• FastAPI — MIT
• Pillow — HPND (僅截圖腳本用)
• Playwright — Apache-2.0 (僅截圖腳本用)