Audioscrobbler Realtime Submission Protocol v1.2 This protocol is now in beta, and the system is mostly stable. 1.1 is the current stable version, see [12]this wiki page Introduction and Scope The Audioscrobbler Realtime Protocol is designed for the submission of now-playing and recent historical data to Last.fm. Submission of bulk historical data is not catered for by this protocol - this will be possible with the (currently unimplemented) bootstrap protocol. The protocol is designed to be as simple and lightweight as possible. It is a REST-style interface based on HTTP, so a working knowledge of HTTP 1.1 is assumed. Protocol Stages The protocol consists of three stages: Handshake The initial negotiation with the Audioscrobbler server to establish authentication and connection details for the session. Now-Playing Optional lightweight notification of now-playing data at the start of the track for realtime information purposes. Submission Submission of full track data at the end of the track for statistical purposes. The Handshake A handshake must occur each time the client is started, and additionally if a BADSESSION response is returned at any time by the Now-Playing or Submission stages. The handshake consists of an HTTP/1.1 GET request to http://post.audioscrobbler.com:80/. Note that the request must be HTTP/1.1 -- specifically the Host: header should be present. The request string is as follows: http://post.audioscrobbler.com/?hs=true&p=1.2& c=&v=&u=&t=&a= Where: hs=true Indicates that a handshake is requested. Hits to post.audioscrobbler.com without this variable set will return a human-readable informational message. p=1.2 Is the version of the Audioscrobbler protocol to which the client conforms. client-id Is an identifier for the client. client-ver Is the version of the client being used. user Is the name of the user. timestamp Is the current UNIX Timestamp. auth Is the authentication token, as described below. Client Identifiers Client identifiers are used to provide a centrally managed database of the client versions, allowing clients to be banned if they are found to be behaving undesirably. The client ID is associated with a version number on the server, however these are only incremented if a client is banned and do not have to reflect the version of the actual client application. 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. Client authors should use the tst identifier for clients which are not publicly distributed. Contact the Audioscrobbler administrators in order to obtain a valid client ID. !!insert email address here!!. Authentication Token The algorithm for generating this token is as follows: token := md5(md5(password) + timestamp) Where timestamp is the same timestamp sent in cleartext in the handshake request. The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The '+' operator represents concatenation of the two strings. Handshake Response The body of the server response consists of a series of \n (ASCII 10) terminated lines. A typical server response will be as follows: OK 17E61E13454CDD8B68E8D7DEEEDF6170 http://62.216.251.205:80/protocol_1.2 http://62.216.251.203:80/nowplaying If the HTTP status code is not 200 OK (indicating a successful transfer), then this constitutes a hard failure. The server is not responding to the request as expected and the client 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. The client should consider the first line of the response to determine the action it should take: OK This indicates that the handshake was successful. Three lines will follow the OK response: 1. Session ID 2. Submission URL 3. Now-Playing URL BANNED This indicates that this client version has been banned from the server. This usually happens if the client is violating the protocol in a destructive way. Users should be asked to upgrade their client application. BADAUTH This indicates that the authentication details provided were incorrect. The client should not retry the handshake until the user has changed their details. BADTIME The timestamp provided was not close enough to the current time. The system clock must be corrected before re-handshaking. FAILED This indicates a temporary server failure. The reason indicates the cause of the failure. The client should proceed as directed in the Hard Failures section. 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. The Now-Playing Notification The Now-Playing notification is a lightweight mechanism for notifying the Audioscrobbler server that a track has started playing. This is used for realtime display of a user's currently playing track, and does not affect a user's musical profile. The Now-Playing notification is optional, but recommended. The submission takes place as a HTTP/1.1 POST transaction with the server, using the URL provided during the handshake phase of the protocol. s= The Session ID string as returned by the handshake. Required. a= The artist name. Required. t= The track name. Required. b= The album title, or empty if not known. l= The length of the track in seconds, or empty if not known. n= The position of the track on the album, or empty if not known. m= The MusicBrainz Track ID, or empty if not known. The body of the server response will consist of a single \n (ASCII 10) terminated line. The client should process the first line of the body to determine the action it should take OK This indicates that the Now-Playing notification was successful. BADSESSION This indicates that the Session ID sent was somehow invalid, possibly because another client has performed a handshake for this user. On receiving this, the client should re-handshake with the server before continuing. The Submission When to Submit The client should monitor the user's interaction with the music playing service to whatever extent the service allows. In order to qualify for submission all of the following criteria must be met: 1. The track must be submitted once it has finished playing. Whether it has finished playing naturally or has been manually stopped by the user is irrelevant. 2. The track must have been played for a duration of at least 240 seconds or half the track's total length, whichever comes first. Skipping or pausing the track is irrelevant as long as the appropriate amount has been played. 3. The total playback time for the track must be more than 30 seconds. Do not submit tracks shorter than this. 4. Unless the client has been specially configured, it should not attempt to interpret filename information to obtain metadata instead of tags (ID3, etc). Submission Stage The submission takes place as a HTTP/1.1 POST transaction with the server, using the URL provided during the handshake phase of the protocol. The submission body may contain the details for up to 50 tracks which are being submitted. Under normal circumstances only a single track will be submitted, however, clients should cache submissions in case of failure. 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 string as returned by the handshake. Required. a[0]= The artist name. Required. t[0]= The track title. Required. i[0]=