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 aStream
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 streamswf
URL to a SWF used by the handshake protocolseek
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 URLurl
Base path of the stream, joined with the base URL when fetching fragmentsbootstrap
Either a URL pointing to the bootstrap or a bootstrapBox
object used for initial information about the streammetadata
Either None or aScriptData
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
Adict
containing keyword arguments passed torequests.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
Adict
containing keyword arguments passed torequests.request()
, such as headers and cookies.
-
class
livestreamer.stream.
RTMPStream
(session, params, redirect=False)¶ RTMP stream using rtmpdump.
Attributes:
params
Adict
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.