Any support questions about this protocol should go to me, (russ at last dot fm) or to the forum.

This still assumes a knowledge of Protocol1, unfortunately. Anyone who merges these two documents gets my undying respect.

> Sure? They are merged here: Protocol1.1.merged

Audioscrobbler Plugin Protocol

  • INTERVAL commands can be at the end of any response block, but don't expect them to be. Always observe the latest INTERVAL you get.
  • Everything must be valid UTF-8. If it's not, don't complain that the system is ignoring you :). If your plugin isn't submitting valid UTF-8, it's logged at our end and I'll probably contact you :).
  • Do not try to guess info from the filename - if there are no tags, don't submit the file.
  • If you get a FAILED message, either try to display the error text in a non-intrusive way, or only display the error once for repeated retries with the same error (the wa2 plugin had a habit of spamming clients with messageboxes, which stopped us doing useful things with the FAILED message).

Handshake:

Request:

http://post.audioscrobbler.com/?hs=true&p=1.1&c=<clientid>&v=<clientver>&u=<user>

Response:

UPTODATE
<md5 challenge>
<url to submit script>
INTERVAL n

Or

UPDATE <updateurl>
<md5 challenge>
<url to submit script>
INTERVAL n

Or

FAILED <reason>
INTERVAL n

Or

BADUSER
INTERVAL n

Client IDs

Client IDs must be registered with Russ. Whilst testing you may use id 'tst', plugin version 1.0. Please do not release any code using the tst id.

Song Submissions

  • Each song should be posted to the server when it is 50% or 240 seconds complete, whichever comes first.
  • If a user seeks (i.e. manually changes position) within a song before the song is due to be submitted, do not submit that song.
  • Songs with a duration of less than 30 seconds should not be submitted.
  • If a MusicBrainz? ID is present in the file (as defined here), then you should send it.
  • If a user is playing a stream instead of a regular file, do not submit that stream/song.

Request:

HTTP Post to submit script given in handshake. Note that all the post variables noted here MUST be supplied for each entry, even if they are blank. All variables must also be sent on one line, no new line seperators as shown below. (hint: standard HTTP post request)

u=<user>&s=<MD5 response>&a[0]=<artist 0>&t[0]=<track 0>&b[0]=<album 0>&m[0]=<mbid 0>&l[0]=<length 0>&i[0]=<time 0>

You can also send multiple submissions in one request, like so:

u=<user>&s=<MD5 response>&
a[0]=<artist 0>&t[0]=<track 0>&b[0]=<album 0>&m[0]=<mbid 0>&l[0]=<length 0>&i[0]=<time 0>&
a[1]=<artist 1>&t[1]=<track 1>&b[1]=<album 1>&m[1]=<mbid 1>&l[1]=<length 1>&i[1]=<time 1>&
...
a[n]=<artist n>&t[n]=<track n>&b[n]=<album n>&m[n]=<mbid n>&l[n]=<length n>&i[n]=<time n>&

If you try to submit more than 10 tracks at once, some of them may not be accepted.

The MD5 response is md5(md5(your_password) + challenge), where MD5 is the ascii-encoded, lowercase MD5 representation, and + represents concatenation. MD5 strings must be converted to their hex value before concatenation with the challenge string and before submission to the final MD5 response.

The individual fields are:

a[0]
- artist name
  • t[0]
    - track title
  • b[0]
    - album name
  • m[0]
    - MusicBrainz? ID (send empty id if you don't know it, don't skip it)
  • l[0]
    - track length in seconds
  • i[0]
    - date in YYYY-MM-DD hh:mm:ss format

    Response:

    FAILED <reason>
    INTERVAL n
    

    Or

    BADAUTH
    INTERVAL n
    

    Or

    OK
    INTERVAL n
    

    If the server returns FAILED, you retry at a later date. When? Would it make sense to recommend an exponential backoff?

    If it returns BADAUTH, you may need to re-handshake (you're likely to get temporarily blocked if you're attempting to resubmit at one-second intervals after getting repeated BADAUTH errors).

    If it returns OK, you should remove the submitted tracks from your plugin's cache. Note that OK does not mean that the submissions have been entered into the DB - it just means we are in a position to process them. The three main reasons that submissions are OK'd but not entered are:

    • Bad UTF-8
    • Bad tagging (we now completely drop any entries which look crap, e.g. 01-artist_blah)
    • Spam filter (sanity checks like claiming to have played 10 songs in 10 seconds -- not possible)

    Plugin Guidelines

    • DO NOT popup error boxes unless absolutely necessary. If you make your plugin pop up a "your password is incorrect" error message every time a song is played, it gets annoying. The server may go offline for periods and cause errors. These should be logged silently!