Fetching contributors…
Cannot retrieve contributors at this time
119 lines (72 sloc) 3.16 KB

API Guide

.. module:: livestreamer

This API is what powers the :ref:`cli` but is also available to developers that wish to make use of the data Livestreamer can retrieve in their own application.

Extracting streams

The simplest use of the Livestreamer API looks like this:

>>> import livestreamer
>>> streams = livestreamer.streams("")

This simply attempts to find a plugin and use it to extract streams from the URL. This works great in simple cases but if you want more fine tuning you need to use a session object instead.

The returned value is a dict containing :class:`Stream <stream.Stream>` objects:

>>> streams
{'best': <HLSStream(' ...')>,
 'high': <HLSStream(' ...')>,
 'low': <HLSStream(' ...')>,
 'medium': <HLSStream(' ...')>,
 'mobile': <HLSStream(' ...')>,
 'source': <HLSStream(' ...')>,
 'worst': <HLSStream(' ...')>}

If no plugin for the URL is found, a :exc:`NoPluginError` will be raised. If an error occurs while fetching streams, a :exc:`PluginError` will be raised.

Opening streams to read data

Now that you have extracted some streams we might want to read some data from one of them. When you call open() on a stream, a file-like object will be returned, which you can call .read(size) and .close() on.

>>> stream = streams["source"]
>>> fd =
>>> data =
>>> fd.close()

If an error occurs while opening a stream, a :exc:`StreamError` will be raised.

Inspecting streams

It's also possible to inspect streams internal parameters, see :ref:`api-stream-subclasses` to see what attributes are available for inspection for each stream type.

For example this is a :class:`HLSStream <stream.HLSStream>` object which contains a url attribute.

>>> stream.url
' ...'

Session object

The session allows you to set various options and is more efficient when extracting streams more than once. You start by creating a :class:`Livestreamer` object:

>>> from livestreamer import Livestreamer
>>> session = Livestreamer()

You can then extract streams like this:

>>> streams = session.streams("")

or set options like this:

>>> session.set_option("rtmp-rtmpdump", "/path/to/rtmpdump")

See :func:`Livestreamer.set_option` to see which options are available.


Simple player

This example uses the PyGObject module to playback a stream using the GStreamer framework.

.. literalinclude:: ../examples/