Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An extendable commandline video downloader for flash video sites like vimeo, youtube, ...
Branch: master


latest commit a9d2c18e41
@rb2k authored


This project is currently unmaintained.
I am afraid that I (@rb2k) am not able to keep up with the amount of changes that sites like Youtube implement on a weekly basis. Even with the support of 3rd parties, there just isn't enough time to play catch up with the latest attempts in obfuscation of the URLs

For now, I'd recommend you take a look at youtube-dl.
They have over 300 contributors and might stand a chance :)

Thanks to all of the contributors!
If you feel like taking over the project, shoot me a message (@rb2k on twitter)!

Original Readme

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
  • laserlemon: Adding gemnasium images to readme
  • mbajur aka Mike Bajur: The instagram plugin
  • Sniper: bugfixes
  • Serabe aka Sergio Arbeo: packaging viddl as a binary
  • simplysoft: Improve vimeo plugin
Something went wrong with that request. Please try again.