mirror of https://github.com/streamlink/streamlink
docs: move API guide pages into second layer
This commit is contained in:
bastimeyer
Sebastian Meyer
parent
7f4c86cfe9
commit
2eedf8a26e
|
|
@ -1,98 +1,7 @@
|
|||
API Guide
|
||||
=========
|
||||
|
||||
This API is what powers the :ref:`CLI <cli:Command-Line Interface>` but is also available to developers that wish
|
||||
to make use of the data Streamlink can retrieve in their own application.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
Extracting streams
|
||||
------------------
|
||||
|
||||
The simplest use of the Streamlink API looks like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> import streamlink
|
||||
>>> streams = streamlink.streams("hls://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8")
|
||||
|
||||
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 :py:class:`Stream <streamlink.stream.Stream>` objects:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams
|
||||
{'41k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear0/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'230k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear1/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'650k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear2/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'990k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear3/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'1900k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'worst': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear0/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'best': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>}
|
||||
|
||||
|
||||
If no plugin for the URL is found, a :py:exc:`NoPluginError <streamlink.exceptions.NoPluginError>` will be raised.
|
||||
If an error occurs while fetching streams, a :py:exc:`PluginError <streamlink.exceptions.NoPluginError>` 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 :py:meth:`open() <streamlink.stream.Stream.open>` on a stream, a file-like object will be
|
||||
returned, which you can call ``.read(size)`` and ``.close()`` on.
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> fd = streams["best"].open()
|
||||
>>> data = fd.read(1024)
|
||||
>>> fd.close()
|
||||
|
||||
If an error occurs while opening a stream, a :py:exc:`StreamError <streamlink.exceptions.StreamError>` will be raised.
|
||||
|
||||
|
||||
Inspecting streams
|
||||
------------------
|
||||
|
||||
It's also possible to inspect the stream's internal parameters. Go to
|
||||
:ref:`Stream subclasses <api/stream:Stream>` to see which attributes are available
|
||||
for inspection for each stream type.
|
||||
|
||||
For example, this is a :py:class:`HLSStream <streamlink.stream.HLSStream>` object which
|
||||
contains a :py:attr:`url <streamlink.stream.HTTPStream.url>` attribute.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams["best"].url
|
||||
'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8'
|
||||
|
||||
|
||||
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
|
||||
:py:class:`Streamlink <streamlink.session.Streamlink>` object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> from streamlink import Streamlink
|
||||
>>> session = Streamlink()
|
||||
|
||||
You can then set options like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> session.set_option("stream-timeout", 30)
|
||||
|
||||
and extract streams like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams = session.streams("URL")
|
||||
|
||||
|
||||
See :py:meth:`Streamlink.set_option() <streamlink.session.Streamlink.set_option>` to see which options are available.
|
||||
api_guide/quickstart
|
||||
|
|
|
|||
|
|
@ -0,0 +1,98 @@
|
|||
Quickstart
|
||||
----------
|
||||
|
||||
This API is what powers the :ref:`CLI <cli:Command-Line Interface>`, but it's also available to developers that wish
|
||||
to make use of the data Streamlink can retrieve in their own application.
|
||||
|
||||
|
||||
Extracting streams
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The simplest use of the Streamlink API looks like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> import streamlink
|
||||
>>> streams = streamlink.streams("hls://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8")
|
||||
|
||||
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 :py:class:`Stream <streamlink.stream.Stream>` objects:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams
|
||||
{'41k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear0/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'230k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear1/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'650k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear2/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'990k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear3/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'1900k': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'worst': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear0/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>,
|
||||
'best': <HLSStream ['hls', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8', 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8']>}
|
||||
|
||||
|
||||
If no plugin for the URL is found, a :py:exc:`NoPluginError <streamlink.exceptions.NoPluginError>` will be raised.
|
||||
If an error occurs while fetching streams, a :py:exc:`PluginError <streamlink.exceptions.NoPluginError>` 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 :py:meth:`open() <streamlink.stream.Stream.open>` on a stream, a file-like object will be
|
||||
returned, which you can call ``.read(size)`` and ``.close()`` on.
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> fd = streams["best"].open()
|
||||
>>> data = fd.read(1024)
|
||||
>>> fd.close()
|
||||
|
||||
If an error occurs while opening a stream, a :py:exc:`StreamError <streamlink.exceptions.StreamError>` will be raised.
|
||||
|
||||
|
||||
Inspecting streams
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It's also possible to inspect the stream's internal parameters. Go to
|
||||
:ref:`Stream subclasses <api/stream:Stream>` to see which attributes are available
|
||||
for inspection for each stream type.
|
||||
|
||||
For example, this is an :py:class:`HLSStream <streamlink.stream.HLSStream>` object which
|
||||
contains a :py:attr:`url <streamlink.stream.HTTPStream.url>` attribute.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams["best"].url
|
||||
'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/gear4/prog_index.m3u8'
|
||||
|
||||
|
||||
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
|
||||
:py:class:`Streamlink <streamlink.session.Streamlink>` object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> from streamlink import Streamlink
|
||||
>>> session = Streamlink()
|
||||
|
||||
You can then set options like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> session.set_option("stream-timeout", 30)
|
||||
|
||||
and extract streams like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> streams = session.streams("URL")
|
||||
|
||||
|
||||
See :py:meth:`Streamlink.set_option() <streamlink.session.Streamlink.set_option>` to see which options are available.
|
||||
Loading…
Reference in New Issue