Following on from getting my Squeezebox Classic, I am now releasing the first public version of my IMMS plugin for Squeezecenter. It has been more difficult to do this due to lack of up to date documentation, but thanks to the Hello World Plugin by Mitch Gerdisch which provides a skeleton for development of SC7 plugins, combined with spending a couple days of RTFC of Squeezecenter (one of the wonders of Open Source) and other plugins.

It's nice to flex my development muscles from time to time now that I have moved into strategic / management technical roles.

What is all this IMMS stuff anyway?

IMMS is a neat bit of software that analyses music files, and then gradually watches and learns listening habits. It then begins to take over and start working out good tracks to play after the one I am currently listening to. Put that it in charge of the playlist and I hardly ever have to press skip. At most, I just need to start playing to sort of music I want and IMMS will take it from there.

I think the magic in IMMS is that it is subtle and unobtrusive - once it has learned, I don't even think about it. When it becomes noticeable is when it isn't running: I am constantly reaching for the remote to change tracks.

What does the plugin do?

IMPORTANT: This plugin will not give you IMMS. It only provides a way to make Squeezecenter talk to IMMS.  You also need to install IMMS separately for the plugin to be any use.

In it's current form, it will fire up an immsd (the program that does the work) for each new client that joins a SC. It will talk to immsd and tell it about the playlist and what is being listened to, skipped, jumped to etc.

In song shuffle mode (important - it only chooses the music to play in this mode, and is just a spectator in other shuffle modes), it will start choosing music. When a track begins playing, it will find something it thinks is appropriate (remember that it has to learn for some time before it starts getting good at this) and move it to the next position in the play list so that it gets played next.

While learning, IMMS will also be running "analyzer" to characterise the sound of the track. This relies on sox to convert whatever audio format the file for analyzer to process it. For this to work effectively, make sure the sox on your system is able to read the file formats you are using. In my case, my server is currently on Debian Etch and the sox with that does not understand FLAC files so I have had to backport the sox from Lenny. Likewise, on the Etch IMMS package, it depends on XMMS which clearly doesn't fit with a small lightweight headless server.  Again, I have backported imms-common from Lenny and removed the gui tools to avoid pointless X libraries. I will not be releasing these backports as they are quick and dirty for my use only and very unofficial.

On Ubuntu, the IMMS packages are also old (in fact so much so that they are not much use with the other software in the distribution) and on my Ubuntu machines I have also ported over the Debian Lenny stuff. Again, these are quick and dirty ports and I am not releasing them publicly.

How to install the plugin

The IMMS plugin .zip package is downloadable here. Simply extract this into your SC7 plugin directory (/var/lib/squeezecenter/Plugins on Debian derived systems). The .zip will extract into a directory named IMMSPlugin.

IMPORTANT: for IMMS to run, it needs to be able to write databases. Within the IMMSPlugin directory is one named immshome. Ensure this is writeable by the user that SC7 runs under on your system. For Debian based distributions:

$ chown squeezecenter:nogroup immshome

If you are paranoid about security then you may also want to make sure nobody else can look in here:

$ chmod go-rwx immshome

Also ensure that you have IMMS installed - if not, the plugin will not do anything until SC7 is restarted with IMMS installed. If your immsd is installed somewhere other than /usr/bin/immsd then edit Plugin.pm and change the line that says our $IMMSD = "/usr/bin/immsd"; to what is appropriate for your system.

Next, we need to enable the plugin. I deliberately set it as disabled by default at this stage as I do not want it interfering or learning until the end user explicitly wants to try it out - it is after all barely tested code. At this point SC7 will require restarting to bring the plugin on board.

Then it should be no more to it than playing music and after some time enjoying IMMS choosing the music (IMPORTANT - again I will say that it will only choose your music for you if you are listening in song shuffle mode, otherwise it is only a spectator).

Using existing IMMS databases

As I have been using IMMS for a while, it has already learned and I want to use the same databases so it doesn't have to learn again. I would recommend allowing the plugin to run initially to test it and allow it to create all the directories and databases with the right permissions before transferring data.

IMMS databases hide under .imms in my home directory, or immshome/<MAC of your player>/.imms with this plugin. If the server is running exactly the same versions of SQLite for the databases then the procedure is simply a case of shutting down Squeezecenter (so the databases are not in use), taking note of the permissions used for the plugin's databases and copying the databases from the original, making sure to keep the same permissions.

If different versions (or more specifically moving to an older version) of SQLite are in use then there is a risk that the above procedure will result in an unusable database and immsd will simply bail out when it is started. Fear not - this is easily solved by dumping the old databases and re-creating the new ones from the dumps instead of copying them in the procedure above. For each database file do the following:

1. Dump the database to a text file:  sqlite3 DATABASE_FILE.db .dump >temp.dump
2. Transfer temp.dump to the machine where you want to create the new database.
3. Restore the database to a fresh file:  sqlite3 temp.db ".read temp.dump"
4. Move the temporary database to replace whichever the dump was from:  mv temp.db DATABASE_FILE.db
5. Check the permissions on this file and change them to match the original permissions of the files from the plugin.
6. Tidy up - remove temp.dump which is no longer needed

At this point it should be safe to start SC again and check that everything is working.

How I use it

For me the magic of IMMS is not having to have playlists. I simply add all my music to the current playlist, set song shuffle mode and press play on a track that I fancy listening to. Once it has learned, IMMS does the rest with little effort on my part. That's why I like it so much - it's intelligent software that isn't constantly fighting for my attention.

Important stuff to keep in mind

This is first public release of the plugin. It is only for those who are happy taking the risk of running early development software. Do not use it if you don't know what this means and are not in a position to understand the risks you are taking. I would appreciate anyone spotting bugs to report them via "contact" on this blog.

IMMS takes time to learn.  If you are not sure if it is working then watch the next few tracks in your playlist. Shortly after a track starts playing, a track from elsewhere in the playlist will get inserted after it. You can also go into the directory immshome/<MAC of your player>/.imms where you should find a bunch of files created by immsd. Look at imms.log which will be updated as new songs get played:

$ tail -f imms.log

Over time the IMMS databases may get quite large. My one is about 140MB right now. Ensure that you have sufficient space for them else you will run into trouble. Also keep in mind that each player will have it's own set of databases. If you have several players and a large music collection then this could result in several GB of disk space being used.

IMMS does sometimes take a while to work out a good song so if songs are skipped in rapid succession then you will end up playing the raw shuffled playlist without IMMS having chosen the song you are listening to. This is no problem, just something to be aware of if you are wondering why the music isn't so great after a series of skips.

If you want to know what is going on deep in the plugin, there is currently a debug log file under immshome which provides a detailed log of what is going on in the plugin. If any weird bugs emerge, then this will probably be the best place to start for working them out.

Finally, if nothing seems to be working, try this quick set of debug steps:

1. Check the plugin has been enabled under the Squeezecenter settings.
2. After turning on a player and giving it time to wake up (immsd only starts when a player is up and running), check for an immsd running (ps ax |grep immsd$) and if not then look into it:
   1. Check if immsd is where the plugin expects and is executable by SC:  ls -l /usr/bin/immsd
   2. Check the permission on immshome:  ls -ld IMMSPlugin/immshome
3. If immsd is working, check the log files as described above which will probably give a clue to what is happening.