ID: README Wed Jul 25 15:11:38 EDT 2012 ground/X

The MP3 database project II
README file.

Introduction:

MP3DB2 is a collection of bash scripts for keeping track of large MP3 
collections.  It will retrieve song information from the filenames and ID3 
tags of a directory or CD of MP3s and store them in a local database.  It 
then allows you to search any of the fields, generate a master listing of 
all your complete albums, see the size of your entire collection, and 
more.  I wrote it because I have over  20,000 MP3s and was starting to get 
dupes because I couldn't remember what  I did and didn't have.
It is also nice to quickly see what MP3 CD a given song/album is on.

This is a complete rewrite of my MP3 database version 1.  Version 1 only 
stored the data that was present in the filenames while version 2 actually 
retrieves information from the ID3 tags of each MP3.

Licensing and Distribution:

This archive of scripts is released in to the Public Domain by its author.  
There are NO restrictions on the usage of these scripts.  I would ask that 
if you use this code in another project you give credit, but this is a 
request NOT  a legal requirement.
Projects in the contrib directory are NOT covered by this license.  Please 
contact the individual authors if you have questions about licensing or 
redistribution of user contributed code.

Installation:

1.  Make sure you have the mp3info program.  It is needed to retrieve info 
from the ID3 tags.  If you don't have it the main distribution site is:

http://ibiblio.org/mp3info/

I am currently using version 0.8.5a for development.  This is the 
version distributed as the mp3info package in Debian/Lenny.  Versions of 
MP3DB2 prior to 3.0 used a different version of mp3info by a different 
author.

2.  Run the configure script located at the root directory of this 
package.  This will create the file ~/.mp3db2rc with default configuration 
settings, then allow you to change the defaults with a menu interface.  
When you are in the menus if you don't understand an option you can select 
it and an explanation of what that option does will be printed.
The configure script will also offer to make directories that can be used 
to store the MP3 database and index files.
If you are upgrading from a previous version of mp3db2 that used the 
mp3db.cfg configuration file you should delete it and regenerate 
~/.mp3db2rc with the included configure script.

3.  Use the mp3gen utility to create the MP3 database.

4.  Enjoy

The following scripts are included in this package:

mp3: Command line database query utility.  obviously you can't use this 
until you have added at least one database file with the mp3gen script.

mp3gen: Database generation utility.  Just run this program without arguments 
for help.  Normally you will just need to give the name of the disc you 
currently have mounted as an argument.  this program will not mount the CD 
since it shouldn't be running as root.

makeplete: This tries to generate a text file that contains a list of your 
complete albums with bitrates included.  It still has some bugs that are 
detailed at the top of the script.

mp3ndx: This Generates an index file for the database.  You don't have to 
have an index for any of the scripts to work it is simply a speed 
improvement.  If you do choose to keep an index make sure to keep it up to 
date by regenerating it when you add new CDS to the database.  mp3ndx also 
takes an -a option if you just want to add one database file to the index.

mp3size: This displays the total size of your MP3 collection in MB and GB.  
If you like to brag about the size of your collection this will be your 
favorite script.

mp3dupe: This script will check to see if a given CD's contents are
already listed in the Database.  It has three modes of operation detailed
below: 
1.  Verify directories only:  This is the default mode if no
command line switches are given.  It checks to make sure every directory
on the source CD is also listed in the Database. 
2.  Verify files and directories: -f command line option 
In this mode after the source directory is verified the script will verify 
each source MP3.  This test can take quite some time.
3.  Verify using complete albums listing: -p command line option
This mode will check to see if each of the directories on the source CD is 
listed in the pletes.txt file.  In order for this mode to work the 
makeplete script must have been previously run.  This mode is the fastest, 
but is also the most prone to errors.

configure: This is a configuration editor and general installation utility 
for this package.  It will create and update the ~/.mp3db2rc file which 
all of these scripts load configuration settings from.  It is best to 
re-run configure after upgrading to a new version of mp3db2 as there may 
have been changes in the configuration file.

get_dev_version: This script will attempt to retrieve the current 
development version of mp3db2 using the HTTP protocol from sourceforge.  
It requires either lynx or wget to do the actual HTTP transfer.  Note that 
you can only run this against a vanilla copy of the current stable version 
of mp3db2.  In order to update a development version more than once you 
must start over with a clean copy of the stable version.  The 
get_dev_version script will refuse to run if it detects a version other 
than the version it was distributed with.

ckrelease: This script is used to sanity check the other scripts for 
syntax errors before a new development release is made.  End users of the 
application will most likely find no use for this script.

utils: This directory contains extra utilities that  are not part of the 
MP3 Database suit.  There is a README file in this sub directory which 
explains the scripts it contains.

contrib: This directory contains code that has been sent to me by other 
users of mp3db2.  If I make a change in one of these scripts it is 
recorded in the changelog of that project's directory.

All of the scripts in this package will accept the following "generic" 
options:
--help or -h: This displays general usage information for the given script 
and exits successfully.
--version: Displays version information and exits successfully.

 Notes about file masks:

One part of the program that may require some additional explanation is the 
"mask" variable in the configuration file.  It is possible to maintain 
separate databases and choose which one to query at run time.  For example 
my primary database contains files named mp3_cd_001, mp3_cd_002, 
mp3_cd_003 ec...  The default mask set in the configuration file of 
"*mp3*" will include all of these files if no mask is specified on the 
command line.  I also have mp3 CDs which contain audio books named 
book_cd_001, book_cd_002, book_cd_003, etc...  This makes it easy to query 
one or both of the databases.  For example to query the primary database I 
would give no -m option on the command line:
mp3 ozzy osbourne
If I wanted to look for a book:
mp3 -m book Stephen King
Or if I wanted to query the entire database:
mp3 -m cd up in smoke
As you can see the filenames you choose are very important to the 
operation of the database.  I would suggest that you use filenames that 
are different enough that you can single any group out, yet have some part 
that is the same so you can match them all with a standard shell wild 
card.

Final notes and contact info:

The latest stable and development versions of this program can always be 
found at the project's homepage:
http://mp3db2.sourceforge.net/

I have now completed the change over to using version 2 of the database 
exclusively.  In my opinion version 2 of this program has all the speed 
and features of version 1.  There will not be any more updates made to 
version 1 of the code even if bugs are found.

If you have any comments/suggestions/feature requests or especially bug 
reports, please feel free to contact me at the Email address below.  I am 
always interested to here from someone with an opinion on the program.  
If you do email me, please include "mp3db2" in the subject line of your 
message.  I receive 30 to 50 spams per day so I have had to resort to 
filtering by from field and subject.

I have created a development discussion list for this project.  If you 
would like to stay up to date with project releases and developments or if 
you can help out please visit the following URL to subscribe to the list.

http://lists.sourceforge.net/lists/listinfo/mp3db2-discuss

If you believe you have found a bug in the program it is helpful if you
test against the latest development version.  You can find the current
development version as a diff against the current stable version on the
project's web site:
http://mp3db2.sourceforge.net/mp3db2-devel.diff
You can also use the included get_dev_version script to update a stable 
version to the current development version.

grnd@users.sourceforge.net