Last Update: Sun Jan 22 14:14:03 EST 2006

musicextras: Automatically download song information Copyright (C) 2003-2004 Zachary P. Landau <>


Musicextras is a program for downloading extra information for songs. Currently it retrieves lyrics, artist images, and album covers. It was designed to make it retrieve new datatypes.

There is now a rubyforge page at You may report bugs, desired plugins, problems with songs not being found that should be, etc, there.


 Ruby 1.8.1 -
 mp3info -
 ruby-gettext (optional) -

For GTK Interface:

 ruby-gnome2 -

For web interface:

 WEBrick -
 html-template 0.16 -


  $ ruby setup.rb config [--disable-nls]
  $ ruby setup.rb setup
 ($ su)
  # ruby setup.rb install

Or, if you don’t use any options, you can just do

 ($ su)
  # ruby setup.rb

You probably want to edit RUBYLIB/musicextras/musicextrasrc.rb. See Usage below.


If you are installing over an old version, I suggest you remove the greylist since new versions may have improved the success rate for matches. You may delete it by using

  $ musicextras -c

Also, you may even want to delete all of the cached results. Sometimes there are changes that affect the lyrics formatting and things like that. This is the case when upgrading from 0.6.1 to 0.6.2. To remove the cache files if they are in the default directory, you may use:

  $ musicextras --clear-cache


The system works by using plugins for various sites. Look in musicsites/ for examples. If you build the rdocs (‘rake rdoc’) more extensive plugin documentation is included with the MusicSite class.

If you write a plugin, please send it to me so I can distribute it with the program. If you know of a good lyrics site and don’t have the ability to write your own plugin, let me know of it and maybe I’ll write one for it.

If the debugging option is used (-d), plugins will log information to $HOME/.musicextras/debug.log This will help you determine what plugins are never finding anything good, etc. If you decide a plugin is useless for you, you can specify which ones you want to use in musicextrasrc.rb. Run ‘musicextras —list-plugins to see which ones you may want.


Look over the settings in $RUBYLIB/musicextras/musicextrasrc.rb. If you make changes you probably want to copy config.rb to $HOME/.musicextras/musicextrasrc.rb so the changes will not be overwritten when you upgrade.

If you just want to print lyrics to the screen, try musicextras —help to see the options for that. But you probably want the gui, so first:

  $ musicextras-gui

The GUI should load but be blank. Then run musicextras with the options you want. This will fetch the information and send it to the GUI.

The recommended way is to run it with your mp3 player. To set it up in xmms, you should use the song_change plugin. Go to Options->Preferences->Effects/General Plugins, click on Song Change and then Configure. The song change command should be something like:

  musicextras -g -f "%f"

Make sure you click ‘Enable plugin’

The cache keeps a list of items that the plugins were unable to find and does not attempt to download them again. Every once in a while you may want to clear this list in case some of the plugin sites add new content. To clear the list, run ‘musicextras —clear-greylist’.

If you are behind a proxy, defining the HTTP_PROXY environmental variable should work, but it is untested. It doesn’t yet support usernames or passwords.


There are a few things to know about the internationalization support in musicextras. By default, musicextras assumes input from the keyboard or mp3 files is ISO-8859-1. To change this, set LANG to the charset you use. For example:

  LANG=ru_RU.utf8 musicextras -f MyRussianMp3.mp3

This will automatically use ISO-8859-5.

If ruby-gettext is installed on your machine, setting LANG will also cause musicextras and musicextras-gui to use strings translated into that language, if available. Note: use the unicode version for your language. For example,

  LANG=es_ES.utf8 musicextras-gui

Using Only The Library

The previous instructions were for using the frontend included. It should be very easy to incorporate the data fetching in your own program, however. Here is a simple example. Suppose you want to wanted to print out the lyrics to a song.

  require 'musicextras/song'
  require 'musicextras/musicsites/_load_sites'  # This loads the plugins

  puts'I Palindrome I', 'They Might Be Giants').lyrics

To see a list of available accessors after your plugins are loaded, try this:

  require 'musicextras/artist'
  require 'musicextras/musicsites/_load_sites'

  puts MusicExtras::Artist.accessors

That’s it.

Writing a GUI

At the moment, there is a GTK and a Web Gui. It should be fairly easy to implement one with another toolkit, however. Just make your GUI a subclass of Gui (gui.rb) and use that as a template. The gtkgui.rb file will probably help too.

It‘d be nice to have a Gui for a crossplatform toolkit, like wxWindows (hint hint).


If you are getting a lot (or only) failures, try testing the plugins by running "musicextras -T". If any of the plugins fail, check the webpage to see if the problem is already known. If not, send me an email and let me know.

See the BUGS list for the full list.