You are reading the documentation for the in-development version of Streamlink.
Session¶
- class streamlink.session.Streamlink(options=None, *, plugins_builtin=True, plugins_lazy=True)¶
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] | 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 ofOptions
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 andStream
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()
andStreamlink.set_option()
methods, as well as the regularget()
andset()
methods of thisOptions
subclass.key
type
default
description
user-input-requester
UserInputRequester | None
None
Instance of
UserInputRequester
to collect input from the user at runtimelocale
str
system locale
Locale setting, in the RFC 1766 format, e.g.
en_US
ores_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;
delimitedstr
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;
delimitedstr
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&
delimitedstr
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
authenticationhttp-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 astr
keyword:segment
: duration of the last segmentlive-edge
: sum of segment durations of thehls-live-edge
value minus onedefault
: 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 thePATH
env varffmpeg-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
valueffmpeg-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
isTrue
, shift timestamps to zerowebbrowser
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
andpluginargument
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]
- 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
- 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]]