YouTube Music (Free) — beta checkpoint
A pre-release snapshot of the working state of main prior to the installer-script PR (#4). Cut so users have a stable reference to pin to while the installer + CI work lands.
Provider (ytmusic_free/)
- Search, browse, and stream tracks, albums, artists, and playlists — without a YouTube Premium account.
- Audio resolution via
yt-dlpusing theandroid_musicclient (no PO token / login required for free-tier content). - Playlist support with a
yt-dlpfallback for unauthenticated playlist responses. - Optional browser-cookie authentication unlocks library sync (liked songs, saved albums, playlists, subscribed artists), personalized recommendations (home feed), and library editing (add/remove items).
- Brand-account support via the
X-Goog-AuthUserheader — enter your brand-account ID once and the provider speaks to that library instead of the primary account.
Watcher add-on (WATCHER_ADDON.md)
- Local Home Assistant add-on that polls the MA container every 10 s and re-installs the provider whenever the Supervisor recreates the container (e.g. after an HA restart). Solves the "files disappear after restarting HA" problem documented in the README.
- Manual install procedure documented for both HAOS (
/mnt/data/supervisor/addons/local/) and Supervised / Container (/root/addons/) installs.
Compatibility
| Without auth | With auth |
|---|---|
| ✅ Search (tracks, albums, artists, playlists) | ✅ Everything in the left column |
| ✅ Stream audio | ✅ Library sync (songs, albums, playlists, artists) |
| ✅ Artist top tracks / albums | ✅ Personalized recommendations |
| ✅ Similar tracks (song radio) | ✅ Library editing (add/remove) |
| ✅ Album / playlist tracks |
Podcast support is not currently included.
Installation
See README → Installation for the provider and WATCHER_ADDON.md for the manual watcher add-on procedure.
Caveats
- This uses YouTube's internal (unofficial) APIs without a premium account. Per the README's Legal Disclaimer, this is against YouTube's Terms of Service — use at your own risk.
- Premium-exclusive content (offline downloads, high-res audio) is not accessible.
- Google may change their APIs at any time, which may break functionality.
What's next (v0.1.0)
- One-line installer script for the watcher add-on (POSIX
sh, HAOS-friendly viacurl + tar) - POSIX-
shtest suite + GitHub Actions CI (shellcheck + tests under bothdashandbash) - Repo-wide LF line-ending enforcement
Tracked in PR #4.
Credits
- Audio extraction technique inspired by open-source players like SimpMusic and NewPipe.
- Built on
ytmusicapiandyt-dlp. - Thanks to @ngocjohn (#2) for catching the HAOS vs. Supervised path discrepancy in
WATCHER_ADDON.md.