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

>>> 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 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.read(1024)
>>> 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
'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 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.