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 $