The mp3dj Project

Mp3dj is a Flex-based web application for searching, browsing, and playing your mp3 collection remotely. Fully featured mp3 player in a webpage includes cross-fade support. Drag-and-drop Winamp compatible .m3u playlist files.

Latest mp3dj release : v4.10 March 2010

Features
Requirements
Installation under Linux
Installation under Mac OS/X
Installation under Windows
Shortcuts and scripts
Using mp3dj
Software bundled with mp3dj
Release Notes

Mp3dj is written in ActionScript & Java - so it's platform independent. It Requires Java, Ant, and BlazeDS. All of the external components are available free, and you don't need to install BlazeDS.

The latest release transitions from an external MySQL server to an embedded hsqldb "pure Java" database engine. The webapp ensures the database always mirrors your mp3 collection. When you deploy and whenever the mp3dj page is (re)loaded, the webapp starts a daemon refresher thread if it's not already running. Running 'ant' deploys the mp3dj web application and starts the Tomcat server.

Provided you already have a JDK and Ant, installation has boiled down to downloading blazeds.zip, editing build.properties, running 'ant', and visiting http://localhost:8400/mp3dj/. Port conflicts with other programs you might be running can be resolved by specifying new values for tomcat.port and/or server.port if necessary. The root directory containing your mp3 files is specified by the mp3.dir property.

BlazeDS is platform independent and the "turnkey" zip bundles Tomcat 6.0.14. The Mp3dj web application uses it's RemoteObject service for quick binary transfers in AMF (Action Message Format). Ant unzips blazeds.zip directly into the mp3dj tree on all platforms. Ant targets to "start" and "stop" perform all server related tasks seamlessly under Windows, Linux, or Mac OS/X. In addition to Tomcat, the sampledb server is started so http://localhost:8400/samples/ is functional. Mp3dj persists to the filesystem, but without a database server.

Mp3dj evolved from a "one-to-many" broadcasting approach to sharing. The idea was to stay out of the player business, and make your collection appreciated by streaming playlists like a radio station. Along came Flash ubiquity and the Flex SDK was open sourced. Flex's mp3 and drag-and-drop support prompted a shift to an "on-demand" sharing model with a fully featured player in a web page. The playlist editor GUI was reduced to a tree and a grid. If you select a playlist, the grid mirrors the contents of an .m3u file in mp3.dir/playlists.subdir. Otherwise, if you search or select a genre or folder - the grid contains tracks you can play just the same, but there's no underlying editing going on when you drag-and-drop within the grid.

Preferences (ex. Fade Seconds and Visible Columns) are stored in files on the client so they persist across sessions. Because playlists are files on the server, they also persist. Everyone with access to your server is welcome to play and edit the common repository. Playlists are Winamp compatible .m3u files containing relative paths so a variety of players can also play them. A handy setup for you LAN.

Checkout source with:

svn co https://mp3dj.svn.sourceforge.net/svnroot/mp3dj/trunk/mp3dj

Testdrive by visiting:

http://mp3dj.homeip.net

Features:

Builds database of mp3 tag information for quick searches.
Single Grid represents both playlists and query results.
Arbitrary columns of tag information can be made visible and sorted/moved.
A tree with branches for Folders, Genres, and Playlists facilitates browsing.
Winamp compatible m3u playlist files are edited using drag-and-drop GUI.
Maintains collection statistics (ex. total hours and average bitrate).
Fully featured mp3 player includes position control, and cross-fade support.
Custom "ticker canvas" scrolls title playing when wider than the window.
Preferences (ex. Fade Seconds and Visible Columns) persist session to session.
Extended Grid and Tree components scroll when you drag near top or bottom.
Bundled Tomcat server is started and stopped seamlessly by Ant.
Integrated hsqldb engine mirrors your collection with no user interaction.

Requirements:

The following external components must be downloaded from elsewhere:

Component	Version	Download Link
Java Development Kit	jdk1.6.0_06	http://java.sun.com/javase/downloads/index.jsp
Ant builder/installer	apache-ant-1.7.0	http://ant.apache.org/bindownload.cgi
BlazeDS	blazeds_turnkey_3-0-0-544	blazeds_turnkey_3-0-0-544.zip

Ant is required to build and install. This is accomplished by saying 'ant' after editing build.properties to configure. The above were tested under Ubuntu 8.10 and 9.10 Linux, Windows XP (SP2), and Mac OS/X 10.4 (Tiger).

Installation under Linux:

1. Download Java Development Kit. The JDK is required to compile the Java source files that are part of the mp3dj distribution; ant will expect to find the Java Compiler (javac) in your PATH so it can build mp3dj. After extracting, define a JAVA_HOME environment variable, and add $JAVA_HOME/bin to your PATH.	http://java.sun.com/javase/downloads/index.jsp Click on the Latest Release [>>Download] button (ex. JDK6 Update 6) and download to a known location (ex. /dist). cd /dist sh ./jdk-6u6-linux-i586.bin vi ~/.bashrc export JAVA_HOME=/dist/jdk1.6.0_06 vi ~/.bash_profile PATH=...:${JAVA_HOME}/bin:...
2. Ant builder is included in Development/Build Tools. Add Ant's bin directory to your PATH so the 'ant command is found.	apt-get install ant vi ~/.bash_profile PATH=...${ANT_HOME}/bin:...
3. Download BlazeDS.	blazeds_turnkey_3-0-0-544.zip I downloaded to /dist.
4. Download and unzip the mp3dj zip file.	http://sourceforge.net/projects/mp3dj cd /dist unzip mp3dj-4.10.zip
5. Configure mp3dj. Set mp3.dir to the directory subordinate to which your ".mp3" files can be found. On my Linux machine it's /music. All playlist.m3u files are housed in /music/[Playlists] in my case.	cd mp3dj-4.10 vi build.properties blazeds.zip=/dist/blazeds_turnkey_3-0-0-544.zip mp3.dir=/music playlists.subdir=[Playlists] server.port=8005 tomcat.port=8400
6. Deploy the mp3dj webapp, and start the Tomcat server. 'ant' is the same as 'ant start'.	ant
7. Visit on localhost with your browser.	http://localhost:8400/mp3dj
8. Now visit in a browser from a remote machine. I installed on a machine called 'tor', so I visit:	http://tor:8400/mp3dj
9. Stop Tomcat server.	ant stop
If you have problems, inspect the Tomcat log:	tail -F blazeds/tomcat/logs/catalina.out

Installation under Mac OS/X:

1. The JDK comes pre-installed, so we simply verify the java compiler is in our path and ready to rumble. Follow directions on the support site if you see "command not found", or want to upgrade.	Click the "terminal" icon on the desktop, and run the compiler: cor:~ marika$ javac -version javac 1.5.0_13 javac: no source files Usage: javac <options> <source files> ...
2. Download Ant builder and add it's bin/ subdirectory to your PATH so the 'ant' command is found. If your not a vi user, use your favorite text editor (ex. TextMate).	<RIGHT>-Click apache-ant-1.7.0-bin.zip Download Linked File as... I downloaded to my wife's home directory. cor:~ marika$ unzip apache-ant-1.7.0-bin.zip cor:~ marika$ vi ~/.bash_profile source .bashrc export PATH=${PATH}:/Users/marika/apache-ant-1.7.0/bin Exit the terminal window (press the red dot in the upper left)
3. Download BlazeDS.	<RIGHT>-Click blazeds_turnkey_3-0-0-544.zip Download Linked File as... I downloaded to my wife's home directory. There's no need to unzip.
4. Download and unzip the mp3dj zip file. http://sourceforge.net/projects/mp3dj	<RIGHT>-Click mp3dj-4.10.zip Download Linked File as... I downloaded to my wife's home directory.
5. Configure mp3dj. Set mp3.dir to the directory subordinate to which your ".mp3" files can be found. All playlist.m3u files are housed in /Users/marika/Music/[Playlists] in my wife's case.	cor:~ marika$ unzip mp3dj-4.10.zip cor:~ marika$ cd mp3dj-4.10 cor:~ marika/mp3dj-4.10$ vi build.properties blazeds.zip=/Users/marika/blazeds_turnkey_3-0-0-544.zip mp3.dir=/Users/marika/Music playlists.subdir=[Playlists] server.port=8005 tomcat.port=8400
6. Deploy the mp3dj webapp, and start the Tomcat server. 'ant' is the same as 'ant start'.	ant
7. Visit on localhost with your browser.	http://localhost:8400/mp3dj
8. Now visit in a browser from a remote machine. I installed on a machine called 'tor', so I visit:	http://tor:8400/mp3dj
9. Stop Tomcat server.	ant stop
If you have problems, inspect the Tomcat log:	tail -F blazeds/tomcat/logs/catalina.out

Installation under Windows:

1. Download the JDK. The Java Development Kit is required to compile the Java source files in the mp3dj distribution.

In a browser (ex. Firefox), visit: http://java.sun.com/javase/downloads/index.jsp.
Click the [Download] button next to the latest release. As of August 2008 the latest release was JDK6 Update 7.
Click (*) Accept License Agreement.
Click Windows Offline Installation, Multi-language.
Click the [Save File] button in the dialog that appears.
Select Save in: Local Disk C:, and press the [Save] button in the file selection dialog that appears.

2. Install the JDK.

Double click My Computer, and explore to C:\
Double click on the downloaded file (ex. jdk-6u6-windows-i586-p.exe).

3. Add JAVA_HOME environment variable. Then add JDK's bin directory to your Path environment variable. This tells the Command Prompt window where to find the java compiler executable (javac.exe). Ant will expect to find the compiler in your Path so it can build mp3dj.

Right click My Computer | Properties | Advanced
Press [Environment Variables] button
Click [New] and add a JAVA_HOME variable with value:
C:\Program Files\Java\jdk1.6.0_06
Double click on Path in the lower (System variable) section.
Then add the following to the end of the value:
;%JAVA_HOME%\bin
(the semicolon at the front separates this new path element from those that appear before it).

4. Verify the JDK is installed and it's bin directory is in your Path by running the compiler in a new Command Prompt window. NOTE: You need to run a new Command Prompt window to pickup the new Environment Variable.

Press Start | All Programs | Accessories | Command Prompt
In the window that appears, type: javac -version
The following message indicates things aren't right:
'javac' is not recognized as an internal or external command,
operable program or batch file.
In that case, explore to the bin directory, record the path, and verify it's what's in your Path Environment Variable. Otherwise, if the correct version is output, your done with this step.

5. Download Ant.

In a browser (ex. Firefox), visit:
http://ant.apache.org/bindownload.cgi
Select the "best available version" (ex. apache-ant-1.7.0-bin.zip)
I download to C:\.

6. Unzip the Ant zip file. All the contents of the Ant zip file live in a single folder (ex. apache-ant-1.7.0) - so we extract directly to C:\.

Single click My Computer, and explore to C:\.
Right click on the downloaded file (ex. apache-ant-1.7.0-bin.zip), and select "Extract All...". Then change the default C:\apache-ant-1.7.0-bin target directory to C:\, and press the Next> button.

7. Add the Ant bin directory to your Path.

Right click My Computer | Properties | Advanced
Press [Environment Variables] button
Double click on Path in the lower (System variable) section.
Then add the following to the end of the value:
;C:\apache-ant-1.7.0\bin
(the semicolon in front separates this new path element from those that appear before it). Then press the [OK] button.

8. Verify that Ant is installed and it's bin folder is your Path by running ant in a new Command Prompt Window.

Start | All Programs |Accessories | Command Prompt
In the window that appears, type: ant and press <Enter>.
The following message indicates things aren't right:
'ant' is not recognized as an internal or external command,
operable program or batch file.
In that case, explore to the bin directory, record the path, and verify it's what's in your Path Environment Variable. Otherwise, if "build.xml not found" appears, you were able to run ant and your done.

9. Download BlazeDS.

In a browser (ex. Firefox), visit:
blazeds_turnkey_3-0-0-544.zip
I downloaded to C:\.

10. Download the mp3dj zip file from
http://sourceforge.net/projects/mp3dj/

In your browser (ex Firefox), visit:
http://sourceforge.net/projects/mp3dj/
Click the Download mp3dj link, and then on the zip file (ex. mp3dj-4.10.zip). Download to C:\.

11. Extract mp3dj zip file. Since all the files in the zip file live in a common folder (ex. mp3dj-4.10), we extract directly to C:\ by stripping the suggested path.

Explore to C:\.
Right click on the downloaded file (ex. mp3dj-4.10.zip), and select the Extract All... menu item. Extract directly to C:\.

12. Configure mp3dj.
Lines beginning with "#" are comments (not engaged). In this step we basically uncomment the Windows lines and make the Linux lines comments. Set mp3.dir to the directory in which your ".mp3" files can be found. On my Windows XP machine it's C:/music. All playlist.m3u files are housed in {mp3.dir}/{playlists.subdir}. In my case, that's C:/music/[Playlists].

My Computer | Explore to C:\mp3dj-4.10
double click build.properties | select from list | WordPad
(engage the appropriate properties - something like:)
blazeds.zip=C:/blazeds_turnkey_3-0-0-544.zip
mp3.dir=C:/music
playlists.subdir=[Playlists]
server.port=8005
tomcat.port=8400
File | Save, press [Yes].

13. Deploy the mp3dj webapp, and start the Tomcat server. 'ant' is the same as 'ant start'.

Start | All Programs |Accessories | Command Prompt
C:\>cd C:\mp3dj-4.10
C:\mp3dj-4.10>ant

14. Visit on localhost with your browser.

http://localhost:8080/mp3dj

15. Now visit in a browser from a remote machine. I installed on a machine called 'tor', so I visit:

http://tor:8400/mp3dj

16. Stop Tomcat server.

C:\mp3dj-4.10>ant stop

If you have problems, inspect the Tomcat log files:

Explore to C:\mp3dj-4.10\blazeds\tomcat\logs,
and double-click on the files there.

Shortcuts and scripts:

go.sh (run flashplayer debugger under Linux/Cygwin)
go.bat (run flashplayer debugger under Windows)
svn co https://mp3dj.svn.sourceforge.net/svnroot/mp3dj/trunk/mp3dj (checkout source)

Using mp3dj:

Hover the mouse over any button or link to display a hint about the action a click will initiate.

At the top is the player, with familiar controls on the left. The yellow area includes a slider with a thumb representing the position. You can click in the slider to send the thumb to a particular position, or drag it by mousing down on the thumb. Right clicking (<CTRL>-click on the Mac) yields a context menu. On the player, this includes an item called Fade Seconds... to configure the player's cross-fading capability:

Below the player, on the left is a tree with branches for Folders, Genres, and Playlists. Clicking the arrow on the left of a branch item opens the branch. You can also open by double-clicking anywhere on the item. Step Up or Down through the lists using the arrow keys.

Create a New Playlist by pressing the plus button on the lower left. Alternatively there's a context menu item called New Playlist (accessible by right clicking on the tree).

The grid is the large area to the right of the tree. The act of creating a New Playlist and renaming it left it selected, and since the playlist is empty - the grid is empty. Add to your playlist by browsing or searching, and then dragging from the grid to your playlist in the tree.

The search text input field is on the lower right. Mp3dj does a search for '' (empty string) when it starts, yielding the entire collection in the grid. As you type characters into the search text input field, the grid will change. Pressing <Enter> updates the grid too. The files table of the mp3dj database is searched for an instance of the search text in name, artist, title, album, or comment.

Clicking the search button to the right of the text input field is equivalent to clicking on the field and pressing <Enter>. If you browse (ex. select a folder) after searching, a single click on the search button refills the grid with your last search result.

You can play any mp3 immediately by double clicking a row of the grid. Mp3dj remembers the context in which you double clicked. If you refill the grid by initiating a search or browsing a folder and wish to return, press the play grid button. Reorder the grid by dragging and dropping tracks within the grid. If the grid represents a playlist, mp3dj is editing a playlist file. For example if the "myplaylist" item in the Playlist branch of the tree is selected, mp3dj is editing mp3.dir/playlists.subdir/myplaylist.m3u. When the current track completes, mp3dj crossfades into the next track in the play grid.

The context menu for the grid includes Visible Columns..., which yields the following dialog:

The columns selected are the columns displayed. This preference and the Fade Seconds preference are placed in a SharedObject and persist session to session. You can drag a column to a new position relative to the others. Clicking on a column header sorts the column.

When a Playlist item is selected in the tree, the grid reflects tracks in an .m3u file. Reorder the playlist by dragging within the grid. Multiple items can be selected for drag within the grid or to a playlist in the tree by using <Ctrl>-click on individual items, or by clicking an item and <Shift>-clicking to select the last item and all items between the two clicks. Dragging near the top or bottom of the tree or grid scrolls any additional items into view.

A Remove Tracks context menu item is available (again through right clicking the grid). It's insensitive till you select rows in the grid for removal. The effect of the remove or reorder operations on a browse/search result is transient, but can be useful when your simply playing the grid.

When a single item is selected in the grid, The A Track Info... context menu item can be selected to show all mp3 tag fields in a dialog:

The message label at the bottom of the interface displays statistics:

The hours:mins:secs duration label above the statistics represents the total duration for the grid contents. The middle button on the left is shuffle, and to it's right is repeat, which has three modes: off, on, and 1. The 1 state is saying "repeat the selected item", rather than the entire list.

The messages column contains information the refresh operation generated.

Message	Description
Bad filename	Filename is not "artist - title.mp3"
No artist	Mp3 tag does not specify "author"
No audio properties	AudioSystem.getAudioFileFormat().getFormat() returned null
No duration	baseFileFormat.propertiesMap.get("duration") returned null
No title	Mp3 tag does not specify "title"
Unrecognized bitrate (bitrate)	Bitrate not variable and not in [16,24,32,40,48,56,64,80,96,112,128,160,192,224,256,320]

Software bundled with mp3dj:

Release Notes:

The 4.10 release is a bugfix release.

Changes for mp3dj-4.10:

Fixed BUG: Clicking on "Sniff'n The Tears" folder doesn't change the grid. Needed to quote apostrophe (') in the getByFolder() sql query string. Now replacing ' with '' (two single quotes).
Tested under Ubuntu 8.10 (Intrepid Ibex).
Tested under Ubuntu 9.10 (Karmic Koala).
Made testdrive website available: http://mp3dj.homeip.net.
Now logging all sql query strings to ./blazeds/tomcat/logs/catalina.out.
Updated Linux Installation instructions to reflect move from Fedora to Ubuntu; replaced 'yum' with 'apt-get install'.

Changes for mp3dj-4.9:

Made mapGenreNumberToText() deal with bare genre number. Was dealing with (17) is Rock, but not 17. No longer putting parenthesis around unrecognized genres strings. These changes were prompted by changes in EasyTAG.
Fixed BUG: Tree items can be out of sync with the grid. Made the files table refresher delete from genre and folder tables, and made the client redraw when treeData is updated. If you've edited tags in your collection, press the Reload button on your browser to initiate a database refresh. It's not until the update operation completes and you Reload once again that the tree and grid will necessarily match. Use 'ant clean; ant' to recreate the database.

Changes for mp3dj-4.8:

Fixed BUG: Under Windows with files in subdirectories 3 or deeper show up in the grid, but double clicking them doesn't initiate play. For example, with mp3.dir=C:/music, and C:/music/NetOK/SubDir60, files in SubDir60 were not playing. When File.separatorChar is \ (Windows) we now transliterate back slashes to forward slashes when entering strings representing "folder" in the database.
Fixed BUG: Generating bogus "Bad filename" messages. Now trimming artist and title variable values rather than what goes in the database since these variables are used subsequently to identify filenames that don't match the "artist - title.mp3" convention. Also changing * from artist/title to + in filename ala EasyTAG.

Changes for mp3dj-4.7:

Fixed BUG: Selected tree item could be out of view after pressing playGridButton. We restore the open branches and select the item that was selected when we double-clicked originally to initiate play, but that item may not be visible. If a tree item was selected, onPlayGridButtonClick() now calls "scrollToIndex()" on the tree.
Propogated app.version from build.xml to the server-side, and made ApplicationService() log it on startup. See blazeds/tomcat/logs/catalina.out. Also updated the run() method in Refresh() to log mp3.dir in a full sentence. Removed resources/version.properties. We propogate by appending to resources/build.properties.
Made ApplicationService output mp3dj version to catalina.out.
Adressed BUG: mp3.dir=/music/BjÃ¶rk not found as /music/BjÃƒÂ¶rk. Corrected Ant side by introducing a filterchain with escapeunicode/ in custom loadproperties. Roadblocked on server side fix to this problem. My only solution required a jump to Java 6, which would lose the primary Mac OS/X 10.5 (Tiger) release, which comes with JDK 1.5.,0_13. The solution required we use properties.load(Reader), and compilation under Java 5 fails because it only supports properties.load(InputStream). The method introduced in Java 6 enables us to say "read UTF-8", while the default encoding used by the Java 5 reader is ISO 8859-1. Resolved to not fix this bug at the expense of requiring Java 6, and backed out of Ant side changes too, so the failure could be diagnosed easily and our build.xml isn't complicated needlessly.
Addressed BUG: When I change mp3.dir from say '/music' to '/music/Beatles', and start the webapp with 'ant', browsers loaded with the old context are broken. For example, clicking on an item in the Folders menu will yield an empty grid. This bug is an artifact of the daemon refresh design. User's need to press their browser's Reload button to update the GUI's reflection of the database. The refresh thread removes before inserting - so we've minimized the window of time in which unremoved items can appear in the interface. Updated the "clean" target to remove db/mp3db. Now when you change mp3.dir, a subsequent 'ant clean' clears the database in a fell swoop.
Added "comment" column to search. The search text field does a case insensitive select of items in the files table that match a substring in name, artist, title, album, or comment.
Migrated from MpegAudioSPI1.9.1 to MpegAudioSPI1.9.4. This change replaced three of the four jar files in the mp3dj distribution by engaging: jl1.0.jar, mp3spi1.9.4.jar, and tritonus_share.jar. Now using mp3.id3tag.length (TLEN) where possible, and falling back on duration. 1.9.4 is the latest, but released 11/30/2005 - so it's crufty and unsupported. Nevertheless, this is the best Java alternative the author has again been able to identify. The upgrade was prompted by an attempt to understand why the total duration for the grid didn't match the total hours displayed in the stats line at the bottom of the interface. I was seeing a difference of 3 hours for a collection of 1426 hours. Now they match for both my pristine collection and a test collection of rogue mp3 files. Note: Duration values can be bogus and still add up. When a duration is way out of bounds save as mp3 to refigure and rewrite the duration id3 metadata using a tool like Audacity.
Fixed BUG: Yielding ActonScript #2032 Stream errors loading files with '#' and other reserved URL char in mp3 file folder or name. Now using escape() in building url for use in instantiating Sound object.
Fixed BUG: The 'artist / title' tickerCanvas display in the player can be empty or stale. Flashplayer has problems parsing rogue mp3 tags. Was never hitting Event.ID3 listener on files misplaced, wrong length, or simply missing artist/title metadata. Double clicking these files would never hit the onId3() handler, and could leave stale values or nothing in the display. Now defaulting to artist and title values from the database, and overriding with ID3info from flashplayer when available and non-empty. When neither the mp3dj refresh operation nor flashplayer can parse both artist and title the file name is used. Adding Bindable variables without the ID3Info layer removed compiler warnings (ex. Data binding will not be able to detect assignments to "artist").
Now delaying creation of mp3.dir/playlists.subdir till it's necessary. Removed validPlaylistsDirectory(), and made it part of newPlaylist(). So we don't create till the [+] button is pressed or <RIGHT>-New Playlist is selected in the tree context.

Changes for mp3dj-4.6:

Dropped the MySQL server requirement. The backend was rewritten to use an embedded pure java database engine (hsqldb). Users are no longer responsible for initiating refresh operations. A singleton Refresh() daemon is run seamlessly by the webapp.
Added server.port property to build.properties. This is the Apache Catalina Server port number. Making it simple to alter server.port and tomcat.port facilitates resolution of possible port conflicts with other programs.
Changed database.dir to mp3.dir in build.properties.
Removed database.url from build.properties. Rather than an arbitrary external MySQL database server, we now bundle hsqldb.jar in mp3dj/db, and use a "no server" file setup. The database url, "jdbc:hsqldb:file:mp3db/mp3db", is hardcoded in ConnectionHelper.java.
Edited ROOT/index.html to include URL to Mp3dj Application too. Created ROOT/docs and added a pointer to Mp3dj Documentation too. See http://localhost:8400.
Removed RefreshApp() and the "refresh" Ant target. Database refreshes happen seamlessly when mp3dj is deployed, and when the mp3dj page is (re)loaded. Refresh() was made into a singleton to ensure only one thread can be running. Output of the integrated refresh operation appears in the server log file (mp3dj/blazeds/tomcat/logs/catalina.out). Rather than creating a new set of *_incoming tables and engaging them in finalize() like in a full backup, we delete rows corresponding to files that no longer exist and update the tag information associated with files that have changed since the last time we refreshed. This is done in place with a single set of (files, folders, and genres) tables. As a result, we can view the database before the first refresh is completed. Tomcat is started from the new "mp3dj/db", yielding mp3dj/db/mp3db/.
Added play grid. Made nextFunction() and previousFunction() feed the player from playGridData so users can search or browse and not destroy a "now playing" context. Added playGridButton, which returns the user to the play grid. Made onGridDoubleClick() store the context including all branch open states so the same tree item is selected when onPlayGridButtonClick() uses what was tree.selectedIndex. We also save and restore searchTextInput.text.

Changes for mp3dj-4.5:

Refrained from starting player at startup.
Made "refresh" target antcall the "install" target to get the ApplicationService to reconnect to the database.
Renamed database.directory property to database.dir in build.properties. Renamed routines and variables in ApplicationService.java and RefreshFiles.java to match.
Engaged blazeds_turnkey_3-0-0-544.zip which includes Flex3 SDK, and Tomcat 6.0.14. Created "unzip-blazeds", which is invoked from the "prepare" target, to recreate blazeds/ when blazeds/blazeds.war is not present. Made the "clean" target remove the blazeds/ subdirectory.
Made "unzip-blazeds" also extract flex_skd_3.zip and runtimes/player/lnx/flashplayer.tar.gz. Made the flashplayer executable, and made the 'go' and 'go.bat' scripts run the bundled debugger.
Removed jboss.* from build.properties, and updated build.xml to deploy to bundled Tomcat server.
Automated the "server.xml edit" to create a /music context to database.dir. Changes to database.dir in build.properties are propagated when you deploy the webapp (see the "install" target in build.xml). A /music context is created by ant when it unzips the blazeds distribution file.
Added "start-windows" and "start-nonwindows" (os family specific) targets to start the bundled Tomcat server.
Made the "run" target deploy the webapp, start Tomcat, and run the browser seamlessly. This is the default Ant target, so simply entering 'ant' in the root mp3dj directory does everything seamlessly.
Augmented start targets with "stop-nonwindows" and "stop-windows" targets. Created separate "-ok" test targets for the matrix of start and stop targets. Added test to ensure scripts exist before attempting to stop. Verifying CATALINA_PID file is available before stopping non-windows servers to avoid messages in the server log when its not running.
Added tomcat.port property to build.properties to facilitate using something other than 8400. Made "install" propagate to the server.xml file.
Refactored getMessage() in session scope into getStats() in application scope. Removed SessionService.java. We've never required client specific state on the server; we have dialogs.
Added "start" and "stop" Ant targets for starting and stopping servers. Made the "run" target depend on "start" rather than "install". Made "clean" depend on "stop" so before removing blazeds/ which contains blazeds/tomcat/bin/${CATALINA_PID}, we shutdown and free up the server ports. Also made the "start" target depend on "stop" to ensure changes to database.dir in build.properties , which are propagated to server.xml get engaged by restarting the Tomcat server.
Updated the go and go.bat flashplayer debugger scripts to use "start" rather than "install".
Added "asdoc" Ant target to recreate docs/asdoc (ActionScript API documentation).
Added Mac OS/X Installation Instructions.
Moved /music <context> from server.xml to blazeds-tomcat-conf-Catalina-localhost-music.xml, and made "install" propagate database.dir. When "refresh" completes successfully it calls "install", and Tomcat hot deploys after the edit so the webapp engages a possibly new database.dir value without restarting the server. Found no other way than a server restart to engage database.url, so we're calling "stop" and then "start" after refreshing successfully.
Removed browser.executable property, and the "run" Ant target. Made "start" the default Ant target.

Changes for mp3dj-4.4:

Fixed BUG: RefreshApp can be silent on connection failure. Dropped use of Logger.global (static). This version will work with either JDK 5 or JDK 6.
Fixed BUG: The Windows Installation instructions present hurdles to novices. Subdivided original 10 step procedure into 27 steps. My wife wanted to enable non admin/developer types, and turned each step into an adventure that grew to be several steps with descriptions of purpose.
Fixed BUG: The Linux Installation needs mysql-server (as well as mysql). Also added instructions for starting and configuring for server restart on reboot under Linux.

Changes for mp3dj-4.3:

Fixed BUG: Files in root won't play. The fix was to make the refresh operation associate a folder value of "." with files residing in database.dir.
Fixed BUG: onGetAll() can generate RangeError: Index out of bounds. Needed to restrict random index chosen at startup to one less than the length of the grid.
Fixed BUG: Play skin can appear when playing. While skipping through bad mp3 files, the player can be stopped to changePosition(), and loadIndex() was reskinng unnecessarily at the wrong point. The fix was to remove the reskinPlayButton() call from loadIndex().

Changes for mp3dj-4.2:

New FEATURE: Now handling search TextInput CHANGE events. This feature was withheld in previous releases because typing 'sss' fast could yield the "All" search result. Because the reply for '' was much larger than the reply for 'sss', the latter could race back from the server first. This implementation serializes so the busy clock matches reality, and ignores intermediate requests (ex. 'ss') when a search is in progress while ensuring a search on the final value is initiated. The grid is not updated while a search is in progress.
Shifted search TextInput background icon (magnifying glass) to separate button. This is so you can click to achieve the same effect as selecting the TextInput field and pressing <Enter> with a single click. The button is handy after you've browsed, and want to refill the grid with the last search result.
Added screenshot of Track Info... grid context menu dialog to Using mp3dj section of homepage.
Fixed BUG: Dropping "gone" item yields "Write playlist failed" Alert. Playlist items are "gone" when a database search on folder and name yields nothing. This can be the result of renaming or moving a file after a playlist is created. file.get("folder") was returning null for gone items erroneously. The fix was to use the folder parsed from the playlist path. So it's ok to drag and drop "gone" items from one playlist to another. NOTE: You can replace a "gone" playlist item by searching for a portion of it's name. If the file was renamed and you find it - drag it to the playlist, select the playlist, and drag the new item up from the end of the list to before or after the "gone" item. Remove a "gone" item like any other - by selecting it, right clicking, and selecting the Remove Tracks context menu item.

Changes for mp3dj-4.1:

Fixed BUG: Under Windows message at bottom (stats) not up-to-date. Refrained from 'ORDER BY id DESC' in finalizing stats table. Now using rs.last() after selecting with 'ORDER by id'. Also no longer caching message.
Replaced initial screenshot in Using mp3dj section of homepage with one from Windows.

Changes for mp3dj-4.0:

The mp3dj GUI was rewritten utilizing Flex2 in mxml and ActionScript. This version features a giant leap from the confines of html and a little Ajax to a rich internet application. Rather than viewing a page of the database, all files are accessible on the client in a scrolled window.
A fully-featured mp3 player was introduced with position control, configurable crossfade, and repeat and shuffle modes.
The interface has been refactored as a result of underlying Flex support for drag-and-drop. This eliminated the need for components, yielding a powerful playlist editor using only a tree, a grid, and a search text input field.
Losing Ices (broadcasting) for the Flex front-end with p/ash
(on-demand) made mp3dj platform independent. This version was tested under Fedora 7 and Windows XP (SP2).

Changes for mp3dj-3.0:

The mp3dj GUI was rewritten utilizing JavaServer Faces. In the previous release, servlets were generating html. Now all html lives in JSPs and backing beans control access to the database and playlist through delegates in the model of a model-view-controller organization.
JavaServer Faces makes internationalization support simple, and it's here in the first version. All labels in JSPs and messages in Java code are centralized in pair of resource files, opening the door for languages other than English. See resources/labels.properties and resources/messages.properties.
Added admin page for editing the configuration via the web interface. The database can also be created/refreshed from the page, which features a custom DHTML progressbar component. This support means you can simply deploy the Web Archive file (ex. mp3dj-3.0.war) and visit the admin page to setup. The interface deals gracefully with a broken configuration and provides instructions for creating a database. Validators check new property values when they're entered, providing immediate "red" messages in a column that collapses when all properties are valid.
All properties live in application context, so they persist across sessions. Default property values are housed in faces-config.xml, which can be edited before building the source distribution. Alternatively you can extract the .war, edit, and recreate the .war using the jar command to your own defaults permanent across deploys.
The refresh operation builds a set of "incoming" tables, which are not engaged until the operation finalizes. As a result, while the operation is in progress, you can continue using the existing database tables. When the [refresh database] button is pressed, it changes to [cancel refresh], so the operation can be stopped. When the operation completes, the progressbar returns to 0%, and the statistics message at the top of the admin page will contain a new date value.
The home page was simplified. A single dataTable represents both the playlist and the database. Rather than adding to the playlist by clicking on a separate files list - this version uses a track menu for all operations. Files are inserted or appended to the playlist by selecting a track number. The same menu is used for removing or repositioning a file already selected for play. The table features a paginator at the top so buttons are stationary. A configuration property (mp3dj.gui.rows) controls the size of the data table.
Controls were consolidated and placed in two rows below a message at the top of the home page. The first row includes the search text field for initiating a query, and a new folders menu which initiates a database query for all files in the associated folder. All playlist controls appear in the second row. The start and stop buttons were removed. Now we're always streaming. The elements dealing with an existing playlist (save, restore, and delete) operate on a single menu.
A [show playlist] button was introduced to display the files selected for play in ascending track number order. While viewing the playlist, the button becomes [show filelist]. This takes you back to your previous search results context. The playlist and filelist contexts are preserved, so you remain on page you navigated to previously in either.
A playing track number menu indicates what is playing now. Selecting a new track with the menu skips too the associated track. The track that's playing and the playing menu appear in red. Other files selected for play appear in green.
A message above the data table to the right of the paginator is updated on each request to indicate what was done last, and along with the paginator indicate the size of the result set. A search generates a message like: 14 found for 'merson Lake', [show playlist] like: 109 in playlist, and selecting from the folder menu might say: 66 in folder.
Added crossfade support. This requires re-encoding with liblame, which was added to Components and is included in the updated install-icecast example script which can be used to install icecast, ices, and libshout. Setting ices.crossfade.seconds to zero disables re-encoding.
Simplified installation by inserting a recognizable variable (ICES_DIRECTORY) into ices.py and having PlaylistDelegate set it with the ices.playlist.directory value. The ices directory can be non-existent initially now too, because the directory, script, playlist.pos, and initial playlist.m3u are created when they don't exist. The source ices.py file lives in <base>/src/com/mp3dj/resources/ices.py.
When the ices.base.directory is changed, ices.py is created in the new directory by replacing instances of ICES_BASE_DIRECTORY while copying resources/ices.py. The playlist.m3u and playlist.pos files are copied from the old base directory. As a result, your streaming the same track after the change.
Both Icecast and Ices are invoked with arguments corresponding to the property sets on the admin page. The configuration file for each is included so you can customize further by engaging your own version of a config file. So, for example, if you wanted a bitrate different from the default of 128kbs - there's no property for that - so you edit the <Bitrate> target you'll find in ices.conf. Pressing the [submit] button or <Enter> kills the ices and icecast daemons and restarts them using the new set of arguments.

Changes for mp3dj-2.1:

Removed the folders SELECT menu. Fixed the width of the files SELECT menu so the scrollbar is visible when the other controls are visible. The folder name is visible when you hover over an option (by way of 'title').
Removed the search field types (the artist, title, and album radio buttons). Entering a search string initiates a search on all three fields. Moved the search field to the top of the page to distinguish it from the other controls.
Made the header (statistics title) a message, which is displayed on startup, or when no other messages are reported. This raised the playlist by a line vertically, and keeps the playlist from jumping up and down. Made all controls generate a feedback message.
Made pathnames in build.properties absolute, so Tomcat can be started from an arbitrary directory. Relative pathnames are fine and make the setup simpler, but assumed you start Tomcat in the main directory. To be more flexible in this regard a separate ices/ subdirectory was created to designate an absolute path users can change by editing build.properties. In addition to editing the absolute paths in build.properties, a step was added the Installation section of the homepage to edit the absolute paths in ices/ices.py (the python script for the source client). Now setting PYTHONPATH to the "ices.directory" to find ices.py python module.
Made skipToo controls start streaming if ices is not already started.
Now sorting the restore and remove SELECT menus.

Changes for mp3dj-2.0:

The database was modified, so you'll need to refresh your database before engaging the new version. Added 'id' field to folders table. Removed the 'toget' and 'bitrates' tables.
Requests for a simpler, more intuitive interface were addressed by removing facilities designed to help build and manage your collection. This version is player-centric, and consists of a single page.
The toget page was migrated to a separate application, bitrates was removed, and 'files' and 'folders' were collapsed into a pair of SELECT menus, which were combined with the 'playlist' page.
Speeded the database refresh operation for large collections by deferring computation of folder percentage values till a single pass after all files and folders are added in RefreshFolders.finalize().

Changes for mp3dj-1.3:

All changes for the 1.3 release were suggested by Peter Petermann (PPetermann@vivaplus.tv).
Created PropertiesSingleton class which reads build.properties using getResourceAsStream() from a copy created in the classpath by the compile target of build.xml. Now we read build.properties once for all classes, and build.properties is no longer expected in CATALINA_HOME.
Added separate check and message for case where build.properties file is not found. Now we generate separate messages for "Unable to open" and "Failed to read" build.properties, and terminate in both cases.
Added copyright notices and licenses to Software used by mp3dj.

Changes for mp3dj-1.2:

No longer flagging the following as bad bitrates: 16,24,32,40,48,56,64,80,96,112
Added 'messages' field to the files table, and removed the 'bad' table.
Made the refresh operation generate uniform "Skipped" messages for files which could not be added to the database.
Added 'messages' field to the stats table, which shows total number of files with messages.
Fixed "16 matches 160 too" bug by making bitrates search exact rather than wildcard.

Changes for mp3dj-1.1:

Updated docs/ with homepage in html, engaged on sourceforge.net.
Created and migrated cvs repository to sourceforge.net.
Created TODEW file for tracking potential changes.
Now including dist/ in .tar.gz (excluding .tar.gz itself) so the .war is included in the tarball.
Made 'ant test' extract .tar.gz in dist, and deploy .war to mp3dj-version.
Added "no duration" to bad messages.
Added "id" field to stats table to avoid "Duplicate key" exception when refresh runs were performed back-to-back within a minute. The "id" field replaces the "date" field as the PRIMARY key for the stats table.

Email comments and bug reports to the main author: Kirk Erickson
Project Page: http://sourceforge.net/projects/mp3dj
Home Page: http://mp3dj.sourceforge.net
Testdrive Page: http://mp3dj.homeip.net

Last modified: