You are reading the documentation for the in-development version of Streamlink.

API Guide#

This API is what powers the CLI but is 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:

>>> import streamlink
>>> streams = streamlink.streams("hls://")

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 Stream objects:

>>> streams
{'41k': <HLSStream ['hls', '', '']>,
 '230k': <HLSStream ['hls', '', '']>,
 '650k': <HLSStream ['hls', '', '']>,
 '990k': <HLSStream ['hls', '', '']>,
 '1900k': <HLSStream ['hls', '', '']>,
 'worst': <HLSStream ['hls', '', '']>,
 'best': <HLSStream ['hls', '', '']>}

If no plugin for the URL is found, a NoPluginError will be raised. If an error occurs while fetching streams, a 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.

>>> fd = streams["best"].open()
>>> data =
>>> fd.close()

If an error occurs while opening a stream, a StreamError will be raised.

Inspecting streams#

It's also possible to inspect the stream's internal parameters. Go to Stream subclasses to see which attributes are available for inspection for each stream type.

For example, this is a HLSStream object which contains a url attribute.

>>> streams["best"].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 Streamlink object:

>>> from streamlink import Streamlink
>>> session = Streamlink()

You can then set options like this:

>>> session.set_option("stream-timeout", 30)

and extract streams like this:

>>> streams = session.streams("URL")

See Streamlink.set_option to see which options are available.