1.. _api_guide:
2
3API Guide
4=========
5
6.. module:: livestreamer
7
8This API is what powers the :ref:`cli` but is also available to developers that wish
9to make use of the data Livestreamer can retrieve in their own application.
10
11
12Extracting streams
13------------------
14
15The simplest use of the Livestreamer API looks like this:
16
17.. code-block:: python
18
19    >>> import livestreamer
20    >>> streams = livestreamer.streams("http://twitch.tv/day9tv")
21
22This simply attempts to find a plugin and use it to extract streams from
23the URL. This works great in simple cases but if you want more
24fine tuning you need to use a `session object`_ instead.
25
26The returned value is a dict containing :class:`Stream <stream.Stream>` objects:
27
28.. code-block:: python
29
30    >>> streams
31    {'best': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
32     'high': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
33     'low': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
34     'medium': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
35     'mobile': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
36     'source': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>,
37     'worst': <HLSStream('http://video11.fra01.hls.twitch.tv/ ...')>}
38
39
40If no plugin for the URL is found, a :exc:`NoPluginError` will be raised.
41If an error occurs while fetching streams, a :exc:`PluginError` will be raised.
42
43
44Opening streams to read data
45----------------------------
46
47Now that you have extracted some streams we might want to read some data from
48one of them. When you call `open()` on a stream, a file-like object will be
49returned, which you can call `.read(size)` and `.close()` on.
50
51
52.. code-block:: python
53
54    >>> stream = streams["source"]
55    >>> fd = stream.open()
56    >>> data = fd.read(1024)
57    >>> fd.close()
58
59If an error occurs while opening a stream, a :exc:`StreamError` will be raised.
60
61
62Inspecting streams
63------------------
64
65It's also possible to inspect streams internal parameters, see
66:ref:`api-stream-subclasses` to see what attributes are available
67for inspection for each stream type.
68
69For example this is a :class:`HLSStream <stream.HLSStream>` object which
70contains a `url` attribute.
71
72.. code-block:: python
73
74    >>> stream.url
75    'http://video38.ams01.hls.twitch.tv/hls11/ ...'
76
77
78Session object
79--------------
80
81The session allows you to set various options and is more efficient
82when extracting streams more than once. You start by creating a
83:class:`Livestreamer` object:
84
85.. code-block:: python
86
87    >>> from livestreamer import Livestreamer
88    >>> session = Livestreamer()
89
90You can then extract streams like this:
91
92.. code-block:: python
93
94    >>> streams = session.streams("http://twitch.tv/day9tv")
95
96or set options like this:
97
98.. code-block:: python
99
100    >>> session.set_option("rtmp-rtmpdump", "/path/to/rtmpdump")
101
102
103See :func:`Livestreamer.set_option` to see which options are available.
104
105
106Examples
107--------
108
109Simple player
110^^^^^^^^^^^^^
111
112This example uses the `PyGObject`_ module to playback a stream using the
113`GStreamer`_ framework.
114
115.. _PyGObject: https://wiki.gnome.org/action/show/Projects/PyGObject
116.. _GStreamer: http://gstreamer.freedesktop.org/
117
118.. literalinclude:: ../examples/gst-player.py
119