.. _api_guide:

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:

.. code-block:: python

    >>> import livestreamer
    >>> streams = livestreamer.streams("http://twitch.tv/day9tv")

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:

.. code-block:: python

    >>> streams
    {'best': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'high': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'low': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'medium': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'mobile': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'source': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
     'worst': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>}


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.


.. code-block:: python

    >>> stream = streams["source"]
    >>> fd = stream.open()
    >>> data = fd.read(1024)
    >>> 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.

.. code-block:: python

    >>> stream.url
    'http://video38.ams01.hls.twitch.tv/hls11/ ...'


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:

.. code-block:: python

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

You can then extract streams like this:

.. code-block:: python

    >>> streams = session.streams("http://twitch.tv/day9tv")

or set options like this:

.. code-block:: python

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


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


Examples
--------

Simple player
^^^^^^^^^^^^^

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

.. _PyGObject: https://wiki.gnome.org/action/show/Projects/PyGObject
.. _GStreamer: http://gstreamer.freedesktop.org/

.. literalinclude:: ../examples/gst-player.py