• Introduction
• Details
• When to send
• Examples
• Internals
• A user's perspective
• Troubleshooting
• General
• Broadcast doesn't get through
• Crashes
• Other
• Custom Broadcasts
• Thanks

Introduction

Any application can easily scrobble their music through Simple Last.fm Scrobbler (SLS). It is just to send certain broadcasts with the appropriate track information, and SLS will do the all the account management, network requests and error-handling etc.

You just have to implement the behavior below, and it should just work. This version of the API has first been implemented in version 1.2.3 of SLS, now available on Android Market (and here).

I'd appreciate it if you'd send an email to simple.lfm.scrobbler@gmail.com and tell me about any apps using this API. That way I can add them to the list of supported apps. Any questions are always welcome.

If you have any questions about this API, or suggestions on how to improve it, please just email me.

Details

The broadcast action is: com.adam.aslfms.notify.playstatechanged.

The intent your app broadcast must contain one of these states:

The possible fields for the intent (to be put in it's extras bundle) are:

Table of source values:

These values are taken from the Last.fm Submissions Protocol Specifiaction, section 3.2.

When to send

You should broadcast an intent with the information above whenever the user starts playing a new track (including when it is the next track in a playlist), resumes a paused track or pauses or stops a already playing track. Sending intents at other times (such as when the user is seeking within a track) is unnecessary, but does no harm.

It is not necessary to broadcast with state set to COMPLETE for a track to scrobble¹; if a new track starts playing and START is broadcast, previously broadcasted tracks will scrobble automatically.

¹If you play the same track again directly after it has finished playing (e.g. looping a playlist with one track), you have to send a COMPLETE for proper scrobbling.

Examples

This sends a broadcast that Chris Cornell's song "You Know My Name" has started playing, and will scrobble any previously playing tracks:

Intent bCast = new Intent("com.adam.aslfms.notify.playstatechanged");
bCast.putExtra("state", START);
bCast.putExtra("app-name", "Example App");
bCast.putExtra("app-package", "com.example.exampleapp");
bCast.putExtra("artist", "Chris Cornell");
bCast.putExtra("album", "Casino Royale");
bCast.putExtra("track", "You Know My Name");
bCast.putExtra("duration", 244);
sendBroadcast(bCast);

And this says that James Marster's song "Looking At You" has finished playing and should be scrobbled:

Intent bCast = new Intent("com.adam.aslfms.notify.playstatechanged");
bCast.putExtra("state", COMPLETE);
bCast.putExtra("app-name", "Example App");
bCast.putExtra("app-package", "com.example.exampleapp");
bCast.putExtra("artist", "James Marsters");
bCast.putExtra("album", "Like A Waterfall");
bCast.putExtra("track", "Looking At You");
bCast.putExtra("duration", 175);
sendBroadcast(bCast);

This might be if you have a radio app, which just started playing a new track:

Intent bCast = new Intent("com.adam.aslfms.notify.playstatechanged");
bCast.putExtra("state", START);
bCast.putExtra("app-name", "Example App");
bCast.putExtra("app-package", "com.example.exampleapp");
bCast.putExtra("artist", "Yohanna");
bCast.putExtra("album", "Eurovision Song Contest: Moscow 2009 (disc 2)");
bCast.putExtra("track", "Is It True? (Iceland)");
bCast.putExtra("duration", 181);
bCast.putExtra("track-number", 3);
bCast.putExtra("mbid", "ceb9d062-145c-4831-839b-3be53e9d5549");
bCast.putExtra("source", "R");
sendBroadcast(bCast);

The app ³ (cubed) implements this API.

Internals

The behavioiur to handle these API broadcasts is implemented in the BroadcastReceiver SLSAPIReceiver. It shouldn't be necessary to examine it, but could further explain the API.

A user's perspective

When a user starts playing music in a music app using this api, she will automatically have her music scrobbled. The first broadcast to be sent to SLS will create an entry in the Supported Apps section, where the user can disable/enable scrobbling from that application (it is enabled by default).

To make this work properly, the two fields app-name and app-package are crucial. app-name is the string that gets displayed to the user, and app-package is what identifies the source of the music played. This should be the "root package" (or whatever it's called) of the music app, and it should never change.

Troubleshooting

General

This API was first implemented in version 1.2.3 of SLS, available on Android Market (and here).

Broadcast doesn't get through

If your broadcast doesn't seem to get through, first check if SLS actually receives it. Everytime SLS gets an intent meant for scrobbling, it outputs to LogCat (debug level): "SLSPlayStatusReceiver" : "Action received was: [received intent]"

If that seems fine, make sure you've logged in to either last.fm or libre.fm (or both). This is one of the first checks that are made when SLS receives an intent, and it will abort if it hasn't authenticated correctly. If this is the cause, you'll get a LogCat message (information level) saying something like: "SLSPlayStatusReceiver" : "The user has not authenticated, won't propagate the submission request".

Otherwise, check LogCat forr error-messages of the form "SLSPlayStatusReceiver" : "Got a bad track from: [some name], ignoring it ([reason])".

Crashes

SLS aspires to never crash, so if it does, please tell me. Whatever data you send to SLS, it should be fine.

Other

Email me, and I'll answer as quickly as I can. Saved LogCats can be useful.

Custom Broadcasts

If you already broadcast your own intents, tell me about them and I'll see if I can work them into SLS.

Thanks

A tip of the hat to jjc1138 of Scrobble Droid, his/her documentation is superb.