從歌單檔案（TXT / CSV / Excel）批次搜尋 YouTube 並下載轉換為 MP3。 自動選擇官方頻道、最高觀看數、最佳時長的影片，並跳過已下載歌曲。 支援 YouTube Data API v3（精準模式）和 yt-dlp（免 key 模式）雙後端。 當使用者說「幫我下載這份歌單」「把這些歌轉成 MP3」「照這個 txt 抓歌」 「從 YouTube 下載音樂」，或上傳歌單檔案並提到「下載」「MP3」「YouTube」時使用。 相關檔案類型：.txt、.csv、.xlsx。 不適用於：影片下載、字幕擷取、串流播放、YouTube 頻道分析。
從歌單檔案批次搜尋 YouTube 並下載為 MP3（192kbps），自動評分選取最佳影片。
執行前確認以下工具已安裝：
pip install yt-dlp openpyxl --break-system-packages -q
ffmpeg -version # 確認 ffmpeg 已安裝
必要依賴：
yt-dlp — YouTube 搜尋與下載openpyxl — 讀取 Excel 檔案（僅 .xlsx 需要）ffmpeg（系統層） — 音訊轉檔為 MP3根據使用者提供方式處理：
/mnt/user-data/uploads/）songs.txt），每行一首歌歌單支援三種格式，詳見 references/playlist-formats.md。
建議先執行預覽，讓使用者確認搜尋結果再正式下載：
python "Download music.py" 歌單.txt -o ./music_output --dry-run
將預覽結果展示給使用者，包含每首歌匹配到的影片標題、頻道、時長與觀看數。
使用者確認後啟動下載：
python "Download music.py" 歌單.txt -o ./music_output
重要參數：
-o / --output：指定輸出目錄（預設 ./music_output）--api-key YOUR_KEY：使用 YouTube Data API（搜尋更精準）--force：強制重新下載（忽略已下載記錄）--dry-run：只搜尋不下載再次執行相同歌單時，已成功下載的歌曲會自動跳過。
下載完成後：
present_files 工具讓使用者下載輸出結構：
music_output/
Shape of You - Ed Sheeran.mp3
愛你 - 王力宏.mp3
download_log.json
執行過程中若遇到錯誤，依以下順序處理：
sudo apt install ffmpeg 或 brew install ffmpegpip install yt-dlp --break-system-packages使用者說：「幫我下載這份歌單的 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 首（附失敗歌曲名稱）。
使用者說：「用 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
使用者貼上：
Shape of You - Ed Sheeran
愛你 - 王力宏
Blinding Lights - The Weeknd
處理方式：將內容寫入 songs.txt，然後按標準流程執行。
原因：系統未安裝 ffmpeg，無法將音訊轉為 MP3。 解法：
sudo apt install ffmpegbrew install ffmpeg原因：歌名太模糊、拼字錯誤、或 YouTube 上不存在。 解法：
歌手 - 歌名）原因：YouTube Data API 每日限額 10,000 quota，每首歌約消耗 202 quota。 解法：
--api-key 參數）原因：download_log.json 可能損壞或被刪除。
解法：
download_log.json--force 強制重新下載