<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
<title>youtube-dl: Documentation</title>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>

<table class="heading"><tr>
	<td class="title"><a href="index.html">youtube-dl</a></td>
	<td class="subtitle">Documentation</td>
</tr></table>

<div class="toc">
<h1>Index</h1>

<ul>
<li><a href="#d1">Getting started</a></li>
<li><a href="#d2">More usage tips</a></li>
<li><a href="#d3">Frequently Asked Questions</a></li>
<li><a href="#d4">Supported sites</a></li>
<li><a href="#d5">Proxy support</a></li>
<li><a href="#d6">YouTube formats</a></li>
<li><a href="#d7">Output template</a></li>
<li><a href="#d8">Configuration</a></li>
</ul>
</div>

<h1 id="d1">Getting started</h1>

<p>In Windows save the exe version somewhere (in your PATH if you want to run it simply as <em>youtube-dl</em>) and run it from the command line.</p>

<p>In Unix, download it, give it execution permission and copy it to one of the PATH directories (typically, <em>/usr/local/bin</em>).</p>

<p>To update, simply call <em>youtube-dl -U</em>, we recommend to do it often.</p>

<p>After that, you should be able to call it from the command line as <em>youtube-dl</em>. I will use <em>youtube-dl</em> in the following examples. Usage instructions are easy. Use <em>youtube-dl</em> followed by a video URL or identifier. Example: <em>youtube-dl "http://www.youtube.com/watch?v=foobar"</em>. The video will be saved to the file <em>foobar.flv</em> in that example. As YouTube.com videos are usually in Flash Video format, their extension should be <em>flv</em>. In Linux and other unices, video players using a recent version of <em>ffmpeg</em> can play them. That includes VLC, MPlayer, etc. Those two work under Windows and other platforms, but you could also get a specific FLV player of your taste.</p>

<p>If you try to run the program and you receive an error message containing the keyword <em>SyntaxError</em> near the end, it means your Python interpreter is too old, remember that youtube-dl need Python version 2.6, 2.7, or 3.3+.</p>

<h1 id="d2">More usage tips</h1>

<p>The program is usually invoked as <em>youtube-dl</em> followed by options and the video URLs. Listing all the options here would make this text too long, so you can run <em>youtube-dl --help</em> and get a summary of them. From that point on you can start experimenting with the different options yourself. The most common ones are -t (or -l) to include the video title in the file name. Also, the -o option can specify the output file name and path. It allows special character sequences that can be used as templates to be replaced. See the "Output template" section for more details.</p>

<p>Some YouTube videos are served using Adobe's proprietary RTMP protocol, which imposes DRM restrictions and encrypts the connection. <em>youtube-dl</em> is not able to download these videos by itself. However, it will attempt to use the <a href="http://rtmpdump.mplayerhq.hu/">rtmpdump</a> program, if it's installed in your system, to download these videos.</p>

<h1 id="d3">Frequently Asked Questions</h1>

<p>The <a href="faq.html">Frequently Asked Questions</a> page contains answers to some common questions that pop up in my e-mail and in the <a href="https://github.com/rg3/youtube-dl/issues">issue tracker</a>. Be sure to check it before reporting problems.</p>

<h1 id="d4">Supported sites</h1>

<p>
youtube-dl can download videos from a lot of sites, here's a list with some of the most popular.
For a complete list, see the <a href="supportedsites.html">Supported sites</a> pages or execute <code>youtube-dl --list-extractors</code>.
</p>

<ul>
<li>YouTube.com.</li>
<li>YouTube.com playlists (playlist URLs in "view_play_list" form).</li>
<li>YouTube.com searches, using the special keyword "ytsearch" as a form of URL, as in "ytsearch:cute kittens". Do not forget the quotes if you want to include spaces in your search. Other variants are "ytsearchN" to download more than the first result, with N being a number, and "ytsearchall".</li>
<li>YouTube.com user videos, using user page URLs or the specifc "ytuser" keyword.</li>
<li>metacafe.com.</li>
<li>Google Video.</li>
<li>Google Video searches ("gvsearch" keyword).</li>
<li>Photobucket videos.</li>
<li>Yahoo! screen.</li>
<li>Yahoo! screen searches ("yvsearch" keyword).</li>
<li>Dailymotion.</li>
<li>DepositFiles.</li>
<li>blip.tv.</li>
<li>vimeo.</li>
<li>myvideo.de.</li>
<li>The Daily Show / Colbert Nation.</li>
<li>The Escapist.</li>
<li>CollegeHumor.</li>
<li>arte.tv.</li>
<li>Soundcloud.</li>
<li>xvideos.</li>
<li>infoq.</li>
<li>mixcloud.</li>
<li>Stanford Open Content.</li>
<li>Youku.</li>
<li>MTV.</li>
<li>XNXX.</li>
<li>Google Plus.</li>
<li>A generic downloader that works in some sites.</li>
</ul>

<h1 id="d5">Proxy support</h1>

<p>youtube-dl supports downloading videos through a proxy, by setting the <em>http_proxy</em> environment variable to the proxy URL, as in <code>http://proxy_machine_name:port/</code>.</p>

<h1 id="d6">YouTube formats</h1>

<p>Using the -f option and other related options, you can specify the video format to be downloaded from YouTube. If you have an order of preference, specify the formats separating them with slashes: <code>-f 22/17/18</code>. Instead of keeping a video format table here, I will refer you to the <a href="http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs">list of YouTube formats on Wikipedia</a>.</p>

<h1 id="d7">Output template</h1>

<p>The -o option allows users to indicate a template for the output file names. The basic usage is not to set any template arguments when downloading a single file, like in <em>youtube-dl -o funny_video.flv "http://some/video"</em>. However, it may contain special sequences that will be replaced when downloading each video. The special sequences have the format <strong>%(NAME)s</strong>. To clarify, that's a percent symbol followed by a name in parenthesis, followed by a lowercase S. Allowed names are:</p>

<ul>
<li><em>id</em>: The sequence will be replaced by the video identifier.</li>
<li><em>url</em>: The sequence will be replaced by the video URL.</li>
<li><em>uploader</em>: The sequence will be replaced by the nickname of the person who uploaded the video.</li>
<li><em>upload_date</em>: The sequence will be replaced by the upload date in YYYYMMDD format.</li>
<li><em>title</em>: The sequence will be replaced by the video title.</li>
<li><em>ext</em>: The sequence will be replaced by the appropriate extension (like <em>flv</em> or <em>mp4</em>).</li>
<li><em>epoch</em>: The sequence will be replaced by the Unix epoch when creating the file.</li>
<li><em>autonumber</em>: The sequence will be replaced by a five-digit number that will be increased with each download, starting at zero.</li>
</ul>

<p>The current default template is <em>%(id)s.%(ext)s</em>, but that will be switchted to <em>%(title)s-%(id)s.%(ext)s</em> (which can be requested with <code>-t</code> at the moment).</p>

<p>In some cases, you don't want special characters such as 中, spaces, or &amp;, such as when transferring the downloaded filename to a Windows system or the filename through an 8bit-unsafe channel. In these cases, add the <code>--restrict-filenames</code> flag to get a shorter title:</p>

<p><code style="white-space: pre;"><span style="color: #888;">$</span> youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
<span style="color: #004;">youtube-dl test video ''_ä↭𝕐.mp4</span>&nbsp;&nbsp;&nbsp;&nbsp;<span style="color: #666;"># All kinds of weird characters</span>
<span style="color: #888;">$</span> youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
<span style="color: #004;">youtube-dl_test_video_.mp4</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color: #666;"># A simple file name</span></code></p>

<h1 id="d8">Configuration</h1>

<p>
You can configure youtube-dl by placing default arguments (such as <code>--extract-audio --no-mtime</code> to always extract the audio and not copy the mtime) into <code>/etc/youtube-dl.conf</code> and/or <code>~/.config/youtube-dl.conf</code>. Arguments in these files may be written across multiple lines, and any line beginning with the <code>#</code> character will be treated as a comment.
</p>

<div class="note">
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/deed.en_US">
<img alt="Creative Commons License" style="border-width:0"
src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png" /></a><br />
Copyright © 2006-2013 Ricardo Garcia Gonzalez</div>
</body>
</html>