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 handshake and submit
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 submit
method may be invoked. Otherwise, an appropriate error message may be
retrieved via the err method.
If the
fake configuration parameter is set, the handshake 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 handshake 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 handshake. 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 submit 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 err method.
If the
fake configuration parameter is set, the submit 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 submit 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!
SEE ALSO¶
scrobbler-helper(1)
- * http://www.last.fm/
- * http://www.audioscrobbler.com/
- * http://www.audioscrobbler.net/
The home site of the "Audio::Scrobbler" module is
http://devel.ringlet.net/audio/Audio-Scrobbler/
AUTHOR¶
Peter Pentchev, <roam@ringlet.net>
COPYRIGHT AND LICENSE¶
Copyright (C) 2005, 2006 by Peter Pentchev.
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 $