# INSTALL Calliope 1.0 Sections in this document: 0 - Notice 00 - Upgrading 000 - Documentation I - Requirements II - Quick Installation III - Detailed Installation IV - Troubleshooting V - Feedback ###################################################################### # 0 - Notice ###################################################################### Calliope is not a file sharing program. Do not use this software to illegally share music. You assume all responsibility for how you choose to use this program. No warranty is expressed or implied. Installing this software could affect any and all sorts of things on your computer; the authors are in no way responsible. This is open source software under the GPL - the code is included under the terms in LICENSE. ###################################################################### # 00 - Upgrading ###################################################################### If you're upgrading calliope from a previous installation there are two primary things to be aware of. You should check to see that you have any newly required perl modules: # perl /usr/local/calliope/lib/Main.pm You also need to make certain your database is current. If you're upgrading from a version prior to alpha_rc13, you will most likely need to drop and re-create your database: # cd /usr/local/calliope/etc/db # ./deletedb_mysql # ./createdb_mysql For postgres, you must be the postgres user: # su postgres # ./deletedb_psql # ./createdb_psql If you're upgrading from alpha_rc13 to any later release, you should be able to upgrade your db without data loss.: # su # calliope upgradedb However, you're probably best off re-loading your database, as there have been many improvements in the loader. You can preserve your lists and users by: # calliope flushdb -rs ###################################################################### # 000 - Documentation ###################################################################### Within calliope, there are a number of README documents that pertain to that "section" of calliope, and are worth reading if you want more in-depth info on calliope. Further, the conf file is itself an important document on calliop's potential features. There's reasonably up-to-date help available from the web interface once calliope is running. And from the command line, "calliope help" will tell you all the command line features you might want to try out. calliope/README - main readme calliope/lib/Artists/README_ARTISTS - about artist loading/filtering calliope/etc/db/README_DB - about the db architecture calliope/dev/README_DEV - for developers calliope/tmpl/README_TMPL - about the template interface system ###################################################################### # I - Requirements ###################################################################### o A Unix like machine o Perl 5.8.0 or later and various modules (listed below) http://www.perl.org/ and http://cpan.org/ o MySQL 3.22 or later http://www.mysql.com/ (including the developer libraries and header files, required for installing the DBD::mysql Perl module) - or - o Postgresql 8.x http://www.mysql.com/ o gcc - you'll need a compiler to install some of the extra perl modules required by calliope o A Frames based web browser with Javascript and Cookies enabled (Javascript required for search function and lists feature) o Apache 1.3 or later http://www.apache.org/httpd/ (or any webserver which supports cgi; supplied config file examples are for apache) - one of: o Mpg123 and a configured sound card most linux installations come with mpg123. You'll need this if you're playing music over a soundcard(s). You can stream music via Icecast. o Icecast 2.0 or later and libshout + Shout.pm (v 2.x) http://www.icecast.org/ and http://developer.icecast.org/libshout/ - and optionally: o Fastcgi (optional, recommended - dramatic performance improvements) http://www.fastcgi.com/ o Apache mod_perl (optional, some performance improvements) http://perl.apache.org/ ###################################################################### # II - The quick install guide, for the impatient (detailed guide is below) ###################################################################### 1. Put the tarball in /usr/local and extract # tar -zxvf calliope1.0x.tar.gz Create a symlink to this version: # ln -s calliope1.0x calliope The installer currently requires that you have mysql or postgres installed, and the perl DBI module (which is a fairly standard part of a database installation). You should edit the configuration file first (located in ~/etc/conf). You may also wish to install Apache as well. You will want to start these services, and have them run at boot. Run the installer as root: # cd calliope/installer # su # ./install If all goes well, you should have a running version of Calliope! If the installer immediately crashes with an error like: "Can't locate Util/DB.pm in @INC (@INC contains: /usr/local/calliope/lib" it means you do not have the perl DBI.pm module installed. This is the generic module that allows perl to talk to a database. Normally, when you install a database, these modules are installed - you may need to install a database before running the installer - at least you'll need the DBI module. You may prefer to: a) continue with the quick manual install starting with step 2 immediately below; or b) go through the detailed install in section III. 2. Install any required (and optional) perl modules that you don't already have. You can test if you have required and optional modules by typing: # perl /usr/local/calliope/lib/Main.pm 3. create your database. mysql # cd /usr/local/calliope/etc/db # su # ./createdb_mysql [-p] postgresql # cd /usr/local/calliope/etc/db # su postgres # ./createdb_psql 4. Create /usr/local/calliope/etc/conf Use conf.dist as a starting point if it exists. Put the same password you picked in step 3 under DBPass. I urge you to get everything working using the 'test' channel type before you try using Soundcard or Icecast. And I'd focus on the soundcard before I tried icecast. Make sure you set DBmod to match the database you created in step 3. 5. users and groups right now, calliope runs as nobody:audio. this should be calliope:audio, there are issues. change your user in the conf file to the apache user, and make sure this user (most likely nobody) has soundcard access, and all should be well. note owner:permissions on var/* and var/log/* should be 775 and nobody:nobody (or whatever Apache runs as and you've set in your conf file). If you plan to use the id3 write feature, your songs will need to be in the same group as your Apache process, and writeable by that group. 6. (load your songs into the database) # /usr/local/calliope/bin/calliope load 7. edit your apache httpd.conf file and restart apache use /usr/local/calliope/etc/calliope.httpd.conf as a guide 8. create users via the web interface 9. (start the calliope jockey daemon) # /usr/local/calliope/bin/calliope start Done! You should now have a running version of Calliope accessible over the web. Since you started out using the 'test' channel type, Calliope will not be playing any music at this point. Instead, it will be picking songs and cycling throught them, one song per minute. You should be able to browse for songs and make requests on the 'request' page. If your User and Group setting match those of your Apache process, you should be able to kill the currently "playing" song by clicking on the 'x' button by the top song in the queue (on the 'request' page). To make it actually play music, edit the conf file, comment out the test channel, and umcomment the soundcard channel. For greater detail, read on... ###################################################################### # III - The slightly more detailed install guide ###################################################################### 1. Unpack Calliope # cd /usr/local # tar -zxvf calliope.x.x.tar.gz # ln -s calliope.x.x calliope Right now, you cannot (easily) put calliope anywhere else. That may change in new versions, but for now, go with the flow, trust me. If you are stubborn and want to try and install Calliope someplace other than /usr/local/calliope, you will need to find and change all the appearances of "/usr/local". But whether calliope would work at that point.... -------------------------------------------------- 2. Install Perl Modules You can test for the required and optional modules by typing: perl /usr/local/calliope/lib/Main.pm If all the required modules are found, this will do the additional step of checking that all of the Calliope code can be parsed and loaded. All required / optional modules are listed in Main.pm if you need a manual listing. NOTE: MP3::Tag, which calliope relies on, does not currently detect multiple genres or the volume frame correctly. There is a patch for ID3v2.pm in ~/dev, it is not required, but can be useful. You may see 'Unidentified Frame' errors if you don't patch, but they are not critical. It is hoped future versions of MP3::tag will incorporate some version of this patch. Following are "manual" instructions. You may also use the installer to load extra modules (vs. an entire install) by typing: .cd /usr/local/calliope/installer ./install -m If the installer immediately crashes with an error like: "Can't locate Util/DB.pm in @INC (@INC contains: /usr/local/calliope/lib" it means you do not have the perl DBI.pm module installed. This is the generic module that allows perl to talk to a database. Normally, when you install a database, these modules are installed - you may need to install a database before running the installer - at least you'll need the DBI module. If you wish to install modules "by hand", under Unix your best bet is to use the CPAN module. The CPAN module generally comes with Perl, unless you're on a Mac. In which case, getting this installed at all will be a challenge right now. At a minimum, you'll probably need to get the OSX Developer kit, which includes CPAN, and a compiler. Type 'man CPAN' or 'perldoc CPAN', or see http://www.cpan.org/ for more information. For example: # perl -MCPAN -e shell [You might need to configure CPAN the first time, good luck.] cpan> install DBI cpan> install DBD::mysql I am told that under Windows you are better off installing Perl modules using the ActiveState PPM (Perl Package Manager), which I assume requires ActiveState Perl. For example: C:\perl\bin> PPM PPM> install DBI PPM> install DBD-Mysql ActiveState Perl is the perl distribution of choice for Windows. Find out more at: http://aspn.activestate.com/ASPN/Reference/Products/ActivePerl/bin/ppm.html If you are installing under Windows however (ok, i'm rather dubious about whether that's even possible, but FWIW), CPAN vs. PPM will be the least of your problems. I've never installed Calliope under Windows myself and you'd be deep into (mostly) uncharted territory, and there is no more Windows-specific help to be found in this INSTALL file. -------------------------------------------------- 3. Create a database. Before creating a database, make certain you edit your etc/conf file, and specify which database you intend to use with the DBmod directive. MYSQL You need to have Mysql installed and running before you can do this step. Mysql comes with most Linux distributions. You can get more information on Mysql at http://www.mysql.com/. Once you are sure Mysql is up and running, create the Calliope database. Easiest and preferred is to: # su # cd /usr/local/calliope/etc/db/ # ./createdb_mysql [-p] Where is a two digit code indicating which shcema version you wish to use (typically the highest number). The -p option is needed if you use a password with mysql. If you already have a database, and which to drop and recreate it: # su # cd /usr/local/calliope/etc/db/ # ./deletedb_mysql [-p] # ./createdb_mysql [-p] You may also be able to use the installer: # cd /usr/local/calliope/installer/ # ./install -d and answer the configuration questions asked, your db will be created automagically, and conf file set up as necessary. If the installer immediately crashes with an error like: "Can't locate Util/DB.pm in @INC (@INC contains: /usr/local/calliope/lib" it means you do not have the perl DBI.pm module installed. This is the generic module that allows perl to talk to a database. Normally, when you install a database, these modules are installed - you may need to install a database before running the installer - at least you'll need the DBI module. You should really edit /usr/local/calliope/etc/db/schemas/schema_.mysql, and provide/alter the user name and password that calliope will use when accessing mysql. This should be the same user, with the same password, as defined in ~/etc/conf as 'DBUser' and 'DBPass'. Also, change the web-admin password. When you're done creating and loading the DB with default data, make certain you reload mysql: # mysqladmin reload This file defines a default user, a default administrator, default user types (admin, guest, etc), default user permission sets, default artist types (band, individual, etc.), and a default set of genres. Although you can edit the data in this file, the web interface provides these abilities to the administrator, and would be the preferred method of modifying your data. If you have a large mp3 collection (>500 albums), and your version of Mysql is less than 3.23.2, then you might need to arrange for the mysql daemon to be launched with the --big-tables command line option (or else it may fail to start). I usually just edit /usr/bin/safe_mysqld (the mysqld startup script) and add the --big-tables option there. Note the --big-tables means mysql writes large tables built to answer a query onto disk instead of using memory. This can cause a performance hit, but may be your only option (unless of course you just bought a Gig of RAM instead :-) NOTE: sometimes, if a machine crashes while calliope is running, the DB can get corrupted. You'd notice if after restarting, calliope starting consuming massive disk / memory, or the machine slows way down, or calliope doesn't run properly. Stop calliope, stop mysql, and run: # myisamchk -rs /var/lib/mysql/calliope/*.MYI You can even insert the above line in /etc/init.d/mysql at the beginning of the 'start' clause (this is no doubt a terrible admin practice, but it works). It's possible these problems stem from calliope not using transactions, which should change by rc16. POSTGRESQL PG support is new as of RC10, but the process to install and use it is nearly the same. You must be user "postgres" to use the db creation script manually (but not if you use installer/install): # su postgres # cd /usr/local/calliope/etc/db/ # ./createdb_psql To first drop the old DB and user: # su postgres # cd /usr/local/calliope/etc/db/ # ./deletedb_psql # ./createdb_psql Note that fastcgi doesn't seem to work with postgres, and postgres support is still somewhat experimental - please report any bugs, or submit and fixes you make! -------------------------------------------------- 4. Configure Calliope To configure Calliope, modify the conf file: # /usr/local/calliope/etc/conf Below are some details on the conf file, but there are numerous comments in the conf file itself that will help you get it configured. There are significantly more configuration variables in the conf file than are described here. This INSTALL may be "out of synch" with the conf file, which continues to change. Trust the conf file, which will always be current with a given distribution. The conf options you will need or want to change at first are most likely as follows (shown in the order you'll encounter them): User, Group - the user and group the calliope daemon will switch to after it starts up. This should presently be nobody:audio, or the user apache runs as, and your audio group. DBMod, DB - there are 5 variables that specify the database name, password, etc. DBMod specifies which database to use (e.g. DBMod mysql or DBMod Pg - these are case-sensitive), and is probably the only variable you should initially change. DBUser, DBName, and DBPass should be changed if you also edit createdb_mysql or createdb_psql, as these two scripts hard code these three variables. In other words, to change the DB name, user name, or password, you must change both the conf file, and the database creation script. ContactEmail - email address to display in the calliope interface ContactURL - url to wrap around the ContactEmail string Protect - none | request | all defines whether a uid/password is required to access calliope. none = free admission, and everyone is an administrator. Primarily used for testing, or if you're the *only* user. request = the home page is free admission, but you'll need access rights to request music. everything = you need access rights to use this installation at all. - full path to your mpg123 program - full path to your ogg123 program - full path to your flac program FileExt - define up to 3 of these, one for mp3, ogg and flac respectively. comment out file types you do not want indexed in the database (and thus that you don't want to play). - the directory (can be multiple) where you store your music files. Specify the directory, loading method to use for this directory, whether it's removable, and if you're using the filesystem (vs. file tags such as id3v2), the arrangement of the directories. More information on this is available in the conf file. ### dep? HasOwnerDirs - set this to 1 if the first level directory in MusicRoot separates the music into different owners OwnerOnly - set to 1 if you have owner directories, and the user must also be the owner in order to download. Set to 0 to allow all users to download (for users of types that have download permission as defined in usertypes in data.sql). By default, users of type 1-3 can download, type 4 and above cannot. ### dep> UseCorrections - calliope offers some "intelligent" artist parsing utilities. The idea is to 1) combine things like "J.s. Bach," "Bach," and "Johann Sebastion Bach" into a single artist, and 2) to identify multiple artists when they're specified in a song title (particularly on compilations). See ~/lib/Artists/README for more details. UseThe - whether or not to include "The" or ",The" in an artist's name. UseFileDate - determines whether the "loaded" date for a song is today, or the file creation date. - Calliope allows multiple channels, and multiple channel types. There are 3 channel types: test - picks songs and pretends to play them, advances to the next song in the queue once per minute soundcard - use the mpg123/ogg program defined in the conf file stream - stream to an icecast server using libshout and Shout.pm More about channel types: test Test mode does not actually play songs in any way, it simply fills up the queue and removes the top song once a minute or so. The advantage here is that you can eliminate any potential problems from mpg123 or shout/icecast while you debug your Calliope installation. soundcard Soundcard mode uses mpg123 or ogg123 to play the songs through a soundcard in your Calliope server. The Mpg123 directive (desribed above) should define the full path to your mpg123 executable. calliope is designed to run as its own user for security reasons. all it's spawned processes should run as the User Group specified above. It's therefore important that the User/Group you use has appropriate permissions to access the soundcard. stream Uses icecast v 2.0 to stream songs. You can get libshout and the Shout.pm perl module from http://www.icecast.org/. Look for the developer tools link on the Icecast download page. http://www.icecast.org/ There are many more configuration options, and they are fairly well explained in the conf file itself. NOTE on permissions, users and soundcards: You may need to set the file permissions on your sound devices (/dev/dsp or /dev/audio) so that the Calliope user (defined above by the User directive) can write to that device. you may need to edit /etc/logindevperm (or a similar file on your distro) in order to get your soundcard to work properly. On Suse 9.1 (at least) the /dev/dsp permissions are set to 600 in some instances, and should be 660, allowing the audio group to use the soundcard (rather than *only* the logged in user). The same problem exists with /dev/snd. Change the permissions to 660 on these two lines in /etc/logindevperm: :0 0660 /dev/dsp0:/dev/dsp1:/dev/dsp2:/dev/dsp3 :0 0660 /dev/snd/* You may also need to check /etc/group and add "calliope" and/or "nobody" (or whatever your calliope runs as) to the audio group. A clear sign that permissions are your problem is that calliope *is* running but you don't hear anything. Issue this command, and you should see at least two calliope processes, (the jockey and controller), and ideally three (including the mpg player): # ps ax | grep calliope | grep -v mysql 9402 ? Ss 0:00 calliope channel 1 jockey 9407 ? S 0:09 calliope soundcard controller : channel 1 22541 S+ 0:00 /usr/bin/mpg123 -R -b 256 calliope If they're all running and you don't hear anything, make sure the user that the mpg player runs as is a member of the audio group, and that the *group* has sound card and mixer access. If you don't see both a "jockey" process AND a soundcard process, then your problem lies elsewhere. -------------------------------------------------- 5. Configure Icecast [ optional ] Ultimately, I'd recommend getting a test channel working, then your sound card, then revisiting this section once you're ready to attempt streaming. Although getting Icecast working is somewhat outside the scope of this document, I'll do what I can to help, since Calliope does support streaming via Icecast. When you have Icecast working, you can stream to it by uncommenting the Icecast variables in the conf file, and defining a channel of type 'stream'. Details are in the conf file. You can define as many streams as you like, but they must be either mp3, or ogg - this is an icecast specific issue (as far as I can tell). Listeners functionality is not currently working, and the UrlMatch is left in the conf file for operability purposes, but is not currently being used. XMMS You must manually enable xmms "title streaming" in order to see the meta- data for the stream: xmms->options->preferences->audio i/o plugins/MPEG Layer 1/2/3/ ->configure->streaming->enable SHOUT/Icecast title Streaming NOTES ON INSTALLING ICECAST I had to download the icecast source, as well as libxslt, libxslt-devel, readline-devel, libogg, libvorbis, zlib-devel and libxml2 in order to get icecast 2.2.0 to compile, your mileage may vary. You then have to install libshout, and finally the Shout.pm module from icecast. Icecast: ./configure make make install Note that you may need to use ./configure --prefix=/usr for compiling some of the subcomponents, particularly libogg and lib vorbis, and possibly libshout. To compile Shout.pm: perl Makefile.pl make make install You'll need to configure Icecast (~/icecast2.2.0/conf/icecast.xml.dist is copied to icecast.xml and configured), set it running. You need to manually turn on the icecast "changeowner" directive, and it should match the User/Group Apache and Calliope will run as (so they can all communicate): icecast -b -c Now, test that icecast is functioning using the test.pl and example.pl scripts in the Shout.pm tarball. You will want to set icecast to start at boot if you're planning on serving streams. Once you've set the server to be up and running, you'll need to stream music to it. You may want to try downloading ices0.4 (mp3 streaming only), and ices-2.x (ogg streaming only), and verify that you can indeed stream music via your web/icecast server, and hear it on using a listening client (e.g. xmms or itunes). Calliope won't need Ices to stream music, and you may want to skip downloading and running Ices. NOTE that the variables IcecastKbps and IcecastSamplerate in the conf file are provided to Shout.pm, which uses them to tell icecast the *expected* rates, not to change the encoding of the streamed music. To do the latter, you need to re-encode the streams with a 3rd party app. You may be able to run the stream through streamTranscoderV3 from oddsock.org and feeding it back to teh icecast server at a lower bitrate. There may be other solutions as well. BSD / MAC right now, streaming does not appear to work on new versions of BSD, particularly mac. we're working on that.... PAUSE BETWEEN SONGS There's a report of buffering problems when playing streaming songs on some platform / client combinations. While I'll try and sort that out, Running the output of Stream.pm through streamTranscoderv3 works fine. SHOUT ERRORS - DEBIAN and FEDORA CORE 5 There's been at least one report that you may need to rebuild libshout from source on Debian in order to get streaming working properly. You almost certainly need to do so on Fedora Core 5: "After compiling and installing libshout make certain the path /usr/local/lib is included in your /etc/ld.so.conf file, then run the ldconfig command as root." Note again that you may prefer instead to use ./configure --prefix=/usr for compiling the subcomponents, particularly libogg and lib vorbis, and possibly libshout, but the above works as well. You may also or instead need to rebuild Shout.pm -------------------------------------------------- 6. Permissions and Ownership VAR DIRECTORY Calliope keeps track of the process ids of its running processes by writing files into /usr/local/calliope/var, and uses var to store m3u files, etc. You may need to create this directory and you need to make sure the directory is owned by the same user and group as defined in your conf: # mkdir /usr/local/calliope/var (optionally) # chown calliope:calligp /usr/local/calliope/var The slightly odd looking command 'chown apache.apache' is a shortcut which sets both the owner and the group as the same time. If your chown command does not support this syntax, then simply do each one separately: # chown -R calliope /usr/local/calliope/var # chgrp -R calligp /usr/local/calliope/var Set permissions: # chmod -R 755 /usr/local/calliope/var You may need to use: # chmod -R 775 /usr/local/calliope/var Make sure the user and group you use above is the same as the user and group configured in your conf. These should also match the user and group which your Apache processes are configured to run as (check the User and Group directive in your httpd.conf file). If you change the User or Group in your conf, be sure to change the ownership of /usr/local/calliope/var (and all the files contained there) to match. COMMAND LINE Next, you may want to set permissions on the command line interface, located at ~calliope/bin/calliope. The command line interface can be used to start and stop calliope, assist in cd burning and many other things. Some commands (start, stop, etc) *require* that you are root. For a list of all current command line features, type: # calliope help Once you've set permissions you're comfortable with, you will probably want to link it into the user bin: # ln -s /usr/local/calliope/bin/calliope /usr/local/bin/calliope This will allows you to type things like "calliope start 3" and not have to specifiy the entire path to calliope. SONG OWNERSHIP If you plan to use the id3 write feature, your songs will need to be in the same group as your Apache process, and writeable by that group. BURNING Ultimately, burning happens via cdrecord. Different distributions handle cdrecord differently; some, including Suse and Redhat, only allow a logged in system user to access the CD. As a result, a CD burning thread runs as a separate user from calliope, ideally as a particular system user. If you run the installer, it should ask you and then set up CD burning. To set up the means to burn CD's manually, select a particular user and group, where the group has cd access (e.g. "disk"). Set BurnUser and BurnGroup in the conf file, set AllowBurning = 1, and run the following as root from the command line, inserting the correct user and group below: (NOTE that the installer will do all this for you) mkdir /usr/local/calliope/var/log/burn; chown $burnuser:$burngroup /usr/local/calliope/var/log/burn; mkdir /usr/local/calliope/var/burn; chown $burnuser:$burngroup /usr/local/calliope/var/burn; touch /usr/local/calliope/var/burn/control_burn; chmod 664 /usr/local/calliope/var/burn/control_burn; touch /usr/local/calliope/var/burn/status_burn; chmod 664 /usr/local/calliope/var/burn/status_burn; chown $burnuser:$burngroup /usr/local/calliope/var/burn/*; If you want more than a single system user to have access to burning, for Suse, you will probably also need to add the main calliope user, and the system users you want to have burn access to the "disk" group in /etc/group, and modify /etc/logindevperm and change permissions from 0600 to 0660 for the /dev/cdrecorder (or whatever your device is for burning cd's). CD burning is new in RC15, and still somewhat expermintal, so please report any problems you have, and be patient as I work out the kinks. A NOTE ON PERMISSIONS Calliope works in concert with many systems. It is both a server, and a CGI application. In addition to files in its own subsystem (anything in the calliope directory), it will access song files (see 'song ownership' above). It works in conjunction with a database server, a web server, and either an icecast server or the sound subsystems (through mpg, ogg, flac, etc.). And it accesses numerous external programs, such as mkfifo, mkisofs, cdrecord, etc. Allowing all of these systems to talk to each other without giving calliope blanket access (eg running it as root as in days of old) is tricky. You may find that calliope works (plays music), but that other features do not work. It's always good to check calliope's log files, as well as apache's error logs to see if a permission error is your problem. Generally, it's easiest if calliope, apache, and icecast all run as the same user/group, although calliope can run as its own user, so long as that user AND the apache user has permission to access the song files, the calliope var/ and var/log directories, and the calliope user has permission to access the sound system. -------------------------------------------------- 7. Populate your Calliope database. LOADER To quickly load your database, simply type: # calliope load Optionally, use 'calliope load -p' for verbose output on what calliope is finding. You may also wish to set a cron job to do this on a regular basis, depending on how often you acquire music. Distributions vary, but this should work: # ln -s /usr/local/callipe/etc/cron.calliope /etc/cron.daily/ NOTE: Calliope has some unusual loader features you may wish to take advantage of, so before loading, read on. CONF calliope's loader features are all controlled by the conf file. calliope supports mp3, ogg, flac, and m4a, and is, as of rc16, fairly easy to extend to new formats (see Interface::mp3.pm if you're interested). calliope supports multiple music collections or music roots, file ownership by user, various filtering and correctional mechanisms, and a great deal more. See calliope/etc/conf for more details on every setting. ALBUM IMAGES & SONG UPLOADS As of RC16, calliope provides for album images. Any image placed in an album's directory will automatically be detected during loading. Alternatively, you can turn on editing mode, and upload images for a particular album. Note that since these images must be visible via the web interface, but that your music directory is most likely not web-accessible, calliope will link, copy, or upload images to a subdirectory of calliope's web directory (calliope/www/albumcovers by default). See the conf -> web interface -> uploads section for various settings relating to how images are linked or copied, and on limits for uploading of files. RELOADING YOUR DATABASE You can always empty your database and reload with different conf settings to see how the loader behaves: # calliope flushdb will empty your music data (but not users, genres, etc.). Then rerun load. Perhaps preferable is: # calliope flushdb -rs Which will (-s) save all your user lists, and (-r) reload the lists once the songs are loaded. CORRECTIONAL FILTERING Prior to loading songs into your database, you may wish to use the renaming module to orginize your compilation songs. # /usr/local/calliope/bin/calliope rename Once launched, you can type h for more details. Rename will go through all the Compilation directories specified in your conf file and look for albums in those directories. It will show you the songs from each album, and ask you to specify the *current* arrangement of artist and song for that album, and then rename the songs in a uniform way. The purpose of this is to allow the loader to pick up artist info (including multiple artists) from the song title. Note that even with UseID3Tags = 1, the loader will use the file name for song and artist info for all compilation albums (if Renamed=1, i.e. if you're using this feature). You may also wish edit the corrections files (~/lib/Artists/Master), and turn UseCorrections on. This tells the loader to look in these files for a matching artist, and correct that artist's name. Again, all info is (will be) web-editable, so you can always correct artist and album info later. Further, the Loader will continue to update the Master file with new artists found. Edit that file (see ~/lib/Artists/README), then run 'calliope clean' to clean up your database. It's worth noting that even if you choose the ID3-only mode in the loader, but also define compilation directories, UseCorrections, and set Renamed equal to 1, calliope will use the file name to determine the song name, not the id3 tag. See /lib/Artists/README_ARTISTS for more details. FILE OWNERSHIP You should also set HasOwnerDirs as appropriate. If all your artists/albums/songs are inside different owner directories, calliope will track the owner (on the web interface), and calliope can be set to only allow a song's owner to download that song (if downloading is on). DATE Finally, UseFileDate allows you to specify whether to use today's date as the date a song is loaded, or the file creation date (the latter being handy if you're reloading a database). If you've previously populated the database, and want to reload all your song data, you can flush the db: # /usr/local/calliope/bin/calliope flushdb This will leave types, dbs, genres, permissions, users, and usertypes intact. You may wish to export your lists before you do this: # /usr/local/calliope/bin/calliope exportlist [] LOADING SONGS Now, populate your database. # /usr/local/calliope/bin/calliope load [-p] where '-p' is optional, and will print out artist, album and song details. The Loader will recursively search every MusicRoot directory configured in conf for files that match the any of the FileExtension directives (also in conf). Any files found will be loaded into the database. In the future when you add or remove songs from one of your MusicRoot directories, run this same command to synchronize the Calliope database with reality. When loading songs, Calliope will try to extract Album, Artist and Song information from the file and directory names. Or you can use MP3 ID3 tags (see below). The loader currently recognizes the following file / directory formats: [ - album]/[.*/].mp3 /[.*/]/.mp3 /.mp3 #NOTE: no album the .mp3 part should be formatted one of the following ways: .mp3 NN .mp3 NN-.mp3 NN - .mp3 where NN is the 2-digit track number 01, 02, 14, etc... "1" is not a valid track number, it must be two digits, like this: "01". here are some valid examples: Orchestral Manoeuvres in the Dark - Dazzle Ships/01 Radio Prague.mp3 Orchestral Manoeuvres in the Dark - Dazzle Ships/02 Genetic Engineering.mp3 Nirvana - Nevermind/01 Smells Like Teen Spirit.mp3 Nirvana - Nevermind/02 In Bloom.mp3 Bjork/I've Seen It All.mp3 Lamb/Fear Of Fours/01 Soft Mistake.mp3 Lamb/Lamb/01 Lusty.mp3 ID3 Tags You can use MP3 ID3 tags to override the file and directory names for the Artist/Album/Song information. You will need to make sure you have the MP3::Info and MP3::Tag perl modules installed. Then set the UseID3Tags directive in conf to 1. MULTIPLE USERS & DATABASE TRANSACTIONS Calliope is of course a multi-user program, and supports transactions when altering the queue, or loading. To fully utilize transactions, your database must support them. In the case of mysql, you may need a professional version of mysql (one with a transational engine built in), and you'll need Berkley-style tables. Postgres should support transactions out of the box. If you plan on having many users (>10?), you may *need* to utilize transactions in order to prevent corruption of the DB. In the case of mysql, you can potentially have mysql rebuild (i.e. clean) its tables every time it starts (probably at boot). -------------------------------------------------- 8. Configure the Web Interface Calliope should really work with a web server. There are three major things you need to do: 1) link calliope's web interface, ~calliope/www, into your web root. 2) alter your web server's configuration file such that it knows about the calliope directory 3) provides cgi support, primarily to home.cgi, and main.cgi. 4) optionally, you can enable mod perl support by pointing to calliope/bin/init.pl The following instructions are specific to Apache, and are probably more germaine to Apache 2.x and Modperl 2.x, but should generally get you by whatever server you're using. To enable the web interface, put a soft link in your Apache document root directory pointing to the Calliope www directory: # ln -s /usr/local/calliope/www /var/www/html/calliope or maybe: # ln -s /usr/local/calliope/www /home/httpd/html/calliope You can find your httpd.conf file, which will tell you where the root web directory is, using: # locate httpd.conf It's typically either in /etc/httpd/conf/httpd.conf or possibly /usr/local/apache2/conf/httpd.conf. You might need to enable the FollowSymLink option in your httpd.conf to allow Apache to follow the above link. To add calliope to your web site, add the ~calliope/etc/httpd.conf to the end of your apache httpd conf file AFTER you've edited it: # cat etc/httpd.conf >> /etc/httpd/conf/httpd.conf If you're using Apache 2, you should symlink calliope's conf file into an appropriate directory - see Apache's httpd.conf file for more information. PASSWORD PROTECTING THE WEB INTERFACE If you would like to password protect Calliope, there are two levels of protection you can choose from: A) protect everything B) just protect the request interface while leaving the home page open to the public This is defined in the conf file, and security is provided by hasing a password via Mysql. The paranoid among you should note that to be truly secure, you should run the request interface over an SSL connection, or the userid/password combos will be sent as plain text over the web. At the moment, calliope doesn't offer support for logging in via an SSL connection, then reverting to an http connection. Using the web server to get a userid password combo via a popup window was discontinued for a number of reasons, so either you chance it, or you'll need to set up an SSL server. If you don't want password protection on the web interface, set Protect to "none" in the conf file. PLEASE NOTE that this will make every user "admin" with complete access. If this is a standalone or home installation, that's fine, but otherwise, we advise against it. VIRTUAL HOSTS If you want Calliope to appear at the top level of your web server (i.e. you are running a dedicated server or virtual host for Calliope), comment out the "Location" directives, and uncomment the "Virtual Host" directive in the httpd.conf file. You'll need to edit the server name to something that corresponds to a subdomain in your hosts file, that is, include "calliope.domain.com" in your /etc/hosts. FASTCGI Fast cgi uses a daemon to speed up calls to cgi applications - for instance, by pooling DB connections. Using fastcgi increases calliope's performance a great deal, and in my experience, blows modperl out of the water. You need: 1) the perl module FCGI.pm (and possibly CGI::Fast, though that's typically installed), which can be found here: http://www.fastcgi.com/ 2) the apache developer packages, needing for compiling mod_fastcgi. 3) the mod_fastcgi module for apache, also found at: http://www.fastcgi.com/ OR, if using Apache2, the new alternative module, apach2-mod_fcgid, which can be found: http://fastcgi.coremail.cn/ This latter module appears to be more stable with calliope. In addition, you must set the UseFastCgi variable in calliope's conf file, and you'll need to modify your calliope apache conf file: etc/calliope.httpd.conf. You may also need to edit your main httpd.conf file, and set up DirectoryIndex. See calliope/etc/calliope.httpd.conf for additional info. ISSUES 1) There are some issues with threads being spawned and not dying properly, which ultimately shows up with apache errors. Reloading the page will bring the page back; restarting apache, making certain any main.fcgi and home.fcgi processes are dead, will clean this up. It would appear that mod_fcgid resolves this. 2) fastcgi doesn't seem to be working with Postgres? 3) The mod_fastcgi was originally built for apache 1.x. It should compile against apache 2.0.x, but may not against 2.2.x. MOD PERL NOTE: as of RC15 (June 06), although you're welcome to try mod perl, I'm recommending fastcgi as by far the better alternative, both from a general performance perspective, and as calliope takes more full advantage of fastcgi. Calliope definitely runs faster under mod_perl. Getting mod_perl to work can be a little trying, so you are advised to get Calliope working period before you attempt mod_perl, but then, if you're thinking about mod_perl, you're probably not even reading these instructions, are you? The main mod_perl interface for calliope is: calliope/bin/init.pl You will need to edit calliope's calliope.httpd.conf file before appending it to Apache's file, or edit the resulting Apache http.conf file in order to use mod_perl with Calliope. More information can be found in calliope/etc/httpd.conf. Calliope should work with either mod_perl 1.x, or 2.x, and instructions for both are in the conf file. Note that if you're using a very recent version of modperl2 (>= 1.999_22) then you'll need to edit init.pl, and use ModPerl2.pm instead of ModPerl.pm. Note that you also need to edit ModPerl.pm, and comment in/out the appropriate "use" lines at the top of the module to be compatible with your version of modperl. Once you've got your web server configuration file set up, restart your server: # service httpd stop # service httpd start or # service httpd restart or possibly: # /etc/init.d/httpd restart or even: # /usr/local/apache2/bin/httpd -k restart TROUBLES? If Calliope has trouble loading modules under mod_perl, but it works fine without mod_perl, you might be suffering from version skew between your command line Perl and the Perl compiled into your Apache. If your version skew is not very large, you might be able to use the 'version skew hack' which is normally commented out in init.pl. See ~/bin/init.pl for more information. -------------------------------------------------- 9. Create users By this point, you should be able to actually use the calliope web interface - the database should be created, your web server should be set up, your perl configured, and the calliope interface should be working. You'll still have to start the jukebox daemon web interface - the database should be created, your web server should be set up, your perl configured, and the calliope interface should be working. You'll still have to start the jukebox daemon to play music, but patience, patience -- you're almost there. As administrator, use the web interface and add new users, using admin:adminpassword to log in. Users are distinguished by type and priority. Type is a number representing the id of one of the usertypes, which are initially specified in data.sql. As calliope admin, you can create new user types, and edit existing ones under the "admin" link on the request home page. There's a fairly comprehensive help section available on using the web interace under "help" on the request home page as well. Default types include: 1=admin priority 1 - 100 2=trusted priority 101 - 200 3=friend priority 201 - 300 4=guest priority 301 - 400 Each type has a corresponding set of permissions indicating what that user type can and cannot do. You can see permission sets either in data.sql, or under Admin->Permissions through the web interface (if you're logged in as a user with 1=admin privleges). Each user type has a range of priorities. The lower the priority, the greater the privileges. Generally a user with lower privileges can mess with the requests of users of a higher privileges, but not vice versa. Priority affects the interaction of user requests on the action queue (at the bottom of the request page), but does *not* affect a user's access to given web interface features. As an administrator, you have access to every feature, as they are all turned on in the interface. The greater the user type number, the fewer features they will apparently see. To best understand all this, create a user of type trusted and friend, and log in / out as all 4 types, and you'll see what appears and disappears. indicates which template folder a user will initially use. The same is true for , and