Audioscrobbler Protocol v1.1 ============================ (document version 0.1) 0. Contents ----------- 1. Terms used in this document 2. Protocol stages 2.1. Hard failures 3. The Handshake 3.1. Client identifiers 3.2. Handshake request 3.3. Handshake server response 3.3.1. Handshake server response actions 3.3.2. Handshake server response information 3.3.3. URL processing 4. The Submission 4.1. When to submit 4.2. Submission request 4.2.1. Submission body 4.2.2. MD5 response 4.2.3. Example submission body 4.3. Submission response 4.3.1. Submission server response actions 4.3.2. Submission server response information 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 on one or more played song from the APP to the SERVER. * AUTHENTICATION TOKEN The AUTHENTICATION TOKEN 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. * 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. 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. 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 : http://post.audioscrobbler.com/?hs=true&p=1.1&c=&v=&u= Where : is an identifier for the client. is the version of the client being used. is the name of the user For completeness, the other parameters are : * 'hs=true' indicates that a handshake is requested * 'p=1.1' is the version of the AudioScrobbler protocol to which the APP conforms. Only version 1.1 is supported at present. 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 * '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. 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= 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.3. 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 UPTODATE 17E61E13454CDD8B68E8D7DEEEDF6170 http://62.216.251.205:80/protocol_1.1 INTERVAL 1 --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.3.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 : * 'UPTODATE' This indicates that the HANDSHAKE was successful and an AUTHENTICATION TOKEN follows. 2 lines will follow the 'UPTODATE' (or 'UPDATE') action. The first line is the AUTHENTICATION TOKEN. This is a string which will be used to authenticate submissions. The second line is the URL to which submissions should be made. At this point, the SESSION has been established. * 'UPDATE ' This indicates that the HANDSHAKE was successful and an AUTHENTICATION TOKEN follows. However, a later version of the APP is available at the specified. Clients should take action based on this. If automated upgrade is supported the usual security concerns relating to executable code should be observed. The APP should follow the procedure above for the 'UPTODATE' response for the remaining body. * '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. * 'BADUSER' This indicates that the username supplied is not recognised. The APP should indicate this to the user and allow them to change the user name used for submission. * 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.3.2. Handshake server response information -------------------------------------------- After the action code has been processed, the body may contain updates from from the SERVER for the information of the APP. At present only a single update information action is defined : * 'INTERVAL ' This indicates that the server wishes clients to connect after a minium of seconds. This allows the server to reduce the impact of client connections by limiting their frequency. Clients should observe this minimum and contact more often than has been indicated. Other update information actions may be added in the future. Clients should not fault update actions which are not understood. (JRF: maybe a 'news update information, or something similar might be used, eg 'NEWS ' to indicate a news update is available? client error response information might come up here, too - particularly for the 'tst' client; eg, 'LASTERRORS 5 submissions dropped'). 3.3.3. URL processing --------------------- The URL supplied in the 'UPTODATE' and 'UPDATE' 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 single submission transaction may contain multiple entries to be submitted. 4.1. When to submit ------------------- 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 user must not have skipped within the file, for example by using a slider bar, fast-forward or rewind button. The user may have temporarily paused playback, so long as they did not skip part of the file. If the user does pause playback, the threshold of played music must be reached. That is, it is the playing time which matters, not the elapsed time since the start of play back. * 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. 4.2. Submission request ----------------------- The SUBMISSION request takes place as a HTTP POST transaction with the SERVER, using the address given in the 'UPTODATE' or 'UPDATE' 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.1 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.1. Submission body ---------------------- The SUBMISSION body may contain the details for up to 10 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 : * 'u=' The user name we are submitting for. * 's=' The MD5 response for the AUTHENTICATION TOKEN given in this session. See below for details. * 'a[0]=' The artist name. * 't[0]=' The track name. * 'b[0]=' The album name, or empty if not known. * 'm[0]=' The MusicBrainz identifier if known, or empty if not known. * 'l[0]=' The length of the track in seconds, or empty if not known. * 'i[0]=