Technical Documentation

Components

How does IMMS work?

Briefly: there is a server process, immsd, that listens on a socket for clients. Clients from music players connect to the server and issue commands when you press Next, Skip, change your playlist etc. The server talks to a database which stores your music preferences and the results of file analysis and tells the client what song to choose next.

TODO: a diagram that shows client <--> server <--> database(s) , etc.

TODO: technical documentation (here or on the wiki?) for devs wanting to build a client. Note how it should behave, what commands to send and receive when, etc.

SQL

Some table definitions for the database in imms2.db. See that file for more details (you can use the sqlite command-line utility to view the database, or a GUI program if you prefer). By default (on linux) the IMMS database is stored in your home directory in ~/.imms .

The 'Identify' table holds information about the file on disk.

CREATE TABLE Identify (

       'path' VARCHAR(4096) UNIQUE NOT NULL,

       'uid' INTEGER NOT NULL,

       'modtime' TIMESTAMP NOT NULL,

       'checksum' TEXT NOT NULL

);

It also maintains the uid <-> sid mapping.

Every file has a unique id - uid.

Every song has an id - sid - but it is shared between different versions of the same song (eg. remixes)

CREATE TABLE Library (

       'uid' INTEGER UNIQUE NOT NULL,

       'sid' INTEGER DEFAULT -1,

       'playcounter' INTEGER DEFAULT 0,

       'lastseen' TIMESTAMP DEFAULT 0,

       'firstseen' TIMESTAMP DEFAULT 0

);

CREATE TABLE Last (

       'sid' INTEGER UNIQUE NOT NULL,

       'last' TIMESTAMP

);

CREATE TABLE Ratings (

       'uid' INTEGER UNIQUE NOT NULL,

       'rating' INTEGER NOT NULL,

       'dev' INTEGER DEFAULT 0

);

'Journal' maintains a record of all play events.

The 'played' field can be used to determine if the song was skipped or not, and 'flags' encodes the rest of the context, such as whether the song was manually selected by the user, etc.

Good for, for example, generating reports about songs popular last week, etc.

CREATE TABLE Journal (

       'uid' INTEGER NOT NULL,

       'played' TIME NOT NULL,

       'flags' INTEGER NOT NULL,

       'time' TIMESTAMP NOT NULL

);

CREATE INDEX Jouranl_uid_i ON Journal (uid);

CREATE TABLE Info (

       'sid' INTEGER UNIQUE NOT NULL,

       'aid' INTEGER NOT NULL,

       'title' TEXT NOT NULL

);

CREATE TABLE Tags (

       'uid' INTEGER UNIQUE NOT NULL,

       'title' TEXT NOT NULL,

       'album' TEXT NOT NULL,

       'artist' TEXT NOT NULL

);

'Artist' identifies an artist entity.

Of particular interest if the 'readable' field which holds IMMS' best guess at the human-readable artist name.

Good for generating reports and such.

CREATE TABLE Artists (

       'aid' INTEGER PRIMARY KEY,

       'artist' TEXT UNIQUE NOT NULL,

       'readable' TEXT UNIQUE,

       'trust' INTEGER DEFAULT 0

);