Audio::Scrobbler(3pm)

💖 NAME 💖

Bestie, meet Audio::Scrobbler — it's the Perl interface to audioscrobbler.com / last.fm. That's the whole vibe. ✨

---

🦋 SYNOPSIS 🦋

Okay so here's the little starter pack, copy it exactly:

use Audio::Scrobbler;

$scrob = new Audio::Scrobbler(cfg => { ... });

$scrob->handshake();
$scrob->submit(artist => "foo", album => "hello", track => "world",
  length => 180);

Look at that. Handshake, then submit. We love a two-step icon. 💅

---

🌸 DESCRIPTION 🌸

So the Audio::Scrobbler module hands you a Perl interface to the track submission API of Last.fm's AudioScrobbler — that's http://www.audioscrobbler.com/, no cap.

And the tea is: so far, only track submissions are handled. That's it, that's the whole menu right now. The future plans include access to the various statistics, so like… someday™. For now bestie, we scrobble. 🎀

---

👑 METHODS 👑

The Audio::Scrobbler class defines the following methods, and yes we're going through every single one, no skipping:

• new ( cfg => { ... } ) — Make a brand new Audio::Scrobbler object and initialize it with the config params you pass in. The parameters themselves get their whole moment down in the handshake and submit method descriptions below, so keep reading, I promise it's worth it. 🫶
• err (message) — Gets or sets the description of the last error this particular Audio::Scrobbler object ran into. Your little emotional support error string. 😭
• handshake () — Performs a handshake with the AudioScrobbler API by making a request to http://post.audioscrobbler.com/ or to a different service like libre.fm (http://turtle.libre.fm). It's giving formal introduction, honestly.

This method requires these configuration parameters to be set:

• progname — The name of the program (or plug-in) doing the AudioScrobbler handshake.
• progver — The version of the program (or plug-in).
• username — The username of the user's AudioScrobbler registration.

Optional parameter:

• service — The URL of the AudioScrobbler service to use. Defaults to http://post.audioscrobbler.com/. http://turtle.libre.fm or other libre.fm instances should also work. ✨

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.

If the fake configuration parameter is set, the handshake method does not actually perform the handshake with the AudioScrobbler API — it just simulates a successful handshake and returns a true value. Fake it till you make it, periodt. 💀

If the verbose configuration parameter is set, the handshake method reports its progress with diagnostic messages to the standard output. Narrator voice: she's talking. 🎤

• submit ( info ) — Submits a single track to the AudioScrobbler API. This method may only be invoked after a successful handshake — do not skip the handshake bestie, that's the whole ritual. 🙈

The track info lives in the hash referenced by the info parameter, and these are the elements it uses:

• title — The track's title.
• artist — The name of the artist performing the track.
• length — The duration of the track in seconds.
• album — The name of the album (optional).

Also, submit requires that these configuration parameters be set for this Audio::Scrobbler object:

• username — The username of the user's AudioScrobbler registration.
• password — The password for the AudioScrobbler registration.

If the submission is successful, the method returns a true value. Otherwise, an appropriate error message may be retrieved via the err method.

If the fake configuration parameter is set, submit does not actually submit the track information to the AudioScrobbler API — it just simulates a successful submission and returns a true value.

If the verbose configuration parameter is set, submit reports its progress with diagnostic messages to the standard output. 👑

And then there's also several methods and functions that are for the module's internal use — the backstage crew, lowkey:

• get_ua () — Creates or returns the cached LWP::UserAgent object that the Audio::Scrobbler class uses to access the AudioScrobbler API.
• URLDecode (string) — Decode a URL-encoded string.

Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html

• URLEncode (string) — Return the URL-encoded representation of a string.

Obtained from http://glennf.com/writing/hexadecimal.url.encoding.html

---

🧚 TODO 🧚

The wishlist, the vision board, the "we'll get to it" pile:

• Do something with UPDATE responses to the handshake.
• Honor INTERVAL in some way.
• Figure out a way to cache unsuccesful submissions for later retrying.
• Web services - stats!

---

🌈 SEE ALSO 🌈

• scrobbler-helper(1)
• http://www.last.fm/
• http://www.audioscrobbler.com/
• http://www.audioscrobbler.net/

The home site of the Audio::Scrobbler module is http://devel.ringlet.net/audio/Audio-Scrobbler/ — that's her house, go say hi. 🏠💜

---

⭐ AUTHOR ⭐

Peter Pentchev, <roam@ringlet.net> — king behavior, honestly. 👑

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2005, 2006 by Peter Pentchev.

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.

$Id: Scrobbler.pm 88 2006-01-02 09:16:32Z roam $

---

Ok that's the whole page bestie, every flag, every param, every vibe, nothing dropped. Slay. 🎀

This little masterpiece is documented for perl v5.36.0, dated 2023-07-20, filed under Audio::Scrobbler(3pm) — and that's the sign-off, muah. 💖✨🦋