Scrobbling API 2.0 Beta 2

Update: The beta period has finished, scrobbling 2.0 is now live :) See http://www.last.fm/forum/21716/_/656608

Thanks everyone for the feedback on the beta so far, we've made a few extra changes and a revised version is now live.
This version is now located at the same url as the rest of the web services http://ws.audioscrobbler.com/2.0/
Any extra feedback is greatly appreciated.

(Note: we plan to turn off the previous beta at http://post.audioscrobbler.com/2.0/ on the 1st of November. The submissions 1.2.1 protocol will of course remain in place indefinitely.)

Changes include:
* Url is now the same as the rest of the webservices (ws.audioscrobbler.com)
* Response format has changed, and is now more consistent with existing web services.
* Scrobble and scrobbleBatch methods have been merged into one scrobble method.
* Http handling and rendering is now taken care of by the same service as the rest of the webservices.
* JSON responses are now available.
* updateNowPlaying, now lives in the track namespace next to scrobble, so the methods are track.scrobble and track.updateNowPlaying
* Meta data is now always returned in the response for both updateNowPlaying and scrobble, this allows us to return ignoredmessages neatly.
* There is no longer a streamAuth field in scrobble.
* Corrections are now marked with a flag on the fields that were corrected, they are 1 if they differ from the sent parameter.


Some documentation / a guide can be found here:
http://users.last.fm/~tims/scrobbling/scrobbling2.html

Below is some brief docs of the parameters.

track.updateNowPlaying

Params:
artist (required) - The artist name.
track (required) - The track name.
album (optional) - The album name.
albumArtist (optional) - The album artist, if this differs from the track artist.
duration (optional) - The length of the track in seconds.
mbid (optional) - The MusicBrainz Track ID.
trackNumber (optional) - The position of the track on the album (don't forget parameter names are case sensitive).
sk (required) - A session key generated by authenticating a user via the authentication protocol.
api_key (required) - A Last.fm API key.
api_sig (required) - A Last.fm method signature. See authentication for more information (http://www.last.fm/api/authentication).

Auth:
This service requires authentication. Please see our authentication how-to.
This is a write service and must be accessed with an HTTP POST request. All parameters should be sent in the POST body form url encoded, including the 'method' parameter. See rest requests for more information.

Sample Responses:
<?xml version='1.0' encoding='utf-8'?>
<lfm status="ok">
<nowplaying>
<track corrected="0">Test Track</track>
<artist corrected="0">Test Artist</artist>
<album corrected="0"></album>
<albumArtist corrected="0"></albumArtist>
<ignoredMessage code="0"></ignoredMessage>
</nowplaying>
</lfm>

Errors:

2 : Invalid service -This service does not exist
3 : Invalid Method - No method with that name in this package
4 : Authentication Failed - You do not have permissions to access the service
5 : Invalid format - This service doesn't exist in that format
6 : Invalid parameters - Your request is missing a required parameter
9 : Invalid session key - Please re-authenticate
10 : Invalid API key - You must be granted a valid key by last.fm
11 : Service Offline - This service is temporarily offline. Try again later.
13 : Invalid method signature supplied
16 : Temp Unavailable - There was an internal error. Please retry your request.
26 : Suspended API key - Access for your account has been suspended, please contact Last.fm

track.scrobble

Params:

These parameters must be specified for each scrobble, where 'i' is an integer indexing the scrobble starting at 0 (if you are sending a single scrobble you may ommit the indexes, but you can not do both). (the index brackets got removed by the forum markup so I had to add spaces, some example parameters would be artist[0]=... track[0]=.. etc.)
artist[ i ] (required) - The artist name.
track[ i ] (required) - The track name.
album[ i ] (optional) - The album name.
albumArtist[ i ] (optional) - The album artist - if this differs from the track artist.
timestamp[ i ] (required) - The time the track started playing, in UNIX timestamp format (integer number of seconds since 00:00:00, January 1st 1970 UTC). This must be in the UTC time zone.
duration[ i ] (optional) - The length of the track in seconds.
mbid[ i ](optional) - The MusicBrainz Track ID.
trackNumber[ i ] (optional) - The position of the track on the album (don't forget parameter names are case sensitive).
streamId[ i ] (optional) - The stream id for this track received from the radio.getPlaylist service.


These parameters apply to the whole request, so they do not need an index.
sk (required) - A session key generated by authenticating a user via the authentication protocol.
api_key (required) - A Last.fm API key.
api_sig (required) - A Last.fm method signature. See authentication for more information (http://www.last.fm/api/authentication).

Auth:
This service requires authentication. Please see our authentication how-to.
This is a write service and must be accessed with an HTTP POST request. All parameters should be sent in the POST body form url encoded, including the 'method' parameter. See rest requests for more information.

Sample Responses:

A single scrobble was sent.
<?xml version='1.0' encoding='utf-8'?>
<lfm status="ok">
<scrobbles accepted="1" ignored="0">
<scrobble>
<track corrected="0">Test Track</track>
<artist corrected="0">Test Artist</artist>
<album corrected="0"></album>
<albumArtist corrected="0"></albumArtist>
<timestamp>1287140447</timestamp>
<ignoredMessage code="0"></ignoredMessage>
</scrobble>
</scrobbles>
</lfm>

2 scrobbles were sent.
<?xml version='1.0' encoding='utf-8'?>
<lfm status="ok">
<scrobbles accepted="2" ignored="0">
<scrobble>
<track corrected="0">Test Track 0</track>
<artist corrected="0">Test Artist 0</artist>
<album corrected="0"></album>
<albumArtist corrected="0"></albumArtist>
<timestamp>1287141093</timestamp>
<ignoredMessage code="0"></ignoredMessage>
</scrobble>
<scrobble>
<track corrected="0">Test Track 1</track>
<artist corrected="0">Test Artist 1</artist>
<album corrected="0"></album>
<albumArtist corrected="0"></albumArtist>
<timestamp>1287141093</timestamp>
<ignoredMessage code="0"></ignoredMessage>
</scrobble>
</scrobbles>
</lfm>

Errors:

2 : Invalid service -This service does not exist
3 : Invalid Method - No method with that name in this package
4 : Authentication Failed - You do not have permissions to access the service
5 : Invalid format - This service doesn't exist in that format
6 : Invalid parameters - Your request is missing a required parameter
9 : Invalid session key - Please re-authenticate
10 : Invalid API key - You must be granted a valid key by last.fm
11 : Service Offline - This service is temporarily offline. Try again later.
13 : Invalid method signature supplied
16 : Temp Unavailable - There was an internal error. Please retry your request.
26 : Suspended API key - Access for your account has been suspended, please contact Last.fm


About ignored scrobbles or nowplaying requests:
The responses contain an ignoredmessage field with a code that is one of:
0 : NONE
1 : Artist name did not pass filters
2 : Track name did not pass filters
3 : Timestamp too far in the past
4 : Timestamp too far in the future
5 : Max daily scrobbles exceeded

Track.updateNowPlaying is wrong. By all means put them in the same namespace (not that that matters, namespacing is hard, the few people who complained are dipshits who have never tried to namespace stuff for 10,000 developers before). You aren't updating the track. If the method acts on the track rather than the user now, it should be (I guess) Track.nowPlaying.

But well, maybe I have the wrong "mind-model" for this.

Otherwise it's great that this is still moving forwards, I was starting to wonder, so I'm happy.

@egw - a working example:

perl lfmCMD.pl method=track.scrobble track[0]="Rocket" album[0]="Hysteria" artist[0]="Def Leppard" timestamp[0]="1287153000" track[1]="Women" album[1]="Hysteria" artist[1]="Def Leppard" timestamp[1]="1287152000" sk="3a5...30b"

turns out the forum markup was stripping out the indexes, sorry about that. I added some spaces.

@toc-rox: thanks!

@roserpens: I admit I can be kind of dumb, but it took me a while to figure out the relationship between track.updateNowPlaying.duration and how long the 'listening now' box is displayed. It might be useful to say what the various parameters' effects are when they're non-obvious.

I have some important questions I've been thinking through for about a year and a half now related to what the scrobbler needs to be able to accomplish.

I see that it now scrobbles several pieces of ID3 data. Are you using this as a solution to the multiple artists with the same name issue? Will the scrobbler finally be able to use that extra ID3 data to differentiate and move those artists to their own pages?

On the issue of trying to scrobble multiple artists from a single piece of ID3 data. I think you may be able to write a spider algorithm that can trawl the text inside the ID3 data and look for keywords to give proper credit to artists for remixes, features etc...

For example:

Album: The History of Trance 1993-2004
Album Artist: George Acosta
Genre: Progressive Trance
The Thrillseekers Feat. Sheryl Deane - Synaesthesia (Fly Away) (Paul Van Dyk Remix)

First the scrobbler should give album artists (compilers, and DJ mix sets) a play count on that album and that track within that album, If you plan on adding actual artists albums instead of the system currently. And a count to their overall listeners, because even if the track isn't them, the listener is listening to that artist mixing the set.

the new algorithm would then isolate each section within each ID3

The Thrillseekers would receive an overall play count

Sheryl Deane would receive a "Featured" Count and an overall count

The song Synaethesia (fly away) (Paul Van Dyk Remix) would receive a play count

Paul Van Dyk would receive a remix count and a count towards hi overall plays

The track would appear in all three of their discographies, but under remixes, features and main respectively.

The algorithm would also know to correlate different abbreviations of the keywords and not that they were different tracks as long as the primary information was correct.
"Featuring, Feat."
"VS. vs. Versus"
"Remix Mix Edit RMX"
etc

The algorithm would also be able to ignore, or inquire from the listener; if they so choose ; about inane data coming in. For example as the number of sites that integrate the api to allow their streaming information to scrobble, the more you are going to end up with bad scrobble data with the current scrobbler api. Youtube is the best proving ground for this. Many song titles for the video's are improperly named somehow or have extra data in them.

It would also be a beneficial incentive to add to the the API the ability for when it's being used on other websites for it to watermark a linkback to that piece of media in users recent plays. This allows traffic to flow freely between lfm and the media supplying it with the data.

Done: http://www.methylblue.com/audioscrobbler/Audioscrobbler-0.9.13.zip

Code: http://github.com/mxcl/Audioscrobbler.app

@egw good point.

@mxcl awesome :) I'm using it now.

@iTranscendence Unfortunately we have been working on this a long time and we are well past the point where new features will make it into the api. This latest beta can be considered a final draft. Unless there's some really clear problems it will probably be the final version.

About artist disambiguation... it will not (and could not) be addressed by the scrobbling api.

That has a lot more to do with how we represent artists internally in our catalogue. It's on our road map, but it's a lot more work than it sounds because of the subtlety of the changes and the scope of systems it will effect.

You're correct it's been a long time coming. We have been planning to do it for years. I wouldn't expect it any time soon, but there is a concrete plan on how to do it. Actually implementing that plan however is a huge ordeal that contains many steps. It's hard to convey the complexity to end users, and even people working at last.fm, since it intuitively doesn't seem like it should be that hard.

Btw, this new api isn't actually going to be collecting much more data, the only new data is the album artist (which is the artist associated with the whole album) which might be useful for compilations and other cases. The main purpose of this api update, is to have proper error messages, make it more consistent with the rest of the api, and to simplify things by ditching handshakes, and letting people just use their api keys instead of needing a client id.

roserpens said:
@iTranscendence Unfortunately we have been working on this a long time and we are well past the point where new features will make it into the api. This latest beta can be considered a final draft. Unless there's some really clear problems it will probably be the final version.

About artist disambiguation... it will not (and could not) be addressed by the scrobbling api.

That has a lot more to do with how we represent artists internally in our catalogue. It's on our road map, but it's a lot more work than it sounds because of the subtlety of the changes and the scope of systems it will effect.

You're correct it's been a long time coming. We have been planning to do it for years. I wouldn't expect it any time soon, but there is a concrete plan on how to do it. Actually implementing that plan however is a huge ordeal that contains many steps. It's hard to convey the complexity to end users, and even people working at last.fm, since it intuitively doesn't seem like it should be that hard.

Btw, this new api isn't actually going to be collecting much more data, the only new data is the album artist (which is the artist associated with the whole album) which might be useful for compilations and other cases. The main purpose of this api update, is to have proper error messages, make it more consistent with the rest of the api, and to simplify things by ditching handshakes, and letting people just use their api keys instead of needing a client id.

Thank you for your response, this will be my last question on this subject in this thread seeing as none of these updates pertain to it.

On a scale of 1 to 10, with 1 being not important at all and 10 being a critical issue, where would you place resolving artists having to share; much to the detriment of them, the statistics and the perception of last.fm; the same artist page?

RogerGEvans said:
I may be mis-understanding how the multiple scrobbles should work, but I can submit to track.scrobble with indexes [0] to [9] and it works fine, but as soon as I submit one with more tracks (i.e. the index is [10] or more) it rejects and returns a 403 forbidden error....

Has this changed from the earlier beta with its index range of 0 - 49?

Thanks

0-49 is still the limit, are you sure you are sorting the parameters correctly? it sounds like you're getting an invalid signature error, what does the response say?

roserpens said:
RogerGEvans said:
I may be mis-understanding how the multiple scrobbles should work, but I can submit to track.scrobble with indexes [0] to [9] and it works fine, but as soon as I submit one with more tracks (i.e. the index is [10] or more) it rejects and returns a 403 forbidden error....

Has this changed from the earlier beta with its index range of 0 - 49?

Thanks

0-49 is still the limit, are you sure you are sorting the parameters correctly? it sounds like you're getting an invalid signature error, what does the response say?

Thanks for the reply - much appreciated :-)

This may, therfore, be down to my interpretation of 'alphabetical order'?

In the sig I was sorting the parameters as;

artist[0]
artist[1]
artist[2]
...
artist[10]
artist[11]
etc.

So should I be including the index in the alphabetical sort? i.e.
artist[0]
artist[1]
artist[10]
artist[11]
artist[2]
artist[3]
?

Thanks

Thanks! I'll give it a go when I get home.... :-)