From 34488702053d995aba6a0dea9995e6a8858402dd Mon Sep 17 00:00:00 2001 From: pukkandan Date: Sat, 7 Aug 2021 14:19:17 +0530 Subject: [PATCH] [docs] Fix some mistakes and improve doc --- Changelog.md | 2 +- README.md | 74 +++++++++++++++++++++---------------- yt_dlp/YoutubeDL.py | 16 +++++--- yt_dlp/downloader/common.py | 7 +++- yt_dlp/options.py | 14 ++----- 5 files changed, 62 insertions(+), 51 deletions(-) diff --git a/Changelog.md b/Changelog.md index 446bd6c316..d07480b5af 100644 --- a/Changelog.md +++ b/Changelog.md @@ -317,7 +317,7 @@ ### 2021.05.20 * Add `html5=1` param to `get_video_info` page requests by [coletdjnz](https://github.com/coletdjnz) * Better message when login required * **Add option `--print`**: to print any field/template - * Deprecates: `--get-description`, `--get-duration`, `--get-filename`, `--get-format`, `--get-id`, `--get-thumbnail`, `--get-title`, `--get-url` + * Makes redundant: `--get-description`, `--get-duration`, `--get-filename`, `--get-format`, `--get-id`, `--get-thumbnail`, `--get-title`, `--get-url` * Field `additional_urls` to download additional videos from metadata using [`--parse-metadata`](https://github.com/yt-dlp/yt-dlp#modifying-metadata) * Merge youtube-dl: Upto [commit/dfbbe29](https://github.com/ytdl-org/youtube-dl/commit/dfbbe2902fc67f0f93ee47a8077c148055c67a9b) * Write thumbnail of playlist and add `pl_thumbnail` outtmpl key diff --git a/README.md b/README.md index 40a3bb8735..be4323771b 100644 --- a/README.md +++ b/README.md @@ -240,10 +240,10 @@ ## General Options: (default) (Alias: --no-abort-on-error) --abort-on-error Abort downloading of further videos if an error occurs (Alias: --no-ignore-errors) - --dump-user-agent Display the current browser identification - --list-extractors List all supported extractors + --dump-user-agent Display the current user-agent and exit + --list-extractors List all supported extractors and exit --extractor-descriptions Output descriptions of all supported - extractors + extractors and exit --force-generic-extractor Force extraction to use the generic extractor --default-search PREFIX Use this prefix for unqualified URLs. For @@ -551,8 +551,8 @@ ## Thumbnail Options: --no-write-thumbnail Do not write thumbnail image to disk (default) --write-all-thumbnails Write all thumbnail image formats to disk - --list-thumbnails Simulate and list all available thumbnail - formats + --list-thumbnails List available thumbnails of each video. + Simulate unless --no-simulate is used ## Internet Shortcut Options: --write-link Write an internet shortcut file, depending @@ -564,30 +564,34 @@ ## Internet Shortcut Options: --write-desktop-link Write a .desktop Linux internet shortcut ## Verbosity and Simulation Options: - -q, --quiet Activate quiet mode + -q, --quiet Activate quiet mode. If used with + --verbose, print the log to stderr --no-warnings Ignore warnings -s, --simulate Do not download the video and do not write anything to disk + --no-simulate Download the video even if printing/listing + options are used --ignore-no-formats-error Ignore "No video formats" error. Usefull - for extracting metadata even if the video - is not actually available for download + for extracting metadata even if the videos + are not actually available for download (experimental) --no-ignore-no-formats-error Throw error when no downloadable video formats are found (default) --skip-download Do not download the video but write all related files (Alias: --no-download) - -O, --print TEMPLATE Simulate, quiet but print the given fields. - Either a field name or similar formatting - as the output template can be used - -j, --dump-json Simulate, quiet but print JSON information. - See "OUTPUT TEMPLATE" for a description of - available keys - -J, --dump-single-json Simulate, quiet but print JSON information - for each command-line argument. If the URL - refers to a playlist, dump the whole - playlist information in a single line - --print-json Be quiet and print the video information as - JSON (video is still being downloaded) + -O, --print TEMPLATE Quiet, but print the given fields for each + video. Simulate unless --no-simulate is + used. Either a field name or same syntax as + the output template can be used + -j, --dump-json Quiet, but print JSON information for each + video. Simulate unless --no-simulate is + used. See "OUTPUT TEMPLATE" for a + description of available keys + -J, --dump-single-json Quiet, but print JSON information for each + url or infojson passed. Simulate unless + --no-simulate is used. If the URL refers to + a playlist, the whole playlist information + is dumped in a single line --force-write-archive Force download archive entries to be written as far as no errors occur, even if -s or another simulation option is used @@ -658,8 +662,8 @@ ## Video Format Options: actually downloadable --no-check-formats Do not check that the formats selected are actually downloadable - -F, --list-formats List all available formats of requested - videos + -F, --list-formats List available formats of each video. + Simulate unless --no-simulate is used --merge-output-format FORMAT If a merge is required (e.g. bestvideo+bestaudio), output to given container format. One of mkv, mp4, ogg, @@ -677,7 +681,8 @@ ## Subtitle Options: (Alias: --write-automatic-subs) --no-write-auto-subs Do not write auto-generated subtitles (default) (Alias: --no-write-automatic-subs) - --list-subs List all available subtitles for the video + --list-subs List available subtitles of each video. + Simulate unless --no-simulate is used --sub-format FORMAT Subtitle format, accepts formats preference, for example: "srt" or "ass/srt/best" @@ -712,7 +717,7 @@ ## Post-Processing Options: --audio-format FORMAT Specify audio format to convert the audio to when -x is used. Currently supported formats are: best (default) or one of - aac|flac|mp3|m4a|opus|vorbis|wav + best|aac|flac|mp3|m4a|opus|vorbis|wav --audio-quality QUALITY Specify ffmpeg audio quality, insert a value between 0 (better) and 9 (worse) for VBR or a specific bitrate like 128K @@ -784,17 +789,22 @@ ## Post-Processing Options: path to the binary or its containing directory --exec CMD Execute a command on the file after - downloading and post-processing. Similar - syntax to the output template can be used + downloading and post-processing. Same + syntax as the output template can be used to pass any field as arguments to the command. An additional field "filepath" that contains the final path of the downloaded file is also available. If no fields are passed, %(filepath)q is appended - to the end of the command + to the end of the command. This option can + be used multiple times + --no-exec Remove any previously defined --exec --exec-before-download CMD Execute a command before the actual download. The syntax is the same as --exec - but "filepath" is not available + but "filepath" is not available. This + option can be used multiple times + --no-exec-before-download Remove any previously defined + --exec-before-download --convert-subs FORMAT Convert the subtitles to another format (currently supported: srt|vtt|ass|lrc) (Alias: --convert-subtitles) @@ -1374,7 +1384,7 @@ # Set "comment" field in video metadata using description instead of webpage_url # EXTRACTOR ARGUMENTS -Some extractors accept additional arguments which can be passed using `--extractor-args KEY:ARGS`. `ARGS` is a `;` (semicolon) seperated string of `ARG=VAL1,VAL2`. Eg: `--extractor-args "youtube:skip=dash,hls;player_client=android" --extractor-args "funimation:version=uncut"` +Some extractors accept additional arguments which can be passed using `--extractor-args KEY:ARGS`. `ARGS` is a `;` (semicolon) seperated string of `ARG=VAL1,VAL2`. Eg: `--extractor-args "youtube:player_client=android_agegate,web;include_live_dash" --extractor-args "funimation:version=uncut"` The following extractors use this feature: * **youtube** @@ -1383,8 +1393,8 @@ # EXTRACTOR ARGUMENTS * `player_skip`: `configs` - skip any requests for client configs and use defaults * `include_live_dash`: Include live dash formats (These formats don't download properly) * `comment_sort`: `top` or `new` (default) - choose comment sorting mode (on YouTube's side). - * `max_comments`: maximum amount of comments to download (default all). - * `max_comment_depth`: maximum depth for nested comments. YouTube supports depths 1 or 2 (default). + * `max_comments`: Maximum amount of comments to download (default all). + * `max_comment_depth`: Maximum depth for nested comments. YouTube supports depths 1 or 2 (default). * **funimation** * `language`: Languages to extract. Eg: `funimation:language=english,japanese` @@ -1443,7 +1453,7 @@ #### Not recommended #### Developer options These options are not intended to be used by the end-user - --test For testing extractors + --test Download only part of video for testing extractors --youtube-print-sig-code For testing youtube signatures diff --git a/yt_dlp/YoutubeDL.py b/yt_dlp/YoutubeDL.py index f4333c7e52..2791d180ac 100644 --- a/yt_dlp/YoutubeDL.py +++ b/yt_dlp/YoutubeDL.py @@ -220,7 +220,7 @@ class YoutubeDL(object): 'temp' and the keys of OUTTMPL_TYPES (in utils.py) outtmpl: Dictionary of templates for output names. Allowed keys are 'default' and the keys of OUTTMPL_TYPES (in utils.py). - A string a also accepted for backward compatibility + For compatibility with youtube-dl, a single string can also be used outtmpl_na_placeholder: Placeholder for unavailable meta fields. restrictfilenames: Do not allow "&" and spaces in file names trim_file_name: Limit length of filename (extension excluded) @@ -234,6 +234,8 @@ class YoutubeDL(object): overwrites: Overwrite all video and metadata files if True, overwrite only non-video files if None and don't overwrite any file if False + For compatibility with youtube-dl, + "nooverwrites" may also be used instead playliststart: Playlist item to start at. playlistend: Playlist item to end at. playlist_items: Specific indices of playlist to download. @@ -246,7 +248,7 @@ class YoutubeDL(object): writedescription: Write the video description to a .description file writeinfojson: Write the video description to a .info.json file clean_infojson: Remove private fields from the infojson - writecomments: Extract video comments. This will not be written to disk + getcomments: Extract video comments. This will not be written to disk unless writeinfojson is also given writeannotations: Write the video annotations to a .annotations.xml file writethumbnail: Write the thumbnail image to a file @@ -420,10 +422,12 @@ class YoutubeDL(object): ffmpeg_location: Location of the ffmpeg/avconv binary; either the path to the binary or its containing directory. postprocessor_args: A dictionary of postprocessor/executable keys (in lower case) - and a list of additional command-line arguments for the - postprocessor/executable. The dict can also have "PP+EXE" keys - which are used when the given exe is used by the given PP. - Use 'default' as the name for arguments to passed to all PP + and a list of additional command-line arguments for the + postprocessor/executable. The dict can also have "PP+EXE" keys + which are used when the given exe is used by the given PP. + Use 'default' as the name for arguments to passed to all PP + For compatibility with youtube-dl, a single list of args + can also be used The following options are used by the extractors: extractor_retries: Number of times to retry for known errors diff --git a/yt_dlp/downloader/common.py b/yt_dlp/downloader/common.py index 396521aa1a..3846a7ee59 100644 --- a/yt_dlp/downloader/common.py +++ b/yt_dlp/downloader/common.py @@ -47,8 +47,11 @@ class FileDownloader(object): min_filesize: Skip files smaller than this size max_filesize: Skip files larger than this size xattr_set_filesize: Set ytdl.filesize user xattribute with expected size. - external_downloader_args: A list of additional command-line arguments for the - external downloader. + external_downloader_args: A dictionary of downloader keys (in lower case) + and a list of additional command-line arguments for the + executable. Use 'default' as the name for arguments to be + passed to all downloaders. For compatibility with youtube-dl, + a single list of args can also be used hls_use_mpegts: Use the mpegts container for HLS videos. http_chunk_size: Size of a chunk for chunk-based HTTP downloading. May be useful for bypassing bandwidth throttling imposed by diff --git a/yt_dlp/options.py b/yt_dlp/options.py index 38c99bbcb2..aef2f81434 100644 --- a/yt_dlp/options.py +++ b/yt_dlp/options.py @@ -190,7 +190,7 @@ def _dict_from_options_callback( general.add_option( '--dump-user-agent', action='store_true', dest='dump_user_agent', default=False, - help='Display the current browser identification and exit') + help='Display the current user-agent and exit') general.add_option( '--list-extractors', action='store_true', dest='list_extractors', default=False, @@ -223,12 +223,6 @@ def _dict_from_options_callback( '--flat-playlist', action='store_const', dest='extract_flat', const='in_playlist', default=False, help='Do not extract the videos of a playlist, only list them') - general.add_option( - '--flat-videos', - action='store_true', dest='extract_flat', - # help='Do not resolve the video urls') - # doesn't work - help=optparse.SUPPRESS_HELP) general.add_option( '--no-flat-playlist', action='store_false', dest='extract_flat', @@ -781,7 +775,7 @@ def _dict_from_options_callback( verbosity.add_option( '-q', '--quiet', action='store_true', dest='quiet', default=False, - help='Activate quiet mode') + help='Activate quiet mode. If used with --verbose, print the log to stderr') verbosity.add_option( '--no-warnings', dest='no_warnings', action='store_true', default=False, @@ -799,7 +793,7 @@ def _dict_from_options_callback( action='store_true', dest='ignore_no_formats_error', default=False, help=( 'Ignore "No video formats" error. Usefull for extracting metadata ' - 'even if the video is not actually available for download (experimental)')) + 'even if the videos are not actually available for download (experimental)')) verbosity.add_option( '--no-ignore-no-formats-error', action='store_false', dest='ignore_no_formats_error', @@ -1282,7 +1276,7 @@ def _dict_from_options_callback( callback=_list_from_options_callback, callback_kwargs={'delim': None}, help=( 'Execute a command on the file after downloading and post-processing. ' - 'Similar syntax to the output template can be used to pass any field as arguments to the command. ' + 'Same syntax as the output template can be used to pass any field as arguments to the command. ' 'An additional field "filepath" that contains the final path of the downloaded file is also available. ' 'If no fields are passed, %(filepath)q is appended to the end of the command. ' 'This option can be used multiple times'))