Merge branch 'develop'

CHANGELOG

@@ -1,9 +1,21 @@
+19 October 2014
+Version 0.3.64
+
+[Update] - Cache javascript file locally to temp dir (less fetching)
+[Update] - Added itag 278 (low-res VP9)
+[Feature] - Retrieve DASH streams (more streams, higher quality audio)
+[Feature] - added remux_audio parameter to download function to remux audio
+            files if ffmpeg or avconv is installed (better compatibility)
+
+-------------------------------------------------------------------------------
+
 27 August 2014
 Version 0.3.62
 
 [Feature] - Added url_https property to return https url
 
 -------------------------------------------------------------------------------
+
 15 August 2014
 Version 0.3.60
 

README.rst

@@ -136,13 +136,13 @@ Download video and show progress:
     >>> best.download(quiet=False)
     3,734,976 Bytes [0.20%] received. Rate: [ 719 KB/s].  ETA: [3284 secs]
 
-Download video, use specific filepath:
+Download video, use specific directory and/or filename:
 
 .. code-block:: pycon
 
-    >>> myfilename = "/tmp/" + best.title + "." + best.extension
-    >>> best.download(filepath=myfilename)
+    >>> filename = best.download(filepath="/tmp/")
 
+    >>> filename = best.download(filepath="/tmp/Game." + best.extension)
 
 Get audio-only streams (m4a and/or ogg vorbis):
 
@@ -152,8 +152,11 @@ Get audio-only streams (m4a and/or ogg vorbis):
     >>> for a in audiostreams:
     ...     print(a.bitrate, a.extension, a.get_filesize())
     ...
-    128k m4a 165076649
+    256k m4a 331379079
+    192k ogg 172524223
+    128k m4a 166863001
     128k ogg 108981120
+    48k m4a 62700449
 
 
 Download the 2nd audio stream from the above list:
@@ -168,39 +171,44 @@ Get the best quality audio stream:
 
     >>> bestaudio = video.getbestaudio()
     >>> bestaudio.bitrate
-    '128k'
+    '256'
 
 Download the best quality audio file:
 
 .. code-block:: pycon
 
     >>> bestaudio.download()
 
-show ALL formats for a video (video+audio, video-only and audio-only):
+show all media types for a video (video+audio, video-only and audio-only):
 
 .. code-block:: pycon
 
     >>> allstreams = video.allstreams
     >>> for s in allstreams:
     ...     print(s.mediatype, s.extension, s.quality)
     ...
+
     normal mp4 1280x720
     normal webm 640x360
     normal mp4 640x360
     normal flv 320x240
     normal 3gp 320x240
     normal 3gp 176x144
     video m4v 1280x720
-    video webm 720x480
+    video webm 1280x720
     video m4v 854x480
-    video webm 640x480
+    video webm 854x480
     video m4v 640x360
-    video webm 480x360
+    video webm 640x360
     video m4v 426x240
-    video webm 360x240
+    video webm 426x240
     video m4v 256x144
+    video webm 256x144
+    audio m4a 256k
+    audio ogg 192k
     audio m4a 128k
     audio ogg 128k
+    audio m4a 48k
 
 
 Installation
@@ -288,14 +296,16 @@ list available dowload streams:
  
     Stream Type    Format Quality         Size            
     ------ ----    ------ -------         ----            
-    1      normal  webm   [640x360]       33 MB           
-    2      normal  mp4    [640x360]       24 MB           
-    3      normal  flv    [320x240]       13 MB           
-    4      normal  3gp    [320x240]       10 MB           
-    5      normal  3gp    [176x144]        3 MB           
-    6      audio   m4a    [48k]            2 MB           
-    7      audio   m4a    [128k]           5 MB           
-    8      audio   m4a    [256k]          10 MB     
+    1      normal  webm   [640x360]       33 MB
+    2      normal  mp4    [640x360]       23 MB
+    3      normal  flv    [320x240]       14 MB
+    4      normal  3gp    [320x240]        9 MB
+    5      normal  3gp    [176x144]        3 MB
+    6      audio   m4a    [48k]            2 MB
+    7      audio   m4a    [128k]           5 MB
+    8      audio   ogg    [128k]           5 MB
+    9      audio   ogg    [192k]           7 MB
+    10     audio   m4a    [256k]          10 MB
 
  
 Download mp4 640x360 (ie. stream number 2):
@@ -308,4 +318,4 @@ Download m4a audio stream at 256k bitrate:
 
 .. code-block:: bash
 
-    $ ytdl -n8 cyMHZVT91Dw
+    $ ytdl -n10 cyMHZVT91Dw

docs-sphinx/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+import sphinx_rtd_theme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -55,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.3.62'
+version = '0.3.64'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.62'
+release = '0.3.64'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -102,8 +103,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
-#html_theme = 'nature'
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# html_theme = 'default'
+# html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs-sphinx/index.rst

@@ -2,7 +2,7 @@ Pafy Documentation
 ******************
 .. module:: Pafy
 
-This is the documentation for Pafy - a Python library for retrieving content and metadata from YouTube
+This is the documentation for Pafy - a Python library to download YouTube content and retrieve metadata
 
 A quick start intro with usage examples is available in the `README <http://github.com/np1/pafy/blob/master/README.rst>`_
 
@@ -39,13 +39,13 @@ Create a Pafy object using the :func:`pafy.new` function, giving a YouTube video
     :type basic: bool
     :param gdata: fetch gdata info (upload date, description, category, username, likes, dislikes)
     :type gdata: bool
-    :param signature: fetch data required to decrypt urls, if encrypted
+    :param signature: Note: The signature argument now has no effect and will be removed in a future version
     :type signature: bool
     :param size: fetch the size of each stream (slow)(decrypts urls if needed) 
     :type size: bool
     :param callback: a callback function to receive status strings
     :type callback: function
-    :rtype: Pafy object
+    :rtype: :class:`pafy.Pafy`
 
 If any of **basic**, **gdata**, **signature** or **size** are *False*, those data items will be fetched only when first called for.
 
@@ -302,7 +302,7 @@ Stream Attributes
 
 .. attribute:: Stream.threed
 
-    Whether the stream is a 3D video (*boolean*)
+    True if the stream is a 3D video (*boolean*)
 
 .. attribute:: Stream.title
 
@@ -331,24 +331,30 @@ An example of accessing Stream attributes::
 Stream Methods
 --------------
 
+
+
+
 .. function:: Stream.get_filesize()     
 
     Returns the filesize of a stream
 
-.. function:: Stream.download([filepath=""][, quiet=False][, callback=None])
+.. function:: Stream.download([filepath=""][, quiet=False][, callback=None][, meta=False][, remux_audio=False])
 
-    Downloads the stream object
+    Downloads the stream object, returns the path of the downloaded file.
 
-    :param filepath: The filepath to use to save the stream, defaults to *title.extension* if ommitted
+    :param filepath: The filepath to use to save the stream, defaults to (sanitised) *title.extension* if ommitted
     :type filepath: string
-    :param quiet: Whether to supress output of the download progress
+    :param quiet: If True, supress output of the download progress
     :type quiet: boolean
     :param callback: Call back function to use for receiving download progress
     :type callback: function or None
+    :param meta: If True, video id and itag are appended to filename
+    :type meta: bool
+    :param remux_audio: If True, remux audio file downloads (fixes some compatibility issues with file format, requires ffmpeg/avconv)
+    :type remux_audio: bool
+    :rtype: str
 
-    If a callback function is provided, it will be called repeatedly for each
-    chunk downloaded.  It must be a function that takes five arguments. These
-    are:
+    If a callback function is provided, it will be called repeatedly for each chunk downloaded.  It must be a function that takes the following five arguments;
 
     - total bytes in stream, *int*
     - total bytes downloaded, *int*
@@ -366,10 +372,9 @@ Example of using stream.download()::
     v = pafy.new("cyMHZVT91Dw")
     s = v.getbest()
     print("Size is %s" % s.get_filesize())
-    s.download()
+    filename = s.download()  # starts download
 
-Will download the file to the current working directory with the filename
-*title.extension* (eg. "cute kittens.mp4") and output the following progress statistics::
+Will download to the current working directory and output the following progress statistics::
 
     Size is 34775366
     1,015,808 Bytes [2.92%] received. Rate: [ 640 kbps].  ETA: [51 secs]