view release on metacpan or  search on metacpan

lib/Audio/Scrobbler2.pm  view on Meta::CPAN

    my $params = $self->_signed_params({
        api_key => $self->{api_key},
        artist  => $artist,
        method  => 'track.updateNowPlaying',
        sk      => $self->{api_session},
        track   => $track,
    });

    return $self->_request($params, 'POST');
}

sub track_scrobble {
    my ($self, $artist, $track, $timestamp) = @_;

    _require_value($artist, 'Artist');
    _require_value($track, 'Track');
    _require_value($self->{api_session}, 'Session key');
    croak 'Timestamp must be a positive integer'
        unless defined $timestamp && $timestamp =~ /\A[1-9][0-9]*\z/;

    my $params = $self->_signed_params({
        api_key   => $self->{api_key},
        artist    => $artist,
        method    => 'track.scrobble',
        sk        => $self->{api_session},
        timestamp => $timestamp,
        track     => $track,
    });

    return $self->_request($params, 'POST');
}

sub _require_value {
    my ($value, $name) = @_;

    croak "$name is required" unless defined $value && length $value;

    return $value;
}

=head1 NAME

Audio::Scrobbler2 - Interface to the Last.fm scrobbling API

=head1 SYNOPSIS

    use Audio::Scrobbler2;

    my $scrobbler = Audio::Scrobbler2->new($api_key, $api_secret);
    my $api_token = $scrobbler->auth_getToken;

    # Ask the user to authorize the token:
    # https://www.last.fm/api/auth/?api_key=$api_key&token=$api_token
    my $api_session = $scrobbler->auth_getSession;

    $scrobbler->track_updateNowPlaying('Artist Name', 'Track Name');
    $scrobbler->track_scrobble('Artist Name', 'Track Name', $started_at);

=head1 DESCRIPTION

Audio::Scrobbler2 implements the desktop authentication flow and the two
Last.fm track submission methods needed by a basic scrobbler. Requests use
HTTPS, UTF-8 form encoding, and verified TLS certificates.

All validation, transport, HTTP, JSON, and Last.fm API failures throw an
exception. The module does not retry requests because retrying a submission
could create a duplicate scrobble.

=head1 METHODS

=head2 new

    my $scrobbler = Audio::Scrobbler2->new($api_key, $api_secret);

Creates a client. Both credentials are required.

=head2 auth_getToken

    my $token = $scrobbler->auth_getToken;

Requests and stores an unauthorized desktop application token.

=head2 auth_getSession

    my $session_key = $scrobbler->auth_getSession;

Exchanges the authorized token for a session key and stores it.

=head2 set_session_key

    $scrobbler->set_session_key($session_key);

Stores an existing non-empty session key.

=head2 track_updateNowPlaying

    my $response = $scrobbler->track_updateNowPlaying($artist, $track);

Updates the currently playing track and returns the decoded Last.fm response.

=head2 track_scrobble

    my $response = $scrobbler->track_scrobble(
        $artist,
        $track,
        $started_at,
    );

Scrobbles a track and returns the decoded Last.fm response. C<$started_at>
must be a positive integer Unix timestamp for when playback started.

=head1 MIGRATING FROM 0.05

Version 1.00 requires a playback start timestamp in C<track_scrobble>. All
failures now throw exceptions instead of returning C<0> or inconsistent error
structures.

=head1 AUTHOR

Pier Dolique (L<Perdolique|https://github.com/Perdolique>),
C<baget@cpan.org>

CPAN ID: BAGET

=head1 COPYRIGHT AND LICENSE

Copyright 2012-2026 Pier Dolique.

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

=cut

1;