Improvement/docs (#924)

* Moved most of the documentation out of the README and into the readthedocs.

* Created additional documentation in readthedocs.

* Moved bumpversion and twine from packages to dev-packages.

* Updated contributor solicitation to be more general

* Capitalization consistency in Features section

* Added prerequisite of python 3.6+ to documentation.

* Removed travis CI build widget since we're using github actions instead.

* Slight rearrangement of the README to improve flow.

* General cleaning of documentation.

Pipfile

@@ -4,10 +4,10 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-bumpversion = "*"
-twine = "*"
 
 [dev-packages]
+bumpversion = "*"
+twine = "*"
 black = "==19.10b0"
 codecov = "*"
 coveralls = "*"

README.md

@@ -4,23 +4,73 @@
   </p>
   <p align="center">
 	  <img src="https://img.shields.io/pypi/v/pytube.svg" alt="pypi">
-	  <a href="https://travis-ci.org/nficano/pytube"><img src="https://travis-ci.org/nficano/pytube.svg?branch=master" /></a>
-	  <a href="http://python-pytube.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/python-pytube/badge/?version=latest" /></a>
-	  <a href="https://codecov.io/gh/nficano/pytube"><img src="https://codecov.io/gh/nficano/pytube/branch/master/graph/badge.svg" /></a>
-      <a href="https://pypi.org/project/pytube/"><img src="https://img.shields.io/pypi/dm/pytube.svg" alt="pypi"></a>
-	  <a href="https://pypi.python.org/pypi/pytube/"><img src="https://img.shields.io/pypi/pyversions/pytube.svg" /></a>
-    <p>
+	  <a href="http://python-pytube.readthedocs.io/en/latest/?badge=latest">
+      <img src="https://readthedocs.org/projects/python-pytube/badge/?version=latest" />
+    </a>
+	  <a href="https://codecov.io/gh/nficano/pytube">
+      <img src="https://codecov.io/gh/nficano/pytube/branch/master/graph/badge.svg" />
+    </a>
+    <a href="https://pypi.org/project/pytube/">
+      <img src="https://img.shields.io/pypi/dm/pytube.svg" alt="pypi">
+    </a>
+	  <a href="https://pypi.python.org/pypi/pytube/">
+      <img src="https://img.shields.io/pypi/pyversions/pytube.svg" />
+    </a>
   </p>
 </div>
 
 
-###  24 July 2020 Actively soliciting contributers!
-Ping @ronncc if you would like to help out!
+### Actively soliciting contributers!
+Have ideas for how pytube can be improved? Feel free to open an issue or a pull
+request!
 
 # pytube
-*pytube* is a very serious, lightweight, dependency-free Python library (and command-line utility) for downloading YouTube Videos.
+*pytube* is a very serious, lightweight, dependency-free Python library (and
+command-line utility) for downloading YouTube Videos.
 
-## Installation
+
+## Documentation
+Detailed documentation about how to use the library can be found on our
+[readthedocs](https://python-pytube.readthedocs.io) page. This is recommended
+for most use cases. If you just want to quickly download a single video,
+the [quickstart](#Quickstart) guide below might be what you're looking for.
+
+
+## Description
+YouTube is the most popular video-sharing platform in the world and as a hacker
+you may encounter a situation where you want to script something to download
+videos. For this I present to you *pytube*.
+
+*pytube* is a lightweight library written in Python. It has no third party
+dependencies and aims to be highly reliable.
+
+*pytube* also makes pipelining easy, allowing you to specify callback functions
+for different download events, such as  ``on progress`` or ``on complete``.
+
+Finally *pytube* also includes a command-line utility, allowing you to quickly
+download videos right from terminal.
+
+
+## Features
+- Support for both progressive & DASH streams
+- Support for downloading complete playlist
+- Easily register ``on_download_progress`` & ``on_download_complete`` callbacks
+- Command-line interfaced included
+- Caption track support
+- Outputs caption tracks to .srt format (SubRip Subtitle)
+- Ability to capture thumbnail URL
+- Extensively documented source code
+- No third-party dependencies
+
+## Quickstart
+This guide is only meant to cover the most basic usage of the library. For more
+detailed information, please refer to our
+[readthedocs](https://python-pytube.readthedocs.io) page.
+
+### Installation
+Pytube requires an installation of python 3.6 or greater, as well as pip.
+Pip is typically bundled with python installations, and you can find options
+for how to install python at https://python.org.
 
 To install from pypi with pip:
 
@@ -28,24 +78,20 @@ To install from pypi with pip:
 $ python -m pip install pytube
 ```
 
-Sometime, the pypi release becomes slightly outdated. To install from the source with pip:
+Sometime, the pypi release becomes slightly outdated. To install from the
+source with pip:
 
 ```bash
 $ python -m pip install git+https://github.com/pytube/pytube
 ```
 
-## Description
-YouTube is the most popular video-sharing platform in the world and as a hacker you may encounter a situation where you want to script something to download videos.  For this I present to you *pytube*.
-
-*pytube* is a lightweight library written in Python. It has no third party dependencies and aims to be highly reliable.
-
-*pytube* also makes pipelining easy, allowing you to specify callback functions for different download events, such as  ``on progress`` or ``on complete``.
-
-Finally *pytube* also includes a command-line utility, allowing you to quickly download videos right from terminal.
-
-### Behold, a perfect balance of simplicity versus flexibility:
+### Using pytube in a python script
+To download a video using the library in a script, you'll need to first import
+the YouTube class from the library, and pass it an argument of the video url.
+From there, you can access the streams and download them.
 
 ```python
+ >>> from pytube import YouTube
  >>> YouTube('https://youtu.be/2lAe1cqCOXo').streams.first().download()
  >>> yt = YouTube('http://youtube.com/watch?v=2lAe1cqCOXo')
  >>> yt.streams
@@ -56,231 +102,14 @@ Finally *pytube* also includes a command-line utility, allowing you to quickly d
   ... .download()
 ```
 
-## Features
-- Support for Both Progressive & DASH Streams
-- Support for downloading complete playlist
-- Easily Register ``on_download_progress`` & ``on_download_complete`` callbacks
-- Command-line Interfaced Included
-- Caption Track Support
-- Outputs Caption Tracks to .srt format (SubRip Subtitle)
-- Ability to Capture Thumbnail URL.
-- Extensively Documented Source Code
-- No Third-Party Dependencies
-
-## Getting started
-
-Let's begin with showing how easy it is to download a video with pytube:
-
-```python
->>> from pytube import YouTube
->>> YouTube('https://youtube.com/watch?v=2lAe1cqCOXo').streams.first().download()
-```
-This example will download the highest quality progressive download stream available.
-
-Next, let's explore how we would view what video streams are available:
-
-```python
->>> yt = YouTube('https://youtube.com/watch?v=2lAe1cqCOXo')
->>> yt.streams
- [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
- <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">,
- <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
- <Stream: itag="248" mime_type="video/webm" res="1080p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="399" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.08M.08" progressive="False" type="video">,
- <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f" progressive="False" type="video">,
- <Stream: itag="247" mime_type="video/webm" res="720p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="398" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.05M.08" progressive="False" type="video">,
- <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="244" mime_type="video/webm" res="480p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="397" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.04M.08" progressive="False" type="video">,
- <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="243" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="396" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.01M.08" progressive="False" type="video">,
- <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015" progressive="False" type="video">,
- <Stream: itag="242" mime_type="video/webm" res="240p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="395" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c" progressive="False" type="video">,
- <Stream: itag="278" mime_type="video/webm" res="144p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="394" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">,
- <Stream: itag="249" mime_type="audio/webm" abr="50kbps" acodec="opus" progressive="False" type="audio">,
- <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
- <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
-```
-You may notice that some streams listed have both a video codec and audio codec, while others have just video or just audio, this is a result of YouTube supporting a streaming technique called Dynamic Adaptive Streaming over HTTP (DASH).
-
-In the context of pytube, the implications are for the highest quality streams; you now need to download both the audio and video tracks and then post-process them with software like FFmpeg to merge them.
-
-The legacy streams that contain the audio and video in a single file (referred to as "progressive download") are still available, but only for resolutions 720p and below.
-
-To only view these progressive download streams:
-
-```python
- >>> yt.streams.filter(progressive=True)
-  [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
-  <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">]
-```
-
-Conversely, if you only want to see the DASH streams (also referred to as "adaptive") you can do:
-
-```python
->>> yt.streams.filter(adaptive=True)
- [<Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
- <Stream: itag="248" mime_type="video/webm" res="1080p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="399" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.08M.08" progressive="False" type="video">,
- <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f" progressive="False" type="video">,
- <Stream: itag="247" mime_type="video/webm" res="720p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="398" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.05M.08" progressive="False" type="video">,
- <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="244" mime_type="video/webm" res="480p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="397" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.04M.08" progressive="False" type="video">,
- <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="243" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="396" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.01M.08" progressive="False" type="video">,
- <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015" progressive="False" type="video">,
- <Stream: itag="242" mime_type="video/webm" res="240p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="395" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c" progressive="False" type="video">,
- <Stream: itag="278" mime_type="video/webm" res="144p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
- <Stream: itag="394" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">,
- <Stream: itag="249" mime_type="audio/webm" abr="50kbps" acodec="opus" progressive="False" type="audio">,
- <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
- <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
-```
-
-You can also interact with Youtube playlists:
-
-```python
->>> from pytube import Playlist
->>> pl = Playlist("https://www.youtube.com/watch?v=Edpy1szoG80&list=PL153hDY-y1E00uQtCVCVC8xJ25TYX8yPU")
->>> for video in pl.videos:
->>>     video.streams.first().download()
-```
-
-Pytube allows you to filter on every property available (see the documentation for the complete list), let's take a look at some of the most useful ones.
-
-To list the audio only streams:
-
-```python
->>> yt.streams.filter(only_audio=True)
-  [<Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">,
-  <Stream: itag="249" mime_type="audio/webm" abr="50kbps" acodec="opus" progressive="False" type="audio">,
-  <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
-  <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
-```
-
-To list only ``mp4`` streams:
-
-```python
->>> yt.streams.filter(subtype='mp4').all()
- [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
- <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">,
- <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
- <Stream: itag="399" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.08M.08" progressive="False" type="video">,
- <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f" progressive="False" type="video">,
- <Stream: itag="398" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.05M.08" progressive="False" type="video">,
- <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="397" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.04M.08" progressive="False" type="video">,
- <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e" progressive="False" type="video">,
- <Stream: itag="396" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.01M.08" progressive="False" type="video">,
- <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015" progressive="False" type="video">,
- <Stream: itag="395" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c" progressive="False" type="video">,
- <Stream: itag="394" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
- <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">]
-```
-
-Multiple filters can also be specified:
-
-```python
->>> yt.streams.filter(subtype='mp4', progressive=True).all()
->>> # this can also be expressed as:
->>> yt.streams.filter(subtype='mp4').filter(progressive=True).all()
-  [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
-  <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">]
-```
-You also have an interface to select streams by their itag, without needing to filter:
-
-```python
->>> yt.streams.get_by_itag(22)
-  <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">
-```
-
-If you need to optimize for a specific feature, such as the "highest resolution" or "lowest average bitrate":
-
-```python
->>> yt.streams.filter(progressive=True).order_by('resolution').desc().all()
-  [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">,
-  <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">]
-```
-Note that ``order_by`` cannot be used if your attribute is undefined in any of the Stream instances, so be sure to apply a filter to remove those before calling it.
-
-If your application requires post-processing logic, pytube allows you to specify an "on download complete" callback function:
-
-```python
- >>> def convert_to_aac(stream, file_handle):
-         return  # do work
-
- >>> yt.register_on_complete_callback(convert_to_aac)
-```
-
-Similarly, if your application requires on-download progress logic, pytube exposes a callback for this as well:
-
-```python
- >>> def show_progress_bar(stream, chunk, bytes_remaining):
-         return  # do work
-
- >>> yt.register_on_progress_callback(show_progress_bar)
-```
-
-You can also download videos to a specific directory with specific filename:
-
-```python
->>> yt = YouTube('https://youtube.com/watch?v=2lAe1cqCOXo')
->>> yt.streams.first().download(output_path="/tmp" ,filename='output')
-```
-
-## Command-line interface (CLI)
-
-Pytube also ships with a tiny CLI for interacting with videos and playlists.
-
-To download the highest resolution progressive stream:
-
-```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo
-```
-
-To view available streams:
-
-```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list
-```
-
-To download a specific stream, use the itag
-
-```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --itag=22
-```
-
-To get a list of all subtitles (caption codes) 
-
-```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list-captions
-```
-
-To download a specific subtitle (caption code) - in this case the
-english subtitles (in srt format) - use:
-
+### Using the command-line interface
+Using the CLI is extremely straightforward as well. To download a video at the
+highest progressive quality, you can use the following command:
 ```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -c en
+$ pytube https://youtube.com/watch?v=2lAe1cqCOXo
 ```
 
-It is also possible to just download the audio stream (default AAC/mp4):
-
+You can also do the same for a playlist:
 ```bash
-$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -a
+$ pytube https://www.youtube.com/playlist?list=PLS1QulWo1RIaJECMeUT4LFwJ-ghgoSH6n
 ```
-
-
-Finally, if you're filing a bug report, the cli contains a switch called ``--build-playback-report``, which bundles up the state, allowing others to easily replay your issue.

docs/index.rst

@@ -20,7 +20,8 @@ Release v\ |version|. (:ref:`Installation<install>`)
   :alt: Python Versions
   :target: https://pypi.python.org/pypi/pytube/
 
-**pytube** is a lightweight, Pythonic, dependency-free, library (and command-line utility) for downloading YouTube Videos.
+**pytube** is a lightweight, Pythonic, dependency-free, library (and
+command-line utility) for downloading YouTube Videos.
 
 -------------------
 
@@ -48,28 +49,28 @@ Features
 - Extensively Documented Source Code
 - No Third-Party Dependencies
 
-Roadmap
--------
-
-- Allow downloading age restricted content
-- Complete ffmpeg integration
-
 The User Guide
 --------------
-This part of the documentation begins with some background information about the project, then focuses on step-by-step instructions for getting the most out of pytube.
+This part of the documentation begins with some background information about
+the project, then focuses on step-by-step instructions for getting the most out
+of pytube.
 
 .. toctree::
    :maxdepth: 2
 
    user/install
    user/quickstart
+   user/streams
+   user/captions
    user/playlist
    user/cli
+   user/exceptions
 
-The API Documentation / Guide
+The API Documentation
 -----------------------------
 
-If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
+If you are looking for information on a specific function, class, or method,
+this part of the documentation is for you.
 
 .. toctree::
    :maxdepth: 2

docs/user/captions.rst

@@ -0,0 +1,32 @@
+.. _captions:
+
+Subtitle/Caption Tracks
+=======================
+
+Pytube exposes the caption tracks in much the same way as querying the media
+streams. Let's begin by switching to a video that contains them::
+
+    >>> yt = YouTube('http://youtube.com/watch?v=2lAe1cqCOXo')
+    >>> yt.captions
+    {'ar': <Caption lang="Arabic" code="ar">, 'zh-HK': <Caption lang="Chinese (Hong Kong)" code="zh-HK">, 'zh-TW': <Caption lang="Chinese (Taiwan)" code="zh-TW">, 'hr': <Caption lang="Croatian" code="hr">, 'cs': <Caption lang="Czech" code="cs">, 'da': <Caption lang="Danish" code="da">, 'nl': <Caption lang="Dutch" code="nl">, 'en': <Caption lang="English" code="en">, 'en-GB': <Caption lang="English (United Kingdom)" code="en-GB">, 'et': <Caption lang="Estonian" code="et">, 'fil': <Caption lang="Filipino" code="fil">, 'fi': <Caption lang="Finnish" code="fi">, 'fr-CA': <Caption lang="French (Canada)" code="fr-CA">, 'fr-FR': <Caption lang="French (France)" code="fr-FR">, 'de': <Caption lang="German" code="de">, 'el': <Caption lang="Greek" code="el">, 'iw': <Caption lang="Hebrew" code="iw">, 'hu': <Caption lang="Hungarian" code="hu">, 'id': <Caption lang="Indonesian" code="id">, 'it': <Caption lang="Italian" code="it">, 'ja': <Caption lang="Japanese" code="ja">, 'ko': <Caption lang="Korean" code="ko">, 'lv': <Caption lang="Latvian" code="lv">, 'lt': <Caption lang="Lithuanian" code="lt">, 'ms': <Caption lang="Malay" code="ms">, 'no': <Caption lang="Norwegian" code="no">, 'pl': <Caption lang="Polish" code="pl">, 'pt-BR': <Caption lang="Portuguese (Brazil)" code="pt-BR">, 'pt-PT': <Caption lang="Portuguese (Portugal)" code="pt-PT">, 'ro': <Caption lang="Romanian" code="ro">, 'ru': <Caption lang="Russian" code="ru">, 'sk': <Caption lang="Slovak" code="sk">, 'es-419': <Caption lang="Spanish (Latin America)" code="es-419">, 'es-ES': <Caption lang="Spanish (Spain)" code="es-ES">, 'sv': <Caption lang="Swedish" code="sv">, 'th': <Caption lang="Thai" code="th">, 'tr': <Caption lang="Turkish" code="tr">, 'uk': <Caption lang="Ukrainian" code="uk">, 'ur': <Caption lang="Urdu" code="ur">, 'vi': <Caption lang="Vietnamese" code="vi">}
+
+Now let's checkout the english captions::
+
+    >>> caption = yt.captions.get_by_language_code('en')
+
+Great, now let's see how YouTube formats them::
+
+    >>> caption.xml_captions
+    '<?xml version="1.0" encoding="utf-8" ?><transcript><text start="10.2" dur="0.94">K-pop!</text>...'
+
+Oh, this isn't very easy to work with, let's convert them to the srt format::
+
+    >>> print(caption.generate_srt_captions())
+    1
+    00:00:10,200 --> 00:00:11,140
+    K-pop!
+
+    2
+    00:00:13,400 --> 00:00:16,200
+    That is so awkward to watch.
+    ...

docs/user/cli.rst

@@ -30,7 +30,7 @@ To get a list of all subtitles (caption codes)
     $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list-captions
 
 To download a specific subtitle (caption code) - in this case the
-english subtitles (in srt format) - use:
+English subtitles (in srt format) - use:
 
 .. code:: bash
 

docs/user/exceptions.rst

@@ -0,0 +1,29 @@
+.. _exceptions:
+
+Exception handling
+==================
+
+Pytube implements a number of useful exceptions for handling program flow.
+There are a number of cases where pytube simply cannot access videos on YouTube
+and relies on the user to handle these exceptions. Generally speaking, if a
+video is unaccessible for any reason, this can be caught with the generic
+VideoUnavailable exception. This could be used, for example, to skip private
+videos in a playlist, videos that are region-restricted, and more.
+
+Let's see what your code might look like if you need to do exception handling::
+
+    >>> from pytube import Playlist, YouTube
+    >>> playlist_url = 'https://youtube.com/playlist?list=special_playlist_id'
+    >>> p = Playlist(playlist_url)
+    >>> for url in p.video_urls:
+    ...     try:
+    ...         yt = YouTube(url)
+    ...     except VideoUnavailable:
+    ...         print(f'Video {url} is unavaialable, skipping.')
+    ...     else:
+    ...         print(f'Downloading video: {url}')
+    ...         yt.streams.first().download()
+
+This will automatically skip over videos that could not be downloaded due to a
+limitation with the pytube library. You can find more details about what
+specific exceptions can be handled here: :py:mod:`pytube.exceptions`.

docs/user/install.rst

@@ -3,7 +3,7 @@
 Installation of pytube
 ======================
 
-This part of the documentation covers the installation of pytube.
+This guide assumes you already have python and pip installed.
 
 To install pytube, run the following command in your terminal::
 
@@ -12,18 +12,18 @@ To install pytube, run the following command in your terminal::
 Get the Source Code
 -------------------
 
-pytube is actively developed on GitHub, where the source is `available <https://github.com/nficano/pytube>`_.
+pytube is actively developed on GitHub, where the source is `available <https://github.com/pytube/pytube>`_.
 
 You can either clone the public repository::
 
-    $ git clone git://github.com/nficano/pytube.git
+    $ git clone git://github.com/pytube/pytube.git
 
-Or, download the `tarball <https://github.com/nficano/pytube/tarball/master>`_::
+Or, download the `tarball <https://github.com/pytube/pytube/tarball/master>`_::
 
-    $ curl -OL https://github.com/nficano/pytube/tarball/master
+    $ curl -OL https://github.com/pytube/pytube/tarball/master
     # optionally, zipball is also available (for Windows users).
 
 Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages by running::
 
     $ cd pytube
-    $ pip install .
+    $ python -m pip install .

docs/user/quickstart.rst

@@ -17,9 +17,9 @@ Begin by importing the YouTube class::
     >>> from pytube import YouTube
 
 Now, let's try to download a video. For this example, let's take something
-popular like PSY - Gangnam Style::
+like the YouTube Rewind video for 2019::
 
-    >>> yt = YouTube('https://www.youtube.com/watch?v=9bZkp7q19f0')
+    >>> yt = YouTube('http://youtube.com/watch?v=2lAe1cqCOXo')
 
 Now, we have a :class:`YouTube <pytube.YouTube>` object called ``yt``.
 
@@ -27,182 +27,35 @@ The pytube API makes all information intuitive to access. For example, this is
 how you would get the video's title::
 
     >>> yt.title
-    PSY - GANGNAM STYLE(강남스타일) M/V
+    YouTube Rewind 2019: For the Record | #YouTubeRewind
 
 And this would be how you would get the thumbnail url::
 
     >>> yt.thumbnail_url
-    'https://i.ytimg.com/vi/mTOYClXhJD0/default.jpg'
-
-Neat, right? Next let's see the available media formats::
-
-    >>> yt.streams.all()
-    [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
-    <Stream: itag="43" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp8.0" acodec="vorbis">,
-    <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
-    <Stream: itag="36" mime_type="video/3gpp" res="240p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">,
-    <Stream: itag="17" mime_type="video/3gpp" res="144p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">,
-    <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
-    <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e">,
-    <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015">,
-    <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c">,
-    <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">,
-    <Stream: itag="171" mime_type="audio/webm" abr="128kbps" acodec="vorbis">]
+    'https://i.ytimg.com/vi/2lAe1cqCOXo/maxresdefault.jpg'
 
-Let's say we want to get the first stream::
-
-    >>> stream = yt.streams.first()
-    >>> stream
-    <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">
-
-And to download it to the current working directory::
-
-    >>> stream.download()
-
-You can also specify a destination path::
-
-    >>> stream.download('/tmp')
-
-
-Working with Streams
-====================
-
-The next section will explore the various options available for working with media
-streams, but before we can dive in, we need to review a new-ish streaming technique
-adopted by YouTube.
-
-DASH vs Progressive Streams
----------------------------
-
-Begin by running the following::
-
-    >>> yt.streams.all()
-    [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
-    <Stream: itag="43" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp8.0" acodec="vorbis">,
-    <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
-    <Stream: itag="36" mime_type="video/3gpp" res="240p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">,
-    <Stream: itag="17" mime_type="video/3gpp" res="144p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">,
-    <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
-    <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e">,
-    <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015">,
-    <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c">,
-    <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">,
-    <Stream: itag="171" mime_type="audio/webm" abr="128kbps" acodec="vorbis">]
-
-
-You may notice that some streams listed have both a video codec and audio
-codec, while others have just video or just audio, this is a result of YouTube
-supporting a streaming technique called Dynamic Adaptive Streaming over HTTP
-(DASH).
-
-In the context of pytube, the implications are for the highest quality streams;
-you now need to download both the audio and video tracks and then post-process
-them with software like FFmpeg to merge them.
-
-The legacy streams that contain the audio and video in a single file (referred
-to as "progressive download") are still available, but only for resolutions
-720p and below.
-
-To only view these progressive download streams::
-
-    >>> yt.streams.filter(progressive=True).all()
-    [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
-    <Stream: itag="43" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp8.0" acodec="vorbis">,
-    <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
-    <Stream: itag="36" mime_type="video/3gpp" res="240p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">,
-    <Stream: itag="17" mime_type="video/3gpp" res="144p" fps="30fps" vcodec="mp4v.20.3" acodec="mp4a.40.2">]
-
-Conversely, if you only want to see the DASH streams (also referred to as
-"adaptive") you can do::
-
-    >>> yt.streams.filter(adaptive=True).all()
-    [<Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
-    <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e">,
-    <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015">,
-    <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c">,
-    <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">,
-    <Stream: itag="171" mime_type="audio/webm" abr="128kbps" acodec="vorbis">]
-
-Pytube allows you to filter on every property available (see
-:py:meth:`pytube.StreamQuery.filter` for a complete list of filter options),
-let's take a look at some common examples:
-
-Query audio only Streams
-------------------------
-
-To query the streams that contain only the audio track::
-
-    >>> yt.streams.filter(only_audio=True).all()
-    [<Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">,
-    <Stream: itag="171" mime_type="audio/webm" abr="128kbps" acodec="vorbis">]
-
-Query MPEG-4 Streams
---------------------
+Neat, right? For advanced use cases, you can provide some additional arguments
+when you create a YouTube object::
 
-To query only streams in the MPEG-4 format::
+    >>> yt = YouTube(
+            'http://youtube.com/watch?v=2lAe1cqCOXo',
+            on_progress_callback=progress_func,
+            on_complete_callback=complete_func,
+            proxies=my_proxies
+        )
 
-    >>> yt.streams.filter(file_extension='mp4').all()
-    [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
-    <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
-    <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
-    <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="135" mime_type="video/mp4" res="480p" fps="30fps" vcodec="avc1.4d401f">,
-    <Stream: itag="134" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.4d401e">,
-    <Stream: itag="133" mime_type="video/mp4" res="240p" fps="30fps" vcodec="avc1.4d4015">,
-    <Stream: itag="160" mime_type="video/mp4" res="144p" fps="30fps" vcodec="avc1.4d400c">,
-    <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">]
+When instantiating a YouTube object, these named arguments can be passed in to
+improve functionality. 
 
-Get Streams by itag
--------------------
-
-To get a stream by a specific itag::
-
-    >>> yt.streams.get_by_itag('22')
-    <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">
-
-Subtitle/Caption Tracks
-=======================
-
-Pytube exposes the caption tracks in much the same way as querying the media
-streams. Let's begin by switching to a video that contains them::
-
-    >>> yt = YouTube('https://youtube.com/watch?v=XJGiS83eQLk')
-    >>> yt.captions.all()
-    [<Caption lang="Arabic" code="ar">,
-    <Caption lang="English (auto-generated)" code="en">,
-    <Caption lang="English" code="en">,
-    <Caption lang="English (United Kingdom)" code="en-GB">,
-    <Caption lang="German" code="de">,
-    <Caption lang="Greek" code="el">,
-    <Caption lang="Indonesian" code="id">,
-    <Caption lang="Sinhala" code="si">,
-    <Caption lang="Spanish" code="es">,
-    <Caption lang="Turkish" code="tr">]
-
-Now let's checkout the english captions::
-
-    >>> caption = yt.captions.get_by_language_code('en')
-
-Great, now let's see how YouTube formats them::
-
-    >>> caption.xml_captions
-    '<?xml version="1.0" encoding="utf-8" ?><transcript><text start="0" dur="5.541">well i&amp;#39...'
-
-Oh, this isn't very easy to work with, let's convert them to the srt format::
-
-    >>> print(caption.generate_srt_captions())
-    1
-    000:000:00,000 --> 000:000:05,541
-    well i'm just an editor and i dont know what to type
+The on_progress_callback function will run whenever a chunk is downloaded from
+a video, and is called with three arguments: the stream, the data chunk, and
+the bytes remaining in the video. This could be used, for example, to display a
+progress bar.
 
-    2
-    000:000:05,541 --> 000:000:12,321
-    not new to video. In fact, most films before 1930 were silent and used captions with video
+The on_complete_callback function will run after a video has been fully
+downloaded, and is called with two arguments: the stream and the file path.
+This could be used, for example, to perform post-download processing on a video
+like trimming the length of it.
 
-    ...
+Once you have a YouTube object set up, you're ready to start looking at
+different media streams for the video, which is discussed in the next section.

docs/user/streams.rst

@@ -0,0 +1,95 @@
+.. _streams:
+
+Working with Streams and StreamQuery
+====================================
+
+The next section will explore the various options available for working with
+media streams, but before we can dive in, we need to review a new-ish streaming
+technique adopted by YouTube. It assumes that you have already created a
+YouTube object in your code called "yt".
+
+DASH vs Progressive Streams
+---------------------------
+
+Begin by running the following to list all streams::
+
+    >>> yt.streams
+    [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
+    <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">,
+    <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
+    ...
+    <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
+    <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
+
+
+You may notice that some streams listed have both a video codec and audio
+codec, while others have just video or just audio, this is a result of YouTube
+supporting a streaming technique called Dynamic Adaptive Streaming over HTTP
+(DASH).
+
+In the context of pytube, the implications are for the highest quality streams;
+you now need to download both the audio and video tracks and then post-process
+them with software like FFmpeg to merge them.
+
+The legacy streams that contain the audio and video in a single file (referred
+to as "progressive download") are still available, but only for resolutions
+720p and below.
+
+Filtering Streams
+=================
+
+Pytube has built-in functionality to filter the streams available in a YouTube
+object with the .filter() method. You can pass it a number of different keyword
+arguments, so let's review some of the different options you're most likely to
+use. For a complete list of available properties to filter on, you can view the
+API documentation here: :py:meth:`pytube.StreamQuery.filter`.
+
+Filtering by streaming method
+-----------------------------
+
+As mentioned before, progressive streams have the video and audio in a single
+file, but typically do not provide the highest quality media; meanwhile,
+adaptive streams split the video and audio tracks but can provide much higher
+quality. Pytube makes it easy to filter based on the type of stream that you're
+interested.
+
+For example, you can filter to only progressive streams with the following::
+
+    >>> yt.streams.filter(progressive=True)
+    [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
+    <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">]
+
+Conversely, if you only want to see the DASH streams (also referred to as
+"adaptive") you can do::
+
+    >>> yt.streams.filter(adaptive=True)
+    [<Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
+    <Stream: itag="248" mime_type="video/webm" res="1080p" fps="30fps" vcodec="vp9" progressive="False" type="video">,
+    <Stream: itag="399" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.08M.08" progressive="False" type="video">,
+    ...
+    <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
+    <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
+
+Filtering for audio-only streams
+--------------------------------
+
+To query the streams that contain only the audio track::
+
+    >>> yt.streams.filter(only_audio=True)
+    [<Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">,
+    <Stream: itag="249" mime_type="audio/webm" abr="50kbps" acodec="opus" progressive="False" type="audio">,
+    <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus" progressive="False" type="audio">,
+    <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus" progressive="False" type="audio">]
+
+Filtering for MP4 streams
+-------------------------
+
+To query only streams in the MP4 format::
+
+    >>> yt.streams.filter(file_extension='mp4')
+    [<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">,
+    <Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">,
+    <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">,
+    ...
+    <Stream: itag="394" mime_type="video/mp4" res="None" fps="30fps" vcodec="av01.0.00M.08" progressive="False" type="video">,
+    <Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2" progressive="False" type="audio">]