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: streamlink.plugin.api.http_session.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
Available options:
interface
(str) Set the network interface, default:
None
ipv4
(bool) Resolve address names to IPv4 only. This option overrides ipv6, default:
False
ipv6
(bool) Resolve address names to IPv6 only. This option overrides ipv4, default:
False
hls-live-edge
(int) How many segments from the end to start live streams on, default:
3
hls-segment-ignore-names
(str[]) List of segment names without file endings which should get filtered out, default:
[]
hls-segment-stream-data
(bool) Stream HLS segment downloads, default:
False
http-proxy
(str) Specify an HTTP proxy to use for all HTTP requests
https-proxy
(str) Specify an HTTPS proxy to use for all HTTPS requests
http-cookies
(dict or str) A dict or a semicolon
;
delimited str of cookies to add to each HTTP request, e.g.foo=bar;baz=qux
http-headers
(dict or str) A dict or semicolon
;
delimited str of headers to add to each HTTP request, e.g.foo=bar;baz=qux
http-query-params
(dict or str) A dict or an ampersand
&
delimited string of query parameters to add to each HTTP request, e.g.foo=bar&baz=qux
http-trust-env
(bool) Trust HTTP settings set in the environment, such as environment variables (HTTP_PROXY, etc.) and ~/.netrc authentication
http-ssl-verify
(bool) Verify SSL certificates, default:
True
http-ssl-cert
(str or tuple) SSL certificate to use, can be either a .pem file (str) or a .crt/.key pair (tuple)
http-timeout
(float) General timeout used by all HTTP requests except the ones covered by other options, default:
20.0
ringbuffer-size
(int) The size of the internal ring buffer used by most stream types, default:
16777216
(16MB)ffmpeg-ffmpeg
(str) Specify the location of the ffmpeg executable use by Muxing streams e.g.
/usr/local/bin/ffmpeg
ffmpeg-verbose
(bool) Log stderr from ffmpeg to the console
ffmpeg-verbose-path
(str) Specify the location of the ffmpeg stderr log file
ffmpeg-fout
(str) The output file format when muxing with ffmpeg e.g.
matroska
ffmpeg-video-transcode
(str) The codec to use if transcoding video when muxing with ffmpeg e.g.
h264
ffmpeg-audio-transcode
(str) The codec to use if transcoding audio when muxing with ffmpeg e.g.
aac
ffmpeg-copyts
(bool) When used with ffmpeg, do not shift input timestamps.
ffmpeg-start-at-zero
(bool) When used with ffmpeg and copyts, shift input timestamps, so they start at zero default:
False
mux-subtitles
(bool) Mux available subtitles into the output stream.
stream-segment-attempts
(int) How many attempts should be done to download each segment, default:
3
.stream-segment-threads
(int) The size of the thread pool used to download segments, default:
1
.stream-segment-timeout
(float) Segment connect and read timeout, default:
10.0
.stream-timeout
(float) Timeout for reading data from stream, default:
60.0
.locale
(str) Locale setting, in the RFC 1766 format e.g. en_US or es_ES default:
system locale
.user-input-requester
(UserInputRequester) instance of UserInputRequester to collect input from the user at runtime. Must be set before the plugins are loaded. default:
UserInputRequester
.
- get_option(key)¶
Returns the current value of the specified option.
- Parameters
key (str) -- key of the option
- 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
- 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
- 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[Type[streamlink.plugin.plugin.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[Type[streamlink.plugin.plugin.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(url)¶
Bases:
object
Plugin base class for retrieving streams and metadata from the URL specified.
- Parameters
url (str) -- URL that the plugin will operate on
- matchers: ClassVar[List[streamlink.plugin.plugin.Matcher]] = None¶
The list of plugin matchers (URL pattern + priority). Use the
streamlink.plugin.pluginmatcher()
decorator for initializing this list.
- matches: Sequence[Optional[Match]]¶
A tuple of
re.Match
results of all defined matchers
- matcher: Pattern¶
A reference to the compiled
re.Pattern
of the first matching matcher
- match: Match¶
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.
- 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]) -- 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]
PluginArgument¶
- class streamlink.options.Argument(name, required=False, requires=None, prompt=None, sensitive=False, argument_name=None, dest=None, is_global=False, **options)¶
Bases:
object
Argument
accepts most of the parameters accepted byArgumentParser.add_argument()
, except thatrequires
is a special case which is only enforced if the plugin is in use. In addition, theargument_name
parameter is the name relative to the plugin, e.g. username, password, etc.- Parameters
name (str) -- Argument name, without
--
or plugin name prefixes, e.g."password"
,"mux-subtitles"
, etc.required (bool) -- Whether the argument is required for the plugin
requires (Optional[List[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
dest (Optional[str]) -- Custom plugin option name
is_global (bool) -- Whether this plugin argument refers to a global CLI argument
options -- Arguments passed to
ArgumentParser.add_argument()
, excludingrequires
anddest
- class streamlink.options.Arguments(*args)¶
Bases:
object
Provides a wrapper around a list of
Argument
. For examplefrom streamlink.plugin import Plugin, PluginArgument, PluginArguments class PluginExample(Plugin): arguments = PluginArguments( PluginArgument( "username", metavar="EMAIL", requires=["password"], help="The username for your account.", ), PluginArgument( "password", metavar="PASSWORD", sensitive=True, help="The password for your account.", ), )
This will add the
--plugin-username
and--plugin-password
arguments to the CLI (assuming the plugin module isplugin
).- requires(name)¶
Find all the arguments required by name
- Parameters
name -- name of the argument the find the dependencies
- Returns
list of dependant arguments
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) -- 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
streamlink.stream.stream.StreamIO
MuxedStream¶
- class streamlink.stream.MuxedStream(session, *substreams, **options)¶
Bases:
streamlink.stream.stream.Stream
Muxes multiple streams into one output stream.
- Parameters
session (streamlink.Streamlink) -- Streamlink session instance
substreams (streamlink.stream.stream.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:
streamlink.stream.stream.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, force_restart=False, start_offset=0, duration=None, **args)¶
Bases:
streamlink.stream.http.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 master/variant 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 (Dict) -- 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[streamlink.stream.hls.HLSStream, streamlink.stream.hls.MuxedHLSStream]]
MuxedHLSStream¶
- class streamlink.stream.MuxedHLSStream(session, video, audio, url_master=None, force_restart=False, ffmpeg_options=None, **args)¶
Bases:
streamlink.stream.ffmpegmux.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 master/variant 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
DASHStream¶
- class streamlink.stream.DASHStream(session, mpd, video_representation=None, audio_representation=None, period=0, **args)¶
Bases:
streamlink.stream.stream.Stream
Implementation of the "Dynamic Adaptive Streaming over HTTP" protocol (MPEG-DASH)
- Parameters
session (streamlink.Streamlink) -- Streamlink session instance
mpd (streamlink.stream.dash_manifest.MPD) -- Parsed MPD manifest
video_representation (Optional[streamlink.stream.dash_manifest.Representation]) -- Video representation
audio_representation (Optional[streamlink.stream.dash_manifest.Representation]) -- Audio representation
period (float) -- Update period
args -- Additional keyword arguments passed to
requests.Session.request()
- classmethod parse_manifest(session, url_or_manifest, **args)¶
Parse a DASH manifest file and return its streams.
- Parameters
session (streamlink.Streamlink) -- Streamlink session instance
url_or_manifest (str) -- URL of the manifest file or an XML manifest string
args -- Additional keyword arguments passed to
requests.Session.request()
- Return type
Dict[str, streamlink.stream.dash.DASHStream]
Exceptions¶
Streamlink has three types of exceptions:
- exception streamlink.StreamlinkError¶
Bases:
Exception
Any error caused by Streamlink will be caught with this exception.
- exception streamlink.PluginError¶
Bases:
streamlink.exceptions.StreamlinkError
Plugin related error.
- exception streamlink.NoPluginError¶
Bases:
streamlink.exceptions.PluginError
No relevant plugin has been loaded.
- exception streamlink.StreamError¶
Bases:
streamlink.exceptions.StreamlinkError
Stream related error.