mp3Librarian is a collection of tools to help you organize, tag, and propagate your mp3's. Mp3Librarian is made up from three applications:
-mp3librarian - A tool to automatically tag mp3 files that are sorted into albums. It does this by using the location of the file in the file system as the bases for the correct id3tags. It also has other album checking capabilities built in.
-mp3CollectionCreator - A tool to create a listing of albums that are composed of mp3's.
-mp3Grabber - A tool to compare two mp3CollectionCreator files and grab any new albums.
Intro: mp3CollectionCreator is a tool used to create a listing of albums that are composed of mp3's. There are two rules that mp3CollectionCreator uses to for albums to be considered valid.
1) All mp3 files must be fully tagged (correctly).
2) Only 1 album may reside in a directory.
Because of these two rules you do not have to have your files in the same directory/file layout that mp3librarian uses and you could sort your mp3's by year if you wanted. Because of rule #1 mp3CollectionCreator checks all of the files in a directory and if they don't have matching id3 tags, every track etc the album will not be added to the list.

Command line args: Both the root directory for finding albums and the location of the file to list albums need to be passed into the application through the command line arguments. Example: mp3collectioncreator -r /mp3/ -f /mp3/mycollection.txt.

File format: The file format of each line of the resulting file is:
For example:
"Alternative<#@#>Staind<#@#>Break The Cycle<#@#>2001<#@#>/mp3/albums/Alternative/Staind/Break The Cycle/"
This information stored in each line is used by mp3Grabber to determine if there are new albums and then get the new albums.

Typical usage: mp3collectioncreator -r /mp3/ -f /mp3/local

Intro: mp3Grabber is a tool to compare two mp3CollectionCreator files and grab any new albums. mp3Grabber will compare the local mp3CollectionCreator file to a remote mp3CollectionCreator file and based upon a rules file it will download any new albums that are not banned. mp3Grabber requires that you pass in the 2 file locations in the command line options. "-l [file location]" is the local mp3 album collection and "-n [file location]" is the new mp3 album collection. Example: "mp3grabber -l /mp3/local.txt -n /mp3/remote.txt".

Rules: When a new album is found that is not on the local collection mp3Grabber will check with a rules file (if one is passed in with -r) to see if the album should be downloaded. The rules file follows the same format as the mp3CollectionCreator files. In the rules file you can set 4 commands to ignore: genre, group, album and year. If only 1 command is specified then all new albums that have the same command will not be downloaded. For example: if you have Alternative<#@#><#@#><#@#><#@#> then any new album that has Alternative as its genre will not be downloaded. If you specify 2 rules then both rules must match for the album to not be downloaded. Same with 3 and 4 commands. If "//" is the first 2 characters in a line of the rules file then the line is ignored (A comment).

// I don't want any Alternative (But other genres are ok)

// I don't want anything by Staind (Doesn't matter if Staind is classified as Alternative or Pop)

// I don't want anything by Staind that came out in 1999 (But give me everything else)

// I don't want Staind's 2000 album "Hold On" (But The 2001 version is downloaded)
<#@#>Staind<#@#>Hold On<#@#>2000<#@#>

The rules file is very powerful, but for most cases you will probably just want to ignore a genre or a particular group that you do not want. (An example rules file in included in the mp3grabber directory of the source.)

Copying: to download the new album you must specify the copy command to use. The reason for this is that it allows for user to determine how the files are going to be moved from system to system. The copy command is set with -c [string] in the command line arguments. You can use mv, ftp, scp or any other tool that has been predetermined by the owner of the "new" mp3CollectionCreator file and yourself*. scp will be demonstrated here.** The copy command will actually be put into the file /tmp/mp3Grabber and then executed as a script so you can use the normal script rules for the string.

Example: -c "scp -r user@host:\"%dir\" \"/mp3/%genre/%group/%album/\"" There are 5 allowable replacements in the copy command: %dir, %genre, %group, %year, %album. %dir is the location of the new album on the remote machine. The other 4 replacements can be used to place the new album directly in the correct spot in your collection. This allows you to properly sort the local mp3 collection while keeping the remote mp3 collection is sorted a different way.

Typical usage: mp3grabber -l /mp3/local -n /mp3/new -r /mp3/rules -c "mkdir /mp3/%group; scp -r user@host:%dir /mp3/%group/%album/"

* The owner of the local and remote collection is more then likely the same person who wishes to simply mirror part of his/her collection from one machine to another (example being an mp3 server and a portable mp3 player or living room mp3 stereo component)
** Note that for scp to work on your system you must be able to log in without entering a password using key authentication.

Intro: mp3librarian is a tool to automatically tag mp3 files that are sorted as albums. It does this by using the location of the file in the file system as the bases for the correct id3tags. It also has other album checking capabilities built in. To use mp3Librarian you must all the songs in the albums and store your mp3's in the following way /genre/group/album/*.mp3. For example the group "Staind" is an "Alternative" band and has an album called "Break The Cycle". You would store the songs for this album in the directory: "/Alternative/Staind/Break The Cycle/".* When you run mp3Librarian it would then check all of the songs to make sure that the genre id3tag says "Alternative", the artist id3tag says "Staind" and the album id3tag says "Break The Cycle". The file name is the only thing that mp3Librarian can't double check and so the mp3 files must be in the format "artist - song.mp3". (note there is an untested feature to have "track - song.mp3" and a -g track option to convert from "track - song.mp3" to "artist - song.mp3") mp3Librarian also checks that the id3 track numbers 1 to "the number of files" are present for each album.

Base directories: Because you wouldn't want mp3Librarian to recheck every album every single time it is run your root mp3 directory needs to be broken up into 2 directories, "albums" and "new". When you get a new mp3 album you would place it in the "new" directory. Example: "new/Alternative/Staind/Break The Cycle/" mp3Librarian would then be run with the -n (for new) option telling it to go through the new directory checking anything that is found inside of "new". If there are no errors that mp3Librarian can not resolve itself (such as all of the files within an album don't have the same year in their id3tag) the album is moved from the "new" directory into the "albums" directory.** mp3Librarian will output all changes and any errors that are encountered while it goes through the mp3's.

Root Directory: The root directory of "new" and "albums" is configurable and needs to be passed to mp3Librarian using the -r option. For example I store my mp3's in "/mp3/" so I would pass "-r /mp3/"

mp3Librarian as a cron job: If you will be getting new albums all of the time you can have mp3Librarian run as a cron job. mp3Librarian has the ability to log all messages and errors to a log file and execute a script (such as e-mailing you that log file) It can also keep a burn file of any new albums that are moved into the "albums" directory so that you can be sure to back up the mp3's onto CD or other preferred format. See mp3Librarian -h for more logging details.

Generating play lists: Because mp3Librarian has the ability to read id3 tags and moves albums around it also has the ability to generate play list files. The play order in the album play lists are based off of the order of the songs in the albums (as given by the track id3tag).*** One of the wonderful side effects of this is that you can just re-run mp3Librarian to get a working play lists after file have been moved around/added. As mp3Librarian descends through each directory it will make a play list of play lists. For example the Alternative directory will have a play list of all of the Alternative artists play lists. The Staind band will have a play list off all of Staind's albums play lists. The albums will in turn will have the list of mp3's for that album. So if you wish to load up all of your mp3's you can just load the albums.m3u play list and you will get every album with the tracks in the correct order.

Web based play lists: mp3Librarian can also generate play lists that will be use on a website with the -w option. Example: The website is and the mp3s are accessible from "" Staind's Break The Cycle would be located in " The Cycle/" To make a play list that conformed to that you would pass "-w"

Typical usage: For normal command line usage (parsing new and then making play lists):
mp3librarian -r /mp3/ -b /mp3/burn -n -c
mp3librarian -r /mp3/ -a

For more advanced cron usage (parsing new and then making play lists):
mp3librarian -r /mp3/ -l /mp3/log -b /mp3/burn -s /mp3/mailScript -n -c
mp3librarian -r /mp3/ -l /mp3/log -s /mp3/mailScript -a -c
mp3librarian -r /mp3/ -l /mp3/log -s /mp3/mailScript -a
mp3librarian -r /mp3/ -l /mp3/log -s /mp3/mailScript -a -w

More: There are other options available. See --help and -d for more options and details.

* It should be noted that storing mp3's based on genre allows for an easier way of managing very large collections that exceed the current hard drive sizes then raiding (Each genre would actually be a link different hard drive).
** Have a "new" directory is also a security feature which allows for the albums directory to be read only to the outside world while the new directory read-write. This allows for uploads without the possibility of corrupting (deleting, overwriting, re-naming, etc) the current albums collection. "new" could also be a link to its own hard drive preventing someone from "stuffing" your albums drive.
*** Having the track numbers determine the play list order is very useful for many albums that seamlessly go from one track to another such as in live works. (And for those who have listened to the CD many time and expect a certain song next.)

File Downloads
Program Requirements