/ 
Music-Audioscrobbler-Submit-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Music::Audioscrobbler::Submit

NAME

Music::Audioscrobbler::Submit - Module providing routines to submit songs to last.fm using 1.2 protocol.

SYNOPSIS

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

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

DESCRIPTION

Music::Audioscrobbler::Submit is a scrobbler for MPD implementing the 1.2 protocol, including "Now Playing' feature.

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:

lastfm_username

lastfm username

lastfm_password

lastfm password. Not needed if lastfm_md5password is set.

lastfm_md5password

MD5 hash of lastfm password.

lastfm_client_id

Client ID provided by last.fm. Defaults to "tst", which is valid for testing only.

lastfm_client_version

Set to the version of your program when setting a valid client_id. Defaults to "1.0"

verbose

Set verbosity level (1 through 4)

logfile

File to output log info to. If set to "STDERR" or undef, will print messages to STDERR. If set to "STDOUT" will print messages to STDOUT.

scrobble_queue

Path to file to queue info to. Defaults to ~/.musicaudioscrobbler_queue

get_mbid_from_mb

Use the Music::Tag::MusicBrainz plugin to get missing "mbid" value. Defaults false.

musictag

True if you want to use Music::Tag to get info from file. This is important if you wish to use filenames to submit from.

musictag_overwrite

True if you want to Music::Tag info to override file info. Defaults to false, which with the unicode problems with Music::Tag is a good thing.

music_tag_opts

Options for Music::Tag

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

Music::Tag, Music::Audioscrobbler::MPD

CHANGES

Release Name: 0.04

  • I noticed that Music::Tag was called with a use function. Removed this line to remove Music::Tag requirement.

  • Added some more level 4 debuging messages.

Release Name: 0.03

  • Added musictag_overwrite option. This is false by default. It is a workaround for problems with Music::Tag and unicode. Setting this to true allows Music::Tag info to overwrite info from MPD. Do not set this to true until Music::Tag returns proper unicode consistantly.

Release Name: 0.02

  • Will print error and die if lastfm_password is not set.

  • Will print error and die if BADAUTH is received.

Release Name: 0.01

  • Initial Release

AUTHOR

Edward Allen III <ealleniii _at_ cpan _dot_ org>

COPYRIGHT

Copyright (c) 2007,2008 Edward Allen III. Some rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either:

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.