TVDinner - Streaming MP3 Server

Installation Docs

Revised: 12.23.2004

The installation docs are constantly being updated (as I have time to do so) and are by no means complete (yet.) For further questions, please see the TVDinner mailing list.

Step 1 - Apache Server Preparation

First, you're going to have to get yourself some hardware. Beef up on HD space or you'll be kicking yourself when your collection clears 30GB. Install whatever OS you're comfortable with (minus Windows) and make sure it works.

Download Apache and mod_perl and compile them together. I don't recommend using the Apache / mod_perl distribution that comes with your OS (for example Red Hat rpm) as there are known problems with some of them. There is an excellent tool for Apache configuration and installation called The Apache Toolbox -- I highly recommend it, as it makes like a lot easier, especially when trying to install Apache with more than one module (ie: SSL, PHP, Python, etc.)

Step 2 - Database

TVDinner was built around a MySQL database because of it's flexability and similarity to Oracle (which I am familiar with.) It could easily be made to use Postgres, Oracle, or a flat file with just a few minor modifications. (use DBI). If you happen to use a different database, please let me know how it went.

For this installation, however, I am going to assume you are using MySQL. Download a copy of the MySQL server and install it on your machine. In this case, it doesn't matter where it comes from (be it RPM, apt-get, or pkg_add).

Make sure that the database is functioning properly, you'll need it in a couple of steps.

Step 3 - Perl Modules

OK. So now you have Apache compiled with mod_perl, we have MySQL installed, it's time to install some perl modules. We'll start with the most important, HTML::Mason.

The easiest way to do this is to use CPAN. From the prompt, issue this command:

$ perl -MCPAN -e shell
cpan> install HTML::Mason

If you encounter problems when installing using CPAN, there is plenty of documentation out there. CPAN is solid, so you shouldn't have any issues.

The following modules are required by TVDinner and included tools. Note: You probably already have some or most of these.

• Apache::MP3
• HTML::Mason
• DBI
• DBD::mysql
• CGI
• Apache::Cookie
• Apache::DBI
• Apache::Session::MySQL
• Apache::Constants
• File::Find
• File::Basename
• Shell
• Getopt::Long
• Getopt::Std
• Pod::Usage
• LWP::UserAgent
• Image::Info
• SOAP::Lite
• MP3::Info
• MP3::Tag
• App::TVDinner::Conf
• App::TVDinner::DB
• App::TVDinner::Lib
• Storable (this should't be required, but appears not to be installed by Apache::Session by default.)

Step 4 - Setting Up TVDinner

Web Interface

For many of you, I hope this is step one (or maybe step two) because I believe every webserver should have Apache/mod_perl installed. On to setting up TVDinner...

Download and unpack the most recent version of TVDinner. You're probably going to want to drop it in /var or /home/username because there are useful tools included that don't (currently) get moved anywhere.

You should end up with a directory scructure like this:

  /tvdinner
    CHANGES
    INSTALL
    LICENSE
    Makefile.PL
    README
    /conf
    /database
    /html
    /lib
    test.pl
    /tools

We'll start with the html directory. Inside is a tvdinner directory...copy it into your Apache document root (ie: /usr/apache/htdocs/tvdinner). Don't panic if you tried to view that directory from a browser...we haven't configured Apache to deal with Mason yet.

There are four Perl modules included with TVDinner: App:TVDinner::DB, App::TVDinner::Lib, App::TVDinner::MP3, and App::TVDinner::Conf.

Change directories into /lib/App/TVDinner. Be sure to edit Conf.pm so that it matches your system config. Return to the top level directory and execute the following commands:

  $ perl Makefile.PL
  $ make
  $ make test
  $ make install

This will install all of the TVDinner modules. If you have problems, please post them to the mailing list or send me an email so that I can correct them.

Database

OK...now, we'll "install" the tvdinner database tables. There's a nice and easy script in the /database directory. From the database directory, run the "install_database" script:

  $ ./install_database.sh

Pay attention to any errors you encounter. The first couple of steps should be run as MySQL's "root" user.

MP3 Directory

Depending on how you want your machine setup, you're going to have to configure the MP3 directory. There are settings in Conf.pm as well as the tvdinner.conf file. I personally set up a /mp3 mount point and dump all of my MP3's in there. It works great for me, but may not be what you want. Be sure to change those config files if you decide to go with a different setup.

Mason Configuration

And last, but not least, let's set up Mason. In the /conf directory, there should be three files: httpd.conf, mason.conf, and tvdinner.conf. Append the contents of the httpd.conf to your existing Apache httpd.conf (do not overwrite it!), then copy the mason.conf and tvdinner.conf into /usr/apache/conf.

Stop and start Apache, and try to get to /tvdinner. Log on with the default system account (username: system, password: tvdinner). Once in, select "system" under menu and add your username with system privileges, or change your system password.

If you encounter errors, please be patient. Fire me or the Yahoo Group an email message describing your problem and I'll try to handle it.

Step 5 - Caring For Your TVDinner Server

Ok, everything is up and running and now you have an empty database. How do your MP3's get there? Why, magic of course!

Collection

Included with your TVDinner package, in the /tools directory, are a set of Perl scripts to help you to organize your MP3 collection and to get files into the TVDinner database. The most important is the collection script.

The "collect.pl" script will scan your /mp3 directory looking for any filenames that currently don't reside in the database. It will then add each one. It doesn't matter where you put the files in /mp3, but I find it easier to use the /new_uploads directory, that way I know what I have yet to add. Let the organize script take care of moving things into their proper place.

  $ ./collect.pl -vab

Note: There are more options for collect, run with the "-?" switch to see them all.

After collect.pl completes, you're ready to stream. You should be able to go to TVDinner, select a track and play it.

Organization

I've also built a way to organize your MP3s. The organize script will move all of your MP3's into the following drectory scructure:

  /alpha/artist/album/filename.mp3
  /uncategorized

I find it best to also create a "/new_uploads" directory. I've included a shell script to create all of the alpha directories called "azdirs.sh" if you don't want to wait for the organize script to generate them all. Organize will only generate alpha directories for those files that you have.

Note: Before running "organize", be sure that you have the permissions under /mp3 set correctly. Remember, in order to be able to change ID3 tags from the web interface, the account that Apache runs under (usually "www") must have permissions to those files. (Yes, yes, I know all about security concerns) I do the following:

  $ cd /mp3
  $ chown -R username:www
  $ find ./ -type f -exec chmod 664 {} \;
  $ find ./ -type d -exec chmod 775 {} \;

Now, you can run organize.pl, or use the web interface under the "system" menu.

Side Note: I've included a shell script that I use to change permissions, fix bad filenames, collect, and organize with the TVDinner distribution called "uber.sh". You will have to edit that file to match your installation.

Special Care

Sometimes, you'll find it necessary to change the filename of an MP3, or manually move it to a different directory. This will cause the "link" between the file and the database to break. In cases like this, you can use the "integrity" script to check for database discrepancies.

There are two ways to run integrity: the first is through the "system" menu in the web interface. The second is via command-line: "integrity.pl".

  $ ./integrity.pl -vb

Other Things To Keep In Mind

I built TVDinner mainly to suit myself. Apache::MP3 has an interface and it's nice and all for smaller MP3 collections, but I found it lacking when it came to extended support. (My collection was built from encoding CD's using CDEX and it was instantly 30GB!) Because I built this tool for myself, I didn't pay a lot of attention to making it easy to install, etc. However, I felt it was a Good Thing (tm) and that I needed to share it with the community.

Also, I don't strive for backwards compatibility with each new release. At this point, there are very little changes to the database structure. Because of that, sometimes you can just replace your /html directory to get the new features. If you have to rebuild, don't panic. Just drop the databases, replace /html and start the collect.pl script again. The critical bulk of information about your MP3's is stored in the ID3 tags.

As always, I'm available to answer questions or even help you to get your system setup. Keep in mind that this project is done in my spare time, so be patient when waiting for responses. If you'd like you help out in any way, simply send me an email and I'll get you started.