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