NAME

SYNOPSIS

    use Music::Audioscrobbler::Submit
    my $mpds = Music::Audioscrobbler::Submit->new(\%options); 

    $mpds->submit("/path/to/song.mp3");

DESCRIPTION

Items are submitted and stored in a queue. This queue is stored as a file using Tie::File. When you submit a track, it will add the queue to the track and process the queue. If it submits all items in the queue, the submit() method will return true. A method called process_scrobble_queue() allows you to try again in case of failure. Do not submit songs more than once!

METHODS

new()

    my $mas = Music::Audioscrobbler::Submit->new($options);
    

options()

Get or set options via hash. Here is a list of available options:

default_options()

Returns a reference to the default options.

now_playing()

Takes a file, hashref, or Music::Tag object and submits the song to Last.FM now playing info. For example:

    $mas->now_playing("/path/to/file.mp3");
    

The hash reference is of the form:

        { artist   => "Artist Name",   # Mandatory
          title    => "Song Title"     # Mandatory
          secs     => 300,             # Length of time in seconds (integers only please). Mandatory
          album    => "Album",         # Optional
          tracknum => 12,              # Optional
          mbid     => '6299a467-95bc-4bc1-925d-71c4e556770d'  # Optional
        }
    

submit()

To submit a song pass an arrayref whose first entry is a File, Music::Tag object, or hashref (see now_playing()) for format) and whose second entry is an integer representing the seconds since epoch (UNIX time). Several songs can be submitted simultaneously. For example:

    $mas->submit->(["/path/to/file.mp3", time]);
    

or:

    $mas->submit->( ["/var/mp3s/song1.mp3", time - 600 ], 
                    ["/var/mp3s/song2.mp3", time - 300 ], 
                    ["/var/mp3s/song3.mp3", time ] );
    

Returns true if song was scrobbled, false otherwise. submit calls process_scrobble_queue(). If it fails, process_scrobble_queue() can be called again.

The following is taken from <http://www.audioscrobbler.net/development/protocol/>:

The client should monitor the user's interaction with the music playing service to whatever extent the service allows. In order to qualify for submission all of the following criteria must be met:

1. The track must be submitted once it has finished playing. Whether it has finished playing naturally or has been manually stopped by the user is irrelevant.

2. The track must have been played for a duration of at least 240 seconds or half the track's total length, whichever comes first. Skipping or pausing the track is irrelevant as long as the appropriate amount has been played.

3. The total playback time for the track must be more than 30 seconds. Do not submit tracks shorter than this.

4. Unless the client has been specially configured, it should not attempt to interpret filename information to obtain metadata instead of tags (ID3, etc).

process_scrobble_queue()

Processes the current scrobble queue. Call this if submit fails and you wish to try again. Do not resubmit a song.

handshake()

Perform handshake with Last.FM. You don't need to call this, it will be called by submit() or now_playing() when necessary.

music_tag_opts()

Get or set the current options for new Music::Tag objects.

logfileout()

Glob reference (or IO::File) to current log file. If passed a value, will use this instead of what the logfile option is set to. Any glob reference that can be printed to will work (that's all we ever do).

status()

Print to log. First argument is a level (0 - 4). For example:

    $mas->status($level, @message);
    

scrobble_queue()

Returns a reference to the current scrobble_queue. This is a tied hash using Tie::File. Useful to found out how many items still need to be scrobbled after a failed submit().

ua()

Returns the LWP::UserAgent used. If passed a value, will use that as the new LWP::UserAgent object.

info_to_hash()

Takes a filename, hashref, or Music::Tag object and returns a hash with the structure required by submit() or now_playing. Normally this is called automatically by submit() or now_playing. See now_playing for syntax of hash.

Examples:

    my $hash = $mas->info_to_hash("/path/to/mp3/file.mp3");
    

is functionally equivalent to

    my $hash = $mas->info_to_hash(Music::Tag->new("/path/to/mp3/file.mp3", $mas->music_tag_opts() ));
    

SEE ALSO

CHANGES

Release Name: 0.05

Release Name: 0.04

Release Name: 0.03

Release Name: 0.02

Release Name: 0.01

AUTHOR

COPYRIGHT

LICENSE

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this Kit, in the file named "Artistic". If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA or visit their web page on the Internet at http://www.gnu.org/copyleft/gpl.html.