NOTE: this is an utter mess, I just copy and pasted the source from the old wiki.

Audioscrobbler Protocol v1.0

Terms

APP
The client software used to play music. could be iTunes / XMMS / any other player.
SERVER
The AudioScrobbler server.
SESSION
A SESSION starts when the APP is loaded, and ends when the APP is closed. A SESSION consists of a single HANDSHAKE followed by multiple SUBMISSIONS.
HANDSHAKE
A HANDSHAKE is the process of inital negotiation of the APP with the SERVER.
SUBMISSION
The process of sending information on one or more played song from the APP to the SERVER.

The Handshake

A Handshake is the first step in beginning a SESSION. A Handshake should occur just once during a SESSION, e.g. when the APP first loads, or after the APP detects 3 catastrophic (i.e. DNS resolution or connection refused) failures in submitting. In this case, the APP should not handshake more than once every 30 minutes. If the APP fails to connect to the handshake URL, the user should be informed.

This is a HTTP GET to the following url:

http://post.audioscrobbler.com?hs=true&v=1.0&c=wa2

  • hs=true indicates a handshake is requested
  • v=1.0 is the version of the APP plugin
  • c=wa2 is the name of the APP
    • Applescriptable MacOS X Application (iTunes) = osx
    • Winamp2 = wa2
    • Winamp3 = wa3
    • XMMS = xms
    • Windows Media Player = wmp
    • SliMP3 = slm
    • MusicMatch Jukebox = mmj
    • FooBar = foo
    • QCD = qcd
    • AmigaAMP = ami

Server responses

Lines in the SERVER responses and APP requests are separated by a unix newline character (\n) only. Expect three lines from the server: pants

UPTODATE http://post.audioscrobbler.com/genericplugin.php INTERVAL 100

* The UPTODATE means your version is up to date. * The url is where to post your data to * INTERVAL is the number of seconds you must wait between sending updates this will be 0 if the server is doing ok, but if the server is under heavy stress, it may go up to avoid too many submissions in a short space of time.

If you are using an outdated version of a plugin, you will see something like this, indicating an update is available:

UPDATE http://www.audioscrobbler.com/page.html http://post.audioscrobbler.com/genericplugin.php INTERVAL 100

This allows you to notify the user, and perhaps load the downloads page in a browser.

Submitting Songs

Song information is sent to the server by a HTTP POST request.

Each song should be posted to the server when it is 50% or 120 seconds complete, whichever comes first.

You must post data using the following variable names, to the address you received during the handshake. The items in <brackets> should be replaced by user data, minus the brackets. To preserve characters that fall outside of normal ASCII, like accented latin characters and Asian languages, UTF-8 encoding is used first, then URL encoding.

The proper order of encoding

# Each field in <> below is converted to UTF-8, then URL-encoded. # Everything outside of <> is not encoded in any way. # Key/value pairs are separated by &

Required variables:

<verbatim> u=<username> p=<md5sum of password, hex encoded> a0?=<artist name> s0?=<song title> l0?=<length of song in seconds> d0?=<UTC Date/Time in YYYY-MM-DD hh:mm:ss format> </verbatim>

Optional variables:

<verbatim> b0?=<album title> m0?=<MusicBrainz?.org MBID for this track> </verbatim>

Date example: A song played on my computer on March 12th, at exactly 4:20pm, in a UTC-6 timezone (Central Standard) would be submitted like this:

2003-03-12 22:20:00

Notice that variables other than user and pass have pair of brackets at the end with a number (an array index). This is because if you need to submit more than one song per transaction (eg. to clear a backlog) you can simply add more of the variables with brackets and increment the number, this creates an array on the server and will cause all songs to be inserted to the database. Only the last 10 songs from a multiple submission are accepted.

You may want to consider using a well featured HTTP library like the cross platform / open source libcurl (http://curl.haxx.se/libcurl/) that can automate url encoding, headers, error handling, background loading, formation of the POST query, etc.

Server response to a song submission:

You will receive either 1 or 2 lines in response to a submission. On the first line, it will be one of these three:

  • OK o if everything went well you will just get OK
  • BADPASS o You sent the wrong username password combo. Get the user to fix it.
  • FAILED <error message> o the space after FAILED followed by an error message is optional. This indicates something went wrong, and you should cache the submission and retry later. The optional description might provide a clue as to the problem.

An optional second line:

  • INTERVAL <seconds> This means the server is very busy, and you should wait at least <seconds> seconds between further submissions. When the server calms down again you will get another INTERVAL response specifiying a lesser number (probably zero).

If the client gets an un-parsable response (probably HTML) then there was an error of some sort, so assume the FAILED response.