You are reading the documentation for the in-development version of Streamlink.
Tutorial¶
Introduction¶
Streamlink is a command-line application, which means that the commands described here should be typed into a terminal, or to be more precise, into a command-line shell.
On Windows, you have to open either the Windows Terminal (recommended), PowerShell or Command Prompt (discouraged). On macOS, open the Terminal app, and if you're on Linux or BSD, the terminal emulator depends on your desktop environment and its configuration.
The way Streamlink works is that it's only a means to extract and transport the streams, and the playback is done by an external video player. Streamlink works best with VLC or mpv, which are also cross-platform, but other players may be compatible too, see the Players page for a complete overview.
Getting started¶
Now to get into actually using Streamlink, let's say you want to watch the
stream located on https://www.twitch.tv/nasa, you start off by telling Streamlink
where to attempt to extract streams from. This is done by setting the URL as the
first argument on the streamlink command:
$ streamlink twitch.tv/nasa
[cli][info] Found matching plugin twitch for URL twitch.tv/nasa
Available streams: audio_only, 160p (worst), 360p, 480p, 720p60, 1080p60 (best)
Note
You don't need to include the protocol when dealing with HTTP(s) URLs,
e.g. just twitch.tv/nasa is enough and quicker to type.
Caution
Depending on the command-line shell in use, any kind of command argument like the input URL for example may need to get quoted or escaped. See the Shell syntax section down below.
This command will tell Streamlink to attempt to extract streams from the URL specified via its plugins system which is responsible for resolving streams from specific streaming services. If it's successful, Streamlink will print out a list of available streams to choose from.
In addition to Streamlink's plugins system, direct stream URLs can be played via the
supported streaming protocols, which also support playback of local files
using the file:// protocol. Relative file paths and absolute paths are supported. All path separators are /,
even on Windows.
$ streamlink hls://file://C:/hls/playlist.m3u8
[cli][info] Found matching plugin stream for URL hls://file://C:/hls/playlist.m3u8
Available streams: 180p (worst), 272p, 408p, 554p, 818p, 1744p (best)
To select a stream and start playback, simply add the stream name as a second argument to the streamlink command:
$ streamlink twitch.tv/nasa 1080p60
[cli][info] Found matching plugin twitch for URL twitch.tv/nasa
[cli][info] Opening stream: 1080p60 (hls)
[cli][info] Starting player: vlc
The stream you chose should now be playing in the player. It's a common use case
to just want to start the highest quality stream and not be bothered with what it's
named. To do this, just specify best as the stream name and Streamlink will
attempt to rank the streams and open the one of highest quality. You can also
specify worst to get the lowest quality.
Now that you have a basic grasp of how Streamlink works, you may want to look into customizing it to your own needs, such as:
Creating a configuration file of options you want to use.
Setting up your player to cache some data before playing the stream to help avoiding buffering issues or reducing its default buffering values for being able to watch low-latency streams.
Shell syntax¶
Depending on your used command-line shell and how you've entered the command, input strings like the URL or other command arguments may need to get escaped or quoted, because command-line shells interpret and treat certain characters as special symbols which can alter the shell's behavior, like characters for substituting/expanding strings, delimiting commands, path/file globbing, etc.
The most relevant characters (among others) for input URLs that can cause unexpected results are
&,;(command delimiting)$,%(variable substitution)?,*(path globbing)
The quoting and escaping behavior varies wildly between each shell and its configuration, so please take a look at your shell's documentation about all the details, if you're unsure.
Quoting and character escaping examples:
URL: https://example/path?a=$one&b=%two%&c=*three*;&
streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&"
streamlink https://example/path?a=\$one\&b=%two%\&c=*three*\;\&
streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&"
streamlink https://example/path\?a=\$one&b=%two%&c=\*three\*\;\&
streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
streamlink "https://example/path?a=`$one&b=%two%&c=*three*;&"
streamlink https://example/path?a=`$one`&b=%two%`&c=*three*`;`&
streamlink "https://example/path?a=$one&b="%"two"%"&c=*three*;&"
streamlink https://example/path?a=$one^&b=^%two^%^&c=*three*^;^&