Mastering Youtube-DL Audio/Video Downloader

youtube-do logo

I really like Youtube-DL. I love it! Yes, i said it. So this here is the 2nd article i’m writing about it in quite a short period. First Youtube-DL article was more introductory, with a short tutorial and a small review part. Here we’ll assume that you’ve read this article and are familiar with CMD (once again, easy to invoke it with CTRL+ESC+C+M+D+ENTER combination). Now i realize not all windows versions will allow that. I am on Windows 7. Check this intro tutorial for CMD if you have no idea what i’m talking about. Indeed, my Youtube-DL tutorial & Review covers basics of accessing and operating CMD, switching between logical drives and manipulating folders. It also explains how to install Youtube-DL, and how to do the most desired thing with it – download youtube video. And so we go.

below are the 3 major ideas we all should know about command line options (parameters):

  1. what are options for applications? in our case, they are those little instructions we pass to the programs, when we want them to act different from the default behavior or protocol.
  2. options usually start with 1 dash – or 2 dashes –. Sometimes options have values, that follow right after the option name (separated by spaces or = equal signs). Long multi-word option values with spaces in them should be included in quotes like this –option “option value dd”.
  3. there can be multiple options and they can have multiple values. all options have default values that do not need to be sent to the program.

so that said, this could be a normal string of command:

>youtube-dl -i –min-filesize 1500k –max-filesize 74.5m

in the example above you can see both one dash and two dash options being passed to youtube-dl. two similar options of minimum sizer and maximum size have differently passed values – 1500kb minimum and 74.5 minutes long maximum. and they are all followed by 2 video URLs, one from youtube, one from vimeo. for the future, when we talk of multiple URLs – this is the case. also processing a playlist will yield multiple video URLs, so that also counts..

General Options for Youtube-DL

Options can be passed to any program, not just in command line, but also by making a shortcut to a program. Then right-click on it and go Properties, and Shortcut tab allows us to change TARGET field, where we then would enter the options.. So if you’re still not so clear, here is the first command that can be executed:

>youtube-dl –version

> denotes we start to enter the command. output comes next, we’ll be marking its start with >>. right now it shows what version of the program you have. here’s an example of what i see…

command line youtube-dl --version option output example

if the date shown is from long time ago, it’ll be nice to update youtube-dl with the -U parameter. please, note, this is one of the options that can be passed both with 1 or 2 dashes (-U or –update). also when we talk about options, Capital Letters actually make difference, so watch out for that. it is simply because there can be hundreds of options, and there are only 25 letters, so they double it with Capitals, historically.. now let’s Update our youtube-dl and see what happens:

>youtube-dl -U
>>youtube-dl is up-to-date (2017.05.29)

>youtube-dl –update
>>youtube-dl is up-to-date (2017.05.29)

youtube-dl update command-line option example both one and two dashes
youtube-dl update command-line option example both one and two dashes

Some More General Input Handling Parameters

So below i will continue without screenshots, and you’ll just have to trust me with the outputs (if required for visual example). =) I promise i won’t lie. Next 2 options are for error handling while processing lists of videos. Option -i or –ignore-errors tells youtube-dl to continue working even if download errors happen. For example, it’ll help skip unavailable videos in a playlist without interrupting the flow. There’s a counter-option –abort-on-error and it will stop the downloading and processing of second and third videos, if there were errors with the first one.

–dump-user-agent option will display the current browser it uses to fool sites into thinking that it’s some person browsing… as mentioned in first article, this is how youtube-dl does things.. with a built-in browser to circumvent any browser based bot-checks.

>youtube-dl –dump-user-agent
>>Mozilla/5.0 (X11; Linux x86_64; rv:10.0) Gecko/20150101 Firefox/47.0 (Chrome)

Now there are really lots of options you can pass to youtube-dl. in this article we will concentrate on most used of them (in my opinion, of course). Also there are some options only for unix/linux version which won’t work in windows, we will ignore those too.

–flat-playlist will help when you don’t want to download videos from the playlist, but just see what videos are included in that playlist. helps when you’ve already downloaded some of them. Pass the –mark-watched option when you want youtube-dl to mark videos as “watched by you” in your youtube (only) account. Use –no-mark-watched if you want those videos to stay “new-for-you” when you login to youtube’s www interface again.. Both these options require you to pass your credentials for the site, check “Authentication Options” section below.

Network & Geo Restriction Options

proxies & protocols

–proxy URL option allows you to specify a proxy to use with the downloading. these days we can’t be too secure, so this might be a great option to use. it does require some prior knowledge of working with proxies.. Proxy can be a site elsewhere handling your data traffic or simply something on your computer like SOCKS5 or something, used for tunneling and authenticating with third party servers, etc. Options -4, –force-ipv4 and -6, –force-ipv6 will force all connections to be via IPv4 or IPv6 respectively.

geo-restriction bypass with proxy

If some sites say you’re not allowed to come in because you live outside of their “preferred coverage area” (aka geo-restriction), well, tell them to suck it with the ultimate bypass options. Use –geo-verification-proxy URL option to verify yourself as one of their own. Just get a proxy in their “area”. This proxy will only be used for IP verification, it will not affect the downloading proxy (if passed with –proxy). This actually helps a lot with and their intent to cater to Europe only sometimes.. Bypassed their checks many times. Just make sure your proxy is not transparent. If you’re in search of a free proxy, open google and type in “free proxy” or “proxy list”.

experimental geo-block bypass without proxy

If proxy is not an option for you, try one of the following 2 experimental options.. –geo-bypass (fakes the X-Forwarded-For HTTP header). –geo-bypass-country CODE will try to force bypass via provided two-letter ISO 3166-2 country code.

Video Selection Options

Following block of options will help with selecting and filtering which videos you’d like youtube-dl to download, and which to leave alone.

playlist filtering

First 3 options let you manage the playlist. –playlist-start NUMBER will start processing playlist videos from the Number-ed one. Default value is 1 – process from the start. –playlist-end NUMBER will tell the program where to stop. –playlist-items ITEMS is more detailed, here you can tell exactly which videos to download. You can recount them as “2,5,6” or put ranges “1-5,7-11” or combine both methods. try to avoid “spaces” in between numbers, dashes and commas. if you must include spaces, pass whole value in quotes like this –playlist items “1, 2, 4”.

>youtube-dl –playlist-items 1-3,5,7,10-13 playlist_URL

search string, video attributes & logic filtering

Second group of options here represent filtering by substring (letter case is not respected, REGEX use is allowed). Now youtube-dl will handle videos from playlist only if their attributes match the required criteria. For example, –match-title SUBSTRING will look for videos with Substring in their titles. –reject-title SUBSTRING will skip any videos with title matching the SUBSTRING.

–max-downloads NUMBER will stop all downloading after NUMBER of files have been processed. –min-filesize SIZE will only look at files with file size larger than SIZE. As mentioned before, size can be the actual file size 100k or 100Kb, or video duration 01:40:30 or 1h40m30s or 100.5m. again, try to avoid spaces in values. If youtube-dl finds a space in parameters, it assumes that the current parameter and/or its value have ended and new parameter or video url has began.. that’s why quotes are important if you cannot avoid having spaces in the parameters values. –max-filesize SIZE obviously does the opposite here, bounds video selection by max file size.

To download videos published on a special date, before it or after it, use –date DATE, –datebefore DATE and –dateafter DATE. Filtering by views can be done with –min-views COUNT and –max-views COUNT. While age restrictions can be observed with –age-limit YEARS parameter.

Finally, you can include ads into the video with this command line parameter –include-ads. Usually youtube-dl will not put ads into the video, does so by default.

Video/Audio Download Options

When downloads are too fast, limit download speed with -r, –limit-rate RATE option. watch out, same parameter only capital letter – means different! Option -R, –retries RETRIES says how many times to retry download if errors were encountered (default – 10 times). You can also tell it not to come back until the job is done with “infinite” value for retries. –buffer-size SIZE limits the buffer size used for downloading.

video fragments handling

While –fragment-retries RETRIES tells yoube-dl how many times you want it to retry every video segment, if errors were encountered.. Skip missing fragments with –skip-unavailable-fragments. Fragments usually referred to many files that any video/audio streams is broken into. it’s much easier for programs to receive video streams as one by one files, which are seamlessly played one after another so we don’t see any interrupts, but generally streams are rarely uninterrupted, only maybe RTMP streams or something.. Same when downloading fragments, youtube-dl will put them all one after another into 1 file and present you with 1 final file. Option –abort-on-unavailable-fragment will stop video download if any of the fragments are unavailable after all retries have been attempted. –keep-fragments option will save all the little files on your disk for you to check out.

video stream playlist download options

video stream playlist is different from a channel playlist. stream playlist is usually passed to the browser/player behind the scenes and has the locations of those fragments, i.e. tells your video player where to actually download the video to show you. it usually is a file and has m3u8 file extension. this is usually important for live streaming. To DVR download the video or use the built-in video downloader –hls-prefer-native option can be used. –hls-prefer-ffmpeg and –hls-use-mpegts give more freedom of choice. while –external-downloader COMMAND will allow for other programs to handle file downloading. this is especially actual for linux. but can matter in Windows too. parameters to the external downloader are passed with –external-downloader-args ARGS option.

Downloading and Filesystem Options

there is a bunch of parameters here, we’ll check some of them… -a, –batch-file FILE tells youtube-dl to look into the FILE for video URLs. –restrict-filenames will only work with normal short filenames and drop long ones, that have spaces and other nasty characters.. -w, –no-overwrites will explicitly tell youtube-dl not to overwrite preexisting files, while -c, –continue will force it to resume any partially downloaded files. By default, youtube-dl tries to resume
broken or interrupted downloads if possible. –no-continue hence comes as the opposite of -c.

Thumbnail images

For thumbnails we have –write-thumbnail and –write-all-thumbnails parameters which will write all thumbnail image(s) format(s) to diskm, while –list-thumbnails will simply simulate and list all available thumbnail formats without writing them to disk. which brings us to our next chapter:

Verbosity & Simulation Options

This is more for programmers and sysadmins, but oh well.. If you want youtube-dl to print no output during its time working, tell it to be quiet with –q, –quiet options. –no-warnings will ignore warnings and won’t bother you with those. -s, –simulate will not actually download any videos, but will print out all the info as if it did. simulating! –skip-download will wring the thumbnails and all, but won’t do the actual download of the video materials. There are different combinations and variations of these options, like -g, –get-url, or -e, –get-title, or –get-id, –get-thumbnail, –get-description, –get-duration, –get-filename, -j, –dump-json, -J, –dump-single-json, –print-json etc.

Youtube-DL Workarounds

Youtube-dl is a great program and team of people making and maintaining it is very smart. And so they came up with some workarounds for some problems you might encounter while downloading youtube videos or doing the youtube mp3 thing. These are very advanced options, please, be careful.

–encoding ENCODING forces all communication to be with the specified encoding.
–no-check-certificate tells youtube-dl not to do HTTPS certificate validation if it’s present
–prefer-insecure will channel all data exchange via an unsecure connection, if possible
–user-agent changes the default user agent from the one printer with –dump-user-agent
–referer URL specifies a custom referrer (when video can only be watched online on a special website and nowhere else)
–add-header FIELD:VALUE lets you change the headers, separate multiple with colon
–sleep-interval SECONDS says how long to wait before downloading next video

Video Format Options

When dealing with online video, I always find different streaming options. It is of course done for different screen sizes and connection types. And that can actually be detected and special certain preferred stream can be downloaded. The list of video formats available for any video can be displayed with -f, –format  FORMAT parameter passed.. The FORMAT codes are located in the list of all formats. To see it, run youtube-dl with one of the -F, –list-formats options. Please, check example below. As you might have guessed, weeI1G46q0o in the code refers to youtube video.

youtube-dl video format selection example
youtube-dl video format selection example

So you can see, I queried the list of all available formats by passing -F option, and then asked for format 22 by indeed doing the -f 22 part. Please, check out the image, it is a standard youtube formats list, it carries more or less same entries for all the videos. It is very valuable, since it reveals something special about youtube’s way of media delivery. To save on hdd space, youtube videos are broken into purely video and purely audio parts, and then each gets saved into several different formats and quality levels. Later depending on your requested format, player chooses both audio and video fitting that format and syncs them on-the-fly. That means “plays them together”.

There are also several streams that have both audio and video, last 5 options in the list above. But best video there is only 720p. While best video in the list is audioless 1080p. Also, please, direct your attention to the formats listed in the image: m4a and webm for audio, mp4, webm and 3gp for video. Do not download video only formats if you cannot add audio to them. Let youtube-dl merge audio and video for you! Yes, it does that! So.. the little trick here is to pick which video and audio streams you like, and then have youtube-dl merge them together into the final output file. If you are lost in those options, simply use this bestvideo+bestaudio trick to let the program chose the best video and audio streams.

>youtube-dl -f bestvideo+bestaudio weeI1G46q0o
>youtube-dl -f 137+251 weeI1G46q0o

This will produce an MKV file (most likely), with 1080p video and 160kbps audio. For this to happen you will need to install ffmpeg though, so maybe stick with 720p at first? it has supposedly even better audio – 192kbps vs 160… no.. they both are VBR average 128kbps.. pretty much..

more format options

–all-formats parameter makes youtube-dl download all available video formats,
–write-sub, –write-auto-sub, –all-subs, –list-subs are all to deal with the available subtitles.
–sub-format FORMAT downloads subtitles of special format from –list-subs, while –sub-lang LANGS can use comma separated list of languages that subtitles are allowe to be in.

Authentication Options

some sites require you to login before browsing or streaming something. Especially life stuff… No problems, youtube-dl can handle authentication! just use the following parameters:
-u, –username USERNAME for the username or account ID
-p, –password PASSWORD for password, if left empty youtube-DL will ask for it in due time
-2, –twofactor TWOFACTOR for possible two-factor authentication code
–video-password PASSWORD to pass special video password (useful on vimeo, etc)

Post-processing Options

I will leave Post-processing Options for another article, they are too extensive to put in this one.


I really hope you found this article helpful. Wee talked a lot about most used parameters that can change default behaviors of youtube-dl when downloading online video. We know now how to pass parameters to youtube-dl, tell it to use proxy or bypass geo-restrictions, how to give us best video and audio and merge it together, and how to do all this as a simulation. We can chose the video or audio we want, or both. Should have i been saying “you” insted? Cause we means you! You can do it too!! Good luck taking over the world of streaming video from here on out! =)

1 Comment

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.