X-Git-Url: https://git.rapsys.eu/youtubedl/blobdiff_plain/c4994c6aff3e03c7848b0a9d4ff9a1873412d31f..374c6a96320fd01ece1af19fa7ca7d7555d7e01a:/README.txt?ds=inline diff --git a/README.txt b/README.txt index 089923b..b773576 100644 --- a/README.txt +++ b/README.txt @@ -1,142 +1,208 @@ NAME ==== -youtube-dl +youtube-dl - download videos from youtube.com or other video platforms SYNOPSIS ======== -youtube-dl [OPTIONS] URL [URL...] +youtube-dl OPTIONS URL [URL...] DESCRIPTION =========== youtube-dl is a small command-line program to download videos from YouTube.com and a few more sites. It requires the Python interpreter, -version 2.x (x being at least 6), and it is not platform specific. It -should work in your Unix box, in Windows or in Mac OS X. It is released -to the public domain, which means you can modify it, redistribute it or -use it however you like. +version 2.6, 2.7, or 3.3+, and it is not platform specific. It should +work on your Unix box, on Windows or on Mac OS X. It is released to the +public domain, which means you can modify it, redistribute it or use it +however you like. OPTIONS ======= - -h, --help print this help text and exit - --version print program version and exit - -U, --update update this program to latest version - -i, --ignore-errors continue on download errors - -r, --rate-limit LIMIT download rate limit (e.g. 50k or 44.6m) - -R, --retries RETRIES number of retries (default is 10) - --buffer-size SIZE size of download buffer (e.g. 1024 or 16k) (default - is 1024) - --no-resize-buffer do not automatically adjust the buffer size. By - default, the buffer size is automatically resized - from an initial value of SIZE. - --dump-user-agent display the current browser identification - --user-agent UA specify a custom user agent - --list-extractors List all supported extractors and the URLs they - would handle + -h, --help print this help text and exit + --version print program version and exit + -U, --update update this program to latest version. Make sure + that you have sufficient permissions (run with + sudo if needed) + -i, --ignore-errors continue on download errors, for example to to + skip unavailable videos in a playlist + --abort-on-error Abort downloading of further videos (in the + playlist or the command line) if an error occurs + --dump-user-agent display the current browser identification + --user-agent UA specify a custom user agent + --referer REF specify a custom referer, use if the video access + is restricted to one domain + --list-extractors List all supported extractors and the URLs they + would handle + --extractor-descriptions Output descriptions of all supported extractors + --proxy URL Use the specified HTTP/HTTPS proxy + --no-check-certificate Suppress HTTPS certificate validation. + --cache-dir DIR Location in the filesystem where youtube-dl can + store downloaded information permanently. By + default $XDG_CACHE_HOME/youtube-dl or ~/.cache + /youtube-dl . + --no-cache-dir Disable filesystem caching Video Selection: ---------------- - --playlist-start NUMBER playlist video to start at (default is 1) - --playlist-end NUMBER playlist video to end at (default is last) - --match-title REGEX download only matching titles (regex or caseless - sub-string) - --reject-title REGEX skip download for matching titles (regex or - caseless sub-string) - --max-downloads NUMBER Abort after downloading NUMBER files + --playlist-start NUMBER playlist video to start at (default is 1) + --playlist-end NUMBER playlist video to end at (default is last) + --match-title REGEX download only matching titles (regex or caseless + sub-string) + --reject-title REGEX skip download for matching titles (regex or + caseless sub-string) + --max-downloads NUMBER Abort after downloading NUMBER files + --min-filesize SIZE Do not download any videos smaller than SIZE + (e.g. 50k or 44.6m) + --max-filesize SIZE Do not download any videos larger than SIZE (e.g. + 50k or 44.6m) + --date DATE download only videos uploaded in this date + --datebefore DATE download only videos uploaded before this date + --dateafter DATE download only videos uploaded after this date + --no-playlist download only the currently playing video + --age-limit YEARS download only videos suitable for the given age + --download-archive FILE Download only videos not present in the archive + file. Record all downloaded videos in it. + +Download Options: +----------------- + + -r, --rate-limit LIMIT maximum download rate in bytes per second (e.g. + 50K or 4.2M) + -R, --retries RETRIES number of retries (default is 10) + --buffer-size SIZE size of download buffer (e.g. 1024 or 16K) + (default is 1024) + --no-resize-buffer do not automatically adjust the buffer size. By + default, the buffer size is automatically resized + from an initial value of SIZE. Filesystem Options: ------------------- - -t, --title use title in file name - --id use video ID in file name - -l, --literal [deprecated] alias of --title - -A, --auto-number number downloaded files starting from 00000 - -o, --output TEMPLATE output filename template. Use %(title)s to get the - title, %(uploader)s for the uploader name, - %(autonumber)s to get an automatically incremented - number, %(ext)s for the filename extension, - %(upload_date)s for the upload date (YYYYMMDD), - %(extractor)s for the provider (youtube, metacafe, - etc), %(id)s for the video id and %% for a literal - percent. Use - to output to stdout. Can also be - used to download to a different directory, for - example with -o '/my/downloads/%(uploader)s/%(title - )s-%(id)s.%(ext)s' . - --restrict-filenames Restrict filenames to only ASCII characters, and - avoid "&" and spaces in filenames - -a, --batch-file FILE file containing URLs to download ('-' for stdin) - -w, --no-overwrites do not overwrite files - -c, --continue resume partially downloaded files - --no-continue do not resume partially downloaded files (restart - from beginning) - --cookies FILE file to read cookies from and dump cookie jar in - --no-part do not use .part files - --no-mtime do not use the Last-modified header to set the file - modification time - --write-description write video description to a .description file - --write-info-json write video metadata to a .info.json file + -t, --title use title in file name (default) + --id use only video ID in file name + -l, --literal [deprecated] alias of --title + -A, --auto-number number downloaded files starting from 00000 + -o, --output TEMPLATE output filename template. Use %(title)s to get + the title, %(uploader)s for the uploader name, + %(uploader_id)s for the uploader nickname if + different, %(autonumber)s to get an automatically + incremented number, %(ext)s for the filename + extension, %(format)s for the format description + (like "22 - 1280x720" or "HD")%(upload_date)s for + the upload date (YYYYMMDD), %(extractor)s for the + provider (youtube, metacafe, etc), %(id)s for the + video id , %(playlist)s for the playlist the + video is in, %(playlist_index)s for the position + in the playlist and %% for a literal percent. Use + - to output to stdout. Can also be used to + download to a different directory, for example + with -o '/my/downloads/%(uploader)s/%(title)s-%(i + d)s.%(ext)s' . + --autonumber-size NUMBER Specifies the number of digits in %(autonumber)s + when it is present in output filename template or + --autonumber option is given + --restrict-filenames Restrict filenames to only ASCII characters, and + avoid "&" and spaces in filenames + -a, --batch-file FILE file containing URLs to download ('-' for stdin) + -w, --no-overwrites do not overwrite files + -c, --continue resume partially downloaded files + --no-continue do not resume partially downloaded files (restart + from beginning) + --cookies FILE file to read cookies from and dump cookie jar in + --no-part do not use .part files + --no-mtime do not use the Last-modified header to set the + file modification time + --write-description write video description to a .description file + --write-info-json write video metadata to a .info.json file + --write-annotations write video annotations to a .annotation file + --write-thumbnail write thumbnail image to disk Verbosity / Simulation Options: ------------------------------- - -q, --quiet activates quiet mode - -s, --simulate do not download the video and do not write anything - to disk - --skip-download do not download the video - -g, --get-url simulate, quiet but print URL - -e, --get-title simulate, quiet but print title - --get-thumbnail simulate, quiet but print thumbnail URL - --get-description simulate, quiet but print video description - --get-filename simulate, quiet but print output filename - --get-format simulate, quiet but print output format - --no-progress do not print progress bar - --console-title display progress in console titlebar - -v, --verbose print various debugging information + -q, --quiet activates quiet mode + -s, --simulate do not download the video and do not write + anything to disk + --skip-download do not download the video + -g, --get-url simulate, quiet but print URL + -e, --get-title simulate, quiet but print title + --get-id simulate, quiet but print id + --get-thumbnail simulate, quiet but print thumbnail URL + --get-description simulate, quiet but print video description + --get-filename simulate, quiet but print output filename + --get-format simulate, quiet but print output format + --newline output progress bar as new lines + --no-progress do not print progress bar + --console-title display progress in console titlebar + -v, --verbose print various debugging information + --dump-intermediate-pages print downloaded pages to debug problems(very + verbose) Video Format Options: --------------------- - -f, --format FORMAT video format code - --all-formats download all available video formats - --prefer-free-formats prefer free video formats unless a specific one is - requested - --max-quality FORMAT highest quality format to download - -F, --list-formats list all available formats (currently youtube only) - --write-srt write video closed captions to a .srt file - (currently youtube only) - --srt-lang LANG language of the closed captions to download - (optional) use IETF language tags like 'en' + -f, --format FORMAT video format code, specifiy the order of + preference using slashes: "-f 22/17/18". "-f mp4" + and "-f flv" are also supported + --all-formats download all available video formats + --prefer-free-formats prefer free video formats unless a specific one + is requested + --max-quality FORMAT highest quality format to download + -F, --list-formats list all available formats (currently youtube + only) + +Subtitle Options: +----------------- + + --write-sub write subtitle file + --write-auto-sub write automatic subtitle file (youtube only) + --all-subs downloads all the available subtitles of the + video + --list-subs lists all available subtitles for the video + --sub-format FORMAT subtitle format (default=srt) ([sbv/vtt] youtube + only) + --sub-lang LANGS languages of the subtitles to download (optional) + separated by commas, use IETF language tags like + 'en,pt' Authentication Options: ----------------------- - -u, --username USERNAME account username - -p, --password PASSWORD account password - -n, --netrc use .netrc authentication data + -u, --username USERNAME account username + -p, --password PASSWORD account password + -n, --netrc use .netrc authentication data + --video-password PASSWORD video password (vimeo only) Post-processing Options: ------------------------ - -x, --extract-audio convert video files to audio-only files (requires - ffmpeg or avconv and ffprobe or avprobe) - --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a", or "wav"; - best by default - --audio-quality QUALITY ffmpeg/avconv audio quality specification, insert a - value between 0 (better) and 9 (worse) for VBR or a - specific bitrate like 128K (default 5) - -k, --keep-video keeps the video file on disk after the post- - processing; the video is erased by default + -x, --extract-audio convert video files to audio-only files (requires + ffmpeg or avconv and ffprobe or avprobe) + --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a", "opus", or + "wav"; best by default + --audio-quality QUALITY ffmpeg/avconv audio quality specification, insert + a value between 0 (better) and 9 (worse) for VBR + or a specific bitrate like 128K (default 5) + --recode-video FORMAT Encode the video to another format if necessary + (currently supported: mp4|flv|ogg|webm) + -k, --keep-video keeps the video file on disk after the post- + processing; the video is erased by default + --no-post-overwrites do not overwrite post-processed files; the post- + processed files are overwritten by default + --embed-subs embed subtitles in the video (only for mp4 + videos) + --add-metadata add metadata to the files CONFIGURATION ============= You can configure youtube-dl by placing default arguments (such as --extract-audio --no-mtime to always extract the audio and not copy the -mtime) into /etc/youtube-dl.conf and/or ~/.local/config/youtube-dl.conf. +mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl.conf. OUTPUT TEMPLATE =============== @@ -163,10 +229,12 @@ lowercase S. Allowed names are: the file. - autonumber: The sequence will be replaced by a five-digit number that will be increased with each download, starting at zero. +- playlist: The name or the id of the playlist that contains the + video. +- playlist_index: The index of the video in the playlist, a five-digit + number. -The current default template is %(id)s.%(ext)s, but that will be -switchted to %(title)s-%(id)s.%(ext)s (which can be requested with -t at -the moment). +The current default template is %(title)s-%(id)s.%(ext)s. In some cases, you don't want special characters such as 中, spaces, or &, such as when transferring the downloaded filename to a Windows system @@ -178,6 +246,22 @@ or the filename through an 8bit-unsafe channel. In these cases, add the $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames youtube-dl_test_video_.mp4 # A simple file name +VIDEO SELECTION +=============== + +Videos can be filtered by their upload date using the options --date, +--datebefore or --dateafter, they accept dates in two formats: + +- Absolute dates: Dates in the format YYYYMMDD. +- Relative dates: Dates in the format + (now|today)[+-][0-9](day|week|month|year)(s)? + +Examples: + + $ youtube-dl --dateafter now-6months #will only download the videos uploaded in the last 6 months + $ youtube-dl --date 19700101 #will only download the videos uploaded in January 1, 1970 + $ youtube-dl --dateafter 20000101 --datebefore 20100101 #will only download the videos uploaded between 2000 and 2010 + FAQ === @@ -187,14 +271,14 @@ Most people asking this question are not aware that youtube-dl now defaults to downloading the highest available quality as reported by YouTube, which will be 1080p or 720p in some cases, so you no longer need the -b option. For some specific videos, maybe YouTube does not -report them to be available in a specific high quality format you''re +report them to be available in a specific high quality format you're interested in. In that case, simply request it with the -f option and youtube-dl will try to download it. I get HTTP error 402 when trying to download a video. What's this? Apparently YouTube requires you to pass a CAPTCHA test if you download -too much. We''re considering to provide a way to let you solve the +too much. We're considering to provide a way to let you solve the CAPTCHA, but at the moment, your best course of action is pointing a webbrowser to the youtube URL, solving the CAPTCHA, and restart youtube-dl. @@ -268,6 +352,8 @@ Please include: youtube-dl -t "http://www.youtube.com/watch?v=uHlDtZ6Oc3s&feature=channel_video_title". A common mistake is not to escape the &. Putting URLs in quotes should solve this problem. +- If possible re-run the command with --verbose, and include the full + output, it is really helpful to us. - The output of youtube-dl --version - The output of python --version - The name and version of your Operating System ("Ubuntu 11.04 x64" or