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.

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

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 runtime

locale

str

system locale

Locale setting, in the RFC 1766 format, e.g. en_US or es_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 ; delimited str 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 ; delimited str 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 & delimited str 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 authentication

http-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 a str keyword:

  • segment: duration of the last segment

  • live-edge: sum of segment durations of the hls-live-edge value minus one

  • default: 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 the PATH env var

ffmpeg-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 is True, 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:
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 (deprecated)

  • 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, **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() 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.