yt-music-downloader

name	yt-music-downloader
description	從歌單檔案（TXT / CSV / Excel）批次搜尋 YouTube 並下載轉換為 MP3。 自動選擇官方頻道、最高觀看數、最佳時長的影片，並跳過已下載歌曲。 支援 YouTube Data API v3（精準模式）和 yt-dlp（免 key 模式）雙後端。 當使用者說「幫我下載這份歌單」「把這些歌轉成 MP3」「照這個 txt 抓歌」 「從 YouTube 下載音樂」，或上傳歌單檔案並提到「下載」「MP3」「YouTube」時使用。 相關檔案類型：.txt、.csv、.xlsx。 不適用於：影片下載、字幕擷取、串流播放、YouTube 頻道分析。
metadata	{"author":"AutoTune-Fetcher","version":"2.0.0","category":"media-download","tags":["youtube","mp3","music","batch-download","playlist"]}

YT Music Downloader

從歌單檔案批次搜尋 YouTube 並下載為 MP3（192kbps），自動評分選取最佳影片。

Instructions

Step 1: 確認環境與依賴

執行前確認以下工具已安裝：

pip install yt-dlp openpyxl --break-system-packages -q
ffmpeg -version   # 確認 ffmpeg 已安裝

必要依賴：

• yt-dlp — YouTube 搜尋與下載
• openpyxl — 讀取 Excel 檔案（僅 .xlsx 需要）
• ffmpeg（系統層） — 音訊轉檔為 MP3

Step 2: 取得歌單

根據使用者提供方式處理：

• 上傳檔案 → 從上傳目錄取得（如 /mnt/user-data/uploads/）
• 直接貼上歌單內容 → 寫入暫存檔案（如 songs.txt），每行一首歌

歌單支援三種格式，詳見 references/playlist-formats.md。

Step 3: 預覽（dry-run）

建議先執行預覽，讓使用者確認搜尋結果再正式下載：

python "Download music.py" 歌單.txt -o ./music_output --dry-run

將預覽結果展示給使用者，包含每首歌匹配到的影片標題、頻道、時長與觀看數。

Step 4: 正式下載

使用者確認後啟動下載：

python "Download music.py" 歌單.txt -o ./music_output

重要參數：

• -o / --output：指定輸出目錄（預設 ./music_output）
• --api-key YOUR_KEY：使用 YouTube Data API（搜尋更精準）
• --force：強制重新下載（忽略已下載記錄）
• --dry-run：只搜尋不下載

再次執行相同歌單時，已成功下載的歌曲會自動跳過。

Step 5: 交付成果

下載完成後：

1. 回報統計：成功 / 跳過 / 失敗數量
2. 列出失敗歌曲（若有），並建議解法
3. 提供輸出目錄路徑或使用 present_files 工具讓使用者下載

輸出結構：

music_output/
  Shape of You - Ed Sheeran.mp3
  愛你 - 王力宏.mp3
  download_log.json

錯誤處理

執行過程中若遇到錯誤，依以下順序處理：

1. ffmpeg 未安裝 → 提示安裝指令：sudo apt install ffmpeg 或 brew install ffmpeg
2. yt-dlp 未安裝 → 執行 pip install yt-dlp --break-system-packages
3. 某首歌搜尋不到 → 確認歌名拼寫，建議改用「歌手 - 歌名」格式提高精準度
4. API Key 無效 → 系統會自動 fallback 到 yt-dlp 模式，但可建議使用者檢查 key
5. 下載速度限制 → 程式每首歌間有 1 秒間隔，通常足夠

Examples

Example 1: 基本 TXT 歌單下載

使用者說：「幫我下載這份歌單的 MP3」並上傳 my_songs.txt

# Step 1: 確認環境
pip install yt-dlp openpyxl --break-system-packages -q

# Step 2: 預覽
python "Download music.py" my_songs.txt -o ./music_output --dry-run

# Step 3: 使用者確認後正式下載
python "Download music.py" my_songs.txt -o ./music_output

結果：成功 8 首、跳過 0 首、失敗 1 首（附失敗歌曲名稱）。

Example 2: 使用 API Key 精準搜尋

使用者說：「用 API key 下載這份 Excel 歌單」

export YOUTUBE_API_KEY=AIzaSy...
python "Download music.py" playlist.xlsx -o ~/Music --dry-run
# 確認後
python "Download music.py" playlist.xlsx -o ~/Music

Example 3: 使用者直接貼歌單

使用者貼上：

Shape of You - Ed Sheeran
愛你 - 王力宏
Blinding Lights - The Weeknd

處理方式：將內容寫入 songs.txt，然後按標準流程執行。

Troubleshooting

Error: ffmpeg not found

原因：系統未安裝 ffmpeg，無法將音訊轉為 MP3。 解法：

• Linux: sudo apt install ffmpeg
• macOS: brew install ffmpeg
• Windows: 從 ffmpeg.org 下載並加入 PATH

Error: 某首歌始終找不到

原因：歌名太模糊、拼字錯誤、或 YouTube 上不存在。 解法：

• 加上歌手名稱（格式 歌手 - 歌名）
• 確認歌名拼寫正確
• 手動搜尋 YouTube 確認是否存在

Error: API Quota 超限

原因：YouTube Data API 每日限額 10,000 quota，每首歌約消耗 202 quota。 解法：

• 改用 yt-dlp 模式（移除 --api-key 參數）
• 分批下載，隔天再繼續
• 約可處理 ~49 首歌/天（用 API 模式）

Error: 已下載歌曲沒有被跳過

原因：download_log.json 可能損壞或被刪除。 解法：

• 確認輸出目錄下有 download_log.json
• 確認 JSON 格式正確
• 若不需要跳過，可使用 --force 強制重新下載