Forum » Development Discussion

Scrobbling API 2.0 Beta 2

 
  • 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

    bleh
    Redigerad av roserpens den 9 nov 2010, 12:53
    • Tecfan sa...
    • Event Moderator
    • 15 okt 2010, 14:56
    looks like nice changes, good work :>

    If you're into /, you might enjoy my (free) tracks: Tecfan
    • mxcl sa...
    • Alumni
    • 15 okt 2010, 15:20
    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 sa...
    • Användare
    • 15 okt 2010, 16:04

    indices?

    Just to be clear, in track.scrobble, the index 'i' is appended to the parameter name? So artist0, track0, artist1, track1, ..., etc?

    • toc-rox sa...
    • Användare
    • 15 okt 2010, 16:28
    @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"

  • @egw what toc-rox said, you need the brackets.

    @mxcl We have been debating and disagreeing about the name since we started this. We've finally agreed they should definitely be in the same namespace and that namespace will be track. I also prefer nowplaying to updateNowPlaying, but we decided to keep it consistent with the "do something" descriptive names of all the other write services. We expect that one day we'll do a 3.0 version of the whole api and change the conventions.

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

    bleh
  • mxcl said:
    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.
    Agreed.

    You can get deep into this by considering what's actually being manipulated, the track's state or the user's activity state, and consider both and the interplay between the two. But, for this API, it's just a simple mutator of the user's activity state.

    As such, the naming breaks down if you consider adding the inverse, accessor op. Adding functionality to retrieve a user's now playing state is pretty simple. But, given this naming approach, you'd add in a Track.getNowPlaying. Makes no sense... which track?

    If you're considering both, I'd go with User.setNowPlaying / User.getNowPlaying and Track.setPlaying / Track.isPlaying. Mutators on both User & Track are convenience given they each manipulate the other's state. But, really, I'd stay away from the Track manipulator given it's a stateless environment.

    User.updateNowPlaying (or User.setNowPlaying) makes more sense and won't break when you go to scale and add ops.

    • egw sa...
    • Användare
    • 15 okt 2010, 17:26
    @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.

  • @egw the duration parameter should always be the duration of the track. Any correlation to how long the listening now box is displayed is arbitrary and may change.

    bleh
  • I'm going to repost this since the thread was closed before a response

    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.

    • egw sa...
    • Användare
    • 16 okt 2010, 04:38
    roserpens said:
    @egw the duration parameter should always be the duration of the track. Any correlation to how long the listening now box is displayed is arbitrary and may change.


    @roserpens Fair enough. All I mean is there wasn't any particular motivation for me to calculate and send the duration until I realized that it affected the 'now playing' behavior. If it didn't do that, I wouldn't have bothered, since artist and track are sufficient identification.

    • mxcl sa...
    • Alumni
    • 16 okt 2010, 10:36
  • Re: I'm going to repost this since the thread was closed before a response

    @iTranscendence we would definitely like to capture more fine grained data about music. It is a very non trivial problem to do well and is beyond the scope of the next version of the scrobbling api which is what this thread is about.

    bleh
  • @egw good point.

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

    bleh
  • Re: Re: I'm going to repost this since the thread was closed before a response

    roserpens said:
    @iTranscendence we would definitely like to capture more fine grained data about music. It is a very non trivial problem to do well and is beyond the scope of the next version of the scrobbling api which is what this thread is about.


    That's understandable, but I believe while you are deep in the code there, you need to be looking for future ways of making those suggestions possible, how to integrate a secondary algorithm into the process that can accomplish all those tasks for you.

    Could you also answer my question in the original post about something that unequivocally should be resolved on this update?

    Since this sites inception artists with the same name have had to share the same page because the scrobbler basically only identified who they were by the artist ID3 data, and not even by their track. Now that the scrobbler is pulling in multiple pieces of ID3 data, are you going to use this to finally correct this problem, to uniquely identify two artists with the same name by also using their track name and album name as primary identifiers? Considering it has been like this for nearly 10 years 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.

    bleh
  • 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

  • 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?

  • [spam]

    [spam]

    Redigerat av en raderad användare den 18 okt 2010, 14:16
  • 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?

    bleh
  • iTranscendence said:
    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?


    It would be wrong for me to assign a number to this, since prioritising tasks has to consider all the other things we have to work on and their urgency. I'm not in a position to do that.

    bleh
  • 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

  • @RogerGEvans
    It should be in lexigraphical order, so yeah 10 comes before 2.
    Most programming languages should sort in the correct order naturally.

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

Anonyma användare kan inte skriva inlägg. Vänligen logga in eller skapa ett konto för att göra inlägg i forumen.