JukeX - THE Multi User Jukebox Application =============================================================================== 1 CONTENTS =============================================================================== 1. Contents 2. Introduction 2.1 Why does the world need another Jukebox? 2.2.Features 3. Installation 2.1 Prerequisites 2.2 Installation 2.3 Building from source 4. User Manual 3.1 Initial configuration 3.2 Playing music 3.2 Pipeline configuration 5. Developer Information 5.1 Internationalisation / localisation 5.2 Known issues 5.3 Planned enhancements 6. Contributors 6.1 Software developers 6.2 French language resources 6.3 Free Software Foundation 7. Open Source Certification =============================================================================== 2 INTRODUCTION =============================================================================== 3.1 Why does the world need another jukebox application? We listen to a lot of music in our office, it enhances the informal atmosphere in which we like to work, increases productivity and makes us happy. Initially we built a jukebox using shell scripts, old washing up liquid bottles and double sided sticky tape. As our music collection grew this solution began to fray at the edges, and we decided to try some of the open-source jukeboxes that had already been written. Why reinvent the wheel? We tried many different jukebox applications over the next few months, but none of them were as powerful, flexible and maintainable as we would have liked. We wanted to create a jukebox application that would allow us to rate tracks. We wanted a jukebox which would enable us to instantly filter out any noisy/profane tunes. We wanted a jukebox that would prevent individual users from 'hogging' the playlist by playing albums and albums of their own music. We wanted a jukebox that could be deployed without building a custom operating system kernel and patched versions of Apache & PHP. We wanted a jukebox that was designed to be maintained and extended. Most of all we wanted a jukebox which didn't use it's "random selection" feature to play 'Freaking Out' by Adema at least 10 times every day. We could not find one, so we wrote one. 3.2 Features JukeX has been designed from the ground up to be as flexible and extensible as possible. It offers the following features. (0) Complete database abstraction. Developers need never access the database directly. (0) Full query language - JukeXQL is an SQL like query language designed specifically for searching for tracks within the JukeX system. (0) Customisable attribute system - Tracks can have arbitrary values assigned to them as required by the developer. (0) Flexible pipeline based music preparation - JukeX has a pluggable and easily extensible 'pipeline' of components that enables JukeX play the music that *you* want to listen to. (Without having to explicitly tell it, of course.) (0) Round robin based user playlists - All user requests are interleaved so no-one can 'hog' the jukebox. (0) Audio banners - Inspirational company songs or messages may be automatically inserted into the playlist at predefined intervals. (0) Search based selection - Randomly play the results of 'SELECT Track WHERE Artist="Celine Dion"' to gain grace and favour with your workmates. (0) Powerful filters - These allow you to filter out any music that you may not want the jukebox to play, and may be enabled and disabled as required. (0) Automatic correction of ID3 tag information - Erroneous information on the MP3s, such as incorrect bitrates, are automatically corrected as they are played. This is just the functionality included in the current release. Look for more exciting features as they are released! =============================================================================== 3 INSTALLATION =============================================================================== 3.1 Prerequisites JukeX is built upon a number of other open-source technologies. In order to run JukeX your system will need the following installed: (0) JDK 1.4 or higher (http://java.sun.com) (0) MySQL 3.2 (http://www.mysql.org) (0) MySQL JDBC Drivers (http://mmmysql.sourceforge.net) (0) ShoutCast/IceCast server (http://www.shoutcast.com)/ (http://www.icecast.org) (0) Shoutcast/IceCast compatible MP3 player, such as xaudio or Winamp (0) Apache Tomcat webserver version 3.3.x or 4.0.x (http://jakarta.apache.org/tomcat) (0) Apache Ant build system (http://jakarta.apache.org/ant) Java Libraries Required (Advanced configuration only) (0) Apache Log4J logging system (http://jakarta.apache.org/log4j) (0) Xerces (http://xml.apache.org) (0) Xalan (http://xml.apache.org) (X) The four preceding libraries may be downloaded in a single archive from http://www.jukex.org/files/lib.zip (0) Java Rowset functions (http://developer.java.sun.com/developer/earlyAccess/crs). You will need a Java Developer Connection account to download this. Please refer to the documentation supplied with these products for details on installing them. 3.2 Installation JukeX consists of a number of services: (0) Database server - This manages all of the JukeX information and the track data. (0) Webserver - The service that provides the web interface. (0) Shoutcast/Icecast - The service which accepts the ShoutCast stream from JukeX and broadcasts it to compatible players. (0) Filestore - The filestore with all your MP3s on, which should be accessible from your webserver (by file or http URL). These services will happily co-exist on the same server, or may be deployed on different servers if, for instance, you already have a separate MySQL database server. The instructions for installation are divided into 2 sections, beginner and advanced. If you are a Java developer and already know what a classpath is, and how to use it, then skip to section 2.4: Advanced configuration. If you're new to Java, or don't have much experience, don't worry, we have thought of you too, and your setup instructions are in section 2.3. 3.3 Simple configuration 3.3.1 Java Configuration Here we'll assume that you've downloaded all the prerequisites from section 2.1. If you haven't you've got a bit to do first, we'll see you in ten minutes. Once you've got the JDK downloaded install it according to the instructions for your platform. Once you've done this you'll need to add the /bin directory of the installation to your PATH. This can be done *temporarily* like this, using your own installation paths. Windows: SET PATH=c:\j2sdk1.4.0\bin;%PATH% Unix: PATH=/usr/java/j2sdk1.4.0/bin:$PATH This will allow you to run the Java tools from anywhere on your hard disk, and will be essential later on. You can test this by typing 'java' at the command line. You should receive the help for the Java virtual machine. If you receive an error here you haven't successfully configured the PATH variable on your system. 3.3.2 Tomcat Installation Tomcat runs pretty much out of the box. Install it as directed (basically, unzip/untar it into a directory somewhere on your machine), and then add an environment variable to your system called TOMCAT_HOME, containing the path to the root of your installation, e.g. Windows: set TOMCAT_HOME=c:\java\lib\tomcat-3.2.4 Unix: TOMCAT_HOME=/usr/local/tomcat-3.2.4 [Optional] The default port for Tomcat is 8080, so the url for the jukebox would be: http://machinename:8080 (http://localhost:8080 should work) If you want to run this on the default web service port of 80, so you don't have to put the port number at the end then edit the file server.xml, which should be in the conf/ directory in your Tomcat installation directory. Find the following section in the file, and change the port parameter from 8080 to whichever port you would like JukeX to run on. [/Optional] 3.3.3 MySQL Installation If you are installing MySQL solely for the purpose of running JukeX, then it should be fairly simple. If you've already got a MySQL server for other reasons then you will already know how to use it, and it will be even easier for you; we'll barely interrupt you whilst you are reading Slashdot. Create a MySQL database, and call it whatever makes sense, for instance we called ours "JukeX". If you are feeling security conscious you can create a user and give them permissions on the database. If you do not do this then you will need to grant the default user ("") all permissions on the JukeX database. In order to create the database tables required for JukeX there is a script provided in the /src/sql directory called mysql_jukebox.txt. Either: Load up the mysql manager (not the windows GUI version) and change databases to your newly created database, then use your favourite text editor to copy and paste these instructions into the mysql manager. OR Edit the mysql_jukebox.txt file, adding the line 'use JukeX;' (where JukeX is the name of the database you have just created) to the top of the file (just below the license statement) and cat the file into mysql: Windows: mysql -D JukeX < mysql_jukebox.txt Unix: cat mysql_jukebox.txt | mysql -h jukex.neoworks.co.uk -U JukeX -pJukeX NOTE: Depending on the version of MySQL you are using you may need to modify the mysql_jukebox.txt file. Most commonly this will involve removing the comment block from the top of the file and possibly removing the DROP statements from the beginning of the SQL. This will create all of the necessary tables. 3.3.4 Ant Installation At the moment it is necessary to build yourself a distribution of JukeX. We hope to address this in future releases so that JukeX is easier to set up. Install ant by unzipping it somewhere in your directory structure, and adding the bin directory to your path, as you did with the Java SDK. 3.3.5 JukeX Installation To install JukeX itself create a directory for it, and unzip/untar the distribution into this directory. The directory structure beneath this will be created automatically. Download the prerequisite libraries from http://www.jukex.org/files/lib.zip, and install by unzipping the file into your jukex root directory. This will create a /lib directory which contains all the necessary jars except one, rowset.jar, which we are prohibited from distributing due to Sun licensing. This is available from: http://developer.java.sun.com/developer/earlyAccess/crs/ and will require you to sign up to download. We hope to remove this dependency in a future release. Once you have installed the libraries run the batch file: setclasspath.bat which will include all of the libraries in your system classpath environment variable. Then build the JukeX system by typing: ant war Once this has completed there will be a file in the dist/ directory called jukex.war. Copy this file to the webapps/ directory under your Tomcat installation, and rename it to "ROOT.war". You may also deploy this using the manager application if you are using tomcat 4. 3.4 Developer Configuration This section is for the kind of hardman/hardwoman who always compiles from source, and never reads the manual anyway. 3.4.1 Prerequisites and more We will assume that if you have skipped to the advanced configuration you already know what you are doing. This means that you've either already got copies of the JDK 1.4, Tomcat, Ant and MySQL installed, or you are able to work out how to do this yourself. 3.4.2 Setup MySQL We have provided a database setup script in src/sql/mysql_jukebox.txt that creates all the tables you need in order to run JukeX. Copy and paste this script into a MySQL prompt / pipe into mysql. NOTE: The scripts do not create the database itself. That is up to you, follow the instructions under MySQL to create a database with whatever name you see fit. 3.4.3 Unzip the source Unzip the source code to JukeX somewhere on your hard disk. It is here that we will build a release customised to your setup. 3.4.4 Compiling the source There are quite a few library dependencies in JukeX, so it is probably best to download our rollup of all the libraries from the homepage (http://www.jukex.org). All of the dependency jars need to go in the JukeX source directory under lib/ or be in your system classpath, as that is where the build target expects to find them. Once you have either symlinked, copied in, or downloaded and unzipped the dependency jars to the lib directory you should be able to easily build a copy of JukeX using the command line: ant war 3.4.5 Deploying the WAR Once you have compiled the source there should be a file called JukeX.war in the /dist directory. This is the compiled, customised application containing all your settings. To use this copy it into the Tomcat webapps directory and start Tomcat. This will automatically unpack and deploy the WAR file, and provided you are using Tomcat and have not altered the settings you will find the jukebox at: http://yourservername:8080/JukeX If you have altered the settings you will probably have a good idea what url and port tomcat is running on anyway. =============================================================================== 4 USER MANUAL =============================================================================== 4.1 Importing your music Before you start using JukeX you'll need to import your music collection(s) into the system. This is so JukeX can read all of the ID3 tags on your MP3 files and make it fast and easy for you to search through them. This is done using the MP3Importer program. This trawls through your music directory finding new tracks to add to the database. The MP3Importer is invoked using the following command line: java MP3Importer -d There are a number of options available: -m Match expression -r Replace expression These two options must be used together and perform a regular expression substitution on the URLs of the tracks being imported. This enables tracks to be imported from a server to which the JukeX server does not have local filesystem access, or has access from a different mount point. e.g. java MP3Importer -m "file://G:" -r "http://music" -d G:\ java MP3Importer -m "file://mnt/nfs/foo" -r "file://mnt/foo" -d /mnt/nfs/foo -n Do not actually import/update tracks -f Force update all tracks Tracks are checked by modification time to detect changes. Sometimes this isn't good enough, so this option forces an update. -s Specify a properties file containing substitutions to apply to imported attributes. Example file contents: Artist=/^[Tt]he (.*)$/$1, The/ This example rewrites all artist names that begin with "the". 4.2 Playing music Once the application is running the music can be started using the "play" action link on the left hand side of the HTML interface. Once music is streaming to the [Ice|Shout]cast server clients may connect to it and begin to listen. 4.3 Pipeline configuration The pipeline is one of the most important aspects of the system. The HTML interface provides an editor that enables elements to be added, removed and configured. Most elements are self explanatory. =============================================================================== 5 DEVELOPER INFORMATION =============================================================================== 5.1 Internationalisation / localisation JukeX uses ResourceBundles for locale specific language customisation. The default ResourceBundle is en_GB and fr is provided as an alternative. Developers wishing to translate the application only need to create a properties file in the src/etc directory of the JukeX distribution and rebuild the application to add support for further languages. Currently there is only one bundle: InterfaceResources. 5.2 Known issues 5.3.1 JukeX Core - JukeXQL queries for attribute values that are not present on all search results will return incomplete result sets. - There is an issue with discovering the duration of tracks. 5.3.2 JukeX User Interface - Some pipeline elements are not fully configurable 5.3.3 JukeX Importer - The importer does not have an option to recurse directories. 5.2 Planned enhancements - The AudioBannerPipelineElement should use a second pipeline to provide a source of tracks for insertion. - All pipeline elements should be full configurable. - Ogg Vorbis support - Add user login and management - Persist session information for registered users - Separate user/administrator functions =============================================================================== 6 CONTRIBUTORS =============================================================================== 6.1 Software developers NeoWorks (http://www.neoworks.com) are an independent software house based in London, England. We specialise in developing bespoke software solutions for customers from individuals to large businesses, as well as providing support and consultancy services. 6.2 French language resources Gregory "XXXL" Kris is an anglo-french entrepreneur who will work for beer. 6.3 Free Software Foundation The Free Software Foundation (http://www.fsf.org) created the General Public License under which this product id released. =============================================================================== 7 OPEN SOURCE CERTIFICATION =============================================================================== This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative. =============================================================================== EOF ===============================================================================