Read and write to with node.js
JavaScript Shell
Pull request Compare This branch is 1 commit ahead, 43 commits behind jammus:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Read and write to users recent plays on


npm install lastfm


var LastFmNode = require('lastfm').LastFmNode;

var lastfm = new LastFmNode({
  api_key: 'apikey',    // sign-up for a key at
  secret: 'secret',
  useragent: 'appname/vX.X MyApp' // optional. defaults to lastfm-node.



lastfm.request(method, options);

Returns a LastFmRequest instance.

Send request to Requests automatically include the API key and are signed and/or sent via POST as described in the API documentation.


Accepts any API method name, eg "artist.getInfo".


All options are passed through to with the exception of the following.

  • write

      Force request to act as a write method. Write methods are signed and sent via POST. Useful for new methods not yet recognised by lastfm-node.
  • signed

      Force request to be signed. See API docs for signature details. Useful for new methods not yet recognised by lastfm-node.
  • handlers

      Default event handlers to attach to the request object on creation.


  • success(json)

      JSON response from
  • error(error)

      Ruh-roh. Either a error returned by or a transmission error.


Returns: a RecentTracksStream instance


  • start()

      Start streaming recent track info.
  • stop()

      Stop streaming recent track info.
  • isStreaming()

      Boolean. True is nowplaying/recent track data is being actively fetched.
  • on(event, listener)

      Adds a listener for the specified event.
  • removeListener(event, listener)

      Removes the listener for the specified event.


  • autostart

      Start streaming automatically. Defaults to false.
  • handlers

      Default event handlers to attach to the request object on creation.


  • lastPlayed(track)

      The user's last scrobbled track.
  • nowPlaying(track)

      Track the user is currently listening to.
  • scrobbled(track)

      Now playing track has been scrobbled.
  • stoppedPlaying(track)

      User stopped listening to current track.
  • error(error)



lastfm.session([user], [key]);

Returns: a LastFmSession instance.

If no key is supplied then the authorise() method must be used before the session can be used to make authenticated calls. See the API documentation for more info.

Public properties:

  • user

      The username of the user associated with the session.
  • key

      The session key. Either passed in or generated using authorise().


  • authorise(token, [options])

      Authorises user with api. See documentation. Options argument has handlers property that has default event handlers to attach to the LastFmSession instance.
  • on(event, handler)

      Adds a listener for the specified event.
  • removeListener(event, handler)

      Removes the listener for the specified event.
  • isAuthorised()

      Returns true if the session has been authorised or a key was specified in the constructor.


  • authorised(session)

      Authorisation of session was successful.
      Note: Only emitted after a call to authorise(). Keys supplied in the constructor are assumed to be valid.
  • error(track, error)



lastfm.update(method, session, options);

Returns a LastFmUpdate instance.

Valid methods are 'nowplaying' and 'scrobble'.

An authorised LastFmSession instance is required to make a successful update.

If a scrobble request receives an 11 (service offline), 16 (temporarily unavailable) or 29 (rate limit exceeded) error code from then the request is automatically retried until it is permanently rejected or accepted. The first retry attempt is made after 10 seconds with subsequent requests delayed by 30 seconds, 1 minute, 5 minutes, 15 minutes and then every 30 minutes.


Accepts all parameters used by track.updateNowPlaying and user.scrobble (see Last.Fm API) as well as:

  • track

      Track for nowplaying and scrobble requests. Uses same format as returned by `RecentTracksStream` events.
  • timestamp

      Required for scrobble requests. Timestamp is in unix time (seconds since 01-01-1970 and is in UTC time).
  • handlers

      Default event handlers to attach to the request object on creation.


  • success(track)

     Update request was successful. 
  • retrying(retry)

     Scrobble request was not successful but will be retried after a delay. Retry object contains the following properties:  
     `delay` - The time in milliseconds before the request will be retried.  
     `error` - The error code returned by the API.  
     `message` - The error message returned by the API.
  • error(track, error)


LastFmInfo, [options]);

Returns: a LastFmInfo instance.

Gets extended info about specified item.

Public properties:

  • itemtype

      Any item with a getInfo method. eg user, track, artist, etc.


  • handlers

      Event handlers to attach to object at creation.
  • various

     Params as specified in API, eg user: "username"

Special cases:

When requesting track info the track param can be either the track name or a track object as returned by RecentTracksStream.


var LastFmNode = require('lastfm').LastFmNode;

var lastfm = new LastFmNode({
  api_key: 'abc',
  secret: 'secret'

var trackStream ='username');

trackStream.on('lastPlayed', function(track) {
  console.log('Last played: ' +;

trackStream.on('nowPlaying', function(track) {
  console.log('Now playing: ' +;

trackStream.on('scrobbled', function(track) {
  console.log('Scrobbled: ' +;

trackStream.on('stoppedPlaying', function(track) {
  console.log('Stopped playing: ' +;

trackStream.on('error', function(error) {
  console.log('Error: '  + error.message);


var session = lastfm.session();
session.authorise(token, {
   handlers: {
      authorised: function(session) {
         lastfm.update('nowplaying', session, { track: track } );
         lastfm.update('scrobble', session, { track: track, timestamp: 12345678 });

var request = lastfm.request("artist.getInfo", {
    artist: "The Mae Shi",
    handlers: {
        success: function(data) {
            console.log("Success: " + data);
        error: function(error) {
            console.log("Error: " + error.message);


Heavily drawn from technoweenie's twitter-node