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.