YouTube 音樂批量下載 MP3 · 自動搜尋 · 自動轉碼 · 雲端備份
發一條歌單訊息，30 首歌自動幫你全部搞掂
淨係將想聽嘅歌名傳過去（Telegram / CLI 都得），Hermes Agent 就會自動完成：搜尋 → 下載 → 轉 MP3 → 嵌入封面同歌手資料 → 雲端備份。全程唔使手動操作，一條訊息 = 一首歌。
淨係要歌名，自動由 YouTube 搵到最佳版本（支援加專輯名精確匹配）
影片一鍵轉最高音質 MP3（320kbps），唔使任何手動轉換
30 首清單一次過傳嚟，自動排隊逐首下載，內置防限流延遲
每首下載完自動上傳 Google Drive，多端隨時攞
自動嵌入專輯封面 + 歌手 / 歌名 / 專輯 metadata
嚴格限定個人使用場景，尊重版權方權益
| ✅ 允許 | ❌ 禁止 |
|---|---|
| 個人離線欣賞（飛機、地鐵、無網絡環境） | 任何形式嘅商業使用、售賣、二次轉售 |
| 個人學習、研究、創作參考 | 公開傳播、再分發、上傳至共享平台 |
| 備份自己已購買 / 已訂閱嘅曲目 | 侵犯版權方合法權益嘅行為 |
一次性設定，之後每次下載都係「傳訊息就得」。
| 組件 | 作用 | 狀態 |
|---|---|---|
| Hermes Agent | 理解你嘅請求，調度成個下載流程 | 已裝 |
| yt-dlp | 由 YouTube 搜尋影片並下載 | 已裝 |
| ffmpeg | 將影片音軌轉做 MP3（必需） | 已裝 |
| deno | JS runtime，YouTube 新版頁面結構需要 | 已裝 |
| cookies.txt | 繞過數據中心 IP 嘅機械人驗證 | 已裝 |
兩條命令都出到版本號即就緒。若果缺失，Hermes Agent 會提示你一鍵安裝。
YouTube 成日改版，舊版 yt-dlp 會下載失敗。建議每個月更新一次。
將想下嘅歌寫入一個 txt 檔案，每行一首，格式見下一節。
開工前要準備好嘅檔案同憑據，一次過列清。除 Google Drive（可選）外全部零成本。
| 檔案 | 點樣準備 | 用途 |
|---|---|---|
songs.txt 歌單 | 文字檔，每行一首「歌手 - 歌名」 | 批量下載嘅輸入清單（見 §3） |
cookies.txt | 瀏覽器擴充（Get cookies.txt）匯出 YouTube 登入 Cookie | 繞過數據中心 IP 嘅機械人驗證（必裝） |
yt-dlp | pip 安裝 / 官方 binary | YouTube 搜尋與下載引擎 |
ffmpeg | apt install ffmpeg 或 brew | 影片音軌轉 MP3（必需） |
deno | curl -fsSL https://deno.land/install.sh | sh | JS runtime，YouTube 新版頁面結構需要 |
| Google Drive OAuth 可選 | google-workspace skill 托管（client_secret + token） | 每首自動上傳「Music-Downloads」資料夾備份 |
推薦格式：歌手 - 歌名，每行一首。亦可以直接貼 YouTube 連結。
傳一條訊息「幫我下載 Taylor Swift - Love Story」，Hermes Agent 內部執行：
輸出一個影片 ID，即最優匹配。
一條命令完成：抽取音軌 → 轉 MP3 最高音質 → 嵌入封面 → 寫入歌手/歌名標籤。
Hermes Agent 下載完會自動將 MP3 上傳到你嘅 Google Drive「Music-Downloads」資料夾，與 Telegram 直傳雙通道交付。
將成個歌單檔案掟俾 Hermes Agent，批量 script 自動逐首處理，內置 2 秒延遲防 YouTube 限流。
直接將 songs.txt 傳俾 Hermes Agent（Telegram 可直接傳檔案），講一句「批量下載成 MP3」。
script 逐行處理：跳過空行同 # 註解 → 搜尋 → 下載轉 MP3 → 上傳 Drive → 等 2 秒 → 下一首。
每首都獨立報告結果，失敗唔影響後續歌曲，最後總結成功/失敗數量。
數字應與歌單行數一致。
輸出包含 Audio file with ID3 version 即正常；同時檢查檔案大小大過 0。
確認 bitrate 320kbps、時長正常、歌手歌名標籤完整。
| 需求 | 命令 |
|---|---|
| 搜尋一首歌 | yt-dlp "ytsearch1:歌手 歌名" --print "%(id)s" --no-playlist |
| 下載轉 MP3 | yt-dlp "URL" -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --add-metadata --no-playlist |
| 批量下載 | bash ~/.hermes/skills/youtube-music-downloader/scripts/download.sh songs.txt ./downloads |
| 更新 yt-dlp | yt-dlp -U |
| 核對數量 | ls ./downloads/*.mp3 | wc -l |
| 驗證檔案 | file ./downloads/*.mp3 |
Q：搵到嘅歌唔啱（撞名 / 翻唱版 / 現場版）？
解決：歌名後加專輯名，例如「Taylor Swift - August folklore」。Hermes Agent 預設會對常見撞名歌曲自動加專輯名優化搜尋。
Q：報錯 "Sign in to confirm you're not a bot"？
原因：伺服器 IP 係數據中心 IP，被 YouTube 判定為機械人。
解決：使用 cookies.txt（由瀏覽器匯出）。Hermes Agent 已內置，遇到此報錯會自動帶上 cookies 重試。
Q：某首歌下載失敗（年齡 / 地區限制）？
部分影片有年齡或地區限制會失敗，屬正常現象。批量模式下單首失敗唔影響其他歌曲，最後總結報告會列出失敗項。
Q：檔案名帶住「(Official Video)」等影片標題後綴？
檔案名取自 YouTube 影片標題，屬正常現象。MP3 內部嘅歌曲 metadata（歌手/歌名）係乾淨準確嘅，播放器顯示不受影響。
Q：下載太頻繁被限流？
批量 script 內置 2 秒延遲。如果需要更大批量，建議分批進行（例如每次 30 首），避免短時間大量請求。
Q：咁樣下載合法嗎？
請嚴格遵守：僅限個人學習、研究、欣賞使用，禁止商業用途與公開傳播。尊重版權，支持正版——請透過購買專輯 / 串流平台訂閱支持你鍾意嘅音樂人。
鍾意呢份指南？請我飲杯咖啡 ☕
☕ 請我喝杯咖啡