Migrations

streamlink 6.0.0

Player-path-only --player CLI argument

Despite having the dedicated CLI argument for setting custom player arguments --player-args, Streamlink used to support setting custom player arguments using the --player CLI argument.

This meant that the --player value had to be treated as a command line string rather than a player path. As a result of this, player paths would need to be quoted if they contained whitespace characters. While the default config file of Streamlink's Windows installer tried to teach this, it was often used incorrectly on command-line shells, especially on Windows where escaping the CLI argument is more difficult compared to POSIX compliant command-line shells. Not quoting the player path on Windows still worked, but at the cost of potentially resolving an incorrect or malicious executable.

The support for custom player arguments in --player was a relic from the Livestreamer project and has finally been removed. --player now only accepts player executable path strings and any custom player arguments need to be set using the --player-args CLI argument where the argument value gets properly interpreted using shell-like syntax.

Streamlink's Windows installer has received a new default config file and users now also can choose to overwrite their existing config file from previous installs. The default behavior remains the same with existing config files staying untouched.

#5305

#5310

Migration

1. Move any custom player arguments from the value of --player to --player-args

2. In config files, remove any quotation from the value of --player (command-line shells will of course require quotation when the player path contains whitespace characters)

{filename} variable in --player-args

The --player-args's {filename} variable has been removed. This was kept as a fallback when the {playerinput} variable as added to prevent confusion around the player's input argument for various different stream transport methods, like stdin, named pipes, passthrough, etc.

#3313

#5310

Migration

1. Rename {filename} to {playerinput}

Plugin.can_handle_url() and Plugin.priority()

Streamlink 2.3.0 deprecated the can_handle_url() and priority() classmethods of Plugin in favor of the plugin matcher API. These deprecated classmethods have now been removed.

#3814

#5403

Migration

1. Replace custom matching logic in Plugin.can_handle_url() with pluginmatcher decorators

2. Replace custom plugin priority matching logic in Plugin.priority() with the priority argument of the pluginmatcher decorators

Plugin.__init__(self, url) compatibility wrapper

Streamlink 5.0.0 deprecated the usage of the old Plugin constructor without the Streamlink session argument. session was added because the old Plugin.bind() classmethod got removed, which previously bound the session instance to the entire Plugin class, rather than individual Plugin instances, causing Python's garbage collector to not be able to let go of any loaded built-in plugins when initializing more than one session.

#4768

#5402

Migration

1. Replace the arguments of custom constructors of each Plugin subclass with *args, **kwargs and call super().__init__(*args, **kwargs)

2. If needed, access the url using self.url

Streamlink.{g,s}et_plugin_option()

The Streamlink.get_plugin_option() and Streamlink.set_plugin_option() methods were removed as a result of moving plugin options from the Plugin classes to individual Plugin instances.

Plugin options now must be get/set referencing the Plugin.options instance and its respective get() and set() methods.

Alternatively, when initializing a Plugin class, e.g. after calling Streamlink.resolve_url() or Streamlink.streams(), an optional pre-initialized instance of Options can be passed to the constructor of the resolved Plugin class.

Be aware that Streamlink.resolve_url() will return the explicit plugin name, plugin class and the resolved URL, whereas Streamlink.streams() will initialize the first matching plugin automatically, so it's possible to pass custom options to a different plugin by accident, if the URL matches an unintended plugin.

#5033

Migration

1. Initialize an Options object with the desired key-value pairs and pass it to the Plugin constructor or the Streamlink.streams() method.

2. After instantiating a Plugin class, get or set its options using the get()/set() methods on the Plugin.options instance.

3. If plugin options need to be accessed in custom Stream implementations related to custom Plugin implementations, then those options need to be passed from the Plugin to the Stream constructor beforehand, since the Streamlink session can't be used for that anymore.

Before

from streamlink.session import Streamlink

session = Streamlink()
session.set_plugin_option("twitch", "api-header", [("Authorization", "OAuth TOKEN")])
streams = session.streams("twitch.tv/...")

After

from streamlink.options import Options
from streamlink.session import Streamlink

session = Streamlink()
options = Options()
options.set("api-header", [("Authorization", "OAuth TOKEN")])
streams = session.streams("twitch.tv/...", options)

Alternative

from streamlink.options import Options
from streamlink.session import Streamlink

session = Streamlink()
pluginname, Pluginclass, resolved_url = session.resolve_url("twitch.tv/...")
options = Options()
options.set("api-header", [("Authorization", "OAuth TOKEN")])
plugin = Pluginclass(session, resolved_url, options)
streams = plugin.streams()

Global plugin arguments

Streamlink 5.3.0 deprecated the is_global=True argument of the pluginargument decorator (as well as the Argument class), as global plugin arguments were deemed unnecessary. The is_global argument has thus been removed now.

#5140

#5033

Migration

1. Get the value of the global argument using Streamlink.get_option() instead of getting it from Plugin.options

plugin.api.validate.text

Streamlink 5.2.0 deprecated the plugin.api.validate.text alias for str. This was a remnant of the Python 2 era and has been removed.

#5090

#5404

Migration

1. Replace plugin.api.validate.text with str

HTTPStream and HLSStream signature changes

The signatures of the constructors of HTTPStream and HLSStream, as well as the HLSStream.parse_variant_playlist() classmethod were changed and fixed.

#5429

Migration

1. Set the Streamlink session instance as a positional argument, or replace the session_ keyword with session

streamlink 5.0.0

Session.resolve_url() return type changes

With the removal of the Plugin.bind() classmethod, the return value of Streamlink.resolve_url() and Streamlink.resolve_url_no_redirect() were changed. Both methods now return a three-element tuple of the resolved plugin name, plugin class and URL.

#4768

Migration

1. Return type changed from tuple[type[Plugin], str] to tuple[str, type[Plugin], str]

streamlink 4.0.0

streamlink.plugin.api.utils

The streamlink.plugin.api.utils module has been removed, including the itertags function and the export aliases for streamlink.utils.parse.

#4455

#4467

Migration

1. Write validation schemas using the parse_{html,json,xml}() validators. Parsed HTML/XML documents enable data extraction with XPath queries.

2. Alternatively, import the parse_{html,json,qsd,xml}() utility functions from the streamlink.utils.parse module

streamlink 3.0.0

Plugin class returned by Session.resolve_url()

In order to enable Plugin constructors to have access to plugin options derived from the resolved plugin arguments, Plugin instantiation moved from Streamlink.resolve_url() to streamlink_cli, and the return value of Streamlink.resolve_url() and Streamlink.resolve_url_no_redirect() were changed.

#4163

Migration

1. Return type changed from Plugin to tuple[type[Plugin], str]