X-Git-Url: https://git.rapsys.eu/youtubedl/blobdiff_plain/1931fa5f23ac75ea766517aa1b5ebf267ad3f97d..0fce975b3a15ab01d247e9f737ca4589b7ceebd7:/README.txt?ds=inline diff --git a/README.txt b/README.txt index 4f41be2..3ba6f53 100644 --- a/README.txt +++ b/README.txt @@ -21,6 +21,14 @@ If you do not have curl, you can alternatively use a recent wget: Windows users can download a .exe file and place it in their home directory or any other location on their PATH. +OS X users can install youtube-dl with Homebrew. + + brew install youtube-dl + +You can also use pip: + + sudo pip install youtube-dl + Alternatively, refer to the developer instructions below for how to check out and work with the git repository. For further options, including PGP signatures, see @@ -73,6 +81,8 @@ OPTIONS configuration in ~/.config/youtube-dl.conf (%APPDATA%/youtube-dl/config.txt on Windows) + --flat-playlist Do not extract the videos of a playlist, + only list them. Video Selection: ---------------- @@ -105,8 +115,6 @@ Video Selection: downloaded videos in it. --include-ads Download advertisements as well (experimental) - --youtube-include-dash-manifest Try to download the DASH manifest on - YouTube videos (experimental) Download Options: ----------------- @@ -141,17 +149,19 @@ Filesystem Options: %(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 id, %(playlist_title)s, + %(playlist_id)s, or %(playlist)s (=title if + present, ID otherwise) for the playlist the video is in, %(playlist_index)s for the - position in the playlist and %% for a - literal percent. %(height)s and %(width)s - for the width and height of the video - format. %(resolution)s for a textual + position in the playlist. %(height)s and + %(width)s for the width and height of the + video format. %(resolution)s for a textual description of the resolution of the video - format. Use - to output to stdout. Can also - be used to download to a different - directory, for example with -o '/my/downloa - ds/%(uploader)s/%(title)s-%(id)s.%(ext)s' . + format. %% 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' . --autonumber-size NUMBER Specifies the number of digits in %(autonumber)s when it is present in output filename template or --auto-number option @@ -168,7 +178,8 @@ Filesystem Options: downloads if possible. --no-continue do not resume partially downloaded files (restart from beginning) - --no-part do not use .part files + --no-part do not use .part files - write directly + into output file --no-mtime do not use the Last-modified header to set the file modification time --write-description write video description to a .description @@ -210,6 +221,10 @@ Verbosity / Simulation Options: -j, --dump-json simulate, quiet but print JSON information. See --output 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. --newline output progress bar as new lines --no-progress do not print progress bar --console-title display progress in console titlebar @@ -230,7 +245,7 @@ Workarounds: information about the video. (Currently supported only for YouTube) --user-agent UA specify a custom user agent - --referer REF specify a custom referer, use if the video + --referer URL specify a custom referer, use if the video access is restricted to one domain --add-header FIELD:VALUE specify a custom HTTP header and its value, separated by a colon ':'. You can use this @@ -243,17 +258,27 @@ Video Format Options: --------------------- -f, --format FORMAT video format code, specify the order of - preference using slashes: "-f 22/17/18". - "-f mp4" and "-f flv" are also supported. - You can also use the special names "best", - "bestvideo", "bestaudio", "worst", - "worstvideo" and "worstaudio". By default, - youtube-dl will pick the best quality. + preference using slashes: -f 22/17/18 . -f + mp4 , -f m4a and -f flv are also + supported. You can also use the special + names "best", "bestvideo", "bestaudio", + "worst", "worstvideo" and "worstaudio". By + default, youtube-dl will pick the best + quality. Use commas to download multiple + audio formats, such as -f + 136/137/mp4/bestvideo,140/m4a/bestaudio. + You can merge the video and audio of two + formats into a single file using -f + (requires ffmpeg or + avconv), for example -f + bestvideo+bestaudio. --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 + --youtube-skip-dash-manifest Do not download the DASH manifest on + YouTube videos Subtitle Options: ----------------- @@ -273,8 +298,9 @@ Subtitle Options: Authentication Options: ----------------------- - -u, --username USERNAME account username + -u, --username USERNAME login with this account ID -p, --password PASSWORD account password + -2, --twofactor TWOFACTOR two-factor auth code -n, --netrc use .netrc authentication data --video-password PASSWORD video password (vimeo, smotri) @@ -285,7 +311,7 @@ Post-processing Options: (requires ffmpeg or avconv and ffprobe or avprobe) --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a", - "opus", or "wav"; best by default + "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 @@ -309,6 +335,10 @@ Post-processing Options: postprocessors (default) --prefer-ffmpeg Prefer ffmpeg over avconv for running the postprocessors + --exec CMD Execute a command on the file after + downloading, similar to find's -exec + syntax. Example: --exec 'adb push {} + /sdcard/Music/ && rm {}' CONFIGURATION ============= @@ -356,10 +386,12 @@ In some cases, you don't want special characters such as 中, spaces, or or the filename through an 8bit-unsafe channel. In these cases, add the --restrict-filenames flag to get a shorter title: - $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc - youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters - $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames - youtube-dl_test_video_.mp4 # A simple file name +``` {.bash} +$ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc +youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters +$ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames +youtube-dl_test_video_.mp4 # A simple file name +``` VIDEO SELECTION =============== @@ -373,18 +405,74 @@ Videos can be filtered by their upload date using the options --date, Examples: - # Download only the videos uploaded in the last 6 months - $ youtube-dl --dateafter now-6months +``` {.bash} +# Download only the videos uploaded in the last 6 months +$ youtube-dl --dateafter now-6months - # Download only the videos uploaded on January 1, 1970 - $ youtube-dl --date 19700101 +# Download only the videos uploaded on January 1, 1970 +$ youtube-dl --date 19700101 - $ # will only download the videos uploaded in the 200x decade - $ youtube-dl --dateafter 20000101 --datebefore 20091231 +$ # will only download the videos uploaded in the 200x decade +$ youtube-dl --dateafter 20000101 --datebefore 20091231 +``` FAQ === +How do I update youtube-dl? + +If you've followed our manual installation instructions, you can simply +run youtube-dl -U (or, on Linux, sudo youtube-dl -U). + +If you have used pip, a simple sudo pip install -U youtube-dl is +sufficient to update. + +If you have installed youtube-dl using a package manager like apt-get or +yum, use the standard system update mechanism to update. Note that +distribution packages are often outdated. As a rule of thumb, youtube-dl +releases at least once a month, and often weekly or even daily. Simply +go to http://yt-dl.org/ to find out the current version. Unfortunately, +there is nothing we youtube-dl developers can do if your distributions +serves a really outdated version. You can (and should) complain to your +distribution in their bugtracker or support forum. + +As a last resort, you can also uninstall the version installed by your +package manager and follow our manual installation instructions. For +that, remove the distribution's package, with a line like + + sudo apt-get remove -y youtube-dl + +Afterwards, simply follow our manual installation instructions: + + sudo wget https://yt-dl.org/latest/youtube-dl -O /usr/local/bin/youtube-dl + sudo chmod a+x /usr/local/bin/youtube-dl + hash -r + +Again, from then on you'll be able to update with sudo youtube-dl -U. + +I'm getting an error Unable to extract OpenGraph title on YouTube playlists + +YouTube changed their playlist format in March 2014 and later on, so +you'll need at least youtube-dl 2014.07.25 to download all YouTube +videos. + +If you have installed youtube-dl with a package manager, pip, setup.py +or a tarball, please use that to update. Note that Ubuntu packages do +not seem to get updated anymore. Since we are not affiliated with +Ubuntu, there is little we can do. Feel free to report bugs to the +Ubuntu packaging guys - all they have to do is update the package to a +somewhat recent version. See above for a way to update. + +Do I always have to pass in --max-quality FORMAT, or -citw? + +By default, youtube-dl intends to have the best options (incidentally, +if you have a convincing case that these should be different, please +file an issue where you explain that). Therefore, it is unnecessary and +sometimes harmful to copy long option strings from webpages. In +particular, --max-quality limits the video quality (so if you want the +best quality, do NOT pass it in), and the only option out of -citw that +is regularly useful is -i. + Can you please put the -b option back? Most people asking this question are not aware that youtube-dl now @@ -490,49 +578,53 @@ list (assuming your service is called yourextractor): 4. Start with this simple template and save it to youtube_dl/extractor/yourextractor.py: - # coding: utf-8 - from __future__ import unicode_literals - - import re - - from .common import InfoExtractor - - - class YourExtractorIE(InfoExtractor): - _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P[0-9]+)' - _TEST = { - 'url': 'http://yourextractor.com/watch/42', - 'md5': 'TODO: md5 sum of the first 10KiB of the video file', - 'info_dict': { - 'id': '42', - 'ext': 'mp4', - 'title': 'Video title goes here', - # TODO more properties, either as: - # * A value - # * MD5 checksum; start the string with md5: - # * A regular expression; start the string with re: - # * Any Python type (for example int or float) - } + ``` {.python} + # coding: utf-8 + from __future__ import unicode_literals + + from .common import InfoExtractor + + + class YourExtractorIE(InfoExtractor): + _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P[0-9]+)' + _TEST = { + 'url': 'http://yourextractor.com/watch/42', + 'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)', + 'info_dict': { + 'id': '42', + 'ext': 'mp4', + 'title': 'Video title goes here', + 'thumbnail': 're:^https?://.*\.jpg$', + # TODO more properties, either as: + # * A value + # * MD5 checksum; start the string with md5: + # * A regular expression; start the string with re: + # * Any Python type (for example int or float) } + } - def _real_extract(self, url): - mobj = re.match(self._VALID_URL, url) - video_id = mobj.group('id') + def _real_extract(self, url): + video_id = self._match_id(url) - # TODO more code goes here, for example ... - webpage = self._download_webpage(url, video_id) - title = self._html_search_regex(r'

(.*?)

', webpage, 'title') + # TODO more code goes here, for example ... + webpage = self._download_webpage(url, video_id) + title = self._html_search_regex(r'

(.*?)

', webpage, 'title') - return { - 'id': video_id, - 'title': title, - # TODO more properties (see youtube_dl/extractor/common.py) - } + return { + 'id': video_id, + 'title': title, + # TODO more properties (see youtube_dl/extractor/common.py) + } + ``` 5. Add an import in youtube_dl/extractor/__init__.py. 6. Run python test/test_download.py TestDownload.test_YourExtractor. This should fail at first, but you can continually re-run it until - you're done. + you're done. If you decide to add more than one test, then rename + _TEST to _TESTS and make it into a list of dictionaries. The tests + will be then be named TestDownload.test_YourExtractor, + TestDownload.test_YourExtractor_1, + TestDownload.test_YourExtractor_2, etc. 7. Have a look at youtube_dl/common/extractor/common.py for possible helper methods and a detailed description of what your extractor should return. Add tests and code for as many as you want. @@ -550,6 +642,26 @@ list (assuming your service is called yourextractor): In any case, thank you very much for your contributions! +EMBEDDING YOUTUBE-DL +==================== + +youtube-dl makes the best effort to be a good command-line program, and +thus should be callable from any programming language. If you encounter +any problems parsing its output, feel free to create a report. + +From a Python program, you can embed youtube-dl in a more powerful +fashion, like this: + + import youtube_dl + + ydl_opts = {} + with youtube_dl.YoutubeDL(ydl_opts) as ydl: + ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc']) + +Most likely, you'll want to use various options. For a list of what can +be done, have a look at youtube_dl/YoutubeDL.py. For a start, if you +want to intercept youtube-dl's output, set a logger object. + BUGS ====