Imported Upstream version 2014.06.07

1 files changed, 122 insertions, 24 deletions

diff --git a/README.txt b/README.txt
index 0015a74..4757a33 100644
--- a/README.txt
+++ b/README.txt
@@ -1,6 +1,3 @@
-NAME
-====
-
 youtube-dl - download videos from youtube.com or other video platforms
 
 SYNOPSIS
@@ -8,6 +5,27 @@ SYNOPSIS
 
 youtube-dl OPTIONS URL [URL...]
 
+INSTALLATION
+============
+
+To install it right away for all UNIX users (Linux, OS X, etc.), type:
+
+    sudo curl https://yt-dl.org/latest/youtube-dl -o /usr/local/bin/youtube-dl
+    sudo chmod a+x /usr/local/bin/youtube-dl
+
+If you do not have curl, you can alternatively use a recent wget:
+
+    sudo wget https://yt-dl.org/downloads/2014.05.13/youtube-dl -O /usr/local/bin/youtube-dl
+    sudo chmod a+x /usr/local/bin/youtube-dl
+
+Windows users can download a .exe file and place it in their home
+directory or any other location on their PATH.
+
+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
+https://rg3.github.io/youtube-dl/download.html .
+
 DESCRIPTION
 ===========
 
@@ -27,7 +45,7 @@ OPTIONS
                                      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
+                                     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
@@ -35,6 +53,9 @@ OPTIONS
     --user-agent UA                  specify a custom user agent
     --referer REF                    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
+                                     option multiple times
     --list-extractors                List all supported extractors and the URLs
                                      they would handle
     --extractor-descriptions         Output descriptions of all supported
@@ -43,6 +64,9 @@ OPTIONS
                                      an empty string (--proxy "") for direct
                                      connection
     --no-check-certificate           Suppress HTTPS certificate validation.
+    --prefer-insecure                Use an unencrypted connection to retrieve
+                                     information about the video. (Currently
+                                     supported only for YouTube)
     --cache-dir DIR                  Location in the filesystem where youtube-dl
                                      can store some downloaded information
                                      permanently. By default $XDG_CACHE_HOME
@@ -66,6 +90,7 @@ OPTIONS
                                      configuration in ~/.config/youtube-dl.conf
                                      (%APPDATA%/youtube-dl/config.txt on
                                      Windows)
+    --encoding ENCODING              Force the specified encoding (experimental)
 
 Video Selection:
 ----------------
@@ -137,8 +162,12 @@ Filesystem Options:
                                      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
+                                     literal percent. %(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' .
     --autonumber-size NUMBER         Specifies the number of digits in
@@ -174,6 +203,7 @@ Verbosity / Simulation Options:
 -------------------------------
 
     -q, --quiet                      activates quiet mode
+    --no-warnings                    Ignore warnings
     -s, --simulate                   do not download the video and do not write
                                      anything to disk
     --skip-download                  do not download the video
@@ -185,7 +215,9 @@ Verbosity / Simulation Options:
     --get-duration                   simulate, quiet but print video length
     --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
+    -j, --dump-json                  simulate, quiet but print JSON information.
+                                     See --output for a description of available
+                                     keys.
     --newline                        output progress bar as new lines
     --no-progress                    do not print progress bar
     --console-title                  display progress in console titlebar
@@ -204,9 +236,9 @@ Video Format Options:
                                      preference using slashes: "-f 22/17/18".
                                      "-f mp4" and "-f flv" are also supported.
                                      You can also use the special names "best",
-                                     "bestaudio", "worst", and "worstaudio". By
-                                     default, youtube-dl will pick the best
-                                     quality.
+                                     "bestvideo", "bestaudio", "worst",
+                                     "worstvideo" and "worstaudio". By default,
+                                     youtube-dl will pick the best quality.
     --all-formats                    download all available video formats
     --prefer-free-formats            prefer free video formats unless a specific
                                      one is requested
@@ -259,6 +291,7 @@ Post-processing Options:
                                      default
     --embed-subs                     embed subtitles in the video (only for mp4
                                      videos)
+    --embed-thumbnail                embed thumbnail in the audio as cover art
     --add-metadata                   write metadata to the video file
     --xattrs                         write metadata to the video file's xattrs
                                      (using dublin core and xdg standards)
@@ -272,7 +305,7 @@ 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. On
+mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl/config. On
 Windows, the configuration file locations are
 %APPDATA%\youtube-dl\config.txt and C:\Users\<Yourname>\youtube-dl.conf.
 
@@ -330,11 +363,14 @@ 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 $ # 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
+    # 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
+
+    $ # will only download the videos uploaded in the 200x decade
+    $ youtube-dl --dateafter 20000101 --datebefore 20091231
 
 FAQ
 ===
@@ -433,14 +469,76 @@ If you want to create a build of youtube-dl yourself, you'll need
 
 Adding support for a new site
 
-If you want to add support for a new site, copy any recently modified
-file in youtube_dl/extractor, add an import in
-youtube_dl/extractor/__init__.py. Have a look at
-youtube_dl/common/extractor/common.py for possible helper methods and a
-detailed description of what your extractor should return. Don't forget
-to run the tests with
-python test/test_download.py Test_Download.test_YourExtractor! For a
-detailed tutorial, refer to this blog post.
+If you want to add support for a new site, you can follow this quick
+list (assuming your service is called yourextractor):
+
+1.  Fork this repository
+2.  Check out the source code with
+    git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
+3.  Start a new git branch with
+    cd youtube-dl; git checkout -b 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<id>[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)
+                }
+            }
+
+            def _real_extract(self, url):
+                mobj = re.match(self._VALID_URL, url)
+                video_id = mobj.group('id')
+
+                # TODO more code goes here, for example ...
+                webpage = self._download_webpage(url, video_id)
+                title = self._html_search_regex(r'<h1>(.*?)</h1>', webpage, 'title')
+
+                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.
+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.
+8.  If you can, check the code with pyflakes (a good idea) and pep8
+    (optional, ignore E501).
+9.  When the tests pass, add the new files and commit them and push the
+    result, like this:
+
+        $ git add youtube_dl/extractor/__init__.py
+        $ git add youtube_dl/extractor/yourextractor.py
+        $ git commit -m '[yourextractor] Add new extractor'
+        $ git push origin yourextractor
+
+10. Finally, create a pull request. We'll then review and merge it.
+
+In any case, thank you very much for your contributions!
 
 BUGS
 ====