/ 
Net-LastFM-Submission-0.64
River stage one • 2 direct dependents • 2 total dependents
/ Net::LastFM::Submission

NAME

Net::LastFM::Submission - Perl interface to the Last.fm Submissions Protocol

SYNOPSIS

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',
);

DESCRIPTION

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

METHODS

new(%args)

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.

handshake()

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
}

now_playing(%args)

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',
});

This is a list of support parameters:

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

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

If the notification is successful, the returned hashref should be the following format:

{
    'status' => 'OK',
}

Else:

{
    'error'  => 'ERROR/BADSESSION',
    'code'   => '200/500', # code of status line response
    'reason' => '...'      # reason of error
}

submit(%args)

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',
    }
);

This is a list of support parameters:

  • artist

    The artist name. Required.

  • title

    The track name. Required.

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

  • length

    The length of the track in seconds. Required when the source is P, optional otherwise.

  • album

    The album title, 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.

  • enc

    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:

{
    'status' => 'OK',
}

Else:

{
    'error'  => 'ERROR/BADSESSION/FAILED',
    'code'   => '200/500', # code of status line response
    'reason' => '...'      # reason of error
}

FUNCTIONS

encode_data($data, $enc)

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.

GENERATE REQUESTS AND PARSE RESPONSES

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.

DEBUG MODE

The module supports debug mode.

BEGIN { $ENV{SUBMISSION_DEBUG}++ };
use Net::LastFM::Submission;

EXAMPLES

See examples/* in this distributive.

SEE ALSO

  • 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 :).

DEPENDENCIES

LWP::UserAgent HTTP::Request::Common Encode Digest::MD5 Carp Exporter

AUTHOR

Anatoly Sharifulin, <sharifulin at gmail.com>

BUGS

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.

SUPPORT & DOCUMENTATION

You can find documentation for this module with the perldoc command.

perldoc Net::LastFM::Submission

You can also look for information at:

COPYRIGHT & LICENSE

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.