This unofficial information is distributed in the hope that it will be useful, but without any warranty; without even implied warranty of merchantability or fitness for a particular purpose.

(Please also read the informative comments left by others below.)

Protocol Stages

The protocol consists of four stages:

Handshake

• The initial negotiation with the Last.fm server to establish authentication and connection details for the session.

Adjustment

• Selection of the Last.fm radio station to be played.

Playlist

• Retrieval of the playlist containing stream URIs.

Scrobbling

• Post track data to Last.fm and optionaly rate it.

The Handshake

The handshake consist of a GET request to http://ws.audioscrobbler.com:80/.

The request string is as follows:

http://ws.audioscrobbler.com/radio/handshake.php?
username=<username>&passwordmd5=<password>
Where:

username
Is the users last.fm username.

password
Is a 32-byte ASCII hexadecimal representation of the MD5 hash of the users last.fm password.

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:

session=13fd57300995f91de0ca9e122c4d35af
stream_url=http://87.117.229.85:80/last.mp3?Session=13fd57300995f91de0ca9e122c4d35af
subscriber=1
framehack=0
base_url=ws.audioscrobbler.com
base_path=/radio
info_message=
fingerprint_upload_url=http://ws.audioscrobbler.com/fingerprint/upload.php
The response consist of a series of key/value pairs:

session
Is the session ID token. "FAILED" if the handshake failed.

stream_url
Is a URL to the old-style stream. It's a regular 128 kbit/s 44.1 kHz MPEG-1 Layer 3 stream with the four character string "SYNC" spliced in between tracks to indicate a song change. The stream will probably be deprecated in the near future in favor of streams pointed to by XSPF playlists.

subscriber
Indicates whether the user is a subscriber to last.fm or not. 1 = True, 0 = False.

framehack
Unsure.

base_url
Is the base URL used to assemble URLs for functions like adjust and control.

base_path
Is the base path used to assemble URLs for functions like adjust and control.

info_message
Informative message. Usually empty.

fingerprint_upload_url
Unsure.

msg
Is an error message if the session failed, otherwise not part of the response.

The Adjustment

To listen to last.fm radio the client need to select what station should be played.

The tuning consist of a GET request to http://ws.audioscrobbler.com:80/.

The request string is as follows:

http://ws.audioscrobbler.com/radio/adjust.php?
session=<session-token>&url=<lastfm-uri>
Where:

session-token
Is the session ID token in the handshake server response.

lastfm-uri
Is a valid last.fm radio URI. For example: lastfm://globaltags/jazz.

Adjust 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:

response=OK
url=lastfm://globaltags/jazz
The response consist of a series of key/value pairs:

response
Is "OK" if the request succeded, otherwise "FAILED".

url
Is the last.fm radio URI.

error
Is the error code if the request failed.

The Playlist

As mentioned in 'The Handshake' section, the old-style stream is assumed to be deprecated and replaced by streams pointed to by a XSPF playlist.

Playlist retrieval consist of a GET request to http://ws.audioscrobbler.com:80/.

The request string is as follows:

http://ws.audioscrobbler.com/radio/xspf.php?
sk=<session-token>&dicovery=<discovery-mode>&desktop=<version>
Where:

session-token
Is the session ID token in the handshake server response.

discovery-mode
Sets the discovery mode. 1 = True, 0 = False. For more info see http://www.last.fm/help/faq/?category=Radio#300

version
A value like '1' is required or nonsense will be returned in the response.

Playlist Response

The body of the server response consists of a XML Shareable Playlist Format (XSPF) formated playlist with zero or more tracks. Example:

<playlist version="1" xmlns:lastfm="http://www.audioscrobbler.net/dtd/xspf-lastfm">;
<title>My+Recommendations</title>
<creator>Last.fm</creator>
<link rel="http://www.last.fm/skipsLeft">20</link>;
<trackList>
<track>
<location>http://kingpin2.last.fm/user/fbf7ad270d0ebe62d335e6ed96422a5b.mp3</location>;
<title>We Stay Behind</title>
<id>104949870</id>
<album>Oh Perilous World (Deluxe Edition) (Disc 1)</album>
<creator>Rasputina</creator>
<duration>199000</duration>
<image>http://cdn.last.fm/depth/catalogue/noimage/cover_med.gif</image>;
<lastfm:trackauth>96ca0</lastfm:trackauth>
<lastfm:albumId>3356043</lastfm:albumId>
<lastfm:artistId>1002220</lastfm:artistId>
<link rel="http://www.last.fm/artistpage">http://www.last.fm/music/Rasputina</link>;
<link rel="http://www.last.fm/albumpage">http://www.last.fm/music/Rasputina/Oh+Perilous+World+%28Deluxe+Edition%29+%28Disc+1%29</link>;
<link rel="http://www.last.fm/trackpage">http://www.last.fm/music/Rasputina/_/We+Stay+Behind</link>;
<link rel="http://www.last.fm/buyTrackURL"></link>;
<link rel="http://www.last.fm/buyAlbumURL">http://www.last.fm/affiliate_sendto.php?link=catch&amp;prod=3356043&amp;pos=65633c2c6d40fbe9c8bf27ce82d2ca5a</link>;
<link rel="http://www.last.fm/freeTrackURL"></link>;
</track>
</trackList>
</playlist>
The basic playlist format is documented in the XSPF specification http://xspf.org/xspf-v1.html, but the response also contain some last.fm specific extensions.

Noteworthy elements:

<link rel="http://www.last.fm/skipsLeft"/>
Unsure.

<location/>
Is the new-style stream. A regular 128 kbit/s 44.1 kHz MPEG-1 Layer 3 stream.

<id/>
Is the track ID in the last.fm music catalog.

<lastfm:trackauth/>
Is the 5-hexdigit Last.fm recommendation key. Appended to the 'L' source ID when submitting track data via Audioscrobbler Protocol v1.2.

The Scrobbling

Submission of track data is done via the Audioscrobbler Protocol v1.2. Rating such as love or ban is also done via the protocol. However the specification states that:

Note: Currently, a web-service must also be called to set love/ban status. We anticipate that this will be phased out soon, and the submission service will handle the whole process.
Loving and banning songs via a web-service new-style is handled by XML-RPC calls.

A XML-RPC call consist of a POST request to http://ws.audioscrobbler.com/1.0/rw/xmlrpc.php with the Content-Type set to text/xml.

The request body is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>method</methodName>
<params>
<param><value><string>user</string></value></param>
<param><value><string>challenge</string></value></param>
<param><value><string>auth</string></value></param>
<param><value><string>artist</string></value></param>
<param><value><string>title</string></value></param>
</params>
</methodCall>
Where:

method
Is the name of the method to be called: loveTrack, unLoveTrack, banTrack or unBanTrack.

user
Is the users last.fm username.

challenge
Is the current UNIX timestamp.

auth
Is the authentication token, a 32-byte ASCII hexadecimal representation of the MD5 hash of the users last.fm password and the timestamp: md5( md5(password) + timestamp )

artist
Is the artist to get love/ban.

title
Is the track title to get love/ban.

References

• Audioscrobbler Protocol v1.2
• "Play last.fm streams without the player"
• "Using last.fm to obtain xml"
• XSPF.org