Installation
Before you start
Installation of the Son may be a bit painful. It's not that each step is particular difficult, but there is so many (minor) things that can go wrong. The following steps are needed in order to be able to start the installation. If you run into problems here, please consult the webpages of the respective provider:
- Compile the plugin for your media player.The source can be found here. In order to that you need a C compiler installed, and probably a lot of libraries available. The error messages here can be very cryptic, the best advise I can give is to check the forums of last.fm. Windows users may run into a very serious problem, after a quick look I was unable to find the source code for the plugins. I think they are supposed to be GPL, which means they should be available. This is just a test, since you need to recompile it later, but if it doesn't work with the unmodified code, it will not work later either. A tip for Suse 9.3 and XMMS user: "If you don't care about bmp (which is a Gnome clone of xmms) use the '--disable-bmp-plugin' option. I also had to point in the glib direction with '--with-glib-prefix=/opt/gnome'." All this is for ./configure. You may also test the plugin using the last.fm, and maybe that is quite enough?
- Install a database like PostgreSQL. It may be helpful to have an admin tool that let you create users and databases. You should find out how to create databases and users.
- Install a webserver like Apache. You should now be able to reach the default page at localhost.
- Install PHP. Find an example php file and verify that the webserver and php talks together.
Ok, there exist a workaround for the compile plugin part, but I find it a bit on the dirty side. First modify your hosts file so that "post.audioscrobbler.com" points to the ip address of your server, then there is some aliasing to be done on the webserver. I have not tried this little trick here, so I will not try to get that right for you. Here is the GET and Host part of the http message:
GET /?hs=true&p=1.1&c=xms&v=0.3.8.1&u="user"krrm HTTP/1.0..Host: post.audioscrobbler.com. Note that "c=xms" denotes the xmms plugin. The Son currently ignores this and also the v (version) parameter.
Database
Create a new database called "music" or whatever you like and then a user called "music". If you go the whatever route, please check all php scripts and the database definition to check if they need to be updated. The definition for the Postgresql database is included. It is only tested with 7.4 (Debain Sarge). If you intend to use another database than PostgreSQL (or maybe Oracle, as they are supposed to be somewhat similar), you need to know that stored procedures are used for adding tracks to the database. This is nothing that a few additional lines of php won't fix, but it must be done. The stored procedures should be readable for anyone with some programming experience. They can be found in the database definition. Also if another database is used, the sql statements may need some adjustments. If anyone does this, please mail me at solfm(at)exponto.com so I can include more detailed descriptions for this.
The database user "music" has more rights than strictly needed, so if your database has "untrusted" users, you could consider thigthen up the rights a bit.
Webserver
I use Apache 1.3 something (still Debain Sarge), but any webserver supporting php and URL rewriting should do just fine.
Add the following aliases (assuming your document root is /var/www)
Alias /music/handshake /var/www/music/handshake.php
Alias /music/resources/ /var/www/resources/
Alias /music/user/resources /var/www/resources/
The aliases are needed in order to let the client get to the right php file and to let the application find common resources as the CSS file and so on.
And some rewriting:
RewriteEngine on
Rewritelog /var/log/apache/rewrite.log
Rewriteloglevel 5
RewriteRule ^/music/user/([^/]+)/artists /music/artists.php?user=$1
RewriteRule ^/music/user/([^/]+)/tracks /music/tracks.php?user=$1
RewriteRule ^/music/user/([^/]+)/select /music/select.php?user=$1
RewriteRule ^/music/user/([^/]+)$ /music/overview.php?user=$1
The rewriting grabs the user name from some URLs and passes it as a parameter to php. It looks better that way. Now, restart your webserver. Note that if you during the next step choose another place for the files than music/ the rewriting rules must be updated. Loglevel can of course be adjusted to whatever you like.
Copy web pages
Copy the web pages into a suitable folder under your webservers document root, this will determine the URLs of the application (unless it is rewritten of course). I have used music/. If you use anything else, you must update all URLs within the application. You can now test the some of the pages like music/index.php. It is even time to create a user, remember username and password. If you're not satisfied with the looks of it, go to the next step.
Modify pages
The pages need to be modified if:
- you don't like the looks of it (I'm supposed to be colour blind)
- you have put the files in other folders than music/
- you use another database than PostgreSQL
- some users use Internet Explorer
Looks can be changed by modifying the CSS file. If the complete layout needs to be updated, just copy & paste the stuff that does things into your own files. This might be some work, but you probably know what you do.
Links can probably be updated by a suitable search and replace through all files.
By the wisedom of someone, most of the database functions within php seems to be database dependant. That means that you must update all database related function calls to someone appropriate to your database. For PostgreSQL they start with pg_. Also remember the stored procedures part. Either rewrite the procedures for your database or move the functionality into the php files.
And don't forget to set the database user and password in the dbconn.php file.
Internet Explorer below version 7 doesn't support "position: fixed" in CSS. As some of the generate pages are quite long, I think it is very nice to always have the menubar available, "postion: fixed" provides this. However it doesn't work in Internet Explorer, so you could either set "position: absolute" in the CSS file or google for some tips to make the pages more IE compatible. The one I tried didn't work. Just for the record, I have spent several hours to ensure that the generated pages are valid xhtml. Don't blame me for poor CSS support in browsers.
Plugin source modification
Before you start you should verify that you are able to compile the plugin without modifications. This should rule out a few sources of errors.
For xmms-scrobbler-0.3.6 open the file "scrobbler.c". Then go to line 16 and change #define SCROBBLER_HS_UR to #define SCROBBLER_HS_URL "http://yourserver/music/handshake" and save the file. Run the compile and install procedures as described. Yep, we're talking of heavy source modifications.
I have only looked into the XMMS plugin, so other plugins may differ significantly. If I get instructions for other plugins I shall include them here.
If this fails completely, you can try the dirty trick at the end of the Before you start section.
What if something goes wrong?
Are the index.php available? If not check the webserver configuration.
Check if the client plugins reports any errors. The XMMS one keeps a separate file where it puts information that is not sent to the database. Under normal conditions this file should be empty. If XMMS is started from a console window messages are also sent to that console.
Use Ethereal or another packet sniffer to verify that the client and the server communicates with each other. The listing is sent half way through the song or after about 4 minutes. Very short songs are not reported (20 or 30 seconds).
Check that the database contains data with commandline or another tool. Webmin is handy for this and more, or look at the pages off your database supplier for tools.
If the compilation doesn't work an d the forums doesn't help you, take a look at the ./configure output. There usually are some more or less cryptic messages in there that might serve as a starting point for a Google search.
