diff --git a/docs-requirements.txt b/docs-requirements.txt index e9ffcbb1..36a639af 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -1,6 +1,7 @@ sphinx >=4.0.0 furo ==2022.09.15 myst-parser >=0.18.0 +sphinx-design >=0.3.0 versioningit >=2.0.0, <3 docutils-stubs diff --git a/docs/cli/tutorial.rst b/docs/cli/tutorial.rst index 7b8510de..89644105 100644 --- a/docs/cli/tutorial.rst +++ b/docs/cli/tutorial.rst @@ -1,40 +1,53 @@ Tutorial --------- +======== + +Introduction +------------ Streamlink is a command-line application, which means that the commands described -here should be typed into a terminal. On Windows, you have to open either the -`Command Prompt`_, `PowerShell`_ or `Windows Terminal`_, on macOS open the `Terminal `_ app, -and if you're on Linux or BSD you probably already know the drill. +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 :ref:`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 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 :command:`streamlink` as the first argument: +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/day9tv - [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv - Available streams: audio, high, low, medium, mobile (worst), source (best) - + $ 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/day9tv`` is enough and quicker to type. + 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, and if it's successful, print out a list of available streams to choose -from. +specified via its :ref:`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 some cases (see :ref:`cli/protocols: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 ``/``, +In addition to Streamlink's plugins system, direct stream URLs can be played via the +:ref:`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. .. code-block:: console @@ -47,14 +60,13 @@ even on Windows. To select a stream and start playback, simply add the stream name as a second argument to the :command:`streamlink` command: -.. sourcecode:: console +.. code-block:: console - $ streamlink twitch.tv/day9tv 1080p60 - [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv + $ 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 @@ -76,3 +88,76 @@ into customizing it to your own needs, such as: .. _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 `_ 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 `_ + - `ZSH manual `_ + + .. 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 `_ + + .. 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 `_ + + .. 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 `_ + - `Percent sign escaping `_ + + .. 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 diff --git a/docs/conf.py b/docs/conf.py index 9bbbf708..f5ab1328 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,6 +26,7 @@ extensions = [ 'ext_plugins', 'ext_releaseref', 'myst_parser', + 'sphinx_design', ] autosectionlabel_prefix_document = True