API Reference

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

Livestreamer

livestreamer.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 livestreamer.Livestreamer

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

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_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:

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-threads (int) The size of the thread pool used to download segments, default: 1
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
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
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.
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 livestreamer.plugin.Plugin(url)

A plugin can retrieve stream information from the URL specified.

Parameters:url – URL that the plugin will operate on
get_streams(*args, **kwargs)

Deprecated since version 1.9.0.

Has been renamed to Plugin.streams(), this is an alias for backwards compatibility.

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.

Changed in version 1.4.2: Added priority parameter.

Changed in version 1.5.0: Renamed priority to stream_types and changed behaviour slightly.

Changed in version 1.5.0: Added sorting_excludes parameter.

Changed in version 1.6.0: sorting_excludes can now be a list of filter expressions or a function that is passed to filter().

Streams

All streams inherit from the Stream class.

class livestreamer.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 livestreamer.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
class livestreamer.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
classmethod parse_manifest(session, url, timeout=60, pvswf=None, **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.
  • pvswf – URL of player SWF for Akamai HD player verification.
class livestreamer.stream.HLSStream(session_, url, **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.

Changed in version 1.7.0: Added args attribute.

classmethod parse_variant_playlist(session_, url, name_key='name', name_prefix='', check_streams=False, **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 accesible.
class livestreamer.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.
class livestreamer.stream.RTMPStream(session, params, redirect=False)

RTMP stream using rtmpdump.

Attributes:

  • params A dict containing parameters passed to rtmpdump

Exceptions

Livestreamer has three types of exceptions:

exception livestreamer.LivestreamerError

Any error caused by Livestreamer will be caught with this exception.

exception livestreamer.PluginError

Plugin related error.

exception livestreamer.NoPluginError

No relevant plugin has been loaded.

exception livestreamer.StreamError

Stream related error.