API Reference¶

This ia reference of all the available API methods in Streamlink.

Streamlink¶

streamlink.streams(url, **params)¶

Attempts to find a plugin and extract streams from the url.

params are passed to Plugin.streams().

Raises NoPluginError if no plugin is found.

Session¶

class streamlink.Streamlink(options=None)¶

A Streamlink session is used to keep track of plugins, options and log settings.

get_option(key)¶

Returns current value of specified option.

Parameters: key -- key of the option

get_plugin_option(plugin, key)¶

Returns current value of plugin specific option.

Parameters

plugin -- name of the plugin
key -- key of the option

get_plugins()¶: Returns the loaded plugins for the session.

load_plugins(path)¶

Attempt to load plugins from the path specified.

Parameters: path -- full path to a directory where to look for plugins

property logger¶: Backwards compatible logger property :return: Logger instance

resolve_url(url: str, follow_redirect: bool = True) → Tuple[Type[streamlink.plugin.plugin.Plugin], str]¶

Attempts to find a plugin that can use this URL.

The default protocol (https) will be prefixed to the URL if not specified.

Raises NoPluginError on failure.

Parameters

url -- a URL to match against loaded plugins
follow_redirect -- follow redirects

resolve_url_no_redirect(url: str) → Tuple[Type[streamlink.plugin.plugin.Plugin], str]¶

Attempts to find a plugin that can use this URL.

The default protocol (https) will be prefixed to the URL if not specified.

Raises NoPluginError on failure.

Parameters: url -- a URL to match against loaded plugins

set_loglevel(level)¶

Sets the log level used by this session.

Valid levels are: "none", "error", "warning", "info" and "debug".

Parameters: level -- level of logging to output

set_logoutput(output)¶

Sets the log output used by this session.

Parameters: output -- a file-like object with a write method

set_option(key, value)¶

Sets general options used by plugins and streams originating from this session object.

Parameters

key -- key of the option
value -- 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 a HTTP proxy to use for all HTTP requests
https-proxy	(str) Specify a HTTPS proxy to use for all HTTPS requests
http-cookies	(dict or str) A dict or a semi-colon (;) delimited str of cookies to add to each HTTP request, e.g. `foo=bar;baz=qux`
http-headers	(dict or str) A dict or semi-colon (;) 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 a 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`
subprocess-errorlog	(bool) Log errors from subprocesses to a file located in the temp directory
subprocess-errorlog-path	(str) Log errors from subprocesses to a specific file
ringbuffer-size	(int) The size of the internal ring buffer used by most stream types, default: `16777216` (16MB)
rtmp-proxy	(str) Specify a proxy (SOCKS) that RTMP streams will use
rtmp-rtmpdump	(str) Specify the location of the rtmpdump executable used by RTMP streams, e.g. `/usr/local/bin/rtmpdump`
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 eg. 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`.

set_plugin_option(plugin, key, value)¶

Sets plugin specific options used by plugins originating from this session object.

Parameters

plugin -- name of the plugin
key -- key of the option
value -- value to set the option to

streams(url, **params)¶

Attempts to find a plugin and extract streams from the url.

params are passed to Plugin.streams().

Raises NoPluginError if no plugin is found.

Plugins¶

class streamlink.plugin.Plugin(*args, **kwargs)¶: Plugin base class for retrieving streams and metadata from the URL specified.

Plugin decorators¶

@streamlink.plugin.pluginmatcher(pattern: Pattern, priority: int = 20) → Callable[[Type[streamlink.plugin.plugin.Plugin]], Type[streamlink.plugin.plugin.Plugin]]¶

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

@streamlink.plugin.pluginargument(name: str, required: bool = False, requires: Optional[Union[str, Sequence[str]]] = None, prompt: Optional[str] = None, sensitive: bool = False, argument_name: Optional[str] = None, dest: Optional[str] = None, is_global: bool = False, **options) → Callable[[Type[streamlink.plugin.plugin.Plugin]], Type[streamlink.plugin.plugin.Plugin]]¶

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.

Plugin arguments¶

class streamlink.options.Arguments(*args)¶

A collection of Argument instances for Plugin classes.

Should not be called directly, see the pluginargument decorator.

requires(name: str) → Iterator[streamlink.options.Argument]¶: Find all Argument instances required by name

class streamlink.options.Argument(name, required=False, requires=None, prompt=None, sensitive=False, argument_name=None, dest=None, is_global=False, **options)¶

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.

__init__(name, required=False, requires=None, prompt=None, sensitive=False, argument_name=None, dest=None, is_global=False, **options)¶

Parameters

name -- Argument name, without leading -- or plugin name prefixes, e.g. "username", "password", etc.
required -- Whether the argument is required for the plugin
requires -- List of arguments which this argument requires, eg ["password"]
prompt -- If the argument is required and not set, this prompt message will be shown instead
sensitive -- Whether the argument is sensitive (passwords, etc.) and should be masked
argument_name -- Custom CLI argument name without plugin name prefix
dest -- Custom plugin option name
is_global -- Whether this plugin argument refers to a global CLI argument
options -- Arguments passed to ArgumentParser.add_argument(), excluding requires and dest

Streams¶

All streams inherit from the Stream class.

class streamlink.stream.Stream(session)¶

This is a base class that should be inherited when implementing different stream types. Should only be created by plugins.

open() → StreamIO¶

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.

Stream subclasses¶

You are able to inspect the parameters used by each stream, different properties are available depending on stream type.

class streamlink.stream.HLSStream(session_, url, url_master=None, multivariant=None, force_restart=False, start_offset=0, duration=None, **args)¶

Implementation of the Apple HTTP Live Streaming protocol

Attributes:

url The URL to the HLS playlist.
args A dict containing keyword arguments passed to requests.request(), such as headers and cookies.

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.

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

Attempts to parse a variant playlist and return its streams.

Parameters

url -- The URL of the variant playlist.
name_key -- Prefer to use this key as stream name, valid keys are: name, pixels, bitrate.
name_prefix -- Add this prefix to the stream names.
check_streams -- Only allow streams that are accessible.
force_restart -- Start at the first segment even for a live stream
name_fmt -- A format string for the name, allowed format keys are name, pixels, bitrate.

property url_master¶: Deprecated

class streamlink.stream.HTTPStream(session_, url, buffered=True, **args)¶

A HTTP stream using the requests library.

Attributes:

url The URL to the stream, prepared by requests.
args A dict containing keyword arguments passed to requests.request(), such as headers and cookies.

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.

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

class streamlink.stream.RTMPStream(session, params, redirect=False, **kwargs)¶

RTMP stream using rtmpdump.

Attributes:

params A dict containing parameters passed to rtmpdump

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.

class streamlink.stream.DASHStream(session, mpd, video_representation=None, audio_representation=None, period=0, **args)¶

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.

classmethod parse_manifest(session, url_or_manifest, **args)¶

Attempt to parse a DASH manifest file and return its streams

Parameters

session -- Streamlink session instance
url_or_manifest -- URL of the manifest file or an XML manifest string

Returns

a dict of name -> DASHStream instances

Exceptions¶

Streamlink has three types of exceptions:

exception streamlink.StreamlinkError¶: Any error caused by Streamlink will be caught with this exception.

exception streamlink.PluginError¶: Plugin related error.

exception streamlink.NoPluginError¶: No relevant plugin has been loaded.

exception streamlink.StreamError¶: Stream related error.