Audioscrobbler Protocol v1.2 ============================ (document version 0.1) 0. Contents ----------- 1. Terms used in this document 2. Protocol stages 2.1. Hard failures 2.2. Fatal failures 3. The Handshake 3.1. Client identifiers 3.2. Authentication token 3.3. Handshake request 3.4. Handshake server response 3.4.1. Handshake server response actions 3.4.2. URL processing 4. The Submission 4.1. Submissions of currently playing tracks 4.1.1. Track list submission request 4.1.2. Track list submission body 4.1.3. Example submission body 4.1.4. Submission response 4.1.5. Submission server response actions 4.2. Submissions of track lists 4.2.1. Track list submission request 4.2.2. Track list submission body 4.2.3. Example submission body 4.2.4. Submission response 4.2.5. Submission server response actions 5. Caching of submissions 6. Protocol use with a web-proxy 7. Application guidelines A. Appendix A - Implementation examples B. Appendix B - Historical information C. Appendix C - Contact details 1. Terms used in this document ------------------------------ * APP The client software used to play music. Could be iTunes / XMMS / any other player. * SERVER The AudioScrobbler server group. There are multiple servers used by the AudioScrobbler system. * 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. A SESSION may be interrupted by network failures. * HANDSHAKE A HANDSHAKE is the process of inital negotiation of the APP with the SERVER. * SUBMISSION The process of sending information from the APP to the SERVER. It may take the form of either a TRACK LIST or a NOW PLAYING submission. * TRACK LIST A list of tracks which have been played by the APP and which are submitted to the SERVER as part of a SUBMISSION. * NOW PLAYING The information about the currently playing track, submitted by the APP to the SERVER as part of a SUBMISSION. * AUTHENTICATION TOKEN The AUTHENTICATION TOKEN is a string which is used to authenticate the user during the HANDSHAKE stage. * SESSION ID The SESSION ID is a string which verifies that this SESSION belongs to a given user. It is obtained from the handshake and is valid for a single SESSION only. * HARD FAILURE A HARD FAILURE is an event which prevents the HANDSHAKE or SUBMISSION from progressing and cannot be resolved by the client. Examples might be DNS failure, server connection failure, and the extinction of all life. A HARD FAILURE terminates a SESSION. * FATAL FAILURE A FATAL FAILURE is an event which prevents the HANDSHAKE or SUBMISSION from progressing, cannot be resolved by the client and must be corrected by either the user or the developer. Examples might be a banned client, an incorrectly formed request, incorrect password, and investigations by Mulder and Scully. A HARD FAILURE terminates a SESSION and must cause the client to cease operation until the fault has been addressed by the user. * THRESHOLD The THESHOLD is the limit of playback before information about a track is submitted to the server. This prevents tracks which begin but the user immediately 'skips' from being submitted. 2. Protocol stages ------------------ The protocol has two stages : * The HANDSHAKE stage * The SUBMISSION stage Each of these will be dealt with below. 2.1. Hard failures ------------------ A HARD FAILURE at either of the HANDSHAKE or SUBMISSION stages should be counted. If 3 HARD FAILURE events occur consecutively, the APP should fall back to the HANDSHAKE phase. If 3 HARD FAILURE events occur consecutively at the HANDSHAKE phase, the APP should wait 30 minutes before attempting a further connection. Upon a successful connection to the server, the APP should reset the HARD FAILURE counter to 0. If the APP fails to connect to the handshake URL, the user may be informed. The user should not be repeatedly informed about a continuing HARD FAILURE. 2.2 Fatal failures ------------------- A FATAL FAILURE at either of the HANDSHAKE or SUBMISSION stages should cause the APP to stop its network operation and require action from the user. These are failures which cannot succeed if they are retried and the APP should never attempt to retry them. Once a change to parameters has been made by the user, the APP should re-start the HANDSHAKE stage. 3. 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 HARD FAILURE events. In this case, the APP should not handshake more than once every 30 minutes (unless a FATAL FAILURE has been resolved). The transaction with the AudioScrobbler server takes place over HTTP. The HANDSHAKE stage uses a GET request to obtain an AUTHENTICATION TOKEN. The GET request should be sent to the following URL (split with newlines to make it readable): http://post.audioscrobbler.com/?hs=true &p=1.2 &c= &v= &u= &t= &a= Where : is an identifier for the client. is the version of the client being used. is the name of the user is the current unix timestamp (seconds since 1970-01-01T00:00 in UTC, as a string in base 10. is an AUTHENTICATION TOKEN calculated from the timestamp and the user's password. See below for details. For completeness, the other parameters are : * 'hs=true' indicates that a handshake is requested * 'p=1.2' is the version of the AudioScrobbler protocol to which the APP conforms. Version 1.1 is also supported, but uses a different protocol; see a separate document for details. 3.1. Client identifiers ----------------------- Client identifiers areallocated centrally by the AudioScrobbler administrators. They are used to provide a centrally managed database of the client version numbers, allowing the APP to inform the user of updates if necessary. The list of clients includes (but is not restricted to) : * 'osx' = Applescriptable MacOS X Application (iTunes) * 'wa2' = Winamp2 plugin * 'wa3' = Winamp3 plugin * 'xms' = XMMS * 'wmp' = Windows Media Player plugin * 'slm' = SliMP3 (SlimServer / SqueezeBox) * 'mmj' = MusicMatch Jukebox * 'foo' = FooBar * 'qcd' = QCD * 'ami' = AmigaAMP * 'ss7' = SlimServer 7 * 'tst' = ALL Experimental clients Clients which have not been allocated an identifier should use the identifier 'tst', with a version number of 1.0. Do not distribute code which uses the experimental identifier. Do not use the identifiers for other clients. Contact the AudioScrobbler administrators for an allocation . 3.2. Authentication token ------------------------- The AUTHENTICATION TOKEN to supply as part of the HANDSHAKE is a combination of the timestamp supplied with the HANDSHAKE request and the user's password. This ensures that the user's password is never sent on the network in plain text. The algorithm for generating the MD5 response is thus : md5response = md5(md5(password) + timestamp) md5() is a function which takes a string and returns the 32-byte hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The '+' binary operator is a concatenation of the two strings. 3.3. Handshake request ---------------------- For clients wishing to communicate directly with the server, a connection should be made to post.audioscrobbler.com port 80. the request should be sent as a standard HTTP GET request, in a form similar to : --8<-------- GET /?hs=true&p=1.1&c=&v=&u=&t=&a= HTTP/1.0 Host: post.audioscrobbler.com User-Agent: YourAgentName/YourVersionNumber Pragma: no-cache --8<-------- Where indicates a '\r\n' (Carriage Return, Line Feed) sequence. Clients using a library to perform this operation should consult their documentation for the correct manner of a performing a GET request. 3.4. Handshake server response ------------------------------ The SERVER will respond in the standard manner for a HTTP transaction. There will be an initial status response, followed by the server headers, and then finally the body of the response. A typical server response might be : --8<-------- HTTP/1.0 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=17E61E13454CDD8B68E8D7DEEEDF6170; Path=/ Content-Type: text/plain;charset=ISO-8859-1 Date: Sat, 10 Sep 2005 16:24:26 GMT Proxy-Connection: close OK 17E61E13454CDD8B68E8D7DEEEDF6170 http://62.216.251.205:80/now_playing http://62.216.251.205:80/protocol_1.2 --8<-------- If the status line ('HTTP/1.0 200 OK') does not give a 200 (indicating a successful transfer) response, then this constitutes a HARD FAILURE. The server is not responding to the request as expected and the APP should handle this. Such events may occur during network outages or when the server is heavily loaded. In addition, 'transparent' proxies may obscure the connection attempt. It is important to be aware, if the APP is performing all communication with the server itself, rather than using a library, that the header lines will be terminated. 3.4.1. Handshake server response actions ---------------------------------------- The body of the server response uses (ASCII 10) terminated lines. The APP should process the first line of the body to determine the action it should take : * 'OK' This indicates that the HANDSHAKE was successful and a SESSION ID follows. 3 lines will follow the 'OK' action. The 1st line is the SESSION ID. This is a string which will be used to associate your submissions with this handshake. The form of the SESSION ID may change without notice. The 2nd line is the URL to which NOW PLAYING information should be given. The 3nd line is the URL to which SUBMISSIONS should be given. At this point, the SESSION has been established. * 'FAILED ' This indicates that a failure has occurred somewhere. The indicates the cause of the failure. Clients should treat this as a HARD FAILURE. The reason may be reported to the user, but the APP should not repeat messages intrusively. Repeated FAILED messages will result in the 30 minute HANDSHAKE deferral being performed. * 'BADAUTH' This indicates that the username or password supplied is not recognised. The APP should indicate this to the user and allow them to change the user name used for submission. This should be treated as a FATAL FAILURE. * 'BADTIME' This indicates that the time supplied is too far from the current time as known to the server. Clients should request that check their clock settings. Developers may want to checkt that their timestamp calculation does not include timezone (ie the time is in UTC). This failure should be treated as a FATAL FAILURE. * 'BANNED' This indicates that the client has been banned by the server. Usually because it is violating the protocol in a manner that is seriously detrimental to the system for other users. This should be treated as a FATAL FAILURE. * All other responses should be treated as a HARD FAILURE. An error may be reported to the user, but as with other messages this should be kept to a minimum. 3.4.2. URL processing --------------------- The URL supplied in the 'OK' actions is in the normal form for URLs. Clients should process this in whatever manner is necessary to perform the connection to the server for SUBMISSION. The APP is not expected to be required to communicate in any scheme other than HTTP. The server address given may differ from that used for the handshake, and this should not be faulted by the APP. The port number may differ from that used for the handshake, and this should not be faulted by the APP. 4. The Submission ----------------- The SUBMISSION stage of the protocol should be entered when the details about music being (or having been listened to) is available. A SUBMISSION may take one of two forms: NOW PLAYING submissions may occur when a track is started. TRACK LIST submissions should occur for tracks which have passed the THRESHOLD or have been cached from earlier attempts. 4.1. Submissions of currently playing tracks -------------------------------------------- The APP may choose to make a SUBMISSION of NOW PLAYING tracks to the SERVER. This will usually be performed immediately after the start of a track. It is optional and will only appear in the user's profile to the extent that it will be indicated as 'Now playing'. 4.1.1. Track list submission request ------------------------------------ The SUBMISSION request takes place as a HTTP POST transaction with the SERVER, using the address given in the 'OK' actions during the HANDSHAKE phase of the protocol. Clients wishing to perform this transaction themselves should submit the request in the standard HTTP POST manner, in a similar form to : --8<-------- POST /now_playing HTTP/1.0 Host: 62.216.251.205 User-Agent: YourAgentName/YourVersionNumber Pragma: no-cache Content-Type: application/x-www-form-urlencoded Content-Length: --8<-------- 4.1.2. Track list submission body ----------------------------------- The SUBMISSION body will contain the details of the track which is currently playing. The request takes the form of a group of form encoded key-value pairs which are submitted to the server as the body of the HTTP POST request. The key-value pairs are : * 's=' The SESSION ID returned during the HANDSHAKE stage. * 'a=' The artist name. Required. * 't=' The track name. Required * 'b=' The album name, or empty if not known. * 'n=' The track number within the album, or empty if not known. * 'm=' The MusicBrainz identifier if known, or empty if not known. * 'l=' The length of the track in seconds, or empty if not known. Required when the is 'P'. Key-value pairs are separated by an '&' character, in the usual manner for form submissions in HTTP. The values given to the keys must be converted to UTF-8 first, and must be URL encoded. 4.1.3. Example submission body ------------------------------ The following submission body is for the use 'gerph', with an undisclosed authentication token and password. The details being submitted are : Track: Lost For Words Album: The Division Bell Artist: Pink Floyd Track number: 10 MusicBrainzID: Length: 314 seconds --8<-------- FIXME --8<-------- Line breaks have been inserted for readability and are not part of the submission. 4.1.4. Submission response -------------------------- The SERVER will respond in the standard manner for a HTTP transaction. There will be an initial status response, followed by the server headers, and then finally the body of the response. A typical server response might be : --8<-------- HTTP/1.0 200 OK Server: Apache-Coyote/1.1 Content-Type: text/plain;charset=ISO-8859-1 Date: Sat, 10 Sep 2005 17:51:14 GMT Proxy-Connection: close OK --8<-------- The same caveats apply to the SUBMISSION response as to the HANDSHAKE response. 4.1.5. Submission server response actions ----------------------------------------- The body of the server response uses (ASCII 10) terminated lines. The APP should process the first line of the body to determine the action it should take : * 'OK' This indicates that the submission request was accepted. It does not mean that the submission was valid, but only that the authentication and the form of the submission was validated. * 'BADSESSION' This indicates that the submission failed because the SESSION ID was incorrect. During development this will occur when the MD5 authentication algorithm is incorrect (see section A.2). In real use, the most likely reason for this response is a race between two clients trying to use the same account. Each client will attempt to obtain an SESSION ID and in the process invalidate the SESSION ID obtained by the other. This may also occur if the server is reset or undergoes serious problems requiring the resetting of SESSION IDs. This is not likely. The APP should wait a random period and then fall back to the HANDSHAKE stage. The random element will ensure that when multiple, identical clients are in use they do not attempt authentication at the same time, resulting in no submissions ever occurring. The APP should not remove submitted tracks from its queue. * All other responses should be treated as a HARD FAILURE. An error may be reported to the user, but as with other messages this should be kept to a minimum. 4.2. Submissions of track lists ------------------------------- The APP should monitor the user's interaction with the music playing service to whatever extent the service allows. In order to qualify for submission the following criteria must be met : * The playback time must have exceeded the THRESHOLD. The THRESHOLD is defined as being the earliest of 240 seconds and half the track's total time. If the total time cannot be determined for track, 240 seconds should be used as the THRESHOLD. * The total playback time for the track must be more than 30 seconds. Do not submit tracks shorter than this. * The music being played must have been tagged with some readable form of name. Clients should use ID3v1(.1) or ID3v2 tags where appropriate, or other mechanisms (eg ShoutCast inline track information) to obtain this information. Unless the client is specially configured, it should not attempt to interpret filename information to obtain this information. * The tag information must include at least the artist and track name. * The submission should occur once the track finishes playing. The track may have been stopped manually or reached the end. 4.2.1. Track list submission request ------------------------------------ The SUBMISSION request takes place as a HTTP POST transaction with the SERVER, using the address given in the 'OK' actions during the HANDSHAKE phase of the protocol. Clients wishing to perform this transaction themselves should submit the request in the standard HTTP POST manner, in a similar form to : --8<-------- POST /protocol_1.2 HTTP/1.0 Host: 62.216.251.205 User-Agent: YourAgentName/YourVersionNumber Pragma: no-cache Content-Type: application/x-www-form-urlencoded Content-Length: --8<-------- 4.2.2. Track list submission body --------------------------------- The SUBMISSION body may contain the details for up to 50 tracks which are being submitted. These must be listed in advancing chronological order; that is, the details must appear in the order in which they occurred in time. Under normal circumstances only a single track will be submitted, but clients are required to cache details in case of network failure, so multiple submissions are expected to be part of the APPs capabilities. The request takes the form of a group of form encoded key-value pairs which are submitted to the server as the body of the HTTP POST request. The key-value pairs are : * 's=' The SESSION ID returned during the HANDSHAKE stage. * 'a[0]=' The artist name. Required. * 't[0]=' The track name. Required * 'b[0]=' The album name, or empty if not known. * 'n[0]=' The track number within the album, or empty if not known. * 'm[0]=' The MusicBrainz identifier if known, or empty if not known. * 'i[0]=