MP3Jukebox Design Document
by Jennie Kim Housman some text by Peter Vessenes
MP3 Jukebox : Design Document
I. Essentials
II. Introduction
This document outlines the design and use of the Ybos MP3Jukebox application, built on the ACS 4.1 platform.
III. Historical Considerations
We like MP3s. We work together. Also, once we were in a tiny little
office, with only like 300 square feet, and we all worked at one big
table. Really! One corner of the office looked like the picture on the
right. This meant we could listen to the same stereo, (especially Abba)
without serious problems.
Now, we work in a large office, with multiple bays, and better lighting.
We can't listen to the same songs all the time. People like me (Peter)
get blasted out by the Abba, when it's loud enough for other people to hear.
And, my enthusiasm for Abba is fading after a few years of Dancing Queen.
Now, we can each, as groups, create shared playlists, and download them
to stereos in our bays. This keeps us from being a group of people with
headphones on that never talk, and it also makes me less annoyed with
the office.
IV. Competitive Analysis
Combine the cost of Oracle, a server, and a network topology that
doesn't mind sending out MP3s without streaming, plus ACS installation,
and you've got yourself at least 1,000 or so CDs plus 5 CD changers to
hold them.
On the other hand, you can't vote on the web with your CD changers.
I'd call us neck and neck with the competition.
V. Design
The system allows
- Voting
- Playlist Creation
- Downloading
It fits our rationality test for community applications -- you can annoy
other people with it. (If you can't annoy someone, it's not a community
application.)
We don't
- Stream
- keep tight controls on the MP3 files (no BFILE columns)
VI. API
Much of the API is covered in the mp3-create.sql file. The mp3 package body and the mp3_playlist package body holds all of the PL/SQL functions and procedures.
- mp3.new: creates a mp3jukebox mp3 item
- mp3.delete: deletes a mp3jukebox mp3 item
- mp3.mark_as_deleted: marks a mp3jukebox mp3 item, without removing it from the file system
- mp3_playlist.new: creates a mp3jukebox playlist item
- mp3_playlist.delete: deletes a mp3jukebox playlist item
- mp3_playlist.item_add: adds a mp3jukebox mp3 item to a playlist
- mp3_playlist.item_remove: removes a mp3jukebox mp3 item from a playlist
- mp3_playlist.vote_cast: adds a vote for or against an mp3jukebox mp3 item on a playlist
- mp3_playlist.item_order_swap: swap the order of a mp3 on a playlist with one listed after it
The TCL procedures are in the /tcl/mp3-procs.tcl, /tcl/scanner-procs.tcl files.
- mp3_search_select_sql: returns sql to perform file search according passed parameters
- get_list_of_mp3s: returns the list of mp3 from the approriate mp3 file location
- mp3_name_from_file: returns the mp3 name from the file name
VII. Data Model Discussion
The MP3Jukebox package makes use of the ACS objects system. The creation of an mp3 item adds a row in the mp3_mp3s table as well as the acs_objects table, where the usual meta-information about this object is stored. This is also true for creation of a playlist item (that adds a row to the mp3_playlists table).
Currently, only the playlists are distinguished according to the different mount instances of the mp3jukebox. This functionality is available for mp3s, however, was not utilized in this version of the application.
VIII. User Interface
How to use it
- Create a playlist
- Add some MP3s to the playlist
- Click the headphones
- Enjoy!
Clicking the headphones when they refer to a playlist will download
an m3u file. Both xmms and winamp should be able to recognize this.
You'll need to set up Netscape to deal with the .m3u files correctly;
check out www.xmms.org for more information.
Clicking the headphones when they refer to an MP3 will download the MP3
directly from AOLServer. We don't, for instance, stream.
The publicly accessible pages are in the root directory of the mounted instance. The administrative pages are under the root directory of the mounted instance (/root directory/admin). You must be granted admin on the node to have access to the admin pages.
The public is allowed to view and download available playlists for each mount instance (playlists are mount-specific). The public is also allowed to vote for currently available mp3s on a playlist. Their votes only affect whether an mp3 is included when a playlist is played. Only administrators can remove an mp3 from a playlist. An mp3 is no longer included when a playlist is served, when the total of the votes submitted is less than or equal to the vote total (to remove an mp3), which is set by a site-wide administrator.
Site-wide administrators may create and delete playlists, add and remove mp3s from playlists, choose the vote total, and add and mark_as_deleted mp3s.
Please note that currently, administrators only mark an mp3 as deleted, i.e. an mp3 is not deleted from the mp3_mp3s table, the acs_objects table, or the file system. (The PL/SQL procedure for that is avavilable
but just not used.)
IX. Configuration/Parameters
This package was built on the ACS 4.1 platform.
During installation of a package instance, an administrator needs to set up two parameters:
- 'MP3FileLocation,' the location of the MP3 Files on your server
- 'MP3StagingLocation', an open directory where MP3s will be placed before they are moved to the MP3FileLocation by the scanner.
The general concept is that the MP3StagingLocation should be world writable.
People will dump MP3s into that directory, via whatever means available.
As the scanner is run, the files will be picked up, inserted into the
database, and moved over to the MP3FileLocation.
We use an ID3 scanner written in Perl to check the information in the
MP3s. If none is returned, we just insert based on the title.
X. Acceptance Tests
XI. Future Improvements/Areas of Likely Change
- More highly refined permissioning system
- Playlist administrators and mp3 administrators?
- feature allowing users to "suggest" an mp3, that maybe voted into a playlist
- One user / one vote..
- MP3s, like playlists, context-dependent (we're not sure on this one.)
XII. Authors
Of the software
- Titi Ala'ilima
- Jennie Kim Housman
- Peter J. Vessenes
- Elizabeth Wirth
XIII. Revision History
We like MP3s. We work together. Also, once we were in a tiny little
office, with only like 300 square feet, and we all worked at one big
table. Really! One corner of the office looked like the picture on the
right. This meant we could listen to the same stereo, (especially Abba)
without serious problems.