.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Audio::Scrobbler 3pm"
.TH Audio::Scrobbler 3pm "2023-07-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Audio::Scrobbler \- Perl interface to audioscrobbler.com/last.fm
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Audio::Scrobbler;
\&
\&  $scrob = new Audio::Scrobbler(cfg => { ... });
\&
\&  $scrob\->handshake();
\&  $scrob\->submit(artist => "foo", album => "hello", track => "world",
\&    length => 180);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Audio::Scrobbler\*(C'\fR module provides a Perl interface to the track
submission \s-1API\s0 of Last.fm's AudioScrobbler \-
http://www.audioscrobbler.com/.  So far, only track submissions are
handled; the future plans include access to the various statistics.
.SH "METHODS"
.IX Header "METHODS"
The \f(CW\*(C`Audio::Scrobbler\*(C'\fR class defines the following methods:
.IP "\(bu" 4
new ( cfg => { ... } )
.Sp
Create a new \f(CW\*(C`Audio::Scrobbler\*(C'\fR object and initialize it with
the provided configuration parameters.  The parameters themselves
are discussed in the description of the handshake and submit
methods below.
.IP "\(bu" 4
err (message)
.Sp
Retrieves or sets the description of the last error encountered in
the operation of this \f(CW\*(C`Audio::Scrobbler\*(C'\fR object.
.IP "\(bu" 4
handshake ()
.Sp
Perfors a handshake with the AudioScrobbler \s-1API\s0 via a request to
http://post.audioscrobbler.com/ or a different service like libre.fm
(http://turtle.libre.fm).
.Sp
This method requires that the following configuration parameters be set:
.RS 4
.IP "\(bu" 4
progname
.Sp
The name of the program (or plug-in) performing the AudioScrobbler handshake.
.IP "\(bu" 4
progver
.Sp
The version of the program (or plug-in).
.IP "\(bu" 4
username
.Sp
The username of the user's AudioScrobbler registration.
.RE
.RS 4
.Sp
Optional parameter:
.IP "\(bu" 4
service
.Sp
The \s-1URL\s0 of the AudioScrobbler service to use, defaults to http://post.audioscrobbler.com/.
http://turtle.libre.fm or other libre.fm instances should also work.
.RE
.RS 4
.Sp
If the handshake is successful, the method returns a true value, and
the submit method may be invoked.  Otherwise, an appropriate error
message may be retrieved via the err method.
.Sp
If the \fBfake\fR configuration parameter is set, the handshake method
does not actually perform the handshake with the AudioScrobbler \s-1API,\s0
just simulates a successful handshake and returns a true value.
.Sp
If the \fBverbose\fR configuration parameter is set, the handshake
method reports its progress with diagnostic messages to the standard output.
.RE
.IP "\(bu" 4
submit ( info )
.Sp
Submits a single track to the AudioScrobbler \s-1API.\s0   This method may only
be invoked after a successful handshake.  The track information is
contained in the hash referenced by the \fBinfo\fR parameter; the following
elements are used:
.RS 4
.IP "\(bu" 4
title
.Sp
The track's title.
.IP "\(bu" 4
artist
.Sp
The name of the artist performing the track.
.IP "\(bu" 4
length
.Sp
The duration of the track in seconds.
.IP "\(bu" 4
album
.Sp
The name of the album (optional).
.RE
.RS 4
.Sp
Also, the submit method requires that the following configuration
parameters be set for this \f(CW\*(C`Audio::Scrobbler\*(C'\fR object:
.IP "\(bu" 4
username
.Sp
The username of the user's AudioScrobbler registration.
.IP "\(bu" 4
password
.Sp
The password for the AudioScrobbler registration.
.RE
.RS 4
.Sp
If the submission is successful, the method returns a true value.
Otherwise, an appropriate error message may be retrieved via the err
method.
.Sp
If the \fBfake\fR configuration parameter is set, the submit method
does not actually submit the track information to the AudioScrobbler \s-1API,\s0
just simulates a successful submission and returns a true value.
.Sp
If the \fBverbose\fR configuration parameter is set, the submit
method reports its progress with diagnostic messages to the standard output.
.RE
.PP
There are also several methods and functions for the module's internal
use:
.IP "\(bu" 4
get_ua ()
.Sp
Creates or returns the cached \f(CW\*(C`LWP::UserAgent\*(C'\fR object used by
the \f(CW\*(C`Audio::Scrobbler\*(C'\fR class for access to the AudioScrobbler \s-1API.\s0
.IP "\(bu" 4
URLDecode (string)
.Sp
Decode a URL-encoded string.
.Sp
Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html
.IP "\(bu" 4
URLEncode (string)
.Sp
Return the URL-encoded representation of a string.
.Sp
Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Do something with \s-1UPDATE\s0 responses to the handshake.
.IP "\(bu" 4
Honor \s-1INTERVAL\s0 in some way.
.IP "\(bu" 4
Figure out a way to cache unsuccesful submissions for later retrying.
.IP "\(bu" 4
Web services \- stats!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\fBscrobbler\-helper\fB\|(1)\fR
.IP "\(bu" 4
http://www.last.fm/
.IP "\(bu" 4
http://www.audioscrobbler.com/
.IP "\(bu" 4
http://www.audioscrobbler.net/
.PP
The home site of the \f(CW\*(C`Audio::Scrobbler\*(C'\fR module is
http://devel.ringlet.net/audio/Audio\-Scrobbler/
.SH "AUTHOR"
.IX Header "AUTHOR"
Peter Pentchev, <roam@ringlet.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005, 2006 by Peter Pentchev.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.7 or,
at your option, any later version of Perl 5 you may have available.
.PP
\&\f(CW$Id:\fR Scrobbler.pm 88 2006\-01\-02 09:16:32Z roam $