X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/659d87e8636edf319139b8c4d293132e2cd14441..da6f76931a7991d6b1537765a71ca6dc9f07b64c:/README diff --git a/README b/README index 350d7a2..28cbcc7 100644 --- a/README +++ b/README @@ -1,16 +1,23 @@ DisOrder ======== -This program is used to play random and chosen tracks from a collection of -digital audio files (for instance MP3 and OGG files). If you just set it going -it plays random tracks from your collection, but you can also ask for specific -tracks to be played, either via a command line program or a web interface, and -you can 'scratch' the current track. +DisOrder is a multi-user software jukebox. + * It can play either selected tracks or pick tracks at random. + * It supports OGG, MP3, FLAC and WAV files, and can be configured to support + anything you can supply a player for (up to a point). + * It supports both ALSA and OSS and can also broadcast an RTP stream over a + LAN; a player for the latter is included. + * Tracks may be selected either via a hierarchical interface or by a fast + word search. + * It has a web interface (allowing access from graphical web browsers) and a + GTK+ interface that runs on Linux and Mac systems. + * Playing tracks can be paused or cancelled ("scratched"). See CHANGES for details of recent changes to DisOrder. -Currently it only runs on Linux. It could probably be ported to other UNIX -variants in some cases without too much effort. Things you will need: +The server supports Linux and can be made to on a Mac (see README.mac). The +clients work on both Linux and the Mac. It could probably be ported to some +other UNIX variants without too much effort. Things you will need: Build dependencies: Name Tested Notes @@ -25,6 +32,7 @@ Build dependencies: libFLAC 1.1.2 GNU C 4.1.2 GNU Make 3.81 + GNU Sed 4.1.5 Python 2.4.4 (optional) GTK+ 2.8.20 (if you want the GTK+ client) GLIB 2.12.4 (if you want the GTK+ client) @@ -83,16 +91,12 @@ NOTE: If you are upgrading from an earlier version, see README.upgrades. See README.client for setting up a standalone client (or read the disobedience man page). - The server is only built by default under Linux. See README.mac concerning - its use under OS X. - 2. Install it. Most of the installation is done via the install target: make installdirs install - The CGI interface has to be installed separately: - - install -m 755 clients/disorder.cgi /usr/local/lib/cgi-bin/disorder + The CGI interface has to be installed separately; see under 'Web Interface' + below. 3. Create a 'jukebox' user and group, with the jukebox group being the default group of the jukebox user. The server will run as this user and group. @@ -113,40 +117,26 @@ NOTE: If you are upgrading from an earlier version, see README.upgrades. * edit the 'scratch' commands to supply scratch sounds (or delete them if you don't want any). * edit the 'trust' command to reflect the user the web interface will - eventually run as. - * edit the 'url' command to give the URL of the web interface. + eventually run as (see below). + * edit the 'url' command to give the URL of the web interface (see below). * add or remove 'stopword' entries as necessary (these words won't take part in track name searches from the web interface). See disorder_config(5) for more details. - See README.raw for details on setting up "raw format" players, which allow - for pausing and gapless play. - -5. Create /etc/disorder/config.private. This should be readable only by the - jukebox group: - - touch /etc/disorder/config.private - chown root:jukebox /etc/disorder/config.private - chmod 640 /etc/disorder/config.private - - Set up a username and password for root, for example with line like this: - - allow root somepassword - - Use (for instance) pwgen(1) to create the password. DO NOT use your root - password - this is a password to give root access to the server, not to give - access to the root login. + See README.streams for how to set up network play. - See disorderd(8) and disorder_config(5) for more details. + If adding new 'player' commands, see README.raw for details on setting up + "raw format" players. Non-raw players are still supported but not in all + configurations and they cannot support pausing and gapless play. -6. Make sure the server is started at boot time. +5. Make sure the server is started at boot time. On many Linux systems, examples/disorder.init should be more or less suitable; install it in /etc/init.d, adapting it as necessary, and make appropriate links from /etc/rc[0-6].d. -7. Start the server. +6. Start the server. On Linux systems with sysv-style init: @@ -157,40 +147,30 @@ NOTE: If you are upgrading from an earlier version, see README.upgrades. start up correctly there should be an error message. Correct the problem and try again. -8. After a minute it should start to play something. Try scratching it, as any - of the users you set up in step 5: +7. After a minute it should start to play something. Try scratching it: disorder scratch The track should stop playing, and (if you set any up) a scratch sound play. -9. Add any other users you want to config.private. Each user's password - should be stored in a file in their home directory, ~/.disorder/passwd, - which should be readable only by them, and should take the form of a single - line: +8. Add any other users you want. These easiest way to do this is: - password MYPASSWORD - - (root doesn't need this as the client can read it out of config.private - when running as root.) + disorder authorize USERNAME - Note that the server must be reloaded (e.g. by 'disorder reconfigure') - when new users are added. + This will automatically choose a random password and add new line to + /etc/disorder/config.private and create /etc/disorder/config.USERNAME. - Alternatively the administrator can create /etc/disorder/config.USERNAME - containing the same thing as above. It can either be owned by the user and - mode 400, or owned by root and the user's group (if you have per-user - groups) and mode 440. + Those users should now be able to access the server from the same host as it + runs on, either via the disorder command or Disobedience. To run + Disobedience from some other host, File->Login allows hostnames, passwords + etc to be configured. - You can use 'disorder authorize' to automatically pick passwords and - create these files. +9. Optionally source completion.bash from /etc/profile or similar, for + example: -10. Optionally source completion.bash from /etc/profile or similar, for - example: + . /usr/local/share/disorder/completion.bash - . /usr/local/share/disorder/completion.bash - - This provides completion over disorder command and option names. + This provides completion over disorder command and option names. Web Interface @@ -249,17 +229,14 @@ You need to configure a number of things to make this work: # htpasswd -b /home/jukebox/http.users othername otherpass Adding password for user othername -4. The jukebox must be configured to trust the web user. I added the following - line to my /etc/disorder/config: - - trust www-data - - This might not be the same on your system! You have to specify the user - that the CGI script runs as, whatever that is. +4. The jukebox must be configured to trust the web user. The example + configuration assumes that this is www-data, but it might be something else + on your system. Edit the 'trust' line if necessary. 5. Install disorder.cgi in an appropriate location. Remember to make it - executable. With the above configuration I installed it as - ~jukebox/public_html/index.cgi. + executable. For example: + + install -m 755 clients/disorder.cgi ~jukebox/public_html/index.cgi 6. Give www-data (or whatever user it is) a password and edit /etc/disorder/config.private accordingly. This file should be mode 640 and @@ -284,16 +261,11 @@ You need to configure a number of things to make this work: configured earlier, and be shown details of what is playing and what other tracks have been configured for future play. -9. Some features take time to start working, for instance those involving - reporting the length of tracks. This is because the server starts up as - quickly as possible even if the full track data has not yet been gathered; - the track data is then calculated in the background. - -10. If you run into problems, always look at the appropriate error log; the - message you see in your web browser will usually not be sufficient to - diagnose the problem all by itself. +9. If you run into problems, always look at the appropriate error log; the + message you see in your web browser will usually not be sufficient to + diagnose the problem all by itself. -11. If you have a huge number of top level directories, then you might find +10. If you have a huge number of top level directories, then you might find that the 'Choose' page is unreasonably large. If so add the following line to /etc/disorder/options.user: label sidebar.choosewhich choosealpha