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

Quickstart

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

>>> 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 and fetch streams manually.

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 an 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({"optional-session-option": 123})

On the session instance, you can set additional options like so:

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

See StreamlinkOptions for all available session options.

Fetching streams

Streams can be fetched in two different ways.

The first example will automatically try to find a matching plugin and available streams from the input URL:

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

See Streamlink.streams() for more.

Streamlink.streams() however doen't allow you to set any plugin options which might be necessary in order to access streams, e.g. when authentication data is required, or plugin options which may alter the plugin's behavior. Be aware that plugin options are distinct from the session options, and since these options depend on the plugin in use, plugin options can't be set without resolving the matching plugin first.

Plugins can therefore be resolved and initialized manually from the input URL, so plugin options can be passed to the plugin:

>>> plugin_name, plugin_class, resolved_url = session.resolve_url("URL")
>>> plugin = plugin_class(session, resolved_url, options={"plugin-option": 123})
>>> streams = plugin.streams()

See Streamlink.resolve_url() and Plugin for more.

Alternatively, the plugin class can be imported directly from the respective module of the streamlink.plugins package. The input URL then must match the plugin's URL matchers.

>>> from streamlink.plugins.twitch import __plugin__ as Twitch
>>> plugin = Twitch(session, "https://twitch.tv/CHANNEL", options={"disable-ads": True, "low-latency": True})
>>> streams = plugin.streams()

Available plugin options are defined using the @pluginargument Plugin class decorator in each plugin's module.