v1.1.3

What's Changed

• fix: keep private playlists off the yt-dlp fallback, un-like deleted tracks by @sproft-bot in #84

Full Changelog: v1.1.2...v1.1.3

v1.1.2

Makes plain-YouTube uploads findable in search when you have more than one music provider enabled.

The bug

v1.1.0 added a second search pass over YouTube Music's Videos tab, which is what indexes live recordings and other regular YouTube uploads. Those results were ranked below the catalog songs, with a reserved slice at the end of the list so they could not be crowded out.

That reservation protected them inside this provider's own list, which turned out not to be the list you see. Music Assistant merges every enabled provider's results into one shared window per media type, taking them in turn and then cutting the merge to the requested limit. With several providers answering, only the first few of our items survive the cut, and anything ranked at the end never reaches the screen.

The result: a video was findable when YouTube Music was your only provider and vanished as soon as Spotify or another provider was enabled alongside it. Reported in #77.

The fix

Each result is now scored by how much of what you typed appears in its title, version and artist names. A video moves ahead of the catalog songs when it covers your query clearly better than every song does.

For a query like porridge radio 7 seconds madrid, the catalog only fuzzy-matches "7 seconds" while the upload matches the whole query, so the upload now leads the results and survives the merge.

Ordinary searches are unchanged. A video that matches your query no better than the catalog stays below the songs, which is right for the common case where the catalog holds the recording you meant.

Three limits keep this from going too far:

• Promoted videos may only take window slots the songs were not going to use, so a query where every video outranks the catalog cannot turn a music search into a wall of YouTube uploads.
• The reservation from v1.1.0 stays, and the number of videos shown is unchanged. Only their position moves.
• When there are no catalog songs to outrank, nothing is reordered, so the scoring never second-guesses the order YouTube Music returned.

Updating

Re-run the installer script, or let the watcher add-on pick the release up, then restart Music Assistant.

What's Changed

• fix: rank a clearly-better video ahead of the catalog songs by @sproft-bot in #81

Full Changelog: v1.1.1...v1.1.2

v1.1.1

Fixes a track whose artist is unknown failing to be added to the library.

The bug

Uploads without a linked artist channel get a placeholder artist mapping with the id unknown. _minimal_track has used it since the first release, and since v1.1.0 the videos-tab search fallback uses it too, so plain-YouTube uploads surfaced by search carry it.

That one id was the only fake artist id get_artist refused to resolve. It missed both the unknown_<name> stub branch and the UC channel-id shape check, so it raised MediaNotFoundError.

Music Assistant resolves a track's artist mappings through the provider's get_artist in two places a user can see:

• Opening the artist page produced an error toast (artist://unknown not found on provider …) and a permanently empty page.
• Adding the track to the library failed. Music Assistant treats MediaNotFoundError as "drop this artist", and when the placeholder was the track's only artist the add then failed hard with Track is missing artist(s) and nothing was saved.

Playback was never affected. The queue path swallows the error, drops the artist, and streams anyway.

The fix

get_artist now returns the same local stub the unknown_<name> ids already got, with the name falling back to Unknown Artist for the bare id. No YouTube Music API call is involved, since that id never had one behind it.

Verified against Music Assistant 2.9.13 and 2.10.0rc4, which share identical code on this path.

Updating

Re-run the installer script, or let the watcher add-on pick the release up, then restart Music Assistant.

What's Changed

• fix: resolve the bare "unknown" artist id to a stub by @sproft-bot in #80

Full Changelog: v1.1.0...v1.1.1

v1.1.0

What's Changed

• feat: surface plain-YouTube uploads in track search; port settings to MA 2.10 by @sproft-bot in #79

Full Changelog: v1.0.2...v1.1.0

v1.0.2

What's Changed

• fix: survive the android_vr shutdown; require the yt-dlp nightly that drops it by @sproft-bot in #76

Full Changelog: v1.0.1...v1.0.2

v1.0.1

What's Changed

• docs: stop pointing failed installs at the 2026-05 pre-release by @sproft-bot in #73
• test: skip the live podcast canary on YouTube's bot check instead of failing by @sproft-bot in #74
• fix: stream audio in bounded range chunks; googlevideo refuses ffmpeg's fetch by @sproft-bot in #75

Full Changelog: v1.0.0...v1.0.1

v1.0.0

What's Changed

• Add MA Provider Watcher installer script + tests + CI by @sproft-bot in #4
• Add pytest suite for the ytmusic_free provider by @sproft-bot in #5
• feat: add install_provider.sh for one-line provider install by @sproft-bot in #8
• Fix: treat HTTP 403 in library_add/remove as no-op for user-owned items by @sproft-bot in #7
• Detect auth lapses and warn on incomplete cookies (issue #6) by @sproft-bot in #9
• fix: actionable docker-missing guidance for install_provider.sh (issue #11) by @sproft-bot in #12
• fix: watcher logs loud error on MA container mismatch + document sh -s -- (issue #11) by @sproft-bot in #14
• fix: detect partial-auth empty library responses (issue #10) by @sproft-bot in #13
• fix: per-type search and graceful artist navigation for non-channel ids (issue #18) by @sproft-bot in #19
• fix: guard get_watch_playlist so radio_mode degrades gracefully (issue #20) by @sproft-bot in #21
• fix: stamp watcher add-on version per run so HA rebuilds the image (issue #22) by @sproft-bot in #23
• fix: detect HAOS apps/local + /addons paths in watcher installer, refresh docs (issue #22) by @sproft-bot in #24
• Artist parsing fix (#25) + browseId/artist handling for album/track artists + tests by @sproft-bot in #26
• feat: YouTube/YTM link paste + video trimming (by @gusjengis) + Copilot fixes by @sproft-bot in #29
• docs: add Credits section, document --repo-owner, tidy feature copy by @sproft-bot in #30
• docs: document ytmusic:// link workaround (issue #31) by @sproft-bot in #34
• feat: add automated Docker image builds via GHCR for standalone Docker users by @jojo141185 in #33
• fix: detect beta/nightly/dev MA containers + curl-pipe hints (issue #35), post-#33/#34 cleanup by @sproft-bot in #36
• Watcher add-on: opt-in auto-update of the provider by @bygadd in #32
• fix: correct watcher auto-update (#32) — disable reverts to bundled, add CI coverage by @sproft-bot in #37
• docs: mention the watcher's opt-in auto-update in the README by @sproft-bot in #38
• docs: credit @jojo141185 and @bygadd in the README by @sproft-bot in #39
• feat: support multiple provider instances (#40) by @sproft-bot in #43
• Make best audio work by @mawoka-myblock in #44
• fix: complete the audio quality fix and guard it with tests (#41) by @sproft-bot in #45
• docs: correct the stale android_music claim in "How it works" by @sproft-bot in #46
• fix: address four follow-ups from the issue #41 audio quality fix by @sproft-bot in #48
• fix: resolve auto-generated mixes via the watch endpoint (#47) by @sproft-bot in #49
• fix: resolve mix details, and stop truncating editorial playlists (#47) by @sproft-bot in #50
• fix: wait out YouTube's pre-roll ad window before streaming (#51) by @sproft-bot in #57
• fix: stop re-rolling auto-generated playlists on every render (#56) by @sproft-bot in #58
• fix: detect the app_* container name Supervisor now uses (#54) by @sproft-bot in #59
• fix: stop a lapsed cookie from deleting the user's library (#55) by @sproft-bot in #60
• feat: podcast support, anonymous (#52) by @sproft-bot in #61
• feat: sync subscribed podcast shows when authenticated (#52) by @sproft-bot in #62
• feat: cache catalogue lookups and carry the album release year (#53) by @sproft-bot in #63
• fix: fail a library sync we could not read instead of reporting it empty (#64) by @sproft-bot in #67
• test: pin the ProviderFeature members the provider declares (#65) by @sproft-bot in #69
• ci: import the provider against real Music Assistant, and check nightly (#66) by @sproft-bot in #70
• feat: record a version and cut releases from tags (#68) by @sproft-bot in #71
• feat: install the newest release by default, and version the watcher (#68) by @sproft-bot in #72

New Contributors

• @sproft-bot made their first contribution in #4
• @jojo141185 made their first contribution in #33
• @bygadd made their first contribution in #32
• @mawoka-myblock made their first contribution in #44

Full Changelog: v0.1.0-beta.1...v1.0.0

v0.1.0-beta.1 — beta checkpoint

⚠️ Superseded by v1.0.0

Install v1.0.0 instead. Both install scripts now fetch the newest release by default, so the documented one-liners already give you it:

curl -fsSL https://raw.githubusercontent.com/sproft/music-assistant-ytmusic/main/scripts/install_provider.sh | sh

This checkpoint is from May 2026 and predates roughly seventy merged pull requests. Among other things, it is missing podcast support, the AI-music filter, the pre-roll fix for 403 Forbidden playback failures, multi-instance support, response caching, and the guard that stops an expired cookie from deleting your Music Assistant library. The notes below still say "podcast support is not currently included" and describe a "what's next" that shipped long ago; they are kept as a record of what this tag was, not as current documentation.

It stays published, and the tag stays put, so anyone who pinned --ref v0.1.0-beta.1 keeps working. It remains flagged as a pre-release, which means the install scripts' "newest release" lookup skips it.

---

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-dlp using the android_music client (no PO token / login required for free-tier content).
• Playlist support with a yt-dlp fallback 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-AuthUser header — 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 via curl + tar)
• POSIX-sh test suite + GitHub Actions CI (shellcheck + tests under both dash and bash)
• 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 ytmusicapi and yt-dlp.
• Thanks to @ngocjohn (#2) for catching the HAOS vs. Supervised path discrepancy in WATCHER_ADDON.md.