Pytube Documentation: Release 9.0.7
Pytube Documentation: Release 9.0.7
Pytube Documentation: Release 9.0.7
Release 9.0.7
Nick Ficano
1 Features 3
2 Roadmap 5
i
ii
pytube Documentation, Release 9.0.7
Release v9.0.7. (Installation) pytube is a lightweight, Pythonic, dependency-free, library (and command-line utility)
for downloading YouTube Videos.
>>> YouTube('https://youtu.be/9bZkp7q19f0').streams.first().download()
>>> yt = YouTube('http://youtube.com/watch?v=9bZkp7q19f0')
>>> yt.streams
... .filter(progressive=True, file_extension='mp4')
... .order_by('resolution')
... .desc()
... .first()
... .download()
Contents 1
pytube Documentation, Release 9.0.7
2 Contents
CHAPTER 1
Features
3
pytube Documentation, Release 9.0.7
4 Chapter 1. Features
CHAPTER 2
Roadmap
5
pytube Documentation, Release 9.0.7
6 Chapter 2. Roadmap
CHAPTER 3
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.
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 .
7
pytube Documentation, Release 9.0.7
3.2 Quickstart
This guide will walk you through the basic usage of pytube.
Let’s get started with some examples.
Now, let’s try to download a video. For this example, let’s take something popular like PSY - Gangnam Style:
>>> yt = YouTube('https://www.youtube.com/watch?v=9bZkp7q19f0')
>>> yt.title
PSY - GANGNAM STYLE() M/V
And this would be how you would get the thumbnail url:
>>> yt.thumbnail_url
'https://i.ytimg.com/vi/mTOYClXhJD0/default.jpg'
>>> yt.streams.all()
[<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F"
˓→acodec="mp4a.40.2">,
>>> stream.download()
>>> stream.download('/tmp')
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.
>>> yt.streams.all()
[<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F"
˓→acodec="mp4a.40.2">,
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">,
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
˓→">,
Pytube allows you to filter on every property available (see pytube.StreamQuery.filter() for a complete
list of filter options), let’s take a look at some common examples:
>>> 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">]
>>> 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">,
>>> yt.streams.get_by_itag('22')
<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F"
˓→acodec="mp4a.40.2">
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">]
>>> caption.xml_captions
'<?xml version="1.0" encoding="utf-8" ?><transcript><text start="0" dur="5.541">well
˓→i&#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
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
...
If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
4.1 API
13
pytube Documentation, Release 9.0.7
• output_path (str or None) – (optional) Output path for writing media file. If one
is not specified, defaults to the current working directory.
• filename (str or None) – (optional) Output filename (stem only) for writing media
file. If one is not specified, the default filename is used.
Return type None
filesize
File size of the media stream in bytes.
Return type int
Returns Filesize (in bytes) of the stream.
includes_audio_track
Whether the stream only contains audio.
Return type bool
includes_video_track
Whether the stream only contains video.
Return type bool
is_adaptive
Whether the stream is DASH.
Return type bool
is_progressive
Whether the stream is progressive.
Return type bool
on_complete(file_handle)
On download complete handler function.
Parameters file_handle (io.BufferedWriter) – The file handle where the media is
being written to.
Return type None
on_progress(chunk, file_handler, bytes_remaining)
On progress callback function.
This function writes the binary data to the file, then checks if an additional callback is defined in the
monostate. This is exposed to allow things like displaying a progress bar.
Parameters
• chunk (str) – Segment of media file binary data, not yet written to disk.
• file_handler (io.BufferedWriter) – The file handle where the media is being
written to.
• bytes_remaining (int) – The delta between the total file size in bytes and amount
already downloaded.
Return type None
parse_codecs()
Get the video/audio codecs from list of codecs.
Parse a variable length sized list of codecs and returns a constant two element tuple, with the video codec
as the first element and audio as the second. Returns None if one is not available (adaptive only).
4.1. API 15
pytube Documentation, Release 9.0.7
class pytube.query.StreamQuery(fmt_streams)
Interface for querying the available media streams.
all()
Get all the results represented by this query as a list.
Return type list
asc()
Sort streams in ascending order.
Return type StreamQuery
count()
Get the count the query would return.
Return type int
desc()
Sort streams in descending order.
Return type StreamQuery
filter(fps=None, res=None, resolution=None, mime_type=None, type=None, subtype=None,
file_extension=None, abr=None, bitrate=None, video_codec=None, audio_codec=None,
only_audio=None, only_video=None, progressive=None, adaptive=None, cus-
tom_filter_functions=None)
Apply the given filtering criterion.
Parameters
• fps (int or None) – (optional) The frames per second.
• resolution (str or None) – (optional) Alias to res.
• res (str or None) – (optional) The video resolution.
• mime_type (str or None) – (optional) Two-part identifier for file formats and for-
mat contents composed of a “type”, a “subtype”.
• type (str or None) – (optional) Type part of the mime_type (e.g.: audio, video).
• subtype (str or None) – (optional) Sub-type part of the mime_type (e.g.: mp4,
mov).
• file_extension (str or None) – (optional) Alias to sub_type.
• abr (str or None) – (optional) Average bitrate (ABR) refers to the average amount
of data transferred per unit of time (e.g.: 64kbps, 192kbps).
• bitrate (str or None) – (optional) Alias to abr.
• video_codec (str or None) – (optional) Video compression format.
class pytube.Caption(caption_track)
Container for caption tracks.
float_to_srt_time_format(d)
Convert decimal durations into proper srt format.
Return type str
Returns SubRip Subtitle (str) formatted time duration.
>>> float_to_srt_time_format(3.89)
'00:00:03,890'
generate_srt_captions()
Generate “SubRip Subtitle” captions.
Takes the xml captions from xml_captions() and recompiles them into the “SubRip Subtitle” format.
4.1. API 17
pytube Documentation, Release 9.0.7
xml_caption_to_srt(xml_captions)
Convert xml caption tracks to “SubRip Subtitle (srt)”.
Parameters xml_captions (str) – XML formatted caption tracks.
xml_captions
Download the xml caption tracks.
class pytube.query.CaptionQuery(captions)
Interface for querying the available captions.
all()
Get all the results represented by this query as a list.
Return type list
get_by_language_code(lang_code)
Get the Caption for a given lang_code.
Parameters lang_code (str) – The code that identifies the caption language.
Return type Caption or None
Returns The Caption matching the given lang_code or None if it does not exist.
4.1.6 Extract
pytube.extract.video_id(url)
Extract the video_id from a YouTube url.
This function supports the following patterns:
• https://youtube.com/watch?v=video_id
• https://youtube.com/embed/video_id
• https://youtu.be/video_id
4.1. API 19
pytube Documentation, Release 9.0.7
4.1.7 Cipher
pytube.cipher.get_transform_plan(js)
Extract the “transform plan”.
The “transform plan” is the functions that the ciphered signature is cycled through to obtain the actual signature.
Parameters js (str) – The contents of the base.js asset file.
Example:
>>> get_transform_plan(js)
['DE.AJ(a,15)',
'DE.VR(a,3)',
'DE.AJ(a,51)',
'DE.VR(a,3)',
'DE.kT(a,51)',
'DE.kT(a,8)',
'DE.VR(a,3)',
'DE.kT(a,21)']
pytube.cipher.map_functions(js_func)
For a given JavaScript transform function, return the Python equivalent.
Parameters js_func (str) – The JavaScript version of the transform function.
pytube.cipher.parse_function(js_func)
Parse the Javascript transform function.
Break a JavaScript transform function down into a two element tuple containing the function name and some
integer-based argument.
Parameters js_func (str) – The JavaScript version of the transform function.
Return type tuple
Returns two element tuple containing the function name and an argument.
Example:
>>> parse_function('DE.AJ(a,15)')
('AJ', 15)
pytube.cipher.reverse(arr, b)
Reverse elements in a list.
This function is equivalent to:
function(a, b) { a.reverse() }
This method takes an unused b variable as their transform functions universally sent two arguments.
Example:
pytube.cipher.splice(arr, b)
Add/remove items to/from a list.
This function is equivalent to:
function(a, b) { a.splice(0, b) }
4.1. API 21
pytube Documentation, Release 9.0.7
Example:
pytube.cipher.swap(arr, b)
Swap positions at b modulus the list length.
This function is equivalent to:
Example:
4.1.8 Exceptions
4.1.9 Mixins
Parameters
• config_args (dict) – Details of the media streams available.
• fmt (str) – Key in stream manifests (ytplayer_config) containing progres-
sive download or adaptive streams (e.g.: url_encoded_fmt_stream_map or
adaptive_fmts).
• js (str) – The contents of the base.js asset file.
4.1.10 Compat
4.1.11 Helpers
4.1. API 23
pytube Documentation, Release 9.0.7
Parameters
• s (str) – A string to make safe for use as a file name.
• max_length (int) – The maximum filename character length.
Return type str
Returns A sanitized string.
4.1.12 Request
• genindex
• modindex
• search
25
pytube Documentation, Release 9.0.7
p
pytube, 13
pytube.cipher, 20
pytube.compat, 23
pytube.exceptions, 22
pytube.extract, 18
pytube.helpers, 23
pytube.mixins, 22
pytube.request, 24
27
pytube Documentation, Release 9.0.7
D J
default_filename (pytube.Stream attribute), 14 js_url() (in module pytube.extract), 18
desc() (pytube.query.StreamQuery method), 16
download() (pytube.Stream method), 14 L
last() (pytube.query.StreamQuery method), 17
E
ExtractError, 22 M
map_functions() (in module pytube.cipher), 21
F mime_type_codec() (in module pytube.extract), 19
filesize (pytube.Stream attribute), 15
filter() (pytube.query.StreamQuery method), 16 O
first() (pytube.query.StreamQuery method), 17 on_complete() (pytube.Stream method), 15
float_to_srt_time_format() (pytube.Caption method), 17 on_progress() (pytube.Stream method), 15
order_by() (pytube.query.StreamQuery method), 17
G
generate_srt_captions() (pytube.Caption method), 17 P
get() (in module pytube.request), 24 parse_codecs() (pytube.Stream method), 15
get_by_itag() (pytube.query.StreamQuery method), 17 parse_function() (in module pytube.cipher), 21
get_by_language_code() (pytube.query.CaptionQuery prefetch() (pytube.YouTube method), 14
method), 18 prefetch_init() (pytube.YouTube method), 14
get_initial_function_name() (in module pytube.cipher), pytube (module), 13
20 pytube.cipher (module), 20
get_signature() (in module pytube.cipher), 20 pytube.compat (module), 23
get_transform_map() (in module pytube.cipher), 20 pytube.exceptions (module), 22
get_transform_object() (in module pytube.cipher), 20 pytube.extract (module), 18
29
pytube Documentation, Release 9.0.7
pytube.helpers (module), 23
pytube.mixins (module), 22
pytube.request (module), 24
PytubeError, 22
R
regex_search() (in module pytube.helpers), 23
RegexMatchError, 22
register_on_complete_callback() (pytube.YouTube
method), 14
register_on_progress_callback() (pytube.YouTube
method), 14
reverse() (in module pytube.cipher), 21
S
safe_filename() (in module pytube.helpers), 23
set_attributes_from_dict() (pytube.Stream method), 16
splice() (in module pytube.cipher), 21
Stream (class in pytube), 14
stream_response() (in module pytube.request), 24
StreamQuery (class in pytube.query), 16
streams (pytube.YouTube attribute), 14
swap() (in module pytube.cipher), 22
T
thumbnail_url (pytube.YouTube attribute), 14
title (pytube.YouTube attribute), 14
U
unescape() (in module pytube.compat), 23
unicode() (in module pytube.compat), 23
V
video_id() (in module pytube.extract), 19
video_info_url() (in module pytube.extract), 19
W
watch_url() (in module pytube.extract), 19
X
xml_caption_to_srt() (pytube.Caption method), 17
xml_captions (pytube.Caption attribute), 18
Y
YouTube (class in pytube), 13
30 Index