Messages from the client to the daemon are prefixed with '> ' and vice versa.

In the following, n refers to a number, and b to a boolean, i.e. 0 or 1. path is self-explanatory

Preamble

> Version
< Version 2.1
> IMMS
> Setup b
> PlaylistChanged n
< GetEntirePlaylist
> Playlist 0 path
> Playlist 1 path
...
> Playlist n path
> PlaylistEnd

The Setup parameter is whether to use X idle statistics. The PlaylistChanged parameter is the length of the playlist.

At this point the server will quiz the client with random queries:

< GetPlaylistItem n
> PlaylistItem n path
...

If, now or later, immsd believes it is out of sync with the playlist,

< PlaylistChanged
> PlaylistChanged n

which triggers a GetEntirePlaylist exchange. Consider this a rebuke—you really should send PlaylistChanged n whenever the playlist changes.

When a new song begins to play, the client sends:

> StartSong n path

When the client is ready to queue up the next song from IMMS:

> SelectNext
< EnqueueNext n

Occasionally the answer will instead be TryAgain, which is self explanatory.

When a song is finished, skipped, or jumped away from:

> EndSong b b b

where the parameters are finished (not skipped), jumping, and bad (if bad is true, no ratings adjustments are made). Watch the log in ~/.imms/imms.log to get the hang of it.

From time to time, the server will send:

< ResetSelection

in which case the client should send SelectNext and replace the upcoming IMMS tune with the resulting EnqueueNext command. This is so IMMS can change its mind about what the best next song would be.

---

The protocol is straightforward and can be implemented as an event loop listening to commands on the server, and a control thread notifying IMMS of the changes in the media player.

Server-originated messages:

• ResetSelection
  immsd changed its mind, reset the selection of the upcoming track and send SelectNext to get the new upcoming track.
• TryAgain
  try SelectNext again
• EnqueueNext pos
  Enqueue track pos as the upcoming track.
• PlaylistChanged
  immsd detects it is out of sync with the playlist. Reply with PlaylistChanged len.
• GetPlaylistItem pos
  Reply with PlaylistItem pos path.
• GetEntirePlaylist
  Reply with a series of Playlist pos path messages and finally PlaylistEnd.
• Version 2.1
  In reply to Version.

Client-originated messages:

• Version
  Get the version (Version 2.1 at the time of this writing).
• IMMS
  Request to be an IMMS client.
• Setup xidle
  Initialization. xidle is 0 or 1.
• PlaylistChanged len
  The playlist has changed and its new length is len.
• SelectNext
  Request the upcoming track to play.
• PlaylistItem pos path
  In reply to GetPlaylistItem pos.
• Playlist pos path
  In partial reply to GetEntirePlaylist.
• PlaylistEnd
  Send after sending all Playlist pos path messages, following GetEntirePlaylist.
• StartSong pos path
• EndSong finished jumping bad
  The parameters are boolean (0 or 1).

Consult the source in immsd/ and clients/ with any unanswered questions, then update this page with the answers.

---