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/ or a
           different service like libre.fm (http://turtle.libre.fm).

           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.

           Optional parameter:

           •   service

               The  URL  of  the  AudioScrobbler  service  to  use, defaults to http://post.audioscrobbler.com/.
               http://turtle.libre.fm or other libre.fm instances should also work.

           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 $

perl v5.36.0                                       2023-07-20                              Audio::Scrobbler(3pm)