Djukebox Overview

The Djukebox system is made up of a set of distributed components:

For a functional installation, you need to run at least one of each of these components.
The only catch is that there can only be one database.

A basic system looks like this: 

                +----------+
                |MP3 Server|\
                +----------+ ---          
               /     ||         \               __(
              /      ||          +-------+     (
             /   +--------+   / -|djtella|----(   G
            /    |Database|- /   +-------+     \  n
           /     +--------+                     ) u
          /      //      \\                    (  t
         /      //        \\                    ) e
   +-------------+        +-----------+        /  l
   |Stereo Server|        |Info Server|       (   l
   +-------------+        +-----------+       )   a
                \\        //                 /    N
                 \\      //                 (     e
                  +------+                   \    t
                  |Client|                    (
                  +------+

Component Overview

Database

The database stores metadata about your music. This is as opposed to storing the music itself. This means that the database knows what music you have, and where it is. It also knows what other components are running in the system.

The database is PostgreSQL.

I choose Postgres over MySQL for a number of reasons. These Include:

The database stores all kinds of stuff. The major structure is that it likes to classify tracks by artist-album-song. It manages multiple encodings of the same song, as well as multiple copies of the same encoding. There is support for other formats (besides MP3) as well.

djshared

djshared runs on every machine which stores mp3's. It is a perl script that reports local music resources to the database.

It works by reading a list of directories to scan from /etc/djukebox.conf. It will poll these directories for differences periodically so all you have to do is add music and the system will eat it up.

djstreamd

djstreamd runs on every machine which stores mp3's. It is a c++ streamer that streams local content to other system components. At present this is either to a djstereod or a djtella process.

djstereod

djstereod runs on each machine that plays mp3's. It is built around a list of songs to play, and has an interface for adding, deleting, pausing, and rearranging this list. When a client requests that djstereod play a track, it looks the track up in the database and then streams it directly from the appropriate mp3 server.

There are plans to add seek functionality to djstereod as well so you can rewind (or fast forward) the currently playing track.

djinfod

djinfod is where clients come to figure out what music is available. It then queries the database and returns matching tracks to the client. It is a single point of access for information about the system.

Right now djinfod just allows you to query the list of available artists, albums from an artist, and tracks from an album. More advanced search functionality is planned.

djrip

Djukebox comes with an integrated ripper/encoder for adding content to the system. When set up and running properly the ripper automates the task of encoding cd's and adding them to your digital collection almost completely. As long as it finds a match for the cd in the FreeDB or the CDDB no user intervention is required.

The Ripper has a 'hungry' mode where it will try to eat as many cd's as you can throw at it, given available disk space, encoding all the while to make more.

The Ripper can also add the tracks to the system for immediate consumption as it finishes them. It stops just short of being able to play the cd while it is ripped.

djtella

djtella interfaces your jukebox to GnutellaNet.

It responds to gnutella searches and routes gnutella traffic. You can then download search results.

It also has a few query strings it will handle differently:

a query for artists will return a list of artists in the system.
a query for artist albums will give you a list of all albums from that artist.

The other cool thing about djtella is that it uses the same djstreamd interface to the jukebox that djstereod does. This means that you only need one djtella instance for an entire djukebox installation. File downloads are streamed from the mp3 host on demand, then proxied through djtella to some happy gnutella user somewhere.

Clients

One of the main strengths of the djukebox system is the client interface provided by the Info Server and the Stereo Server. This interface implements most of the dirty work involved in the system so that clients can be written at a high level, not worrying about many details of the system.

This makes it easy to develop a variety of user interfaces, each suited to a different task.

Currently the only usable client is the mod_perl based one. This client provides an easily accessable interface to the whole system. With the mod_perl client running on one of your machines all you need is a machine with a web browser to control the system.

The DjMessage protocol

With the exception of the database, the Djukebox system is glued together with a lightweight, custom object model called DjMessage. The DjMessage library defines the protocol that the different components speak to eachother. Presently there are C++ and perl bindings for DjMessage. One of the primary benefits of libDjMessage is that the messages themselves are read out of a big perl data structure. This data structure is then read by some perl scripts that write all the code for the library for you. So adding a message is as simple as adding a few lines to the messages file.