You are reading the documentation for the in-development version of Streamlink.

Session

Bases: object

The Streamlink session is used to load and resolve plugins, and to store options used by plugins and stream implementations.

Parameters:

  • options (Mapping[str, Any] | Options | None) -- Custom options

  • plugins_builtin (bool) -- Whether to load built-in plugins or not

  • plugins_lazy (bool) -- Load built-in plugins lazily. This option falls back to loading all built-in plugins if the pre-built plugin JSON metadata is not available (e.g. in editable installs) or is invalid.

http: HTTPSession

An instance of Streamlink's requests.Session subclass. Used for any kind of HTTP request made by plugin and stream implementations.

options: StreamlinkOptions

Options of this session instance. StreamlinkOptions is a subclass of Options with special getter/setter mappings.

plugins: StreamlinkPlugins

Plugins of this session instance.

set_option(key, value)

Sets general options used by plugins and streams originating from this session object.

This is a convenience wrapper for self.options.set().

Please see StreamlinkOptions for the available options.

Parameters:

  • key (str) -- key of the option

  • value (Any) -- value to set the option to

Return type:

None

get_option(key)

Returns the current value of the specified option.

This is a convenience wrapper for self.options.get().

Please see StreamlinkOptions for the available options.

Parameters:

key (str) -- key of the option

Return type:

Any

resolve_url(url, follow_redirect=True)

Attempts to find a plugin that can use this URL.

The default protocol (https) will be prefixed to the URL if not specified.

Return values of this method are cached via functools.lru_cache().

Parameters:

  • url (str) -- a URL to match against loaded plugins

  • follow_redirect (bool) -- follow redirects

Raises:

NoPluginError -- on plugin resolve failure

Returns:

A tuple of plugin name, plugin class and resolved URL

Return type:

tuple[str, type[Plugin], str]

resolve_url_no_redirect(url)

Attempts to find a plugin that can use this URL.

The default protocol (https) will be prefixed to the URL if not specified.

Parameters:

url (str) -- a URL to match against loaded plugins

Raises:

NoPluginError -- on plugin resolve failure

Returns:

A tuple of plugin name, plugin class and resolved URL

Return type:

tuple[str, type[Plugin], str]

streams(url, options=None, **params)

Attempts to find a plugin and extracts streams from the url if a plugin was found.

Parameters:

  • url (str) -- a URL to match against loaded plugins

  • options (Options | None) -- Optional options instance passed to the resolved plugin

  • params -- Additional keyword arguments passed to Plugin.streams()

Raises:

NoPluginError -- on plugin resolve failure

Returns:

A dict of stream names and Stream instances

get_plugins()

Returns the loaded plugins of this session.

Deprecated in favor of plugins.get_loaded().

load_builtin_plugins()

Loads Streamlink's built-in plugins.

Deprecated in favor of using the plugins_builtin keyword argument.

load_plugins(path)

Loads plugins from a specific path.

Deprecated in favor of plugins.load_path().

Parameters:

path (str)

Return type:

bool

class streamlink.session.options.StreamlinkOptions(session)

Bases: Options

Streamlink's session options.

The following options can be accessed using the Streamlink.get_option() and Streamlink.set_option() methods, as well as the regular get() and set() methods of this Options subclass.

key

type

default

description

user-input-requester

UserInputRequester | None

None

Instance of UserInputRequester to collect input from the user at runtime

locale

str

system locale

Locale setting, in the RFC 1766 format, e.g. en_US or es_ES

interface

str | None

None

Network interface address

ipv4

bool

False

Resolve address names to IPv4 only, overrides ipv6

ipv6

bool

False

Resolve address names to IPv6 only, overrides ipv4

http-proxy

str | None

None

Proxy address for all HTTP/HTTPS requests

https-proxy (deprecated)

str | None

None

Proxy address for all HTTP/HTTPS requests

http-cookies

dict[str, str] | str

{}

A dict or a semicolon ; delimited str of cookies to add to each HTTP/HTTPS request, e.g. foo=bar;baz=qux

http-headers

dict[str, str] | str

{}

A dict or a semicolon ; delimited str of headers to add to each HTTP/HTTPS request, e.g. foo=bar;baz=qux

http-query-params

dict[str, str] | str

{}

A dict or an ampersand & delimited str of query string parameters to add to each HTTP/HTTPS request, e.g. foo=bar&baz=qux

http-trust-env

bool

True

Trust HTTP settings set in the environment, such as environment variables (HTTP_PROXY, etc.) and ~/.netrc authentication

http-ssl-verify

bool

True

Verify TLS/SSL certificates

http-disable-dh

bool

False

Disable TLS/SSL Diffie-Hellman key exchange

http-ssl-cert

str | tuple | None

None

TLS/SSL certificate to use, can be either a .pem file (str) or a .crt/.key pair (tuple)

http-timeout

float

20.0

General timeout used by all HTTP/HTTPS requests, except the ones covered by other options

ringbuffer-size

int

16777216 (16 MiB)

The size of the internal ring buffer used by most stream types

mux-subtitles

bool

False

Make supported plugins mux available subtitles into the output stream

stream-segment-attempts

int

3

Number of segment download attempts in segmented streams

stream-segment-threads

int

1

The size of the thread pool used to download segments in parallel

stream-segment-timeout

float

10.0

Segment connect and read timeout

stream-timeout

float

60.0

Timeout for reading data from stream

hls-live-edge

int

3

Number of segments from the live position of the HLS stream to start reading

hls-live-restart

bool

False

Skip to the beginning of a live HLS stream, or as far back as possible

hls-start-offset

float

0.0

Number of seconds to skip from the beginning of the HLS stream, interpreted as a negative offset for livestreams

hls-duration

float | None

None

Limit the HLS stream playback duration, rounded to the nearest HLS segment

hls-playlist-reload-attempts

int

3

Max number of HLS playlist reload attempts before giving up

hls-playlist-reload-time

str | float

"default"

Override the HLS playlist reload time, either in seconds (float) or as a str keyword:

  • segment: duration of the last segment

  • live-edge: sum of segment durations of the hls-live-edge value minus one

  • default: the playlist's target duration

hls-segment-queue-threshold

float

3

Factor of the playlist's targetduration which sets the threshold for stopping early on missing segments

hls-segment-stream-data

bool

False

Stream data of HLS segment downloads to the output instead of waiting for the full response

hls-segment-ignore-names

List[str]

[]

List of HLS segment names without file endings which should get filtered out

hls-segment-key-uri

str | None

None

Override the address of the encrypted HLS stream's key, with support for the following string template variables: {url}, {scheme}, {netloc}, {path}, {query}

hls-audio-select

List[str]

[]

Select a specific audio source or sources when multiple audio sources are available, by language code or name, or "*" (asterisk)

dash-manifest-reload-attempts

int

3

Max number of DASH manifest reload attempts before giving up

ffmpeg-ffmpeg

str | None

None

Override for the ffmpeg/ffmpeg.exe binary path, which by default gets looked up via the PATH env var

ffmpeg-no-validation

bool

False

Disable FFmpeg validation and version logging

ffmpeg-verbose

bool

False

Append FFmpeg's stderr stream to the Python's stderr stream

ffmpeg-verbose-path

str | None

None

Write FFmpeg's stderr stream to the filesystem at the specified path

ffmpeg-loglevel

str | None

None

Set FFmpeg's -loglevel value

ffmpeg-fout

str | None

None

Set the output format of muxed streams, e.g. "matroska"

ffmpeg-video-transcode

str | None

None

The codec to use if transcoding video when muxing streams, e.g. "h264"

ffmpeg-audio-transcode

str | None

None

The codec to use if transcoding video when muxing streams, e.g. "aac"

ffmpeg-copyts

bool

False

Don't shift input stream timestamps when muxing streams

ffmpeg-start-at-zero

bool

False

When ffmpeg-copyts is True, shift timestamps to zero

webbrowser

bool

True

Enable or disable support for Streamlink's webbrowser API

webbrowser-executable

str | None

None

Path to the web browser's executable

webbrowser-timeout

float

20.0

The maximum amount of time which the webbrowser can take to launch and execute

webbrowser-cdp-host

str | None

None

Custom host for the Chrome Devtools Protocol (CDP) interface

webbrowser-cdp-port

int | None

None

Custom port for the Chrome Devtools Protocol (CDP) interface

webbrowser-cdp-timeout

float

2.0

The maximum amount of time for waiting on a single CDP command response

webbrowser-headless

bool

False

Whether to launch the webbrowser in headless mode or not
Parameters:

session (Streamlink)

get(key)

Get the stored value of a specific key

Parameters:

key (str)

Return type:

Any

set(key, value)

Set the value for a specific key

Parameters:

  • key (str)

  • value (Any)

Return type:

None

class streamlink.session.plugins.StreamlinkPlugins(builtin=True, lazy=True)

Bases: object

Streamlink's session-plugins implementation. This class is responsible for loading plugins and resolving them from URLs.

See the Streamlink.plugins attribute.

Unless disabled by the user, Streamlink will try to load built-in plugins lazily, when accessing them for the first time while resolving input URLs. This is done by reading and interpreting serialized data of each plugin's pluginmatcher and pluginargument data from a pre-built plugins JSON file which is included in Streamlink's wheel packages.

Plugins which are sideloaded, either from specific user directories or custom input directories, always have a higher priority than built-in plugins.

Parameters:

  • builtin (bool)

  • lazy (bool)

__getitem__(item)

Access a loaded plugin class by name

Parameters:

item (str)

Return type:

type[Plugin]

__setitem__(key, value)

Add/override a plugin class by name

Parameters:

  • key (str)

  • value (type[Plugin])

Return type:

None

__delitem__(key)

Remove a loaded plugin by name

Parameters:

key (str)

Return type:

None

__contains__(item)

Check if a plugin is loaded

Parameters:

item (str)

Return type:

bool

get_names()

Get a list of the names of all available plugins

Return type:

list[str]

get_loaded()

Get a mapping of all loaded plugins

Return type:

dict[str, type[Plugin]]

load_builtin()

Load Streamlink's built-in plugins

Return type:

bool

load_path(path)

Load plugins from a custom directory

Parameters:

path (str | Path)

Return type:

bool

update(plugins)

Add/override loaded plugins

Parameters:

plugins (Mapping[str, type[Plugin]])

clear()

Remove all loaded plugins from the session

iter_arguments()

Iterate through all plugins and their Arguments

Return type:

Iterator[tuple[str, Arguments]]

iter_matchers()

Iterate through all plugins and their Matchers

Return type:

Iterator[tuple[str, Matchers]]

match_url(url)

Find a matching plugin by URL and load plugins which haven't been loaded yet

Parameters:

url (str)

Return type:

tuple[str, type[Plugin]] | None