You are reading the documentation for the in-development version of Streamlink.
API Reference#
This is a reference of all the available API methods in Streamlink.
Streamlink#
- streamlink.streams(url, **params)#
Initializes an empty Streamlink session, 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
params -- Additional keyword arguments passed to
streamlink.Streamlink.streams()
- Raises:
NoPluginError -- on plugin resolve failure
- Returns:
A
dict
of stream names andstreamlink.stream.Stream
instances
Session#
- class streamlink.Streamlink(options=None)#
Bases:
object
The Streamlink session is used to load and resolve plugins, and to store options used by plugins and stream implementations.
- Parameters:
options (Optional[Dict[str, Any]]) -- Custom options
- http: HTTPSession#
An instance of Streamlink's
requests.Session
subclass. Used for any kind of HTTP request made by plugin and stream implementations.
- set_option(key, value)#
Sets general options used by plugins and streams originating from this session object.
- Parameters:
key (str) -- key of the option
value (Any) -- value to set the option to
- Return type:
None
Available options:
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-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
hls-segment-attempts (deprecated)
int
3
See
stream-segment-attempts
hls-segment-threads (deprecated)
int
3
See
stream-segment-threads
hls-segment-timeout (deprecated)
float
10.00
See
stream-segment-timeout
hls-timeout (deprecated)
float
60.00
See
stream-timeout
dash-segment-attempts (deprecated)
int
3
See
stream-segment-attempts
dash-segment-threads (deprecated)
int
3
See
stream-segment-threads
dash-segment-timeout (deprecated)
float
10.00
See
stream-segment-timeout
dash-timeout (deprecated)
float
60.00
See
stream-timeout
http-stream-timeout (deprecated)
float
60.00
See
stream-timeout
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-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 zero
- get_option(key)#
Returns the current value of the specified option.
- Parameters:
key (str) -- key of the option
- Return type:
Any
- set_plugin_option(plugin, key, value)#
Sets plugin specific options used by plugins originating from this session object.
- Parameters:
plugin (str) -- name of the plugin
key (str) -- key of the option
value (Any) -- value to set the option to
- Return type:
None
- get_plugin_option(plugin, key)#
Returns the current value of the plugin specific option.
- Parameters:
plugin (str) -- name of the plugin
key (str) -- key of the option
- Return type:
Optional[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
- 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
- Return type:
Tuple[str, Type[Plugin], str]
- streams(url, **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
params -- Additional keyword arguments passed to
streamlink.plugin.Plugin.streams()
- Raises:
NoPluginError -- on plugin resolve failure
- Returns:
A
dict
of stream names andstreamlink.stream.Stream
instances
- get_plugins()#
Returns the loaded plugins for the session.
- load_plugins(path)#
Attempt to load plugins from the path specified.
- Parameters:
path (str) -- full path to a directory where to look for plugins
- Returns:
success
- Return type:
bool
Plugins#
Plugin#
- class streamlink.plugin.Plugin(*args, **kwargs)#
Bases:
object
Plugin base class for retrieving streams and metadata from the URL specified.
- Parameters:
session -- The Streamlink session instance
url -- The input URL used for finding and resolving streams
- matchers: ClassVar[Optional[Matchers]] = None#
The list of plugin matchers (URL pattern + priority + optional name). This list supports matcher lookups both by matcher index, as well as matcher name, if defined.
Use the
pluginmatcher()
decorator to initialize plugin matchers.
- arguments: ClassVar[Optional[Arguments]] = None#
The plugin's
Arguments
collection.Use the
pluginargument()
decorator to initialize plugin arguments.
- matcher: Optional[Pattern] = None#
A reference to the compiled
re.Pattern
of the first matching matcher
- match: Optional[Match] = None#
A reference to the
re.Match
result of the first matching matcher
- id: Optional[str] = None#
Metadata 'id' attribute: unique stream ID, etc.
- title: Optional[str] = None#
Metadata 'title' attribute: the stream's short descriptive title
- author: Optional[str] = None#
Metadata 'author' attribute: the channel or broadcaster name, etc.
- category: Optional[str] = None#
Metadata 'category' attribute: name of a game being played, a music genre, etc.
- matches: Matches#
A list of optional
re.Match
results of all defined matchers. This list supports match lookups both by the respective matcher index, as well as matcher name, if defined.
- property url: str#
The plugin's input URL. Setting a new value will automatically update the
matches
,matcher
andmatch
data.
- streams(stream_types=None, sorting_excludes=None)#
Attempts to extract available streams.
Returns a
dict
containing the streams, where the key is the name of the stream (most commonly the quality name), with the value being aStream
instance.The result can contain the synonyms best and worst which point to the streams which are likely to be of highest and lowest quality respectively.
If multiple streams with the same name are found, the order of streams specified in stream_types will determine which stream gets to keep the name while the rest will be renamed to "<name>_<stream type>".
The synonyms can be fine-tuned with the sorting_excludes parameter, which can be one of these types:
A list of filter expressions in the format
[operator]<value>
. For example the filter ">480p" will exclude streams ranked higher than "480p" from the list used in the synonyms ranking. Valid operators are>
,>=
,<
and<=
. If no operator is specified then equality will be tested.A function that is passed to
filter()
with a list of stream names as input.
- Parameters:
stream_types -- A list of stream types to return
sorting_excludes -- Specify which streams to exclude from the best/worst synonyms
- Returns:
A
dict
of stream names andstreamlink.stream.Stream
instances
- _get_streams()#
Implement the stream and metadata retrieval here.
Needs to return either a dict of
streamlink.stream.Stream
instances mapped by stream name, or needs to act as a generator which yields tuples of stream names andstreamlink.stream.Stream
instances.
- save_cookies(cookie_filter=None, default_expires=604800)#
Store the cookies from
session.http
in the plugin cache until they expire. The cookies can be filtered by supplying a filter method. e.g.lambda c: "auth" in c.name
. If no expiry date is given in the cookie then thedefault_expires
value will be used.- Parameters:
cookie_filter (Optional[Callable[[Cookie], bool]]) -- a function to filter the cookies
default_expires (int) -- time (in seconds) until cookies with no expiry will expire
- Returns:
list of the saved cookie names
- Return type:
List[str]
- load_cookies()#
Load any stored cookies for the plugin that have not expired.
- Returns:
list of the restored cookie names
- Return type:
List[str]
- clear_cookies(cookie_filter=None)#
Removes all saved cookies for this plugin. To filter the cookies that are deleted specify the
cookie_filter
argument (seesave_cookies()
).- Parameters:
cookie_filter (function) -- a function to filter the cookies
- Returns:
list of the removed cookie names
- Return type:
List[str]
Plugin decorators#
- @streamlink.plugin.pluginmatcher(pattern, priority=20, name=None)#
Decorator for plugin URL matchers.
A matcher consists of a compiled regular expression pattern for the plugin's input URL, a priority value and an optional name. The priority value determines which plugin gets chosen by
Streamlink.resolve_url
if multiple plugins match the input URL. The matcher name can be used for accessing it and its matching result when multiple matchers are defined.Plugins must at least have one matcher. If multiple matchers are defined, then the first matching one according to the order of which they have been defined (top to bottom) will be responsible for setting the
Plugin.matcher
andPlugin.match
attributes on thePlugin
instance. ThePlugin.matchers
andPlugin.matches
attributes are affected by all defined matchers, and both support referencing matchers and matches by matcher index and name.import re from streamlink.plugin import HIGH_PRIORITY, Plugin, pluginmatcher @pluginmatcher(re.compile("https?://example:1234/(?:foo|bar)/(?P<name>[^/]+)")) @pluginmatcher(priority=HIGH_PRIORITY, pattern=re.compile(""" https?://(?: sitenumberone |adifferentsite |somethingelse ) /.+\.m3u8 """, re.VERBOSE)) class MyPlugin(Plugin): ...
- @streamlink.plugin.pluginargument(name, required=False, requires=None, prompt=None, sensitive=False, argument_name=None, dest=None, is_global=False, **options)#
Decorator for plugin arguments. Takes the same arguments as
streamlink.options.Argument
.from streamlink.plugin import Plugin, pluginargument @pluginargument( "username", requires=["password"], metavar="EMAIL", help="The username for your account.", ) @pluginargument( "password", sensitive=True, metavar="PASSWORD", help="The password for your account.", ) class MyPlugin(Plugin): ...
This will add the
--myplugin-username
and--myplugin-password
arguments to the CLI, assuming the plugin's module name ismyplugin
.
Plugin arguments#
- class streamlink.options.Argument(name, required=False, requires=None, prompt=None, sensitive=False, argument_name=None, dest=None, is_global=False, **options)#
Bases:
object
Accepts most of the parameters accepted by
ArgumentParser.add_argument()
, except thatrequires
is a special case which is only enforced if the plugin is in use. In addition, thename
parameter is the name relative to the plugin name, but can be overridden byargument_name
.Should not be called directly, see the
pluginargument
decorator.- Parameters:
name (str) -- Argument name, without leading
--
or plugin name prefixes, e.g."username"
,"password"
, etc.required (bool) -- Whether the argument is required for the plugin
requires (Optional[Union[str, Sequence[str]]]) -- List of arguments which this argument requires, eg
["password"]
prompt (Optional[str]) -- If the argument is required and not set, this prompt message will be shown instead
sensitive (bool) -- Whether the argument is sensitive (passwords, etc.) and should be masked
argument_name (Optional[str]) -- Custom CLI argument name without plugin name prefix
dest (Optional[str]) -- Custom plugin option name
is_global (bool) -- Whether this plugin argument refers to a global CLI argument (deprecated)
options -- Arguments passed to
ArgumentParser.add_argument()
, excludingrequires
anddest
Streams#
All streams inherit from the Stream
class.
Stream#
- class streamlink.stream.Stream(session)#
Bases:
object
This is a base class that should be inherited when implementing different stream types. Should only be created by plugins.
- Parameters:
session (Streamlink) -- Streamlink session instance
- open()#
Attempts to open a connection to the stream. Returns a file-like object that can be used to read the stream data.
- Raises:
StreamError -- on failure
- Return type:
StreamIO
MuxedStream#
- class streamlink.stream.MuxedStream(session, *substreams, **options)#
Bases:
Stream
Muxes multiple streams into one output stream.
- Parameters:
session (streamlink.Streamlink) -- Streamlink session instance
substreams (Stream) -- Video and/or audio streams
options -- Additional keyword arguments passed to
ffmpegmux.FFMPEGMuxer
. Subtitle streams need to be set via thesubtitles
keyword.
HTTPStream#
- class streamlink.stream.HTTPStream(session_, url, buffered=True, **args)#
Bases:
Stream
An HTTP stream using the
requests
library.- Parameters:
session (streamlink.Streamlink) -- Streamlink session instance
url (str) -- The URL of the HTTP stream
buffered (bool) -- Wrap stream output in an additional reader-thread
args (Dict) -- Additional keyword arguments passed to
requests.Session.request()
- args: Dict#
A dict of keyword arguments passed to
requests.Session.request()
, such as method, headers, cookies, etc.
HLSStream#
- class streamlink.stream.HLSStream(session_, url, url_master=None, multivariant=None, force_restart=False, start_offset=0, duration=None, **args)#
Bases:
HTTPStream
Implementation of the Apple HTTP Live Streaming protocol.
- Parameters:
session (streamlink.Streamlink) -- Streamlink session instance
url (str) -- The URL of the HLS playlist
url_master (Optional[str]) -- The URL of the HLS playlist's multivariant playlist (deprecated)
multivariant (Optional[M3U8]) -- The parsed multivariant playlist
force_restart (bool) -- Start from the beginning after reaching the playlist's end
start_offset (float) -- Number of seconds to be skipped from the beginning
duration (Optional[float]) -- Number of seconds until ending the stream
args -- Additional keyword arguments passed to
requests.Session.request()
- classmethod parse_variant_playlist(session_, url, name_key='name', name_prefix='', check_streams=False, force_restart=False, name_fmt=None, start_offset=0, duration=None, **request_params)#
Parse a variant playlist and return its streams.
- Parameters:
session (streamlink.Streamlink) -- Streamlink session instance
url (str) -- The URL of the variant playlist
name_key (str) -- Prefer to use this key as stream name, valid keys are: name, pixels, bitrate
name_prefix (str) -- Add this prefix to the stream names
check_streams (bool) -- Only allow streams that are accessible
force_restart (bool) -- Start at the first segment even for a live stream
name_fmt (Optional[str]) -- A format string for the name, allowed format keys are: name, pixels, bitrate
start_offset (float) -- Number of seconds to be skipped from the beginning
duration (Optional[float]) -- Number of second until ending the stream
request_params -- Additional keyword arguments passed to
HLSStream
,MuxedHLSStream
, orrequests.Session.request()
- Return type:
Dict[str, Union[HLSStream, MuxedHLSStream]]
- property url_master#
Deprecated
MuxedHLSStream#
- class streamlink.stream.MuxedHLSStream(session, video, audio, url_master=None, multivariant=None, force_restart=False, ffmpeg_options=None, **args)#
Bases:
MuxedStream
Muxes multiple HLS video and audio streams into one output stream.
- Parameters:
session (streamlink.Streamlink) -- Streamlink session instance
video (str) -- Video stream URL
audio (Union[str, List[str]]) -- Audio stream URL or list of URLs
url_master (Optional[str]) -- The URL of the HLS playlist's multivariant playlist (deprecated)
multivariant (Optional[M3U8]) -- The parsed multivariant playlist
force_restart (bool) -- Start from the beginning after reaching the playlist's end
ffmpeg_options (Optional[Dict[str, Any]]) -- Additional keyword arguments passed to
ffmpegmux.FFMPEGMuxer
args -- Additional keyword arguments passed to
HLSStream
- property url_master#
Deprecated
DASHStream#
- class streamlink.stream.DASHStream(session, mpd, video_representation=None, audio_representation=None, **args)#
Bases:
Stream
Implementation of the "Dynamic Adaptive Streaming over HTTP" protocol (MPEG-DASH)
- Parameters:
session (Streamlink) -- Streamlink session instance
mpd (MPD) -- Parsed MPD manifest
video_representation (Optional[Representation]) -- Video representation
audio_representation (Optional[Representation]) -- Audio representation
args -- Additional keyword arguments passed to
requests.Session.request()
- classmethod parse_manifest(session, url_or_manifest, period=0, **args)#
Parse a DASH manifest file and return its streams.
- Parameters:
session (Streamlink) -- Streamlink session instance
url_or_manifest (str) -- URL of the manifest file or an XML manifest string
period (int) -- Which MPD period to use (index number) for finding representations
args -- Additional keyword arguments passed to
requests.Session.request()
- Return type:
Dict[str, DASHStream]
Exceptions#
Streamlink has multiple types of exceptions:
- exception streamlink.exceptions.StreamlinkError#
Bases:
Exception
Any error caused by Streamlink will be caught with this exception.
- exception streamlink.exceptions.PluginError#
Bases:
StreamlinkError
Plugin related error.
- exception streamlink.exceptions.FatalPluginError#
Bases:
PluginError
Plugin related error that cannot be recovered from.
Plugins should use this
Exception
when errors that can never be recovered from are encountered. For example, when a user's input is required and none can be given.
- exception streamlink.exceptions.NoPluginError#
Bases:
StreamlinkError
Error raised by
Streamlink.resolve_url()
andStreamlink.resolve_url_no_redirect()
when no plugin could be found for the given input URL.
- exception streamlink.exceptions.NoStreamsError#
Bases:
StreamlinkError
Plugins should use this
Exception
inPlugin._get_streams()
when returningNone
or an emptydict
is not possible, e.g. in nested function calls.
- exception streamlink.exceptions.StreamError#
Bases:
StreamlinkError
Stream related error.