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.
Migration
Move any custom player arguments from the value of
--player
to--player-args
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.
Migration
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.
Migration
Replace custom matching logic in
Plugin.can_handle_url()
withpluginmatcher
decoratorsReplace custom plugin priority matching logic in
Plugin.priority()
with thepriority
argument of thepluginmatcher
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.
Migration
Replace the arguments of custom constructors of each
Plugin
subclass with*args, **kwargs
and callsuper().__init__(*args, **kwargs)
If needed, access the
url
usingself.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.
Migration
Initialize an
Options
object with the desired key-value pairs and pass it to thePlugin
constructor or theStreamlink.streams()
method.After instantiating a
Plugin
class, get or set its options using theget()
/set()
methods on thePlugin.options
instance.If plugin options need to be accessed in custom
Stream
implementations related to customPlugin
implementations, then those options need to be passed from thePlugin
to theStream
constructor beforehand, since theStreamlink
session can't be used for that anymore.
from streamlink.session import Streamlink
session = Streamlink()
session.set_plugin_option("twitch", "api-header", [("Authorization", "OAuth TOKEN")])
streams = session.streams("twitch.tv/...")
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)
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.
Migration
Get the value of the global argument using
Streamlink.get_option()
instead of getting it fromPlugin.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.
Migration
Replace
plugin.api.validate.text
withstr
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.
Migration
Set the
Streamlink
session instance as a positional argument, or replace thesession_
keyword withsession
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.
Migration
Return type changed from
tuple[type[Plugin], str]
totuple[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
.
Migration
Write validation schemas using the
parse_{html,json,xml}()
validators. Parsed HTML/XML documents enable data extraction with XPath queries.Alternatively, import the
parse_{html,json,qsd,xml}()
utility functions from thestreamlink.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.
Migration
Return type changed from
Plugin
totuple[type[Plugin], str]