ProMP3 - Apache module for music organizing, playing and streaming mp3 files.
# Using Apache::DBI is optional PerlModule Apache::DBI
# The main configuration file for ProMP3 # set the correct path for wherever you place it PerlRequire /path/to/promp3.handler.pl
# require the ProMP3 module PerlModule ProMP3
# 'promp3' (in the "Location" below) can be
# whatever you choose but remember this for later
<Location "/promp3/">
SetHandler perl-script
PerlHandler ProMP3
</Location>
This module will import information about your mp3's into a database and use that information to either play them directly from the webserver, or stream them to the client.
What sets ProMP3 apart from the rest of the mp3 tools is that it does play mp3's from the server. Meaning it uses Xmms on the server and sends the music out a soundcard on the server. It's on my To-Do list to add support for other players.
-- Can play directly from xmms on the server ...or
-- Allows streaming of mp3's over http
-- Categorizes by album genre for later displaying
-- Allows creation of ``custom'' categories to pick out your favorites and full editting capability of the custom lists.
-- Allows random selections: ``Play 100 tracks from Rock'' or ``Add 300 tracks from Jay's Favorites''
-- Allows full text searching on Artist, Album or Song title.
-- probably a few more smaller points I can't think of.
ProMP3 came about from working in a fairly open office with fairly open people. And also the desire to control a whole-home stereo from any of the multiple computers throughout my house. I couldn't find any tools to do this. To make matters worse, the streaming software I did find was geared towards napster-crazy folks who want to listen to the 200 songs randomly through streaming. Nothing I tried (or even wrote in the beginning) could withstand the 1000+ plus albums in my collection. They were either too slow, or impossible to quickly find what I wanted.
So the things I focused on was organization, speed and playing from a central server. I added streaming later to please the napster-crazy folks.
See the b<INSTALL> file for specific instructions.
Once you get everything installed, and everything seems to be running, it's time to fire up a browser. As much as I hate to admit it, Netscape 4 is not the browser to use for ProMP3. Everything will work just fine, but for some reason, it takes longer for Netscape to render the page then generating it and downloading does. Internet Explorer seems to render the fastest while NS6 is a close second.
SIDE NOTE: I spent way too much time on the pretty-factor of the package. There is heavy use of javascript and style sheets. You must use a browser that supports these and be sure that they are allowed.
Go to the webserver and the directory specfied in the <Location> tag in the httpd.conf file. Using the default would translate to http://your.server.com/promp3/. Of course, an IP address can be substituted in place of your.server.com. This should bring up the intial page. If you have songs loaded in xmms already, you may see them listed on this page. Let's take a moment to look at what's being displayed here.
There are four ``drop-downs'' along the top of the window, currently they are labelled ``Category'', ``Random'', ``Search'' and ``Edit''. You can click on any one of them and an area should slide down to reveal actions you can take. I spent a lot of time getting that sliding motion so enjoy the geek-factor to its fullest.
This allows you to quickly pick a category (or ``genre'') to view with the purpose of listening to it. You'll see later how to stream them or put them into the playlist. Once you've created custom categories, you'll see them listed in the bottom surrounded by quotes.
This allows you to ``Add'' to the playlist or ``Make a new list'' where you specify a number of tracks to pick randomly from a category or custom category. First, you'd specify if you'd like to ``Add'' to the current list, meaning whatever is currently in the playlist stays there, and the tracks will be added to it. Otherwise you can wipe out whatever is in there and create a new list of the random selections. The category selection here is the same as under the category section.
This enables full text searching on Artist name, Album name, or Song title. Just pick what you'd like to search on, then type what you're searching for in the text box, and submit it. It uses a full pattern matching system so the less you type the more you'll get back. And typing nothing at all returns everything which currently is the only way to view everything in your collection. This search is not case sensitive so ``bach'' will match ``Johann Bach''. ``Ann'' will match ``Johann Bach'' as well as ``Anne Murray''.
This is to edit your custom categories. Just choose a custom category (If you haven't created any, nothing will be in the drop down). This will show all of the albums in custom list and allow you to remove the unwanted albums. Take note, you can't play anything from this screen, just edit.
Also at the top is a list of what's currently playing, the Artist and the Song title, and the Album it's from. It will try to deduce if the player is stopped, paused or playing and the current position in the track.
The Side bar, contains the really good stuff. At all times the controls for the player on the server will be there (even if you aren't allowed to control it).
The first thing is the current volume in a percent range from 0 to 100. The picture below it will display it rounded to the nearest multiple of 10. You can click anywhere on that image to set the volume. The smaller end of the slope represents quieter and the bigger end represents louder. So by clicking on the very right, you'll set the volume around 100%, clicking on the very left, you'll set the volume down around 0%.
The next box is the player controls, these should be pretty self-explanatory and I won't talk much about them. But I couldn't find a way to poll xmms for the current random setting or repeat setting. So you'll have to guess.
The text links below the controls are the actions you can take. On the bottom of every page will be the ``Current Playlist'' option, which will show you the contents of the current playlist. You should always have this option even if you're already on the current playlist. Also, if you're coming from a host not allowed to control the player or to stream, this will be the only option. The other actions may or may not show up depending on what kind of page your viewing. A common action is ``Invert Selection'', which will take any checkboxes you have selected and invert them to not selected and vice versa for boxes not selected. The others should be self explanatory, such as ``Stream Selections'' will stream the selected tracks. etc etc.
There isn't too much to explain here. This is where you'll see the tracks in the current playlist, or the results of a search, or the results of selecting a category, or editting a custom category. But there are a few things I'd like to point out, In the ``Current Playlist'' you can click on a track to start playing that immediately. In other types of listings you can click on the album title to popup a box showing the tracks on the album.
NOTE: In some versions you'll see pencil by the album name, that is currently an unimplemented edit feature to edit the labels on the album and tracks.
I won't lie, the setup isn't easy. But I've tried to make everything run as smooth as possible, but only to a point. ProMP3 is on it's third or fourth major rewrite and I want to finally get it out the door and to the public.
Contact me with any questions or concerns.
Jay Jacobs jay@lach.net
ProMP3 is about 99% my own code. There may be a few lines from Apache::MP3 by Lincoln Stein in there. The very first version of ProMP3 was called ``Apache::MP3Playlist'' and was based on a pre 1.0 version of Apache::MP3 by Lincoln Stein. I ended up taking his advice (``become a contributing Netizen!'') and evolved my orginal ``Apache::MP3Playlist'' into the ProMP3 you have now. But I would like to thank Lachlan Dunlop and my coworkers at LachNet Inc. for putting up with my ``does that work nice for you?'' and ``does that make sense?'' and the ever present ``Hey, try this out.''
perl, mod_perl, and that kind of stuff.