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 and streamlink.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:

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-disable-dh	(bool) Disable SSL Diffie-Hellman key exchange
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-no-validation	(bool) Disable FFmpeg validation and version logging. default: `False`
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. default: `None`.

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 and streamlink.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 and match 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 a Stream 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 and streamlink.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 and streamlink.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 the default_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 (see save_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 and Plugin.match attributes on the Plugin instance. The Plugin.matchers and Plugin.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):
    ...

Parameters:

pattern (Pattern) --
priority (int) --
name (Optional[str]) --

Return type:

Callable[[Type[Plugin]], Type[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 is myplugin.

Parameters:

name (str) --
required (bool) --
requires (Optional[Union[str, Sequence[str]]]) --
prompt (Optional[str]) --
sensitive (bool) --
argument_name (Optional[str]) --
dest (Optional[str]) --
is_global (bool) --

Return type:

Callable[[Type[Plugin]], Type[Plugin]]

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 that requires is a special case which is only enforced if the plugin is in use. In addition, the name parameter is the name relative to the plugin name, but can be overridden by argument_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
options -- Arguments passed to ArgumentParser.add_argument(), excluding requires and dest

class streamlink.options.Arguments(*args)

Bases: object

A collection of Argument instances for Plugin classes.

Should not be called directly, see the pluginargument decorator.

requires(name)

Find all Argument instances required by name

Parameters:: name (str) --
Return type:: Iterator[Argument]

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 the subtitles 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.

property url: str: The URL to the stream, prepared by requests with parameters read from args.

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, or requests.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, period=0, **args)

Bases: Stream

Implementation of the "Dynamic Adaptive Streaming over HTTP" protocol (MPEG-DASH)

Parameters:

session (streamlink.Streamlink) -- Streamlink session instance
mpd (MPD) -- Parsed MPD manifest
video_representation (Optional[Representation]) -- Video representation
audio_representation (Optional[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, 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() and Streamlink.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 in Plugin._get_streams() when returning None or an empty dict is not possible, e.g. in nested function calls.

exception streamlink.exceptions.StreamError

Bases: StreamlinkError

Stream related error.