Twitch embedded ads / commercial ad break / purple screen (November 2022)

[bastimeyer]

Opening a new meta thread as a replacement for the old one from two years ago (#3210), as ads were not embedded by Twitch almost the whole year, so it's a bit outdated and lots of people are getting confused.

What are embedded ads and why is this a problem for users of Streamlink?

Please read this section written in the docs:
https://streamlink.github.io/latest/cli/plugins/twitch.html#embedded-ads

What has changed?

Not much. Twitch has once again started to embed ads into HLS streams which replace the actual stream data. This has been the case already since 2019 and has been an ongoing thing since then, with several time spans where embedded ads were turned off again, sometimes for days, and sometimes for several months. In the past year, Twitch didn't embed ads at all. Now that they have announced a rebuild of their embeddable web-player, they also announced changes to their ad program. Since Streamlink uses the same API calls which Twitch's embeddable web-player makes, ads are once again included directly in the HLS stream.

What can be done to get rid of ads?

1. Preventing ads

   1. Via authentication, if you have a paid subscription of Twitch Turbo or specific channels:
      https://streamlink.github.io/latest/cli/plugins/twitch.html#authentication
      Note: the docs were just fixed in the 5.1.0 release from 2022-11-14:
      via plugins.twitch: OAuth token of account with turbo does not prevent pre-roll ads #4939
   2. By setting a set of known headers for triggering the generation of different streaming access tokens, e.g. for players where Twitch usually doesn't show ads, like the front page player on their website, embedded web players for specific sites/events, etc. This is explained in the docs linked above. Streamlink had already implemented workarounds several times over the past years by switching to different API call parameters for using a different kind of web player where Twitch doesn't serve ads, and all of those workarounds had to be reverted after a short while again. It is currently unknown whether any of those web players exist and which API parameters would be needed. The --twitch-api-header and newly added --twitch-access-token-param CLI parameters allow users to change the API headers and parameters when acquiring a streaming access token, so that if something new gets discovered, users don't have to wait for a new Streamlink release.

2. Filtering out ads from the output
   As explained in the docs, Streamlink supports filtering out unwanted segments from HLS streams, like embedded ads. This can be done via the --twitch-disable-ads CLI parameter.

   Please make sure to be using the latest Streamlink release:
   https://streamlink.github.io/install.html
   Release 5.1.0 with a fix for the ad filtering has just been published on 2022-11-14.

   Filtering out ads means that the output of Streamlink will stop during the filtering and that playback in the video player will stop. Since there will be a stream discontinuity when resuming the stream after the ad break, certain players like VLC might still have a problem, even though it is not a stream discontinuity between the regular stream and ads. If you're having issues with your video player, even in the current unfixed state, please try using a different player instead, like MPV for example. Even though Streamlink's CLI defaults to VLC for its simplicity and ease of use, other players are a better alternative.

Other solutions?

We can't do anything about embedded ads and all possible solutions and workarounds are mentioned above. Since I've been asked a lot, Streamlink can not replace ad content with other content from lower bitrate streams, which certain web browser extensions can do for example, because Streamlink's output is a progressive stream where stream discontinuities need to be avoided. It is also not the focus of Streamlink to provide an ad-free experience. The main goal is being able to output a stream that can be viewed by all video players.

Streamlink also won't switch to a Twitch proxy server which relays HLS playlist requests to Twitch servers in countries where ads apparently are not embedded into the stream. If you want to use a proxy server, then use the available options.

Why do ads not get filtered out by default?

You need to set the --twitch-disable-ads CLI parameter, because it alters the logic of the HLS implementation, and we don't want to have a custom/specific altering logic as the default.

Streamlink Twitch GUI

If you're a Streamlink Twitch GUI user, just make sure that you're using the latest version of both Streamlink and the Twitch GUI. Then enable the "Skip advertisements embedded into streams" checkbox in the streaming settings menu, so that the Twitch GUI will set the --twitch-disable-ads parameter for you when launching streams.

Preventing ads via Streamlink authentication (as explained above) is a completely different thing compared to the Twitch GUI's own authentication. Streamlink authentication can be done via Streamlink's config file (see the docs), or by setting the parameter in the Twitch GUI's custom Streamlink launch parameters. In order to do that, advanced settings need to be enabled first in the Twitch GUI's main settings menu, then the field will become available in the streaming settings menu and it works just like on the command line shell. Proper support for Streamlink authentication for Twitch won't be implemented in Streamlink Twitch GUI due to the nature of the API differences and how the OAuth token is obtained.

More here:

• Embedded ads streamlink-twitch-gui#754
• https://github.com/streamlink/streamlink-twitch-gui/wiki

How can I set any parameters if I launch Streamlink via a different program?

If the program you're launching Streamlink with doesn't allow you to set the parameter, then take a look at the docs for Streamlink config file(s):
https://streamlink.github.io/latest/cli/config.html

Player passthrough

Make sure that you are not accidentally bypassing Streamlink by setting the --player-passthrough=hls parameter. If you do, then Streamlink will launch the player with the resolved HLS URL as launch parameter, meaning that the player will read the HLS stream on its own instead of Streamlink. Then ads filtering via Streamlink obviously won't work. Stream discontinuities in this case however should be handled by the player just fine, so if you are fine with watching ad breaks or if you've set authentication data, this can be a viable alternative compared to Streamlink's ad filtering.

---

Changelog

https://streamlink.github.io/changelog.html

• 5.1.2: fixed special case of mid-roll ads filtering (plugins.twitch: fix ad filtering bug #5007)
• 5.1.0: fixed mid-roll ads not being filtered out correctly (plugins.twitch: fix date offset of prefetch ads #4942)