viddl-rb: Initially created by Marc Seeger (@rb2k)


Gem VersionBuild Status Dependency Status


gem install viddl-rb


Download a video: viddl-rb

Viddl-rb supports the following command line options:

-e, --extract-audio              Extract the audio track of the download to a separate file
-a, --abort-on-failure           Abort if one of the videos in a list fails to download
-u, --url-only                   Just display the download url without downloading the file.
-t, --title-only                 Just display the title without downloading the file.
-f, --filter REGEX               Filters a video playlist according to the regex (Youtube only right now)
-s, --save-dir DIRECTORY         Specifies the directory where videos should be saved
-d, --downloader TOOL            Specifies the tool to download with. Supports 'wget', 'curl', 'aria2c' and 'net-http'
-q, --quality QUALITY            Specifies the video format and resolution in the following way: width:height:format (e.g. 1280:720:mp4)
                                 The width, height and format may be omitted with a *.
                                 For example, to match any quality with a height of 720 pixels in any format specify --quality *:720:*
-h, --help                       Displays the help screen

Download a video and extract the audio: viddl-rb --extract-audio

In both cases we'll name the output file according to the video title.

Setting the video save directory: viddl-rb --save-dir C:/myvideos

The --save-dir option works with both absolute and relative paths (relative based on the directory viddl-rb is run from). If you want to save to a folder with spaces in it, you have to quote the path like this: --save-dir "C:/my videos"

Want faster download speeds?

Consider installing aria2 ( aria2 differs from curl and wget in that it supports opening multiple connections when downloading a file which may give significant speed improvements if the download service limits the bandwidth a connection receives. viddl-rb will use aria2 as the default downloader if it is available.

Youtube plugin specifics:

Download all videos on a playlist: viddl-rb

Download all videos from a user: viddl-rb

Download all videos from a channel: viddl-rb

Filter videos to download from a user/channel/playlist: viddl-rb --filter /internet/i

The --filter argument accepts a regular expression and will only download videos where the title matches the regex. It uses the same syntax as Ruby regular expression literals do.

Library Usage:

require 'viddl-rb'

download_urls = ViddlRb.get_urls("")
download_urls.first     # => "http://o-o.preferred.arn06s04.v3.lscac ..."

The ViddlRb module has the following module public methods:

  • get_urls_names(url) -- Returns an array of one or more hashes that has the keys :url which points to the download url and :name which points to the name (which is a filename safe version of the video title with a file extension). Returns nil if the url is not recognized by any plugins.

  • get_urls_exts(url) -- Same as get_urls_names but with just the file extension (for example ".mp4") instead of the full filename, and the :name key is replaced with :ext. Returns nil if the url is not recognized by any plugins.

  • get_urls(url) -- Returns an array of download urls for the specified video url. Returns nil if the url is not recognized by any plugins.

  • get_names(url) -- Returns an array of filenames for the specified video url. Returns nil if the url is not recognized by any plugins.

  • io=(io_object) -- By default all plugin output to stdout will be suppressed when the library is used. If you are interested in the output of a plugin, you can set an IO object that will receive all plugin output using this method. For example:

require 'viddl-rb' = $stdout     # plugins will now write their output to $stdout

All the get methods in the ViddlRb module will raise either a ViddlRb::PluginError or a ViddlRb::DownloadError if the plugin fails. A ViddlRb::PluginError is raised if the plugin fails in an unexpected way, and a ViddlRb::DownloadError is raised if the video could not be downloaded for some reason. An example of that is if a Youtube video is not embeddable - then it can't be downloaded.

rescue ViddlRb::DownloadError => e
  puts "Could not get download url: #{e.message}"
rescue ViddlRb::PluginError => e
  puts "Plugin blew up! #{e.message}\n" +


  • curl/wget/aria2c or the progress bar gem
  • Nokogiri
  • ffmpeg if you want to extract audio tracks from the videos

Co Maintainers:

  • kl: Windows support (who knew!), bug fixes, veoh plugin, metacafe plugin, refactoring it into a library, ...
  • farleyknight: Various small fixes and improvements


  • albertoboni bandcamp plugin, soundcloud improvements
  • divout aka Ivan K: plugin, bugfixes
  • mbajur aka Mike Bajur: The instagram plugin
  • Sniper: bugfixes
  • Serabe aka Sergio Arbeo: packaging viddl as a binary
  • laserlemon: Adding gemnasium images to readme