MP3Cattle is a Java based GUI for a database that contains mp3 information.
MP3Cattle allows a user to build a play list based upon rankings/genres/labels
or by selecting from the available artists/albums/songs. MP3Cattle allows
multiple users to have different rankings/genres for one collection of
mp3's, allow different playlists to be generated based upon the current
user. Users can also limit a query based upon a size or time limit.
MP3Cattle is now released as a .jar file with all needed java packages. The
source code for MP3Cattle is also included in the .jar file.
MP3Cattle depends on a relational database.
Currently MP3Cattle only supports MySQL. I was using v3.22.27 and v3.22.32
of MySQL during testing and development, which is a bit old but I don't
think newer versions should give users any trouble. You can dowload
MP3Cattle uses the packages below. These packages are now bundled as part
of the MP3Cattle .jar file and do NOT need to be downloaded and installed.
They are listed here to show support for other Open Source projects.
JDBC MySQL Driver
MP3Cattle uses JDBC to communicate with MySQL. It uses the MM.MySQL JDBC
driver located here.
I've tested MP3Cattle using 1.2b, 2.0pre5, 2.0.2 and 2.0.4.
MP3Info Java Package
MP3Info is a set of classes that gives access to ID3 v1.x information.
MP3Cattle was tested using v1.5 of MP3Info which can
be downloaded here.
LOG4J is a flexible logging mechanism that MP3Cattle uses to log information
to a file and/or a file. You can download the latest version
was tested with v1.1.1.
You can download the latest version here.
MP3Cattle uses MySQL as its backend database and currently is the
only database supported.
In v1.2.0 of MP3Cattle there should be a setup directory. In this directory
you will find two scripts setup_db.sh or setup_db.bat. These scripts
will setup the mysql database for you, use the .bat for Windows and the
.sh for unix/linux. If you are on a Windows system try running setup_db.bat
from the command line so that you can see any errors that are reported.
One thing to check if you do have errors is that MySQL is currently
Once you have the database setup you are ready to setup the configuration file.
MP3Cattle gets information from the mp3cat.cfg file, that resides in the
directory where MP3Cattle.class resides. This file has the standard config
The supported variables are as follows:
||Directory to find mp3 files that need to be added to the database
||Root directory where all mp3 files will be stored
||The default user that MP3Cattle will start with
||Path to where you want to save your mp3 play lists
||Set to true if files in the unsorted directory should be added when
MP3Cattle first starts to load. If set to false the unsorted directory
is initially ignored. However the Refresh Tree button would take into
account any files listed in the unsorted directory.
||If this value is set to true, the Artist,Album,Title and Track ID3
fields, if these fields don't contain any values, will be defaulted
to MP3Cattle's values for these fields automatically when the Song
Propterties dialog is brought up.
||This variable is the command that is used to launch a play list. The
value should include a %LIST% reference which is replaced by the tmp
name of the playlist. Example: /xmms/path/xmms -p %LIST% &. On linux
and unix platforms make sure to include the & to run the player in the
background. For windows machines you don't need to worry about this.
||This variable should be set to a path where you will be mp3 files that
will be added to MP3Cattle using the mp3 file's ID3 tags. You will also
be able to edit the file's ID3 tags from within MP3Cattle.
||This variable should be set to the host that is running the database.
Set this to localhost if MP3Cattle is running on the same machine as the
||This variable is set to the log4j config file. The default logging.cfg is probably all you need.
||Path that will be appended onto files when saved as a playlist.
MP3PATH was removed in v1.1 since it was used exactly as MP3ROOT.
||NOT USED as of v1.1
||Path that will be appened onto files when saved as a networked playlist.
REMOVED in v1.1. v1.1 allows you to specify an alternative path in
the save play list dialog
||NOT USED as of v1.1
Once you have setup your mp3cat.cfg file you are ready to compile the MP3Cattle
source. Compile all of the java files in the mp3cat and mp3cat/mp3cat directory,
javac *java mp3cat/*java from the mp3cat directory. Once you successfully
compile MP3Cattle you are ready to start using MP3Cattle.
See the User's Guide for the details.
Here is a listing of error codes, what they mean and where they are in the code.
The name of the error is: NAME_OF_SOURCE_FILE.REASON.
In v1.10 and later versions the error codes give more details of the problem.
I'm hoping in most cases the errors will be enough information to give you
a good idea of what the problem is.
|Error Code||Reason / Fix||Version Added|
||Could not find the mp3cat.cfg file. Currently MP3Cattle looks in
the directory where the MP3Cattle class is found. Place a valid
mp3cat.cfg file in this directory
||Had problems reading your config file. This is a java.IO exception.
||Problem creating your database connection. Somethings to check:
- database is running
- you have the mm.mysql driver installed and in your CLASSPATH
- You have the correct user and password setup, user: mp3 with
||The song naming format is incorrect. The correct format is
||The song naming format, for a Various Artist, is incorrect.
The correct format is:
artist/album/track_artist - songname.mp3
MP3Cattle uses JUnit as its testing
framework. If you want to run the tests that come in the mp3cat/tests
directory you will need to download the junit java package.
Once you have JUnit installed you can run individual tests or
AllTestsSuite to run all of tests on your MP3Cattle installation.
Here is a current listing of the
If you want to report a new bug just follow the above link and click
Submit A Bug link.
To help determine what the problem might be you can turn on logging
by setting all categories in the logging.cfg file to DEBUG and
then running MP3Cattle to try and reproduce the bug. If you do
this please include this with any bug report or email.
v1.21 - 10/20/2001 Maintainance Release
v1.20 - 09/05/2001 Evolution Release
- MP3ItemProperties Dialog boxes now remeber where they
were where there is more than 1.
- You can now double click items in the play list table
- Some internal changes to make code more robust
- MP3CatDBI interface was created
- Database code cleanup
- Added better support for Album/Aritst merges
v1.10 - 03/14/2001 Evolution Release
- It takes a long time to get the correct play
length of an mp3. Right now the 3rd party
package I'm using is not
looking at the VBR time tag so every frame
must be counted to get the correct time. I've
talked with the maintainer
of the package and a fix should be coming.
Once this is fixed the time constraint
functionality should work much better.
- Items from the unsorted directory will not be
created if the artist/album/song contain escape
- Fixed issue where Alternative path was not
- Fixed ranking bug where an item that was added
would not receive the proper ranking.
- Fixed bug where file handles were not being
- Fixed a bug where a name change could result in
misordering if there were only two items
- Added the DBCheck feature that will verify that
the file system and the database are in sync.
Any items found on the file system that are
not in the database are added and any items not
found on the file system are removed from that
- Removed buttons in the status panel and
replaced them with right click menus.
- Moved the building of the MP3Tree into its own
thread to help performance.
- Added support for sorting columns in the query
- Added .jar file with release.
- Added ability to limit queries. Currently the
limit is shown by different colored cells in
the playlist table.
- Added ability to move rows around in the Play
List table. Holding down the control key and
using the up/down arrows it is possible to move
single rows around the table.
v1.02 - 01/21/2001 Maintenance Release
- Added an unsorted directory option. This allows you to have a directory
where unsorted mp3s are stored. You can then edit these mp3's ID3 tag
and then refresh the tree to add these mp3 files into MP3Cattle.
- Added ID3v1 support. Thanks to the mp3info java package.
- Added ability to change rankings for multiple items. If you double
click on a group of items, you will cycle through all selected items.
- Added MVC pattern for genres/labels/artist/album lists. (BUG: 225036 and
- Added delete key functionality to Tree and query result table
- Added some command line arguments: -c conf file to use a different config
file, --useTestDB to use mp3_test instead of mp3 and --help or -h for
- Added Launch PlayList button, which launches a mp3 player with the playlist
that is currently listed in the query result table. The user can set
their player in the config dialog.
- Added Clear List button, to clear the current playlist.
- Added ability to specify the database host in the config dialog.
- Added ability to specify a different MP3Path for saving play lists. This
is useful for networked machines.
- Added keyboard functionality to: add items to play list, launch the play
list, save play list, clear play list, refresh the tree.
- Added ability to store a play list with an alternative MP3Root. This would
be useful in the case of network mappings.
- Added ability to change the track number that is stored in MP3Cattle's
- Fixed bug in init_db.sql script that had columns as BINARY type.
- Fixed bug that didn't delete all user information when a user was deleted
(BUG: 226947 )
- Fixed bug that casued multiple user rankings to conflict with one another
(BUG: 405879 )
- Fixed a problem if two songs had the same name in an album. Now if there
is a name conflict a number is added to the end of the song name and
this continues until a unique song name is found. ie song.mp3,
song 1.mp3, song 2.mp3 (BUG: 407480)
- Fixed problem where an artist or album could conflict with an aritst or
album of the same name, but with a different case. (BUG: 407482)
- Fixed multi user ranking issue, where rankings of one user would not allow
another user to rank a song by means of an artist or album. (BUG: 407483)
v1.01 - 12/20/2000 Maintenance Release
- Fixed album ranking bug. If an album doesn't have a ranking
it will by default use the artist ranking (BUG: 127154)
- Fixed problem when moving mp3 files around (BUG: 127152)
- Fixed bug when merging two albums together not all tracks appear
- Added more tests to the testing framework. Inlcuding tests that
test all fixed bugs.
v1.00 - 11/01/2000 Initial Release
- Changed main class from Test.java to MP3Cattle.java
- Throws an exception if the Add directory doesn't exist (BUG: 125035)
- Determines if the database connection is closed, and
reopens it if needed, before communicating with the database.
- Added initial Testing framework.
- Started to add better error codes.
- Added more variables to config file.
- Added a init_users.sql script to setup the mp3 user with mp3 as the
password and the mp3 and mp3_test databases.
- Fixed bug that would throw an exception when the file name was incorrect.
- Aded the mp3scrubber perl script
Here are some things that I would like to do in the future:
- ID3v2 info/editor
- Nomad Jukebox/MP3 Player support. Taking a playlist and copy the files
to another directory so that they can be downloaded easily into a player.
- Better support for various artists from ID3 information.
- Add a MP3Item interface to help clean up some code
- Database layer cleanup.
- Drag and Drop to playlist
- Genre/Label database table merge
- Ability to retain rankings,genres,labels between items and to set these
values easily for a group of items.
- Use DeleteOnExit for tmp files
- Backup helper (So you can keep track of where mp3s are on CDRs)
- A better or advanced query interface
- More information in the playlist panel
- Integration into the AMS system. See freshmeat for AMS info.
If you have any questions/comments/bugs please send me an email at
MP3Cattle is hosted on: