STREAMLINK(1) | Streamlink | STREAMLINK(1) |
streamlink - extracts streams from various services and pipes them into a video player of choice
Streamlink is command-line application, this means the commands described here should be typed into a terminal. On Windows this means you should open the command prompt or PowerShell, on Mac OS X open the Terminal app and if you're on Linux or BSD you probably already know the drill.
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.
Now to get into actually using Streamlink, let's say you want to watch the stream located on http://twitch.tv/day9tv, you start off by telling Streamlink where to attempt to extract streams from. This is done by giving the URL to the command streamlink as the first argument:
$ streamlink twitch.tv/day9tv [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv Available streams: audio, high, low, medium, mobile (worst), source (best)
NOTE:
This command will tell Streamlink to attempt to extract streams from the URL specified, and if it's successful, print out a list of available streams to choose from.
In some cases (Supported streaming protocols) local files are supported using the file:// protocol, for example a local HLS playlist can be played. 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, we simply add the stream name as a second argument to the streamlink command:
$ streamlink twitch.tv/day9tv source [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv [cli][info] Opening stream: source (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 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:
Writing the command-line options every time is inconvenient, that's why Streamlink is capable of reading options from a configuration file instead.
Streamlink will look for config files in different locations depending on your platform:
Platform | Location |
Unix-like (POSIX) | 0.0 • 2 $XDG_CONFIG_HOME/streamlink/config • 2 ~/.streamlinkrc 168u |
Windows | %APPDATA%\streamlink\streamlinkrc |
You can also specify the location yourself using the --config option.
NOTE:
NOTE:
The config file is a simple text file and should contain one command-line option (omitting the dashes) per line in the format:
option=value
or for a option without value:
option
NOTE:
# Player options player=mpv --cache 2048 player-no-close # Authenticate with Twitch twitch-oauth-token=mytoken
NOTE:
You may want to use specific options for some plugins only. This can be accomplished by placing those settings inside a plugin specific config file. Options inside these config files will override the main config file when a URL matching the plugin is used.
Streamlink expects this config to be named like the main config but with .<plugin name> attached to the end.
Platform | Location |
Unix-like (POSIX) | 0.0 • 2 $XDG_CONFIG_HOME/streamlink/config.twitch • 2 ~/.streamlinkrc.ustreamtv 168u |
Windows | %APPDATA%\streamlink\streamlinkrc.youtube |
Have a look at the list of plugins to see the name of each built-in plugin.
It's possible to access subscription content on Twitch by giving Streamlink access to your account.
Authentication is done by creating an OAuth token that Streamlink will use to access your account. It's done like this:
$ streamlink --twitch-oauth-authenticate
This will open a web browser where Twitch will ask you if you want to give Streamlink permission to access your account, then forwards you to a page with further instructions on how to use it.
Crunchyroll requires authenticating with a premium account to access some of their content. To do so, the plugin provides a couple of options to input your information, --crunchyroll-username and --crunchyroll-password.
You can login like this:
$ streamlink --crunchyroll-username=xxxx --crunchyroll-password=xxx http://crunchyroll.com/a-crunchyroll-episode-link
NOTE:
Once logged in, the plugin makes sure to save the session credentials to avoid asking your username and password again.
Nevertheless, these credentials are valid for a limited amount of time, so it might be a good idea to save your username and password in your configuration file anyway.
WARNING:
You can use the --http-proxy and --https-proxy options (you need both since the plugin uses both protocols) to access the Crunchyroll servers through a proxy to be able to stream region locked content.
When doing this, it's very probable that you will get denied to access the stream; this occurs because the session and credentials used by the plugin where obtained when logged from your own region, and the server still assumes you're in that region.
For this, the plugin provides the --crunchyroll-purge-credentials option, which removes your saved session and credentials and tries to log in again using your username and password.
Like Crunchyroll, the FunimationNow plugin requires authenticating with a premium account to access some content: --funimation-email, --funimation-password. In addition, this plugin requires a incap_ses cookie to be sent with each HTTP request (see issue #2088); this unique session cookie can be found in your browser and sent via the --http-cookie option.
For example:
$ streamlink --funimation-email='xxx' --funimation-password='xxx' --http-cookie 'incap_ses_xxx=xxxx=' https://funimation.com/shows/show/an-episode-link
NOTE:
Streamlink will attempt to load standalone plugins from these directories:
Platform | Location |
Unix-like (POSIX) | $XDG_CONFIG_HOME/streamlink/plugins |
Windows | %APPDATA%\streamlink\plugins |
NOTE:
There are many types of streaming protocols used by services today and Streamlink supports most of them. It's possible to tell Streamlink to access a streaming protocol directly instead of relying on a plugin to extract the streams from a URL for you.
A protocol can be accessed directly by specifying it in the URL format:
protocol://path [key=value]
Accessing a stream that requires extra parameters to be passed along (e.g. RTMP):
$ streamlink "rtmp://streaming.server.net/playpath live=1 swfVfy=http://server.net/flashplayer.swf"
When passing parameters to the built-in stream plugins the values will either be treated as plain strings, as is the case in the above example for swfVry, or they will be interpreted as Python literals. For example you can pass a Python dict or Python list as one of the parameters.
$ streamlink "rtmp://streaming.server.net/playpath conn=['B:1', 'S:authMe', 'O:1', 'NN:code:1.23', 'NS:flag:ok', 'O:0']" $ streamlink "hls://streaming.server.net/playpath params={'token': 'magicToken'}"
In the above examples conn will be passed as the Python list:
['B:1', 'S:authMe', 'O:1', 'NN:code:1.23', 'NS:flag:ok', 'O:0']
and params will be passed as the Python dict:
{'token': 'magicToken'}
Most streaming technologies simply requires you to pass a HTTP URL, this is a Adobe HDS stream:
$ streamlink hds://streaming.server.net/playpath/manifest.f4m
Name | Prefix |
Adobe HTTP Dynamic Streaming | hds:// |
Akamai HD Adaptive Streaming | akamaihd:// |
Apple HTTP Live Streaming | hls:// [1] |
MPEG-DASH [2] | dash:// |
Real Time Messaging Protocol | rtmp:// rtmpe:// rtmps:// rtmpt:// rtmpte:// |
Progressive HTTP, HTTPS, etc | httpstream:// [1] |
You can use the --http-proxy and --https-proxy options to change the proxy server that Streamlink will use for HTTP and HTTPS requests respectively. As HTTP and HTTPS requests can be handled by separate proxies, you may need to specify both options if the plugin you use makes HTTP and HTTPS requests.
Both HTTP and SOCKS proxies are supported, authentication is supported for both types.
NOTE:
For example:
$ streamlink --http-proxy "http://user:pass@10.10.1.10:3128/" --https-proxy "socks5://10.10.1.10:1242" $ streamlink --http-proxy "socks4a://10.10.1.10:1235" --https-proxy "socks5h://10.10.1.10:1234"
$ streamlink [OPTIONS] <URL> [STREAM]
Usually, the protocol of http(s) URLs can be omitted ("https://"), depending on the implementation of the plugin being used.
Alternatively, the URL can also be specified by using the --url option.
Use best or worst for selecting the highest or lowest available quality.
Fallback streams can be specified by using a comma-separated list:
"720p,480p,best"
If no stream is specified and --default-stream is not used, then a list of available streams will be printed.
Multiple directories can be used by separating them with a comma.
Returns status code 1 for false and 0 for true.
Useful for external scripting.
Can be repeated to load multiple files, in which case the options are merged on top of each other where the last config has highest priority.
Valid levels are: none, error, warning, info, debug, trace
Alias for "--loglevel none".
Useful for external scripting.
Default is: "no".
The locale is formatted as [language_code]_[country_code], eg. en_US or es_ES.
Default is: system locale.
This is a shell-like syntax to support using a specific player:
streamlink --player=vlc <url> [stream]
Absolute or relative paths can also be passed via this option in the event the player's executable can not be resolved:
streamlink --player=/path/to/vlc <url> [stream] streamlink --player=./vlc-player/vlc <url> [stream]
To use a player that is located in a path with spaces you must quote the parameter or its value:
streamlink "--player=/path/with spaces/vlc" <url> [stream] streamlink --player "C:\path\with spaces\mpc-hc64.exe" <url> [stream]
Options may also be passed to the player. For example:
streamlink --player "vlc --file-caching=5000" <url> [stream]
As an alternative to this, see the --player-args parameter, which does not log any custom player arguments.
This value can contain formatting variables surrounded by curly braces, { and }. If you need to include a brace character, it can be escaped by doubling, e.g. {{ and }}.
Formatting variables available:
It's usually enough to use --player instead of this unless you need to add arguments after the filename.
Default is: "{filename}".
Example:
streamlink -p vlc -a "--play-and-exit {filename}" <url> [stream]
This makes it possible to handle stream disconnects if your player is capable of reconnecting to a HTTP stream. This is usually done by setting your player to a "repeat mode".
Behavior will be similar to the continuous HTTP option, but no player program will be started, and the server will listen on all available connections instead of just in the local (loopback) interface.
The URLs that can be used to access the stream will be printed to the console, and the server can be interrupted using CTRL-C.
Stream types that can be converted into a playable URL are:
Make sure your player can handle the stream type when using this.
It does however have the side-effect of sometimes closing a player before it has played back all of its cached data.
This option will instead let the player decide when to exit.
This value can contain formatting variables surrounded by curly braces, { and }. If you need to include a brace character, it can be escaped by doubling, e.g. {{ and }}.
This option is only supported for the following players: mpv, vlc.
e.g. to put the current date in your VLC window title, the string "$A" could be inserted inside your --title string.
A full list of the format codes VLC uses is available here: https://wiki.videolan.org/Documentation:Format_String/
e.g. to put the current version of mpv running inside your mpv window title, the string "${{mpv-version}}" could be inserted inside your --title string.
A full list of the format codes mpv uses is available here: https://mpv.io/manual/stable/#property-expansion
Formatting variables available to use in --title:
Otherwise, it is the string "No Category"
Examples:
streamlink -p vlc --title "{title} -!- {author} -!- {category} \$A" <url> [stream] streamlink -p mpv --title "{title} -- {author} -- {category} -- (\${{mpv-version}})" <url> [stream]
You will be prompted if the file already exists.
You will be prompted if the file already exists.
You will be prompted if the file already exists.
Usually, the protocol of http(s) URLs can be omitted (https://), depending on the implementation of the plugin being used.
This is an alternative to setting the URL using a positional argument and can be useful if set in a config file.
Use best or worst for selecting the highest or lowest available quality.
Fallback streams can be specified by using a comma-separated list:
"720p,480p,best"
This is an alternative to setting the stream using a positional argument and can be useful if set in a config file.
The number of fetch retry attempts can be capped with --retry-max.
If --retry-max is set without setting --retry-streams, the delay between retries will default to 1 second.
Default is: 1.
The order will be used to separate streams when there are multiple streams with the same name but different stream types. Any stream type not listed will be omitted from the available streams list. A * can be used as a wildcard to match any other type of stream, eg. muxed-stream.
Default is: "rtmp,hls,hds,http,akamaihd,*".
If all of the available streams get excluded, best and worst will become inaccessible and new special stream synonyms best-unfiltered and worst-unfiltered can be used as a fallback selection method.
Uses a filter expression in the format:
[operator]<value>
Valid operators are >, >=, < and <=. If no operator is specified then equality is tested.
For example this will exclude streams ranked higher than "480p":
">480p"
Multiple filters can be used by separating each expression with a comma.
For example this will exclude streams from two quality types:
">480p,>medium"
Default is: 10.0.
Default is: 3.
Default is: 1.
Default is: 10.0.
Default is: 60.0.
The lower the value the lower latency from the source you will be, but also increases the chance of buffering.
Default is: 3.
Default is: 3.
Default is: 3.
Default is: 1.
Default is: 10.0.
Example: --hls-segment-ignore-names 000,001,002
This will ignore every segment that ends with 000.ts, 001.ts and 002.ts
Default is: None.
NOTE:
Example: --hls-segment-key-uri "https://example.com/hls/encryption_key"
Default is: None.
Examples:
--hls-audio-select "English,German" --hls-audio-select "en,de" --hls-audio-select "*"
NOTE:
Default is: 60.0.
Default is: 00:00:00.
Default is: unlimited.
Default is: 60.0.
The ringbuffer is used as a temporary storage between the stream and the player. This is to allows us to download the stream faster than the player wants to read it.
The smaller the size, the higher chance of the player buffering if there are download speed dips and the higher size the more data we can use as a storage to catch up from speed dips.
It also allows you to temporary pause as long as the ringbuffer doesn't get full since we continue to download the stream in the background.
Default is: "16M".
NOTE:
Example: 127.0.0.1:9050
Example: "/usr/local/bin/rtmpdump"
Default is: 60.0.
This is generic option used by streams not covered by other options, such as stream protocols specific to plugins, e.g. UStream.
Default is: 3.
This is generic option used by streams not covered by other options, such as stream protocols specific to plugins, e.g. UStream.
Default is: 1.
This is generic option used by streams not covered by other options, such as stream protocols specific to plugins, e.g. UStream.
Default is: 10.0.
This is generic option used by streams not covered by other options, such as stream protocols specific to plugins, e.g. UStream.
Default is: 60.0.
This is only available on RTMP streams.
Useful when debugging rtmpdump related issues.
Useful when debugging rtmpdump related issues.
Example: "/usr/local/bin/ffmpeg"
Default is: "copy".
Example: "h264"
Default is: "copy".
Example: "aac"
Example: "http://hostname:port/"
Example: "https://hostname:port/"
Can be repeated to add multiple cookies.
Can be repeated to add multiple headers.
Can be repeated to add multiple query parameters.
Usually a bad idea, only use this if you know what you're doing.
Usually a bad idea, only use this if you know what you're doing.
Expects a .pem file.
Expects a .crt and a .key file.
Default is: 20.0.
If left blank you will be prompted.
NOTE:
Default is: "english".
Example:
streamlink http://play.sbs.co.kr/onair/pc/index.html best --sbscokr-id S01
Defaults is 1.
Example:
"_twitch_session_id=xxxxxx; persistent=xxxxx"
NOTE:
Default is: "hls".
Streamlink Contributors
2019, Streamlink
January 31, 2019 | 1.0.0 |