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

thumb.jpgMp3dj 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.jpgBlazeDS 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:
Testdrive by visiting:

Features:

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:

Using mp3dj:

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

All.jpg

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:

FadeSeconds.jpg

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.

playGrid.pngYou 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:

VisibleColumns.jpg

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:

TrackInfo.jpg

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

Bottom.jpg

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:

Changes for mp3dj-4.9:

Changes for mp3dj-4.8:

Changes for mp3dj-4.7:

Changes for mp3dj-4.6:

Changes for mp3dj-4.5:

Changes for mp3dj-4.4:

Changes for mp3dj-4.3:

Changes for mp3dj-4.2:

Changes for mp3dj-4.1:

Changes for mp3dj-4.0:

Changes for mp3dj-3.0:

Changes for mp3dj-2.1:

Changes for mp3dj-2.0:

Changes for mp3dj-1.3:

Changes for mp3dj-1.2:

Changes for mp3dj-1.1:


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

sourceforge

Last modified: