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

Small Office Pic 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 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


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.

The TCL procedures are in the /tcl/mp3-procs.tcl, /tcl/scanner-procs.tcl files.

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 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 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: 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

XII. Authors

Of the software

XIII. Revision History