Twitch music provider

[Drizzt321]

Created a Twitch Music Provider, to listen to audio_only streams. Primarily for DJ streams, but could probably be used for any stream.

I'm not a Python developer, and I heavily used Claude Code, so while I did look at things, I'm more a Java developer, rather than Python.

Website docs update: music-assistant/music-assistant.io#561

[Drizzt321]

Sorry for the delay, it's been a busy week. Should have your concerns handled now. Hopefully doesn't raise new ones :)

[Copilot]

Pull request overview

Adds a new Twitch Audio music provider to Music Assistant, enabling playback of Twitch channel audio-only streams (via Streamlink) with optional raid-following via Twitch EventSub, plus a comprehensive provider-specific test suite.

Changes:

• Introduces music_assistant.providers.twitch provider implementation (OAuth, browse/search, radio streaming, caching, ad passthrough, raid-following).
• Adds an EventSubClient WebSocket implementation for channel.raid subscriptions and switching active queues on raids.
• Adds extensive pytest coverage (API client behavior, streaming/reconnects, recommendations, browsing/search, OAuth/refresh/revoke, EventSub, raid-following) and fixtures; adds Streamlink dependency.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
music_assistant/providers/twitch/__init__.py	Main Twitch provider: OAuth config flow, Twitch API helpers, browse/search/radios, Streamlink streaming with reconnects and ad-state tracking, raid-following logic.
music_assistant/providers/twitch/eventsub.py	EventSub WebSocket client for raid subscriptions + reconnect/backoff management.
music_assistant/providers/twitch/ad_handling.py	Streamlink Twitch plugin monkey-patch to pass through ad segments while tracking ad-break state.
music_assistant/providers/twitch/manifest.json	Provider manifest declaring domain, beta stage, and Streamlink requirement.
requirements_all.txt	Adds streamlink>=8.0,<9 to the full requirements set.
tests/providers/twitch/__init__.py	Test package marker for Twitch provider tests.
tests/providers/twitch/conftest.py	Shared fixtures/mocks for Twitch provider tests (mock responses, mock MA/core objects, fixture loader).
tests/providers/twitch/test_provider.py	Provider lifecycle/config entry tests (setup/init/unload/features).
tests/providers/twitch/test_auth.py	OAuth action handling, token exchange, refresh, and revoke behavior tests.
tests/providers/twitch/test_twitch_api.py	Tests for request headers, pagination, batching, caching, and error handling in API calls.
tests/providers/twitch/test_browse.py	Browse structure + library radios + search behavior tests.
tests/providers/twitch/test_recommendations.py	Recommendations folder creation and contents tests.
tests/providers/twitch/test_streaming.py	StreamDetails + Streamlink streaming generator behavior, reconnect logic, and token header tests.
tests/providers/twitch/test_ad_handling.py	Validates Streamlink monkey-patching behavior using injected fake Streamlink modules.
tests/providers/twitch/test_eventsub.py	EventSub client message handling, subscribe/unsubscribe, reconnect/backoff behavior tests.
tests/providers/twitch/test_raid.py	Raid-following behavior tests, including grace-period handling and multi-queue switching.
tests/providers/twitch/fixtures/followed_channels.json	Twitch API fixture: followed channels pagination.
tests/providers/twitch/fixtures/live_streams.json	Twitch API fixture: live streams response.
tests/providers/twitch/fixtures/search_results.json	Twitch API fixture: search results response.
tests/providers/twitch/fixtures/user_lookup.json	Twitch API fixture: /helix/users response.
tests/providers/twitch/fixtures/token_exchange.json	Twitch OAuth token exchange fixture.
tests/providers/twitch/fixtures/token_refresh.json	Twitch OAuth refresh fixture.
tests/providers/twitch/fixtures/eventsub_welcome.json	EventSub fixture: welcome message.
tests/providers/twitch/fixtures/eventsub_reconnect.json	EventSub fixture: reconnect message.
tests/providers/twitch/fixtures/eventsub_revocation.json	EventSub fixture: revocation message.
tests/providers/twitch/fixtures/eventsub_raid.json	EventSub fixture: raid notification message.

[Drizzt321]

Updated as per Copilot reivew.

[OzGav]

The current approach with both browse() and get_library_radios() implemented is not correct. We recently standardised the radio provider pattern — if a provider declares LIBRARY_RADIOS and implements get_library_radios(), the base class handles browse automatically by calling the get_library_*() methods. You should not also be implementing browse() or declaring BROWSE in SUPPORTED_FEATURES.
The correct pattern is:

get_library_radios() yields all followed channels (all of them) and MA's library sync takes care of adding and removing from the library automatically
recommendations() is the right place to surface currently live channels since it is surfaced to the user on demand

Users therefore have all of their library from the provider in the MA library and use the search to find more.

Please remove browse() and remove BROWSE from SUPPORTED_FEATURES.
If you have a specific use case that genuinely requires a dedicated browse implementation that cannot be served by this pattern, please raise it and we can discuss, but our strong preference is to maintain the standardised approach across all providers."

[OzGav]

To be clear. You are filtering out non-live channels but this method is only called on each full sync of the library at the specified interval, so that could be hours old. A channel that was live when the sync ran will appear in the library, and one that wasn't live will be missing — even though the user follows both. The live status enrichment (viewer count in the name, live thumbnail) will also be stale by the time the user sees it, so it has no value here. The library should be a stable list of all followed channels with basic profile info and nothing more.

[OzGav]

The other thing here is that for unhandled status codes it raises MusicAssistantError directly — this is the base exception and should not be used directly. ProviderUnavailableError or SetupFailedError would be appropriate for an unexpected HTTP status I would think.

[OzGav]

There are nine of these. You need to be catching the specific errors you are looking for to ensure they are handled correctly.

[OzGav]

When you call asyncio.create_task() without storing the result, any exceptions raised by that task are silently lost with no way to know something went wrong. Look at how how other providers do this — please apply the same pattern to the other create_task() calls in eventsub.py

[OzGav]

Typing this as Any is defeating mypy type checking. I think this should be aiohttp.ClientSession and below ws should be aiohttp.ClientWebSocketResponse

[OzGav]

You need to fix these rather than ignore them. If you fix the types I mentioned before then somthing like this should work (so look at all the ignores again you will be able to fix them)

try:
    self._ws = await self._http_session.ws_connect(url)
except aiohttp.ClientError:
    logger.debug("EventSub: WebSocket connection failed", exc_info=True)
    continue

async for msg in self._ws:
    if self._stopped:
        break
    ...

[OzGav]

How come you aren't using MA's cache system?

[OzGav]

General comment on the docstrings. They should provide clarity to the caller, not explain implementation. Several docstrings describe internal mechanics, e.g.: _create_streamlink_session: "Blocking — call via to_thread" is an implementation note, not caller-facing
The format needs to be Sphinx-style. e.g.

def my_function(param1: str, param2: int, param3: bool = False) -> str:
    """
    Brief one-line description of the function.

    :param param1: Description of what param1 is used for.
    :param param2: Description of what param2 is used for.
    :param param3: Description of what param3 is used for.
    """

[MarvinSchenkel]

So I just did some digging in the TOS and I am afraid we cannot merge this PR because of it :(. Specifically:

• D1 - Embeddable Experiences: You must adopt and integrate our embeddable player for all Twitch video content. You may not use any other player or system to display Twitch video content without Twitch’s prior written permission.
• X1.I: You will not access undocumented Program Materials or otherwise attempt to derive or use the underlying source code of undocumented Program Materials without Twitch’s prior written permission. You may only access data from Program Materials consistent with the terms of this Agreement and, unless you have Twitch’s prior written permission, will only access Program Materials documented on the Twitch. StreamLink seems to use undocumented GraphQL API's

What is your interpretation of this?

[Drizzt321]

Sorry for how delayed getting back to you I have been, work has slammed me. I should be able to pick this back up in a few weeks.