Audio::Scrobbler - Perl interface to audioscrobbler.com/last.fm

NAME

Audio::Scrobbler - Perl interface to audioscrobbler.com/last.fm

SYNOPSIS

  use Audio::Scrobbler;

  $scrob = new Audio::Scrobbler(cfg => { ... });

  $scrob->handshake();
  $scrob->submit(artist => "foo", album => "hello", track => "world",
    length => 180);

DESCRIPTION

The Audio::Scrobbler module provides a Perl interface to the track submission API of Last.fm's AudioScrobbler - http://www.audioscrobbler.com/. So far, only track submissions are handled; the future plans include access to the various statistics.

METHODS

The Audio::Scrobbler class defines the following methods:

new ( cfg => { ... } )
Create a new Audio::Scrobbler object and initialize it with the provided configuration parameters. The parameters themselves are discussed in the description of the the handshake manpage and the submit manpage methods below.
err (message)
Retrieves or sets the description of the last error encountered in the operation of this Audio::Scrobbler object.
handshake ()
Perfors a handshake with the AudioScrobbler API via a request to http://post.audioscrobbler.com/.
This method requires that the following configuration parameters be set:
- progname
  The name of the program (or plug-in) performing the AudioScrobbler handshake.
- progver
  The version of the program (or plug-in).
- username
  The username of the user's AudioScrobbler registration.
If the handshake is successful, the method returns a true value, and the the submit manpage method may be invoked. Otherwise, an appropriate error message may be retrieved via the the err manpage method.

If the fake configuration parameter is set, the the handshake manpage method does not actually perform the handshake with the AudioScrobbler API, just simulates a successful handshake and returns a true value.

If the verbose configuration parameter is set, the the handshake manpage method reports its progress with diagnostic messages to the standard output.
submit ( info )
Submits a single track to the AudioScrobbler API. This method may only be invoked after a successful the handshake manpage. The track information is contained in the hash referenced by the info parameter; the following elements are used:
- title
  The track's title.
- artist
  The name of the artist performing the track.
- length
  The duration of the track in seconds.
- album
  The name of the album (optional).
Also, the the submit manpage method requires that the following configuration parameters be set for this Audio::Scrobbler object:
- username
  The username of the user's AudioScrobbler registration.
- password
  The password for the AudioScrobbler registration.
If the submission is successful, the method returns a true value. Otherwise, an appropriate error message may be retrieved via the the err manpage method.

If the fake configuration parameter is set, the the submit manpage method does not actually submit the track information to the AudioScrobbler API, just simulates a successful submission and returns a true value.

If the verbose configuration parameter is set, the the submit manpage method reports its progress with diagnostic messages to the standard output.

There are also several methods and functions for the module's internal use:

get_ua ()
Creates or returns the cached LWP::UserAgent object used by the Audio::Scrobbler class for access to the AudioScrobbler API.
URLDecode (string)
Decode a URL-encoded string.
Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html
URLEncode (string)
Return the URL-encoded representation of a string.
Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html

TODO

Do something with UPDATE responses to the handshake.
Honor INTERVAL in some way.
Figure out a way to cache unsuccesful submissions for later retrying.
Web services - stats!

AUTHOR

Peter Pentchev, <roam@ringlet.net>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

$Id: Scrobbler.pm 88 2006-01-02 09:16:32Z roam $

Audio::Scrobbler - Perl interface to audioscrobbler.com/last.fm