Update changelog.

[youtubedl] / README.txt

diff --git a/README.txt b/README.txt
index c5e2ce3748efc0b57cbcbd6e4496c4637a229bf8..fc9f17e558e28b26a7459ddd519fb1cf84185be8 100644 (file)
--- a/README.txt
+++ b/README.txt
@@ -1,7 +1,7 @@
 NAME
 ====
 
 NAME
 ====
 

-youtube-dl
+youtube-dl - download videos from youtube.com or other video platforms

 
 SYNOPSIS
 ========
 
 SYNOPSIS
 ========


@@ -23,23 +23,28 @@ OPTIONS
 
     -h, --help                 print this help text and exit
     --version                  print program version and exit
 
     -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     maximum download rate (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.
+    -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
     --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

-    --proxy URL                Use the specified HTTP/HTTPS proxy
+    --extractor-descriptions   Output descriptions of all supported extractors
+    --proxy URL                Use the specified HTTP/HTTPS proxy. Pass in an
+                               empty string (--proxy "") for direct connection

     --no-check-certificate     Suppress HTTPS certificate validation.
     --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:
 ----------------
 
 Video Selection:
 ----------------


@@ -58,6 +63,23 @@ Video Selection:
     --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
     --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 listed in the archive
+                               file. Record the IDs of 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:
 -------------------
 
 Filesystem Options:
 -------------------


@@ -71,7 +93,10 @@ Filesystem Options:
                                %(uploader_id)s for the uploader nickname if
                                different, %(autonumber)s to get an automatically
                                incremented number, %(ext)s for the filename
                                %(uploader_id)s for the uploader nickname if
                                different, %(autonumber)s to get an automatically
                                incremented number, %(ext)s for the filename

-                               extension, %(upload_date)s for the upload date
+                               extension, %(format)s for the format description
+                               (like "22 - 1280x720" or "HD"),%(format_id)s for
+                               the unique id of the format (like Youtube's
+                               itags: "137"),%(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,
                                (YYYYMMDD), %(extractor)s for the provider
                                (youtube, metacafe, etc), %(id)s for the video id
                                , %(playlist)s for the playlist the video is in,


@@ -82,12 +107,14 @@ Filesystem Options:
                                ownloads/%(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
                                ownloads/%(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

-                               --autonumber option is given
+                               --auto-number 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
     --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
+    -c, --continue             force resume of partially downloaded files. By
+                               default, youtube-dl will resume downloads if
+                               possible.

     --no-continue              do not resume partially downloaded files (restart
                                from beginning)
     --cookies FILE             file to read cookies from and dump cookie jar in
     --no-continue              do not resume partially downloaded files (restart
                                from beginning)
     --cookies FILE             file to read cookies from and dump cookie jar in


@@ -96,6 +123,7 @@ Filesystem Options:
                                file modification time
     --write-description        write video description to a .description file
     --write-info-json          write video metadata to a .info.json file
                                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:
     --write-thumbnail          write thumbnail image to disk
 
 Verbosity / Simulation Options:


@@ -112,34 +140,42 @@ Verbosity / Simulation Options:
     --get-description          simulate, quiet but print video description
     --get-filename             simulate, quiet but print output filename
     --get-format               simulate, quiet but print output format
     --get-description          simulate, quiet but print video description
     --get-filename             simulate, quiet but print output filename
     --get-format               simulate, quiet but print output format

+    -j, --dump-json            simulate, quiet but print JSON information

     --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)
     --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)

+    --write-pages              Write downloaded intermediary pages to files in
+                               the current directory to debug problems

 
 Video Format Options:
 ---------------------
 
 
 Video Format Options:
 ---------------------
 

-    -f, --format FORMAT        video format code, specifiy the order of
-                               preference using slashes: "-f 22/17/18"
+    -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

     --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)
     --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-sub                write subtitle file (currently youtube only)
-    --only-sub                 [deprecated] alias of --skip-download
+
+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
     --all-subs                 downloads all the available subtitles of the

-                               video (currently youtube only)
+                               video

     --list-subs                lists all available subtitles for the video
     --list-subs                lists all available subtitles for the video

-                               (currently youtube only)
-    --sub-format LANG          subtitle format [srt/sbv] (default=srt)
-                               (currently youtube only)
-    --sub-lang LANG            language of the subtitles to download (optional)
-                               use IETF language tags like 'en'
+    --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:
 -----------------------
 
 Authentication Options:
 -----------------------


@@ -147,6 +183,7 @@ 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:
 ------------------------
 
 Post-processing Options:
 ------------------------


@@ -164,13 +201,18 @@ Post-processing Options:
                                processing; the video is erased by default
     --no-post-overwrites       do not overwrite post-processed files; the post-
                                processed files are overwritten by default
                                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
 
 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 ~/.config/youtube-dl.conf.
+mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl.conf. On
+Windows, the configuration file locations are
+%APPDATA%\youtube-dl\config.txt and C:\Users\<Yourname>\youtube-dl.conf.

 
 OUTPUT TEMPLATE
 ===============
 
 OUTPUT TEMPLATE
 ===============


@@ -202,9 +244,7 @@ lowercase S. Allowed names are:
 -   playlist_index: The index of the video in the playlist, a five-digit
     number.
 
 -   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
 
 In some cases, you don't want special characters such as 中, spaces, or
 &, such as when transferring the downloaded filename to a Windows system


@@ -241,14 +281,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
 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
 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.
 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.