ZoltanPlayer README =================== ZoltanPlayer - Music playing daemon Copyright (C) 1991-2001 Angel Ortega Home Page: http://www.triptico.com/software/zoltan.html This software is GPL. NO WARRANTY. See file 'COPYING' for details. Intro ----- ZoltanPlayer is a music playing daemon. It accepts remote commands via its own mini HTTP server and can use seamlessly Audio or Data CDs. Audio CDs are played internally (optionally querying CDDB info servers) and digital songs in audio CDs are played via external players. It's not limited to CDs, as a hard disk directory can also be used. The optimal equipment for ZoltanPlayer is a CDROM-equipped computer directly connected to an amplifier or stereo. It's not a streaming server, nor a ripper, nor a simple HTTP+HTML interface jukebox (this could be done with a CGI). ZoltanPlayer integrates the controlling of CD insertion / eject with the capability of directly playing CD Audio and spawning external player for MP3 / Ogg Vorbis / whatever song files. ZoltanPlayer only runs on Linux by now. Compilation ----------- ZoltanPlayer depends of no libraries. To compile ZoltanPlayer, just do $ make A binary called 'zoltan' will be generated. There are some compilation time options to tweak, specially for some (arbitrary) limits. There are currently a limit of 16384 songs and 512 groups per media and 32 maximum external players, controlled by the MAX_SONGS, MAX_GROUPS and MAX_PLAYERS constants, respectively. If you happen to have more than that number of songs, just do $ make CFLAGS=-DMAX_SONGS=100000 and the same for the others. The default config file is /etc/zoltan.conf; if you don't like it, you can change it by $ make CFLAGS=-DDEFAULT_CONFIG_FILE=/opt/zoltan/zoltan.conf or whatever you want (this can be changed in run-time, too). Installation ------------ As root, do # make install and the binary will be installed in /usr/local/sbin. If you want it in, say, /usr/sbin, change the prefix using # make install PREFIX=/usr you also must create a config file. Save zoltan.conf.sample as /etc/zoltan.conf and modify to suit your needs. Read the info there, specially about file and directory permissions. Running it ---------- Easy; just do $ /usr/local/sbin/zoltan and it will move to background automatically. You can specify an alternate config file as the first and only parameter. ZoltanPlayer is quite verbose; you would like to drop its standard and error output to the bit bucket /dev/null. It refuses to run as root, so choose a non-priviledged user. By default, ZoltanPlayer accepts HTTP queries on port 6543 (unless you changed it in the configuration file). So point a web browser to it and you'll see an interactive (and spartan) web interface, where you can load CDs / unload CDs / play songs / change volume / etc. Commands you can send to ZoltanPlayer ------------------------------------- Here is a list of commands you can send to ZoltanPlayer: * mount: Mounts the CD in the drive (closing it if necessary). If it's a CD Audio, it will take info about it and search the local CDDB cache; if no info for this CD is found, it will query a remote CDDB server. If it's a CD-ROM, it will traverse it recursively looking for playable files and the subdirectories containing songs will be treated as groups. Anyway, the list of songs will be stored in its internal database ready for playing. * umount: Unmounts the CD, and ejects it. * xmount: A combination of the previous two. If CD is mounted, umount it, and vice-versa. * hd: Reads a directory from the hard disk (this directory must be defined in the config file to be used). It will be treated the same as a CD-ROM. This command can also be used to re-read the hard disk directory contents if it has been updated since ZoltanPlayer read it. * play: Starts playing the first song. * stop: Stops playing. * pause: Pauses / unpauses the currently playing song. * next-song: Moves to the next song and plays it. * prev-song: Move to the previous song and plays it. * goto-N: Moves to song number N and plays it. * next-group: Moves to the first song of the next group and plays it. If no group is defined (as in Audio CDs), it restarts playing from the first song. * prev-group: Moves to the first song of the previous group and plays it. If no group is defined (as in Audio CDs), it restarts playing from the first song. * song-info: Returns information about the song being played in one line. This command can be used from a shell script to display the info on an LCD, a ticker or something like that. * vol-up: Pumps up the volume by 5%. Only operative if the sound card mixer is being used (see sample config file). * vol-down: Lowers the volume by 5%. Only operative if the sound card mixer is being used. * cd-info: Shows the current list of songs, and information about the current group and song being played, if any. * skip-N: disable the song number N (do not play it). * rest-N: enable the previously disabled song number N. * toggle: toggle the skip selection. * toggle-playlist: toggle the skip selection for those songs inside playlists. * shuffle: shuffle the playing order of songs. * unshuffle: get back to original sorting of songs (CD order for Audio CDs, or alphabetical ordering if song files from CDROMs or hard disk). All this commands (or any unrecognized one), except song-info and cd-info, returns an HTML page with clickable links. You can send this commands (from, say, a dock customizable button application for window managers as WindowMaker of from an X10 remote control application) to a ZoltanPlayer server using lynx. For example, to mount a CD, you can type $ lynx -dump http://zoltanserver.example.com:5432/mount > /dev/null and the CD at zoltanserver will be closed, read and get ready for playing. When will this damned MP3 song finish? -------------------------------------- Knowing the duration of a digital song is a tricky business. An external 'sizer' program could be used to analyze each song, but if you use many formats (.mp3, .ogg, .wav, etc), obtaining such a program for every format can be hard or even impossible. So, ZoltanPlayer doesn't do magic and acts just like you would do, that is, using a chronograph to time how much the song lasts, and saving each song's length to a file. The song lengths are CRC'ed and cached in the file /var/cache/zoltan.dat. ZoltanPlayer needs to write there, so be kind to him (permission access and so). You can also change the song cache path to whatever you want if /var/cache is not an option. Security model -------------- Since version 0.2.10, ZoltanPlayer includes an IP-based security model (previous versions didn't). Using the 'auth' keyword in zoltan.conf you can say which IP or range of IPs are allowed to access the internal HTTP server; access from any other than the explicitly authorized ones is denied. You can allow access from one server by using auth 192.168.20.45 or a complete network using an IP and a netmask, as in auth 192.168.1.0/255.255.255.0 see zoltan.conf.sample for details. If you don't use any authorization directives, the previous default behaviour (allow access to everybody) is used. CD covers --------- You can command ZoltanPlayer to show an image associated with each CD by its CDDB id by adding the following line to zoltan.conf: cddb_cover_images: /var/cddb/cover_images.lst And adding there, on each line, CDDB id / image URL pairs, as the following: 8910230a http://images.amazon.com/images/P/B000003CA1.01.LZZZZZZZ.jpg 9108090b http://www.triptico.com/data/themask.jpg dd120d10 http://photo.sing365.com/music/picture.nsf/CoverPicUnid/48256C71003578A248256A7A002B777A/$file/Fantastic+Star.jpg Yes, you have to do it by hand. If you know of a system / server / whatever that allows to associate CDDB ids with its cover image automatically, please let me know. Misc Notes ---------- - In the addons/ directory you have some icons and a configuration file for using wmAppl to control a remote ZoltanPlayer. They can be used as an example for another clients. I'm particularly interested in seeing a setup using an IR remote control; if you have one, send it to me and I'll add it to this directory. - ZoltanPlayer is a work in progress; everything works fine, but please write if you find a bug / annoyance / anything. --- Angel Ortega http://www.triptico.com