1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
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 <macOS 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 :ref:`Players <players: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 :command:`streamlink` command:
.. code-block:: console
$ 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 :ref:`plugins system <plugins:Plugins>` 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
:ref:`supported streaming protocols <cli/protocols: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.
.. code-block:: console
$ 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 :command:`streamlink` command:
.. code-block:: console
$ 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 :ref:`configuration file <cli/config: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.
.. _Command Prompt: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands
.. _PowerShell: https://docs.microsoft.com/en-us/powershell/
.. _Windows Terminal: https://docs.microsoft.com/en-us/windows/terminal/get-started
.. _macOS Terminal: https://support.apple.com/guide/terminal/welcome/mac
.. _VLC: https://videolan.org/
.. _mpv: https://mpv.io/
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 <escape-character_>`_ 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*;&``
.. tab-set::
.. tab-item:: POSIX compliant
- `BASH manual <bash_>`_
- `ZSH manual <zsh_>`_
.. code-block:: sh
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*\;\&
.. tab-item:: FISH
- `FISH language documentation <fish_>`_
.. code-block:: fish
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\*\;\&
.. tab-item:: PowerShell
- `PowerShell language specification <pwsh_>`_
.. code-block:: pwsh
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*`;`&
.. tab-item:: Windows Batch
- `Escape characters, delimiters and quotes <batch-ss64_>`_
- `Percent sign escaping <batch-so_>`_
.. code-block:: bat
streamlink "https://example/path?a=$one&b="%"two"%"&c=*three*;&"
streamlink https://example/path?a=$one^&b=^%two^%^&c=*three*^;^&
.. _escape-character: https://en.wikipedia.org/wiki/Escape_character
.. _bash: https://www.gnu.org/software/bash/manual/bash.html
.. _zsh: https://zsh.sourceforge.io/Doc/Release/zsh_toc.html
.. _fish: https://fishshell.com/docs/current/language.html
.. _pwsh: https://learn.microsoft.com/en-us/powershell/scripting/lang-spec/chapter-02
.. _batch-ss64: https://ss64.com/nt/syntax-esc.html
.. _batch-so: https://stackoverflow.com/a/31420292
|
