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

resolve_url(url, follow_redirect=True)¶

Attempts to find a plugin that can use this URL.

The default protocol (http) 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)¶

Attempts to find a plugin that can use this URL.

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

Raises NoPluginError on failure.

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

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`
hds-live-edge	(float) Specify the time live HDS streams will start from the edge of stream, default: `10.0`
hds-segment-attempts	(int) How many attempts should be done to download each HDS segment, default: `3`
hds-segment-threads	(int) The size of the thread pool used to download segments, default: `1`
hds-segment-timeout	(float) HDS segment connect and read timeout, default: `10.0`
hds-timeout	(float) Timeout for reading data from HDS streams, default: `60.0`
hls-live-edge	(int) How many segments from the end to start live streams on, default: `3`
hls-segment-attempts	(int) How many attempts should be done to download each HLS segment, default: `3`
hls-segment-ignore-names	(str[]) List of segment names without file endings which should get filtered out, default: `[]`
hls-segment-threads	(int) The size of the thread pool used to download segments, default: `1`
hls-segment-stream-data	(bool) Stream HLS segment downloads, default: `False`
hls-segment-timeout	(float) HLS segment connect and read timeout, default: `10.0`
hls-timeout	(float) Timeout for reading data from HLS streams, default: `60.0`
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`
http-stream-timeout	(float) Timeout for reading data from HTTP streams, default: `60.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`
rtmp-timeout	(float) Timeout for reading data from RTMP streams, default: `60.0`
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`. General option used by streams not covered by other options.
stream-segment-threads	(int) The size of the thread pool used to download segments, default: `1`. General option used by streams not covered by other options.
stream-segment-timeout	(float) Segment connect and read timeout, default: `10.0`. General option used by streams not covered by other options.
stream-timeout	(float) Timeout for reading data from stream, default: `60.0`. General option used by streams not covered by other options.
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. Must be set before the plugins are loaded. default: `UserInputRequester`.

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

A plugin can retrieve stream information from the URL specified.

Parameters: url -- URL that the plugin will operate on

clear_cookies(cookie_filter=None)¶

Removes all of the 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

load_cookies()¶

Load any stored cookies for the plugin that have not expired.

Returns: list of the restored cookie names

classmethod priority(url)¶: Return the plugin priority for a given URL, by default it returns NORMAL priority. :return: priority level

save_cookies(cookie_filter=None, default_expires=604800)¶

Store the cookies from http in the plugin cache until they expire. The cookies can be filtered by supplying a filter method. eg. 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 (function) -- 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

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 and the value is a Stream object.

The result can contain the synonyms best and worst which points 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. This can be either 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.

class streamlink.options.Arguments(*args)¶

Provides a wrapper around a list of Argument. For example

class PluginExample(Plugin):
    arguments = PluginArguments(
        PluginArgument("username",
                       help="The username for your account.",
                       metavar="EMAIL",
                       requires=["password"]),  // requires the password too
        PluginArgument("password",
                       sensitive=True,  // should be masked in logs, etc.
                       help="The password for your account.",
                       metavar="PASSWORD")
    )

This will add the --plugin-username and --plugin-password arguments to the CLI (assuming the plugin module is plugin).

requires(name)¶

Find all the arguments required by name

Parameters: name -- name of the argument the find the dependencies
Returns: list of dependant arguments

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

Argument accepts most of the same parameters as ArgumentParser.add_argument(), except requires is a special case as in this case it is only enforced if the plugin is in use. In addition the name parameter is the name relative to the plugin eg. username, password, etc.

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

Parameters

name -- name of the argument, without -- or plugin name prefixes, eg. "password", "mux-subtitles", etc.
(bool) (sensitive) -- if the argument is required for the plugin
requires -- list of the arguments which this argument requires, eg ["password"]
prompt -- if the argument is required and not given, this prompt will show at run time
(bool) -- if the argument is sensitive (passwords, etc) and should be masked in logs and if prompted use askpass
argument_name --
option_name --
options -- arguments passed to ArgumentParser.add_argument(), excluding requires, and dest

Streams¶

All streams inherit from the Stream class.

class streamlink.stream.Stream(session)¶

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.

Stream subclasses¶

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

class streamlink.stream.AkamaiHDStream(session, url, swf=None, seek=None)¶

Implements the AkamaiHD Adaptive Streaming protocol

Attributes:

url URL to the stream
swf URL to a SWF used by the handshake protocol
seek Position to seek to when opening the stream

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.HDSStream(session, baseurl, url, bootstrap, metadata=None, timeout=60, **request_params)¶

Implements the Adobe HTTP Dynamic Streaming protocol

Attributes:

baseurl Base URL
url Base path of the stream, joined with the base URL when fetching fragments
bootstrap Either a URL pointing to the bootstrap or a bootstrap Box object used for initial information about the stream
metadata Either None or a ScriptData object that contains metadata about the stream, such as height, width and bitrate

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, timeout=60, pvswf=None, is_akamai=False, **request_params)¶

Parses a HDS manifest and returns its substreams.

Parameters

url -- The URL to the manifest.
timeout -- How long to wait for data to be returned from from the stream before raising an error.
is_akamai -- force adding of the akamai parameters
pvswf -- URL of player SWF for Akamai HD player verification.

class streamlink.stream.HLSStream(session_, url, url_master=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.

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.

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.