MP3Cattle's Sourceforge Project Page


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 MySQL here.

Good News

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.


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 here. MP3Cattle was tested with v1.1.1.


You can download the latest version here.


Database Setup

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 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 running.

Once you have the database setup you are ready to setup the configuration file.

Config File

MP3Cattle gets information from the mp3cat.cfg file, that resides in the directory where MP3Cattle.class resides. This file has the standard config format of:


The supported variables are as follows:
ADDROOT Directory to find mp3 files that need to be added to the database 1.00
MP3ROOT Root directory where all mp3 files will be stored 1.00
DEFAULTUSER The default user that MP3Cattle will start with 1.00
MP3PLAYLISTPATH Path to where you want to save your mp3 play lists 1.01
ADD_UNSORTED_ON_LOAD 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. v1.10
DEFAULTID3INFO 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. v1.10
PLAYER 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. v1.10
UNSORTEDPATH 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. v1.10
DBHOST 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 database. v1.10
LOGCONFIG This variable is set to the log4j config file. The default logging.cfg is probably all you need. v1.20
Depreciated Variables
MP3PATH 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
MP3NETWORKPATH 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.

Error Codes

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 CodeReason / FixVersion Added
MP3Cattle.ConfigFileFailure 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 v1.01
MP3Cattle.ConfigReadError Had problems reading your config file. This is a java.IO exception. Cause??? v1.01
MP3Cattle.MP3ManagerSQLError Problem creating your database connection. Somethings to check:
  • database is running
  • you have the mm.mysql driver installed and in your CLASSPATH environmnet variable
  • You have the correct user and password setup, user: mp3 with password: mp3
MP3Manager.SongFormatError The song naming format is incorrect. The correct format is artist/album/track_songname.mp3 v1.01
MP3Manager.VariousArtistSongFormatError The song naming format, for a Various Artist, is incorrect. The correct format is: artist/album/track_artist - songname.mp3 v1.01

Testing Framework

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 known bugs.
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.

Version History

v1.21 - 10/20/2001 Maintainance Release v1.20 - 09/05/2001 Evolution Release v1.10 - 03/14/2001 Evolution Release v1.02 - 01/21/2001 Maintenance Release v1.01 - 12/20/2000 Maintenance Release v1.00 - 11/01/2000 Initial Release


Here are some things that I would like to do in the future:


If you have any questions/comments/bugs please send me an email at
MP3Cattle is hosted on: SourceForge Logo