API Reference#

This is a reference of all the available API methods in 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 (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

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

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:
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[List[Matcher]]] = None#

The list of plugin matchers (URL pattern + priority).

Use the pluginmatcher() decorator to initialize this list.

arguments: ClassVar[Optional[Arguments]] = None#

The plugin's Arguments collection.

Use the pluginargument() decorator to initialize this collection.

matches: Sequence[Optional[Match]]#

A tuple of re.Match results of all defined matchers

matcher: Optional[Pattern]#

A reference to the compiled re.Pattern of the first matching matcher

match: Optional[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 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)#

Decorator for plugin URL matchers.

A matcher consists of a compiled regular expression pattern for the plugin's input URL and a priority value. The priority value determines which plugin gets chosen by Streamlink.resolve_url if multiple plugins match the input URL.

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.

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) --

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:
Return type:

Dict[str, 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: StreamlinkError

Plugin related error.

exception streamlink.NoPluginError#

Bases: PluginError

No relevant plugin has been loaded.

exception streamlink.StreamError#

Bases: StreamlinkError

Stream related error.