This document presents a detailed look at the actual system architecture of the OPENdj system, and is organized as follows:
Audio System Overview
In the diagram above, the large boxes represent separate systems: the DJ (typically a single computer), the OPENdj server (typically multiple networked computers), and the listeners (typically one machine per listener). The empty space between the boxes is the Internet (or some other network).
This design has several advantages:
The diagram presents two distinct kinds of data flows: audio data flows and control data flows. The audio data must somehow get from the broadcaster's live feed to the listener's speaker. The control data flows ensure that this happens properly and in a secure manner.
Audio Data Flow
The description and accompanying diagram just presented are not entirely true. They are accurate for the Win32 broadcaster using JRev. For the UNIX broadcaster using LiveIce, it is slightly different:
So, to summarize the difference in Win32 vs. UNIX implementations: The Win32 version of the broadcasting software spawns a separate process for the LAME encoder and "manually" handles audio capture, piping the raw audio to the MP3 encoder, reading the MP3 stream from the MP3 encoder, and (finally) piping the MP3 stream to JRev which relays it to a shoutcast server. The UNIX version simply spawns a liveice process, which handles all the audio capture, MP3 encoding, and shoutcast streaming responsibilities itself.
Control Data Flow
But just understanding the audio-data flow is not enough. For the audio to flow properly, a control conversation is also occurring between DJServer and OPENdj-client. The control conversation is much more interesting:Chat System Overview
As in the audio system overview, the large boxes represent separate systems: the DJ, the OPENdj server, and the listener(s). Decoupling the audio flow from the chat flow provides for a more flexible architecture allowing the design and implementation of each to vary without disrupting the other. For complete details on the OPENdj Chat Protocol, read the spec.
Chat for Listeners
Listeners can enter the chat by clicking on a link from the same web page that starts up the listener's audio player. The link resolves to a simple web page that contains a Java applet. The browser downloads and executes the applet code. The applet asks the listener to pick a username for the chat. If the name is taken, the user is asked to choose another. Once an acceptable name has been selected, the listener enters the chat room. The listener then sees any comments made by other chatters, and can make comments of their own.
Chat for DJs
When OPENdj-client is told by DJServer to start broadcasting, it also starts up an instance of the chat program. In this case, it is not running as a Java applet, but rather within OPENdj-client. In this situation, the chat program uses an auto-login protocol to log in to the ChatServer. This is possible because the DJ has already logged in to DJServer. Once logged in, the DJ can see and comments that listeners make, and can send comments of their own.
Component Specifications
This section describes each component of the OPENdj system. For components provided by third parties, only the protocols and other public interfaces required are described.
Media Source
The actual content has to come from somewhere. This architecture assumes it can be anything you can plug into your sound card through some sort of line-in jack. Typically, this would be an RCA jack or perhaps a headphone-type jack. On the computer side of things, the signal from that card must be available through normal operating system interfaces.
Media Encoder
An MP3 encoder used in the OPENdj system. The current implementation uses the LAME encoder, but other encoders could be used. The only requirement OPENdj assumes is that those encoders expose a command line interface that allows the programs can handle receiving signals on standard input and writing the encoded signal on to standard output.
Broadcasting Software
The broadcasting software coordinates all the efforts between:
The broadcasting software is called OPENdj-client, and runs on Win32 and UNIX (though Linux is to date the only one tested, other flavors should require very little porting effort). The details of the design of OPENdj-client are provided in the DJServer Clients document.
Source-to-Media Server Transport
The broadcasting software does not directly send the signal to the media server. Rather, a wrapper library is used which sits on top of real media transport library. The current incarnation of OPENdj assumes that the media server understands the shoutcast protocol. For the UNIX version of OPENdj-client, the wrapper library is built on top of LiveIce, for the Win32 version, the wrapper library is built on top of JRev.
Server Operations
The DJServer is responsible for:
A detailed description of the OPENdj Streaming Protocol is presented in the OPENdj Streaming Protocol Specification.
Media Server
The Media Server used in the current OPENdj system is Icecast. Icecast was chosen because (using Expect), external software (e.g. the DJServer) can programmatically query and control it. OPENdj requires that the media server be able to programmatically provide interfaces for these operations:
On the listening side, Icecast supports the shoutcast protocol. Any media server which meets the criteria above and supports the shoutcast protocol could be used in place of Icecast, with minor changes to the OPENdj system.
Audio Player
On the listening end, any player that supports the shoutcast/MP3 protocol will work. These currently include: RealPlayer and WinAmp for Windows, Macast and Soundjam for Macintosh, XMMS and FreeAmp for UNIX.