Audio::Scrobbler(3p)  User Contributed Perl Documentation Audio::Scrobbler(3p)



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:

       o   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.

       o   err (message)

           Retrieves or sets the description of the last error encountered in
           the operation of this "Audio::Scrobbler" object.

       o   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:

           o   progname

               The name of the program (or plug-in) performing the
               AudioScrobbler handshake.

           o   progver

               The version of the program (or plug-in).

           o   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.

       o   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:

           o   title

               The track's title.

           o   artist

               The name of the artist performing the track.

           o   length

               The duration of the track in seconds.

           o   album

               The name of the album (optional).

           Also, the submit method requires that the following configuration
           parameters be set for this "Audio::Scrobbler" object:

           o   username

               The username of the user's AudioScrobbler registration.

           o   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:

       o   get_ua ()

           Creates or returns the cached "LWP::UserAgent" object used by the
           "Audio::Scrobbler" class for access to the AudioScrobbler API.

       o   URLDecode (string)

           Decode a URL-encoded string.

           Obtained from
           http://glennf.com/writing/hexadecimal.url.encoding.html

       o   URLEncode (string)

           Return the URL-encoded representation of a string.

           Obtained from
           http://glennf.com/writing/hexadecimal.url.encoding.html

TODO
       o   Do something with UPDATE responses to the handshake.

       o   Honor INTERVAL in some way.

       o   Figure out a way to cache unsuccesful submissions for later
           retrying.

       o   Web services - stats!

SEE ALSO
       scrobbler-helper(1)

       o   http://www.last.fm/

       o   http://www.audioscrobbler.com/

       o   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 $



perl v5.12.2                      2006-01-02              Audio::Scrobbler(3p)
