MP3box v 0.3

Web-based remote control for SoundPlay

Scot Hacker, 10/9/99
Updates at www.betips.net/software.

See Revision History and read docs carefully for changes in this version. Changes to installation/configuration over the previous version are marked in bold as Update.

---

About

MP3box is a perl-based system for controlling SoundPlay from a Web interface on a remote or local TCP/IP-connected BeOS box, probably located in a home entertainment system. It can also be used over a LAN or anywhere on the Internet, with appropriate permissions. While MP3box was designed for remote use on headless machines, the system can just as easily be used for browsing and navigating a collection of MP3 files on a local machine.

Unlike similar systems for Linux or Windows, MP3box is heavily attribute-based. All page views depend on finding valid MP3 attributes for display, and playlist creation is also completely dependent on having indexed MP3/ID3 attributes. A snippet of the web interface is shown to the right. Click for full-size version. See also the control base for the system (currently undesigned).

MP3box lets you:

• Navigate through collections of MP3 files, playing either entire directories or individual tracks.

• Play entire playlists or selected tracks from playlists.

• Stop, start, and change the pitch and volume of SoundPlay.

• Query your system for MP3 files matching any criteria, much as you would from the BeOS Find panel, but through a web interface. Query results can be saved as playlists, and will show up immediately for access from the control base.

While I intend to continue development of MP3box/BeOS, I am seeking bug fixes and feature enhancements from other users who intend to use the system. Please consider this a collaborative project, open to all comers.

---

Installation

You'll need to have the following software installed on your BeOS machine to run MP3box.
Please read the Installation and Configuration sections completely.

1. You must be running a BeOS-based, CGI-capable Web server. I use RobinHood.

2. Update: Place the contents of the server_root folder in the root of your web server. i.e. you'll have, for example:

   ~/public_html/cgi-bin/mp3_base.pl
   ~/public_html/cgi-bin/mp3_list.pl
   ~/public_html/cgi-bin/mp3_browse.pl
   ~/public_html/cgi-bin/mp3_query.pl
   ~/public_html/mp3box/and_its_files_and_subdirs
   

   Note that this arrangement is different from v0.1 because some configurations of RobinHood choked when using a subdirectory of cgi-bin. If you installed v0.1, you can now delete the mp3box subdirectory of cgi-bin.

3. You must have perl installed on your system. If you don't already, you'll find it in the /optional/develop folder on your system if you installed the optional items with R4.5. Otherwise, get it from BeWare.

4. You must have Tom Spindler's Be::Attribute perl module installed. You can install this automatically from the command line (via CPAN), once perl has been installed. Complete installation details here (it's easier than it looks).

5. Update: If you want to run MP3 queries, you'll also need Simon Huet's Be::SimpleQuery perl module installed, which allows for case-insensitive queries. Look in the tools folder in this distribution, unpack the archive, and type make install. You can then delete the archive and source folder.

6. And of course, in order to run queries on BeOS, you must have indexes for the attributes you intend to query. For each volume on which you're storing MP3s, open a Terminal and cd to that volume, then type:

   mkindex Audio:Genre
   mkindex Audio:Artist
   mkindex Audio:Title
   mkindex Audio:Album  
   

   ... adding any other genres you intend to query. If you can run a successful query from the BeOS Find panel, you'll be able to do it from the mp3_query.pl page. Because BeOS indexes only index attributes *after* the indexes have been created, you'll have to make sure those old attributes get re-rewritten. You can do this be copying folder from one location to another, or by running id3attr over your directories, or by running the processtracks script in this distribution, or by encoding all of your new MP3 files with a tool like RipEnc, which takes care of this automatically.

7. Update: You'll need the latest version of Attilla Mazei's hey to send messages from the perl scripts to SoundPlay. If you already have hey installed, please get the latest version, or else several things won't work (we use the new -s flag to suppress the output, and to enable seeking backwards in SoundPlay. Place hey in your path (~/config/bin).

8. Put some playlists in the folder mp3box/playlists in your server root. Playlists must have the filetype text/x-soundplay-playlist or they won't be recognized by SoundPlay.

---

Configuration

Some files and scripts in MP3box depend on knowing paths specific to your system. Thanks to Justin Sherril, this can now all be done from a single web page rather than having to edit individual scripts.

Open a browser and enter http://your_ip_or_domain/cgi-bin/mp3_settings.pl. Enter your default playlist directory (this should be something like ~/public_html/mp3box/playlists ), the default volume name you want to be used on the query page, the ip address or domain of your server (the default should always work when using the system locally), and any number of directories to browse from the Browse function.

Click Update Settings and wait 40 seconds (if you know how to fix this delay, let me know ... we believe we're doing everything right here... this might be a RobinHood problem).

---

Preparing Your System

Because MP3box depends completely on having ID3 tags copied into ID3 attributes in the filesystem, you won't get far if you haven't been doing this all along. You may find Jonas Sundstrom's collection of MP3 attribute management tools useful for this, as well as the id3attr tool mentioned earlier. In any case, you must have the following attributes attached to the audio/x-mpeg filetype:

Artist Title Album Track Year Comment Genre Rating

Audio:Artist Audio:Title Audio:Album Audio:Track Audio:Year Audio:Comment Audio:Genre Audio:Rating

String String String Int32 Int32 String String Int32

visible visible visible visible visible visible visible visible

editable editable editable editable editable editable editable editable

Once your filetypes are set up, you may find the script processtracks in the tools folder useful. If you're using MP3box on a local machine, it will be useful only if you haven't been religiously setting your MP3 attributes all along (if you use RipEnc to do all your encoding, you'll be covered :). If you're running MP3box on a home entertainment system and FTP'ing your files into place, they'll lose their attributes when transferred. processtracks will let you re-attribute all your tracks quickly through a telnet session. Of course, processtracks is only useful if you've been storing your ID3 tags religiously, since those aren't lost in transfer.

It works by finding a list of all MP3 files in a given directory structure, then making sure each one has the correct MIME type (audio/x-mpeg), then copying those files' ID3 tags to attributes and adding appropriate indexes to disk volumes if necessary. processtracks depends on the presence of id3attr being somewhere in your path. Edit the first line of processtracks before running it and make the path is equal to the path where you store your MP3 files.

---

Usage

1. Launch SoundPlay. I'm working on auto-launching SoundPlay if it isn't running, but I've hit a snag. See the code at the top of mp3_base.pl if you think you can help.

2. Open a browser and enter http://your_ip_or_domain/cgi-bin/mp3_base.pl. This is the base of operations, and everything can be controlled from here -- directory browsing, playlist listening, playlist creation, and SoundPlay controls. Bookmark that page.

Tip: When creating queries, start broad -- don't try to be too specific, unless you have a gazillion MP3 files. Start by entering criteria only for the genre, for example. Also, if most of your tracks are in just a few genres, edit mp3_query.pl to put your most-used genres at the top of the list.

---

What the Files Do

mp3_base.pl: Builds the control page. Sends commands to SoundPlay. Dynamically generates a linked list of available playlists. Lets you browse through directories full of MP3s

mp3_list.pl: Used when playing playlists. Functionally similar to mp3_play.pl. Operates on parameters passed from its own URL.

mp3_play.pl: Used when browsing and playing directories and files. Functionally similar to mp3_list.pl. Operates on parameters passed from its own URL.

mp3_query.pl: An interface for building playlists based on ID3/MP3 attribute queries. This script shows three different faces depending on whether you're building a query, reviewing query results, or saving / playing a playlist from query results.

mp3_settings.pl: Builds a web form that lets user establish common settings to be used by all scripts.

mp3_common.pl: Holds default settings and establishes routines that can be called from any script.

---

To-Do List / Known Bugs

These are issues to be worked out. Anyone is welcome to submit fixes and improvements on these.

• SoundPlay must be launched before anything will work. I've got some code in mp3_base.pl that will check the system roster to see if it's running, and launch it if not. It works, but won't return control of the page to the browser and I don't know why. Suggestions welcome.

• It's not possible to navigate back up through directory structures without using the browser's back button or returning to home base. I've got a bare start on this, but it isn't complete. Suggestions welcome.

• Missing or badly formed attributes will appear as garbage in the page. It serves as a nice reminder of the importance of setting all of your attributes properly, but it's still annoying. I tried to do some error checking for this but failed. Help needed.

• There are currently no Next/Prev controls. This is because it's a bad idea to send scripting messages to interface widgets since their views might move around in the layout in the future. This could be gotten around using perl, though it would take some pretty tricky parsing of lists that I haven't even looked at yet. Also see below on the SoundPlay SDK.

• SoundPlay 3.4 and beyond includes an HTTP plug-in interface, and the SDK is downloadable from Marco's site. There are potentially a lot of cool things we can do with this interface, and someone with vision and skill should look into ways to integrate its features into this project :). For instance, it may be the easiest way to get Next/Prev controls working.

• Playlists must have the MIME type text/x-soundplay-playlist or they won't be recognized by SoundPlay. I doubt there's a fix for this. Playlists created from the query interface or by SoundPlay itself set the MIME type properly, so this shouldn't be an issue for most purposes.

• Some pages still need to be designed. This interface can get as fancy as we want it to be. Feel free to present your own designs (though there's no guarantee I'll use them).

---

Credits

Thanks to Marco Nelissen for writing SoundPlay, for making it scriptable, and for giving me a clue about how to talk to script hooks from hey.

Thanks to Tom Spindler for creating the Be::Attribute and Be::Query perl modules.

Thanks to Simon Huet for creating the Be::SimpleQuery module for case-insensitive queries.

Thanks to Justin Sherril for code for creating a common, shared config file, and for various and sundry perl tips and suggestions.

A few snippets of perl and their comments come from a friendly community member whose name escapes me, and I can't find his email messages. He was working on a system like this to read mail on a remote BeOS machine. I'll include his name here as soon as I can dig it up (oops).

---

Revision History

v0.3 Incorporated Justin Sherril's common settings file. No need to edit perl scripts manually -- users can do it all from a single web form.

v0.2: Query-based playlist creation now fully functional, including case-insensitive queries. Using a new version of hey with a -silent option to keep return values out of generated pages. No. of tracks in each folder now reported. Base page now has at least an initial design. No need to have a track pre-loaded in SoundPlay -- it happens automatically (though SoundPlay must still be launched, but that can happen from UserBootscript). No longer storing scripts in a subdir of cgi-bin, as this caused problems with some RobinHood configurations. No more HTML files -- everything is perl.

v0.1: Initial release