yubal：開源 YouTube Music 下載器，整理連結成有標籤的本地音樂庫

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

2026 年自架媒體櫃這個圈子，正在安靜地從「寫一個 yt-dlp 腳本抓歌」演化到「把下載、打標籤、去重、歌詞、媒體伺服器整合做成一條流水線」。會出現這個轉向，是因為 Nas 與 HomeLab 使用者已經被 Spotify 與 YouTube Music 寵壞了：他要的是封面整齊、標題統一、隨手一播就有歌詞的那種體驗，而不是一堆檔名亂碼的資料夾。yubal 就是站在這個交叉口上的代表作品：它本質上是一個 YouTube Music 下載器，但把下載之後所有繁瑣的整理工作都吃下來，輸出一份 Navidrome、Jellyfin 都能直接掃得到、有封面有歌詞有 ReplayGain 的私有音樂庫。

來源頁面把 yubal 描述成「把已有的音訊來源連結整理成標準化的媒體庫」，這個說法只講了一半。 GitHub 倉庫 description「Self-hosted YouTube Music downloader. Paste a link, get a tagged, organized library」，yubal 處理的「音訊來源連結」實際上就是 YouTube Music 的歌曲、專輯與播放清單連結。這點會在後面的法律與條款段落詳細拆開，因為它直接決定你適不適合用這個工具。

yubal 把 YouTube Music 連結變成有標籤的本地音樂庫

yubal 是一個用 Python 3.12 以上、FastAPI 後端、uv workspace 多套件結構打造的開源專案，目前以 MIT 授權在 GitHub 上的 guillevc/yubal 倉庫維護，截至 2026 年 7 月已累積約 1438 顆星、47 個 fork。底層下載引擎是 yt-dlp，再透過 ytmusicapi 抓元資料、ffmpeg 做轉碼、lrclib.net 撈歌詞。把它想成「下載引擎 + 元資料刮削 + 檔案庫管理員」三層疊起來的服務，就不會被來源那種「私有圖書管理員」的擬人化比喻誤導。

它的核心工作流非常線性：你丟一個 YouTube Music 連結進去，yubal 先透過 yt-dlp 抓音訊串流、轉成你指定的格式，接著用 ytmusicapi 撈歌手、專輯、發行年、曲目編號，把檔名重新命名成 歌手/年份 - 專輯/曲目編號 - 歌名.副檔名 的結構，再從 lrclib.net 拉對齊時間軸的 .lrc 歌詞檔，最後寫入 ReplayGain 標籤讓播放音量一致。輸出的資料夾結構，README 裡直接用 Pink Floyd 與 Radiohead 示範：

data/
  Pink Floyd/
    1973 - The Dark Side of the Moon/
      01 - Speak to Me.opus
      01 - Speak to Me.lrc
      02 - Breathe.opus
      02 - Breathe.lrc
      cover.jpg
  _Playlists/
    My Favorites [n2g-XhDv].m3u

這裡有兩個細節值得駐足。首先是播放清單的處理方式：yubal 並不是把同一首歌複製成五份散在五個資料夾，而是所有曲目都收在專輯資料夾裡，播放清單另外生成 .m3u 檔用相對路徑指過去。這就是 README 強調的「smart deduplication」，背後的邏輯是寸土寸金的 Nas 硬碟空間不該被同一首歌重複佔用。另一個細節是 .lrc 歌詞檔的命名，必須與音訊檔主檔名一致，這是 Navidrome、Jellyfin 內建歌詞顯示功能的必要條件，yubal 預設 YUBAL_FETCH_LYRICS=true 與 YUBAL_YTMUSIC_LYRICS_FALLBACK=true，前者從 lrclib.net 撈，後者在 lrclib 查不到時退回 YouTube Music 自己的歌詞。

與我們先前介紹過的 AudioMass 瀏覽器音訊編輯器不同，yubal 不處理「剪輯音訊」這件事，它只負責「取得音訊並整理」；而同樣是開源媒體工具的 FreeCut 處理的是影片剪輯，定位上更接近「拿到素材之後才開始做」的階段。yubal 站的是再往前一步的「先把素材放進庫裡」這個位置。

Opus 為預設格式，媒體伺服器整合作業測試

yubal 預設輸出 Opus 格式（YUBAL_AUDIO_FORMAT=opus），這是 README 明確推薦的選項。理由很技術：Opus 在 64 至 128 kbps 的位元率就能達到 MP3 320 kbps 聽感上難以分辨的音質，副檔名小、高頻細節保留完整，對於把音樂庫放在 Nas 上、頻寬與儲存都有限的 self-hosted 場景特別合適。如果你用的是不支援 Opus 的播放器，可以改成 mp3 或 m4a；yubal 會在 YouTube 提供原始檔可直接下載時不做轉碼，需要時才透過 ffmpeg 處理，避免無謂的運算浪費。

媒體伺服器整合是 yubal 設計上很明確的目標，README 直接列了三個實測過的目標：

推薦組合是 yubal 加上 Navidrome，前者把檔案整理好、後者負責串流播放，再搭配 Symfonium（Android）、Amperfy 或 Arpeggi（iOS）、Supersonic（桌面）當客戶端。這條堆疊在 HomeLab 圈子裡已經算是相對成熟的 self-hosted 音樂方案，yubal 補上的就是「檔案來源到媒體櫃」這最後一哩路。

排程同步與瀏覽器擴充功能

一次性下載整個播放清單只是 yubal 的一半，另一半是訂閱式同步。預設 YUBAL_SCHEDULER_ENABLED=true、YUBAL_SCHEDULER_CRON="0 0 * * *"，也就是每天午夜把你訂閱的 YouTube Music 播放清單重新掃一次，把新增的曲目自動下載、套用與既有專輯一致的命名規則、補進對應的 .m3u。對於訂閱「My Favorites」或「Release Radar」這類會持續更新的清單，這個機制等於讓你的私有音樂庫自動長大。

另一個加分的設計是瀏覽器擴充功能，目前已上架 Firefox Add-ons（addons.mozilla.org/firefox/addon/yubal），Chrome 版本則要從 GitHub Releases 的 ext-v 標籤手動安裝。擴充功能直接在 YouTube 與 YouTube Music 的頁面上插入按鈕，可以一鍵把目前曲目或播放清單送進你自架的 yubal 實例。這個體驗上跟 AI YouTube Transcript 那種「在 YouTube 頁面上直接抽取內容」的瀏覽器擴充功能概念相近，差別在於一個抽字幕、一個抽音訊。但這個擴充功能會把你的 yubal 端點與瀏覽器綁在一起，預設又沒有 API 認證，所以具體的資安風險我們留到後面那段專門講。

Pin

你該知道的法律與條款邊界

yubal 的程式碼是 MIT 授權，這部分毫無問題。你可以合法地下載、修改、自架、甚至做衍生作品。但程式碼的授權與「使用這個程式下載的內容」是兩件事，後者才是真正的風險所在。yubal 的下游行為有三層需要分開理解。

最直接的一層是 YouTube 的服務條款。YouTube 的 Terms of Service 第 5.B 條明文禁止「access Content through any technology or means other than the playback functionality of the Service」，白話文就是「不得繞過 YouTube 官方播放器取得內容」。yt-dlp 與 yubal 這類工具從技術上就是在這條紅線邊緣，這也是 2020 年 RIAA 對 youtube-dl 提出 DMCA takedown 的根本理由（後來 GitHub 復原，但法律爭議並沒有真正結束）。即使你只是下載自己付費訂閱的 YouTube Music Premium 內容，條款上仍然不被允許，只是 YouTube 個人用戶被實際追究的案例非常少。

再往內一層，是音樂本身的著作權。在台灣的脈絡下，從串流平台側錄下載受保護的錄音著作，原則上會涉及《著作權法》第 92 條「公開演出或公開傳輸」的灰色地帶。單純個人私下保存、不另行分享或重製散布，實務上檢察官通常不會主動偵辦，但只要把檔案放到公開的 Navidrome 實例讓其他人能串流播放，就跨過了從「個人使用」到「公開傳輸」的門檻，這時侵權風險會明顯上升。yubal 預設是 self-hosted 工具，技術上很容易意外開放給親友或整個網際網路，部署前必須先想清楚誰能連得到。

Pin

相對容易安心的，是第三種情境，也是 yubal 真正能安心發揮的地方。YouTube 上有大量以 Creative Commons 授權發布的音樂、創作者自己上傳的原始作品、公開授權的演奏錄音，這類內容下載與重製在授權範圍內是被允許的。如果你本來就是獨立音樂創作者、想把 CC 授權的素材整理進自己的媒體櫃做二次創作參考，yubal 的整理能力在這個脈絡下是合理且低風險的工具。我們在過去討論 開源剪輯工具 時也提過類似的邏輯：工具本身的技術價值，與你拿它處理什麼內容，是兩個獨立的判斷。

預設 CORS 全開與無認證 API 的資安風險

yubal 在 2026 年 7 月仍有一個未解的開放議題，編號 #153，標題是「Default CORS and unauthenticated API allow arbitrary websites to control a yubal instance」。這是 GitHub Issues 上由外部資安研究者提交的 draft，內容直指 yubal Docker 預設配置的三個疊加問題：Dockerfile 把 YUBAL_HOST 設為 0.0.0.0、README 快速上手把容器 port 8000 對外發布、packages/api/src/yubal_api/settings.py 把 cors_origins 預設為 ["*"]，而 API 路由又完全沒有掛認證 dependency。

這三個條件疊在一起的意思是：你照著 README 快速上手跑起來的 yubal 實例，整個 API 是任何網頁都能直接 fetch 的。包含 upload_cookies（上傳你的 YouTube cookies 檔）、delete_cookies、create_job（觸發下載任務）、create_subscription（訂閱播放清單）這些具副作用的路由全都不需要 token。攻擊面是你只要在裝了 yubal 的機器上用瀏覽器逛到一個惡意網頁，那個網頁就能透過 cross-origin fetch 控制你的 yubal。它能讀你的任務記錄、能改你的訂閱、最嚴重是能換掉你的 cookies.txt。

cookies.txt 這個檔案在 yubal 的設計裡是讓你匯入 YouTube Music 帳號的登入 cookie，用來抓私人播放清單或付費訂閱內容；如果這個檔案被換掉或外流，等於你的 YouTube 帳號登入狀態被別人拿走，這個風險等級遠遠超過「下載侵權音樂」本身。。研究者給出的修法建議是：所有非健康檢查的 API 路由都應該強制認證、YUBAL_CORS_ORIGINS 預設值應改成 yubal UI 自己的 origin 而不是 ["*"]。截至本文寫作時這個 issue 仍處於 open 狀態，作者還沒合併修法。實際部署前最起碼要把 YUBAL_CORS_ORIGINS 改成白名單、把 port 對外發布改成 only localhost 或 LAN、並把 yubal 放到反代後面加上基本認證；如果你想暴露到公網，請務必自己加一層反向代理 + 存取控制，不要直接把 8000 對外。

專案活躍度與社群反饋

從 GitHub 的客觀指標來看，yubal 是個仍在積極維護的專案。截至 2026 年 7 月，最新正式 release 是 v0.9.1（2026-06-11 發布，同步把 yt-dlp 升到 2026.6.9），main 分支最近一次推送落在 2026-07-06，內容是把 yt-dlp 再往上拉到 2026.7.4。這種 yt-dlp 跟版頻率是下載類工具能不能長期用的硬指標，因為 YouTube 反爬機制幾乎每個月都在更新，下載引擎沒有跟版就等於慢慢失效。yubal 的開發者對這件事顯然有意識。

開放議題方面，除了前面提的 #153 資安問題，還有 #158 SoundCloud 整合（功能擴充）、#159 嵌入式歌詞（要直接把歌詞寫進音訊檔的中繼資料）、#148 已訂閱的「喜歡的歌曲」清單無法定期同步、#151 Top songs 播放清單的命名邏輯調整。closed issues 的回應速度看起來正常，#149 的 I/O 錯誤也已在近期版本修掉。整體而言社群討論雖不算熱烈，但開發者對 issue 的關注是持續的。

適合誰、不適合誰

yubal 對的使用者輪廓相當明確：你已經有一台 Nas 或常駐 Linux 機器、已經跑著 Navidrome 或 Jellyfin、想把自己的音樂收藏從「散亂的 MP3 資料夾」升級成「有元資料、有歌詞、有封面的正式媒體櫃」，而且你能接受「下載來源是 YouTube Music」這個條件本質上的灰色地帶。如果你本來就在用 yt-dlp 自己抓歌，但又懶得每次都手動整理 metadata、寫 .lrc、處理重複檔案，yubal 確實能省下大量繁瑣工作。

你不該考慮 yubal 的情境也同樣清楚。如果你要的是完全合法、零風險的音樂收藏方案，正路是買 YouTube Music Premium、Apple Music、Spotify Premium 之類的正版訂閱，或直接購買 CD 與數位專輯再自行轉檔。如果你只是想試用一下、沒有自架環境，yubal 對你來說部署成本太高。如果說你的目標是「把自己的創作或 CC 授權音樂整理進媒體櫃」，那 yubal 是合理的工具選擇。這個情境下不存在 YouTube ToS 問題，純粹是在用它強大的整理 pipeline。

與其它自架工具的定位對比上，yubal 跟 FeedCraft 這類 RSS 中介層其實有個共同的設計哲學：都是「把來源訊號定時抓回來、整理成你以後查得到的形式」。FeedCraft 做文字、yubal 做音訊；兩者都依賴排程抓取、都預期長期放在 Nas 上跑。這個 pattern 在 self-hosted 工具圈會越來越常見。和 Antify 那種裝在桌面的工具相比，yubal 是伺服器型應用，安裝門檻更高但設定完之後可以一直放著運作。

結論：技術扎實的媒體櫃管家，但條款風險要自己扛

從純技術角度評價，yubal 是 2026 年 self-hosted 音樂櫃領域裡完成度最高的開源選項之一：元資料刮削紮實、Opus 預設合理、與 Navidrome 的整合開箱即用、排程同步與瀏覽器擴充功能補齊了最後一塊使用體驗，開發節奏也算穩定。這份技術成績單完全值得肯定。

但這個工具的核心下游行為（也就是下載 YouTube Music 內容）同時也是它的法律與條款包袱。YouTube ToS 第 5.B 條、台灣著作權法第 92 條的灰色地帶、#153 號尚未修補的資安議題，這三件事是技術優點沒辦法抵銷的決策成本。把它當成「合法的免費音樂來源」是危險的誤讀；把它理解成「一套強大的音訊整理 pipeline，至於要餵什麼內容進去由你決定並自負風險」會更準確。如果你已經想清楚這幾個邊界，並準備好做相應的 CORS 白名單與反代設定，那 yubal 確實是目前 self-hosted 音樂櫃生態裡最值得花時間研究的工具之一。

常見問題

yubal 是完全免費的嗎？

yubal 程式碼本身是 MIT 授權、免費且開源，你可以在自己的硬體上免費使用。但要讓它正常運作，你需要自備一台常駐機器（Nas、Linux 小主機或 VPS）、Docker 執行環境、以及足夠的儲存空間放整理後的音樂庫。如果你選擇訂閱 YouTube Music Premium 以便存取完整曲目，那個訂閱費是付給 Google、不是付給 yubal。

yubal 會不會違法？

工具本身是合法的開源軟體，但使用它下載受版權保護的 YouTube Music 內容，會涉及 YouTube 服務條款第 5.B 條的禁止行為，以及台灣著作權法第 92 條公開傳輸的灰色地帶。個人私下保存實務上很少被追究，但如果你把整理後的檔案放到對外開放的媒體伺服器讓他人串流，侵權風險會明顯上升。下載 Creative Commons 授權或你自己擁有權利的內容則是相對低風險的使用方式。

預設配置安全嗎？

不安全。預設 Docker 配置會把 API 暴露在 0.0.0.0:8000、CORS 開成 ["*"]、且完全沒有 API 認證，這代表任何你瀏覽到的惡意網頁都能透過 cross-origin fetch 控制你的 yubal 實例。正式部署前請把 YUBAL_CORS_ORIGINS 改成白名單、port 改成只在 localhost 或內網、並在前面加一層反代做基本認證。

yubal 跟直接用 yt-dlp 有什麼差別？

yt-dlp 是下載引擎，yubal 是包在 yt-dlp 外面的完整整理流水線。yt-dlp 給你的是「檔案」，yubal 給你的是「有元資料、有歌詞、有封面、與媒體伺服器整合好的資料夾結構」。如果你只想偶爾手動抓幾首歌，yt-dlp 加上自己寫的腳本就夠了；如果你希望建立一個會自動同步、長期維護的 self-hosted 音樂櫃，yubal 省下的整理時間會非常可觀。

可以串流到 Navidrome 與 Jellyfin 嗎？

可以，而且這是 yubal 的主要設計目標之一。README 明確測試過 Navidrome、Jellyfin 與 Gonic 三個媒體伺服器：Navidrome 開箱即用、Jellyfin 需要勾選 Use non-standard artists tags、Gonic 則需要額外設定 GONIC_MULTI_VALUE_ARTIST。播放清單會自動生成 .m3u 檔，Navidrome 與 Jellyfin 都支援，Gonic 不支援。