1.. image:: https://img.shields.io/pypi/v/Pafy.svg
2 :target: https://pypi.python.org/pypi/pafy
3.. image:: https://img.shields.io/pypi/dm/Pafy.svg
4 :target: https://pypi.python.org/pypi/pafy
5.. image:: https://img.shields.io/coveralls/np1/pafy/develop.svg
6 :target: https://coveralls.io/r/np1/pafy?branch=develop
7.. image:: https://landscape.io/github/mps-youtube/pafy/develop/landscape.svg
8 :target: https://landscape.io/github/mps-youtube/pafy/develop
9 :alt: Code Health
10.. image:: https://travis-ci.org/mps-youtube/pafy.svg?branch=develop
11 :target: https://travis-ci.org/mps-youtube/pafy
12.. image:: https://img.shields.io/pypi/wheel/Pafy.svg
13 :target: http://pythonwheels.com/
14 :alt: Wheel Status
15
16Features
17--------
18
19- Retreive metadata such as viewcount, duration, rating, author, thumbnail, keywords
20- Download video or audio at requested resolution / bitrate / format / filesize
21- Command line tool (ytdl) for downloading directly from the command line
22- Retrieve the URL to stream the video in a player such as vlc or mplayer
23- Works with age-restricted videos and non-embeddable videos
24- Small, standalone, single importable module file (pafy.py)
25- Select highest quality stream for download or streaming
26- Download video only (no audio) in m4v or webm format
27- Download audio only (no video) in ogg or m4a format
28- Retreive playlists and playlist metadata
29- Works with Python 2.6+ and 3.3+
30- Optionally depends on youtube-dl (recommended; more stable)
31
32
33Documentation
34-------------
35
36Full documentation is available at http://pythonhosted.org/pafy
37
38Usage Examples
39--------------
40
41Here is how to use the module in your own python code. For command line tool
42(ytdl) instructions, see further below
43
44.. code-block:: pycon
45
46 >>> import pafy
47
48create a video instance from a YouTube url:
49
50.. code-block:: pycon
51
52 >>> url = "https://www.youtube.com/watch?v=bMt47wvK6u0"
53 >>> video = pafy.new(url)
54
55get certain attributes:
56
57.. code-block:: pycon
58
59 >>> video.title
60 'Richard Jones: Introduction to game programming - PyCon 2014'
61
62 >>> video.rating
63 5.0
64
65 >>> video.viewcount, video.author, video.length
66 (1916, 'PyCon 2014', 10394)
67
68 >>> video.duration, video.likes, video.dislikes
69 ('02:53:14', 25, 0)
70
71 >>> print(video.description)
72 Speaker: Richard Jones
73
74 This tutorial will walk the attendees through development of a simple game using PyGame with time left over for some experimentation and exploration of different types of games.
75
76 Slides can be found at: https://speakerdeck.com/pycon2014 and https://github.com/PyCon/2014-slides
77
78
79list available streams for a video:
80
81.. code-block:: pycon
82
83 >>> streams = video.streams
84 >>> for s in streams:
85 ... print(s)
86 ...
87 normal:mp4@1280x720
88 normal:webm@640x360
89 normal:mp4@640x360
90 normal:flv@320x240
91 normal:3gp@320x240
92 normal:3gp@176x144
93
94
95show all formats, file-sizes and their download url:
96
97.. code-block:: pycon
98
99 >>> for s in streams:
100 ... print(s.resolution, s.extension, s.get_filesize(), s.url)
101 ...
102 1280x720 mp4 2421958510 https://r1---sn-aiglln7e.googlevideo.com/videoplayba[...]
103 640x360 webm 547015732 https://r1---sn-aiglln7e.googlevideo.com/videoplaybac[...]
104 640x360 mp4 470655850 https://r1---sn-aiglln7e.googlevideo.com/videoplayback[...]
105 320x240 flv 345455674 https://r1---sn-aiglln7e.googlevideo.com/videoplayback[...]
106 320x240 3gp 208603447 https://r1---sn-aiglln7e.googlevideo.com/videoplayback[...]
107 176x144 3gp 60905732 https://r1---sn-aiglln7e.googlevideo.com/videoplayback?[...]
108
109
110get best resolution regardless of file format:
111
112.. code-block:: pycon
113
114 >>> best = video.getbest()
115 >>> best.resolution, best.extension
116 ('1280x720', 'mp4')
117
118
119get best resolution for a particular file format:
120(mp4, webm, flv or 3gp)
121
122.. code-block:: pycon
123
124 >>> best = video.getbest(preftype="webm")
125 >>> best.resolution, best.extension
126 ('640x360', 'webm')
127
128get url, for download or streaming in mplayer / vlc etc:
129
130.. code-block:: pycon
131
132 >>> best.url
133 'http://r12---sn-aig7kner.c.youtube.com/videoplayback?expire=1369...
134
135Download video and show progress:
136
137.. code-block:: pycon
138
139 >>> best.download(quiet=False)
140 3,734,976 Bytes [0.20%] received. Rate: [ 719 KB/s]. ETA: [3284 secs]
141
142Download video, use specific directory and/or filename:
143
144.. code-block:: pycon
145
146 >>> filename = best.download(filepath="/tmp/")
147
148 >>> filename = best.download(filepath="/tmp/Game." + best.extension)
149
150Get audio-only streams (m4a and/or ogg vorbis):
151
152.. code-block:: pycon
153
154 >>> audiostreams = video.audiostreams
155 >>> for a in audiostreams:
156 ... print(a.bitrate, a.extension, a.get_filesize())
157 ...
158 256k m4a 331379079
159 192k ogg 172524223
160 128k m4a 166863001
161 128k ogg 108981120
162 48k m4a 62700449
163
164
165Download the 2nd audio stream from the above list:
166
167.. code-block:: pycon
168
169 >>> audiostreams[1].download()
170
171Get the best quality audio stream:
172
173.. code-block:: pycon
174
175 >>> bestaudio = video.getbestaudio()
176 >>> bestaudio.bitrate
177 '256'
178
179Download the best quality audio file:
180
181.. code-block:: pycon
182
183 >>> bestaudio.download()
184
185show all media types for a video (video+audio, video-only and audio-only):
186
187.. code-block:: pycon
188
189 >>> allstreams = video.allstreams
190 >>> for s in allstreams:
191 ... print(s.mediatype, s.extension, s.quality)
192 ...
193
194 normal mp4 1280x720
195 normal webm 640x360
196 normal mp4 640x360
197 normal flv 320x240
198 normal 3gp 320x240
199 normal 3gp 176x144
200 video m4v 1280x720
201 video webm 1280x720
202 video m4v 854x480
203 video webm 854x480
204 video m4v 640x360
205 video webm 640x360
206 video m4v 426x240
207 video webm 426x240
208 video m4v 256x144
209 video webm 256x144
210 audio m4a 256k
211 audio ogg 192k
212 audio m4a 128k
213 audio ogg 128k
214 audio m4a 48k
215
216
217Installation
218------------
219
220pafy can be installed using `pip <http://www.pip-installer.org>`_:
221
222.. code-block:: bash
223
224 $ [sudo] pip install pafy
225
226or use a `virtualenv <http://virtualenv.org>`_ if you don't want to install it system-wide:
227
228.. code-block:: bash
229
230 $ virtualenv venv
231 $ source venv/bin/activate
232 $ pip install pafy
233
234
235Command Line Tool (ytdl) Usage
236------------------------------
237
238
239.. code-block:: bash
240
241 usage: ytdl [-h] [-i] [-s]
242 [-t {audio,video,normal,all} [{audio,video,normal,all} ...]]
243 [-n N] [-b] [-a]
244 url
245
246 YouTube Download Tool
247
248 positional arguments:
249 url YouTube video URL to download
250
251 optional arguments:
252 -h, --help show this help message and exit
253 -i Display vid info
254 -s Display available streams
255 -t {audio,video,normal,all} [{audio,video,normal,all} ...]
256 Stream types to display
257 -n N Specify stream to download by stream number (use -s to
258 list available streams)
259 -b Download the best quality video (ignores -n)
260 -a Download the best quality audio (ignores -n)
261
262
263ytdl Examples
264-------------
265
266Download best available resolution (-b):
267
268.. code-block:: bash
269
270 $ ytdl -b "http://www.youtube.com/watch?v=cyMHZVT91Dw"
271
272Download best available audio stream (-a)
273(note; the full url is not required, just the video id will suffice):
274
275.. code-block:: bash
276
277 $ ytdl -a cyMHZVT91Dw
278
279
280get video info (-i):
281
282.. code-block:: bash
283
284 $ ytdl -i cyMHZVT91Dw
285
286list available dowload streams:
287
288.. code-block:: bash
289
290 $ ytdl cyMHZVT91Dw
291
292 Stream Type Format Quality Size
293 ------ ---- ------ ------- ----
294 1 normal webm [640x360] 33 MB
295 2 normal mp4 [640x360] 23 MB
296 3 normal flv [320x240] 14 MB
297 4 normal 3gp [320x240] 9 MB
298 5 normal 3gp [176x144] 3 MB
299 6 audio m4a [48k] 2 MB
300 7 audio m4a [128k] 5 MB
301 8 audio ogg [128k] 5 MB
302 9 audio ogg [192k] 7 MB
303 10 audio m4a [256k] 10 MB
304
305
306Download mp4 640x360 (ie. stream number 2):
307
308.. code-block:: bash
309
310 $ ytdl -n2 cyMHZVT91Dw
311
312Download m4a audio stream at 256k bitrate:
313
314.. code-block:: bash
315
316 $ ytdl -n10 cyMHZVT91Dw
317
318IRC
319---
320
321The mps-youtube irc channel (`#mps-youtube` on Freenode) can be used for discussion of pafy.
322