Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

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/