Repository: streamlink/streamlink

Issue:
Default Stream quality to best? (documentation improvement)
### Checklist

- [ ] This is a bug report.
- [ ] This is a plugin request.
- [x] This is a feature request.
- [x] I used the search function to find already opened/closed issues or pull requests.

### Description
I personally use streamlink for all my stream needs (mostly twitch), so I type a lot of streamlink commands into the terminal so any less typing would be appreciated. 

This would only require a minimal change (see [my fork](https://github.com/streamlink/streamlink/compare/master...Germandrummer92:master)) and would as far as I can see it not break anything, as even if someone just wanted to print the available qualities they are still printed and you can just exit the source stream immediately as you will most likely type into the same terminal window again.

If someone actually wants the behavior of just printing the stream qualities I could implement a separate option for that although I'm not sure anyone actually uses that.

### Expected / Actual behavior

`streamlink twitch.tv/pgl_dota`

defaults to
`streamlink twitch.tv/pgl_dota best` 
instead of just printing the stream qualities

Let me know if this makes sense and I would open a pull request with my one-line change!






Discussion:
You can already specify a default quality. See [--default-stream](https://streamlink.github.io/cli.html#cmdoption-default-stream). Just add it to your config file and you wont have to enter a quality every time.
As @skulblakka this is something users can set via their config file. We don't want to default to `best` without a user specifying it as `best` typically requires a large amount of bandwidth which may negatively impact the end user if they have any sort of limitation or cap in place. I'm going to close this out for now since it's easy to work around via existing settings.

Edit: Do you feel we could communicate this better via the documentation? If so can you detail what you looked at prior to creating this issue to see if we can improve the path users follow to find out about these options?
I went through the docs related to --default-stream and I think we could definitely improve them. They're super bare bones right now and not very useful. It doesn't really explain how to set ti and use it.
> so I type a lot of streamlink commands into the terminal so any less typing would be appreciated.

I guess the --default-stream option is the solution already, but if you want to shorten the command even more, use aliases/functions (bash? you said terminal).

```
function sl() {
	streamlink "$1" best
	}
```

I use many functions like that for diferent purposes and many different sites. I'd go insane by typing them all the time or even just copy-pasting from a text file.
Your function is not ideal and only takes one argument. This is a better one:

```bash
function sl() {
	streamlink --default-stream best "$@"
}
```
Actually, if you put the default-stream into the streamlinkrc you don't have to retype the argument for every function you define (if you're like me and have different ones for example and are even too lazy to type the argument in your zshrc/bashrc :smile: ).

Also, for completeness sake here is the function I use. It also autocompletes my stream names to twitch if it doesnt include a "/" (e.g. any other url will just be passed through).
```bash
wt() {
     url="$1"
     if [[ "$url" =~ ".*twitch.*" || "$url" =~ ".*/.*" ]]; then
         streamlink "$url" "${@:2}"
     else
         streamlink "twitch.tv/$url" "${@:2}"
     fi
 }
```

This means, that
`wt twitch.tv/ppd` and
`wt ppd` will work.

Thanks for all the help though :+1: 

Resolving patch:
diff --git a/docs/ext_argparse.py b/docs/ext_argparse.py
--- a/docs/ext_argparse.py
+++ b/docs/ext_argparse.py
@@ -28,7 +28,7 @@
 
 _block_re = re.compile(r":\n{2}\s{2}")
 _default_re = re.compile(r"Default is (.+)\.\n")
-_note_re = re.compile(r"Note: (.*)\n\n", re.DOTALL)
+_note_re = re.compile(r"Note: (.*)(?:\n\n|\n*$)", re.DOTALL)
 _option_re = re.compile(r"(?m)^((?!\s{2}).*)(--[\w-]+)")
 
 
diff --git a/src/streamlink_cli/argparser.py b/src/streamlink_cli/argparser.py
--- a/src/streamlink_cli/argparser.py
+++ b/src/streamlink_cli/argparser.py
@@ -163,8 +163,10 @@ def boolean(value):
     help="""
     A URL to attempt to extract streams from.
 
-    If it's a HTTP URL then "http://" can be omitted.
-    The URL can also be specified using the --url option.
+    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.
     """
 )
 positional.add_argument(
@@ -175,13 +177,13 @@ def boolean(value):
     help="""
     Stream to play.
 
-    Use "best" or "worst" for highest or lowest quality available.
+    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
+    If no stream is specified and --default-stream is not used, then a
     list of available streams will be printed.
     """
 )
@@ -224,7 +226,8 @@ def boolean(value):
     "--can-handle-url-no-redirect",
     metavar="URL",
     help="""
-    Same as --can-handle-url but without following redirects when looking up the URL.
+    Same as --can-handle-url but without following redirects
+    when looking up the URL.
     """
 )
 general.add_argument(
@@ -275,7 +278,7 @@ def boolean(value):
     help="""
     Enable or disable the automatic check for a new version of Streamlink.
 
-    Default is no
+    Default is "no".
     """
 )
 general.add_argument(
@@ -294,7 +297,7 @@ def boolean(value):
     subtitle and audio language.
 
     The locale is formatted as [language_code]_[country_code],
-     eg. eg. en_US or es_ES
+    eg. en_US or es_ES.
 
     Default is system locale.
     """
@@ -330,7 +333,7 @@ def boolean(value):
       streamlink --player "vlc --file-caching=5000" <url> <quality>
 
     As an alternative to this, see the --player-args parameter,
-    which does not log the customer player arguments.
+    which does not log any custom player arguments.
     """
 )
 player.add_argument(
@@ -340,7 +343,8 @@ def boolean(value):
     help="""
     This option allows you to customize the default arguments which
     are put together with the value of --player to create a command
-    to execute.
+    to execute. Unlike the --player parameter, custom player
+    arguments will not be logged.
 
     This value can contain formatting variables surrounded by curly
     braces, {{ and }}. If you need to include a brace character, it
@@ -357,6 +361,11 @@ def boolean(value):
     need to add arguments after the filename.
 
     Default is "{0}".
+
+    Example:
+
+      streamlink -p vlc -a "--play-and-exit {{filename}}" <url> <quality>
+
     """.format(DEFAULT_PLAYER_ARGUMENTS)
 )
 player.add_argument(
@@ -393,7 +402,6 @@ def boolean(value):
     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".
-
     """
 )
 player.add_argument(
@@ -485,9 +493,11 @@ def boolean(value):
     help="""
     A URL to attempt to extract streams from.
 
-    If it's a HTTP URL then "http://" can be omitted.
+    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.
+    This is an alternative to setting the URL using a positional argument
+    and can be useful if set in a config file.
     """
 )
 stream.add_argument(
@@ -495,7 +505,16 @@ def boolean(value):
     type=comma_list,
     metavar="STREAM",
     help="""
-    Open this stream when no stream argument is specified, e.g. "best".
+    Stream to play.
+
+    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.
     """
 )
 stream.add_argument(
@@ -528,7 +547,8 @@ def boolean(value):
     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.
+    can be used as a wildcard to match any other type of stream,
+    eg. muxed-stream.
 
     Default is "rtmp,hls,hds,http,akamaihd,*".
     """
@@ -683,9 +703,11 @@ def boolean(value):
     type=str,
     metavar="CODE",
     help="""
-    Selects a specific audio source, by language code, when multiple audio sources are available.
+    Selects a specific audio source by language code
+    when multiple audio sources are available.
 
-    Note: This is only useful in special circumstances where the regular locale option fails.
+    Note: This is only useful in special circumstances
+    where the regular locale option fails.
     """)
 transport.add_argument(
     "--http-stream-timeout",
@@ -801,6 +823,7 @@ def boolean(value):
 
     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.
     """)
 transport.add_argument(
@@ -814,7 +837,7 @@ def boolean(value):
     "--subprocess-cmdline", "--cmdline", "-c",
     action="store_true",
     help="""
-    Print command-line used internally to play stream.
+    Print the command-line used internally to play the stream.
 
     This is only available on RTMP streams.
     """
@@ -844,7 +867,7 @@ def boolean(value):
     "--ffmpeg-ffmpeg",
     metavar="FILENAME",
     help="""
-    FFMPEG is used to access mux separate video and audio streams.
+    FFMPEG is used to access or mux separate video and audio streams.
     You can specify the location of the ffmpeg executable if it is
     not in your PATH.
 
@@ -855,7 +878,7 @@ def boolean(value):
     "--ffmpeg-verbose",
     action="store_true",
     help="""
-    Write the console output from ffmpeg to the console
+    Write the console output from ffmpeg to the console.
     """
 )
 transport.add_argument(
@@ -863,14 +886,16 @@ def boolean(value):
     type=str,
     metavar="PATH",
     help="""
-    Path to write the output from the ffmpeg console
+    Path to write the output from the ffmpeg console.
     """
 )
 transport.add_argument(
     "--ffmpeg-video-transcode",
     metavar="CODEC",
     help="""
-    When muxing streams transcode the video to this CODEC, defaults to copy (no transcode)
+    When muxing streams transcode the video to this CODEC.
+
+    Default is "copy".
 
     Example: "h264"
     """
@@ -879,7 +904,9 @@ def boolean(value):
     "--ffmpeg-audio-transcode",
     metavar="CODEC",
     help="""
-    When muxing streams transcode the audio to this CODEC, defaults to copy (no transcode)
+    When muxing streams transcode the audio to this CODEC.
+
+    Default is "copy".
 
     Example: "aac"
     """
@@ -892,7 +919,7 @@ def boolean(value):
     help="""
     A HTTP proxy to use for all HTTP requests.
 
-    Example: http://hostname:port/
+    Example: "http://hostname:port/"
     """
 )
 http.add_argument(
@@ -901,7 +928,7 @@ def boolean(value):
     help="""
     A HTTPS capable proxy to use for all HTTPS requests.
 
-    Example: http://hostname:port/
+    Example: "https://hostname:port/"
     """
 )
 http.add_argument(
@@ -1003,8 +1030,7 @@ def boolean(value):
     help="""
     Attempts to load plugins from these directories.
 
-    Multiple directories can be used by separating them with a
-    semi-colon.
+    Multiple directories can be used by separating them with a semicolon.
     """
 )
 plugin.add_argument(
@@ -1037,7 +1063,6 @@ def boolean(value):
     Note: This method is the old and clunky way of authenticating with
     Twitch, using --twitch-oauth-authenticate is the recommended and
     simpler way of doing it now.
-
     """
 )
 plugin.add_argument(
@@ -1086,7 +1111,7 @@ def boolean(value):
     metavar="SESSION_ID",
     help="""
     Set a specific session ID for crunchyroll, can be used to bypass
-    region restrictions
+    region restrictions.
     """
 )
 plugin.add_argument(
@@ -1107,7 +1132,8 @@ def boolean(value):
     "--schoolism-email",
     metavar="EMAIL",
     help="""
-    The email associated with your Schoolism account, required to access any Schoolism stream.
+    The email associated with your Schoolism account,
+    required to access any Schoolism stream.
     """
 )
 plugin.add_argument(
@@ -1123,23 +1149,23 @@ def boolean(value):
     default=1,
     metavar="PART",
     help="""
-    Play part number PART of the lesson
+    Play part number PART of the lesson.
 
-    Defaults is 1
+    Defaults is 1.
     """
 )
 plugin.add_argument(
     "--daisuki-mux-subtitles",
     action="store_true",
     help="""
-    Automatically mux available subtitles in to the output stream
+    Automatically mux available subtitles in to the output stream.
     """
 )
 plugin.add_argument(
     "--rtve-mux-subtitles",
     action="store_true",
     help="""
-    Automatically mux available subtitles in to the output stream
+    Automatically mux available subtitles in to the output stream.
     """
 )
 plugin.add_argument(
@@ -1148,16 +1174,16 @@ def boolean(value):
     choices=["en", "ja", "english", "japanese"],
     default="english",
     help="""
-    The audio language to use for Funimation streams; japanese or english
+    The audio language to use for Funimation streams; japanese or english.
 
-    Default is english
+    Default is "english".
     """
 )
 plugin.add_argument(
     "--funimation-mux-subtitles",
     action="store_true",
     help="""
-    Enable automatically including available subtitles in to the output stream
+    Enable automatically including available subtitles in to the output stream.
     """
 )
 plugin.add_argument(
@@ -1178,14 +1204,15 @@ def boolean(value):
     "--pluzz-mux-subtitles",
     action="store_true",
     help="""
-    Automatically mux available subtitles in to the output stream
+    Automatically mux available subtitles in to the output stream.
     """
 )
 plugin.add_argument(
     "--wwenetwork-email",
     metavar="EMAIL",
     help="""
-    The email associated with your WWE Network account, required to access any WWE Network stream.
+    The email associated with your WWE Network account,
+    required to access any WWE Network stream.
     """
 )
 plugin.add_argument(
@@ -1213,7 +1240,7 @@ def boolean(value):
     "--npo-subtitles",
     action="store_true",
     help="""
-    Include subtitles for the deaf or hard of hearing, if available
+    Include subtitles for the deaf or hard of hearing, if available.
     """
 )
 plugin.add_argument(


Test patch: