Net::LastFM::Submission - Perl interface to the Last.fm Submissions Protocol
use Net::LastFM::Submission; my $submit = Net::LastFM::Submission->new( user => 'net_lastfm', password => '12', ); $submit->handshake; $submit->submit( artist => 'Artist name', title => 'Track title', time => time - 10*60, # 10 minutes ago ); $submit->now_playing( artist => 'Artist name', title => 'Track title', );
The module provides a simple Perl interface to the Last.fm Submissions Protocol (current version is 1.2.1).
The Last.fm Submissions Protocol is designed for the submission of now-playing and recent historical track data to Last.fm user profiles (aka 'Scrobbling').
http://www.lastfm.ru/api/submissions
This is a constructor for Net::LastFM::Submission object. It takes list of parameters or hashref parameter.
# list my $submit = Net::LastFM::Submission->new( user => 'net_lastfm', password => '12', ); # hashref my $submit = Net::LastFM::Submission->new({ user => 'net_lastfm', password => '12', });
This is a list of support parameters:
user
The name of the Last.FM user. Required.
password
The password of the Last.FM user. Required for Standard authentication only. It is used for generate authentication token. See http://www.lastfm.ru/api/submissions#1.2.
api_key
The API key from your Web Services account. Required for Web Services authentication only.
api_secret
The API secret from your Web Services account. Required for Web Services authentication only. It is used for generate authentication token. See http://www.lastfm.ru/api/submissions#1.3.
secret_key
The Web Services session key generated via the authentication protocol. Required for Web Services authentication only.
client_id
The identifier for the client. Optional. Default value is tst. See http://www.lastfm.ru/api/submissions#1.1.
client_ver
The version of the client being used. Optional. Default value is 1.0.
ua
The user agent of the client. Optional. Default value is LWP::UserAgent object with timeout 10 seconds.
enc
The encoding of the data, the module tries to encode the data (artist/title/album) unless the data is UTF-8. See function encode_data. Optional. Default value is cp1251.
The initial negotiation with the submissions server to establish authentication and connection details for the session. See http://www.lastfm.ru/api/submissions#handshake.
$submit->handshake;
If the handshake is successful, the returned hashref should be the following format:
{ 'status' => 'OK', 'sid' => 'Session ID', # the scrobble session id 'url' => { 'np' => 'Now-Playing URL', 'sm' => 'Submission URL' } }
Else:
{ 'error' => 'BANNED/BADAUTH/BADTIME/FAILED', 'code' => '200/500', # code of status line response 'reason' => '...' # reason of error }
Optional lightweight notification of now-playing data at the start of the track for realtime information purposes. See http://www.lastfm.ru/api/submissions#np.
It takes list of parameters or hashref parameter.
# list $submit->now_playing( artist => 'Artist name', title => 'Track title', ); # hashref $submit->now_playing({ artist => 'Artist name', title => 'Track title', });
artist
The artist name. Required.
title
The track name. Required.
album
The album title, or an empty string if not known.
length
The length of the track in seconds, or an empty string if not known.
id
The position of the track on the album, or an empty string if not known.
mb_id
The MusicBrainz Track ID, or an empty string if not known.
The encoding of the data, the module tries to encode the data (artist/title/album) unless the data is UTF-8. See function encode_data. Optional.
If the notification is successful, the returned hashref should be the following format:
{ 'status' => 'OK', }
{ 'error' => 'ERROR/BADSESSION', 'code' => '200/500', # code of status line response 'reason' => '...' # reason of error }
Submission of full track data at the end of the track for statistical purposes. See http://www.lastfm.ru/api/submissions#subs.
It takes list of parameters (information about one track) or list of hashref parameters (limit of Last.FM is 50).
# list $submit->submit( artist => 'Artist name', title => 'Track title', ); # hashref $submit->submit( grep { $_->{'source'} = 'R' } { artist => 'Artist name 1', title => 'Track title 1', time => time - 10*60, }, { artist => 'Artist name 2', title => 'Track title 2', } );
time
The time the track started playing, in UNIX timestamp format. Optional. Default value is current time.
source
The source of the track. Optional. Default value is R.
rating
A single character denoting the rating of the track. Empty if not applicable.
The length of the track in seconds. Required when the source is P, optional otherwise.
The encoding of the data, the module tries to encode the data (artist/title/album) unless the data is UTF-8. Optional.
If the submit is successful, the returned hashref should be the following format:
{ 'error' => 'ERROR/BADSESSION/FAILED', 'code' => '200/500', # code of status line response 'reason' => '...' # reason of error }
Function tries encode $data from $enc to UTF-8 and remove BOM-symbol. See Encode.
use Net::LastFM::Submission 'encode_data'; encode_data('foo bar in cp1251', 'cp1251');
Encoding of all data for Last.fm must be UTF-8.
Module can generate a requests for handshake, now playing and submit operations. These methods return HTTP::Request instance. One request has support parameters same as method.
_request_handshake()
Generate GET request for handshake. See handshake() method.
_request_now_playing(%args)
Generate POST request for now playing. See now_playing(%args) method.
_request_submit(%args)
Generate POST request for submit. See submit(%args) method.
Also module can parse a response (HTTP::Response instance) of these requests.
_response($response)
my $request = $self->_request_handshake; # generate request for handshake, return HTTP::Request instance ... my $response = send_request($request); # send this request, return HTTP::Response instance ... $self->_response($response); # parse this request
This feature can use for async model (even-driven) such as POE, IO::Lambda or AnyEvent.
See POE::Component::Net::Submission::LastFM.
The module supports debug mode.
BEGIN { $ENV{SUBMISSION_DEBUG}++ }; use Net::LastFM::Submission;
See examples/* in this distributive.
Net::LastFM
A simple interface to the Last.fm API. Moose-like interface. Very simple and powerful.
Audio::Scrobbler
Perl interface to audioscrobbler.com/last.fm. Old interface for submit.
Music::Audioscrobbler::Submit
Module providing routines to submit songs to last.fm using 1.2 protocol. Use path to a track or Music::Tag or hashref. Very big :).
LWP::UserAgent HTTP::Request::Common Encode Digest::MD5 Carp Exporter
Anatoly Sharifulin, <sharifulin at gmail.com>
<sharifulin at gmail.com>
Please report any bugs or feature requests to bug-net-lastfm-submission at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-LastFM-Submission. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-net-lastfm-submission at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Net::LastFM::Submission
You can also look for information at:
Github
http://github.com/sharifulin/net-lastfm-submission/tree/master
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-LastFM-Submission
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Net-LastFM-Submission
CPANTS: CPAN Testing Service
http://cpants.perl.org/dist/overview/Net-LastFM-Submission
CPAN Ratings
http://cpanratings.perl.org/d/Net-LastFM-Submission
Search CPAN
http://search.cpan.org/dist/Net-LastFM-Submission
Copyright (C) 2009 Anatoly Sharifulin
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Net::LastFM::Submission, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::LastFM::Submission
CPAN shell
perl -MCPAN -e shell install Net::LastFM::Submission
For more information on module installation, please visit the detailed CPAN module installation guide.