WebService::Audioscrobbler - An object-oriented interface to the Audioscrobbler WebService API

WebService-Audioscrobbler documentation Contained in the WebService-Audioscrobbler distribution.

Index

Code Index:

NAME

Top

WebService::Audioscrobbler - An object-oriented interface to the Audioscrobbler WebService API

SYNOPSIS

Top

This module aims to be a full implementation of a an object-oriented interface to the Audioscrobbler WebService API (as available on http://www.audioscrobbler.net/data/webservices/). Since version 0.04, the module fully supports data caching and, thus, complies to the service's recommended usage guides.

    use WebService::Audioscrobbler;

    my $ws = WebService::Audioscrobbler->new;

    # get an object for artist named 'foo'
    my $artist  = $ws->artist('foo');

    # retrieves tracks from 'foo'
    my @tracks = $artist->tracks;

    # retrieves tags associated with 'foo'
    my @tags = $artist->tags;

    # fetch artists similar to 'foo'
    my @similar = $artist->similar_artists;

    # prints each one of their names
    for my $similar (@similar) {
        print $similar->name . "\n";
    }

    ...

    # get an object for tag 'bar'
    my $tag = $ws->tag('bar');

    # fetch tracks tagged with 'bar'
    my @bar_tracks = $tag->tracks;

    ...

    my $user = $ws->user('baz');

    my @baz_neighbours = $user->neighbours;

Audioscrobbler is a great service for tracking musical data of various sorts, and its integration with the LastFM service (http://www.last.fm) makes it work even better. Audioscrobbler provides data regarding similarity between artists, artists discography, tracks by musical genre (actually, by tags), top artists / tracks / albums / tags and how all of that related to your own musical taste.

Currently, only of subset of these data feeds are implemented, which can be viewed as the core part of the service: artists, tags, tracks and users. Since this module was developed as part of a automatic playlist building application (still in development) these functions were more than enough for its initial purposes but a (nearly) full WebServices API is planned.

In any case, code or documentation patches are welcome.

METHODS

Top

new([$cache_root]

Creates a new WebService::Audioscrobbler object. This object can then be used to retrieve various bits of information from the Audioscrobbler database. If $cache_root is specified, Audioscrobbler data will be cached under this directory, otherwise it will use Cache::FileCache defaults.

artist($name)

Returns an WebService::Audioscrobbler::Artist object constructed using the given $name. Note that this call doesn't actually check if the artist exists since no remote calls are dispatched - the object is only constructed.

track($artist, $title)

Returns an WebService::Audioscrobbler::Track object constructed used the given $artist and $title. The $artist parameter can either be a WebService::Audioscrobbler::Artist object or a string (in this case, a WebService::Audioscrobbler::Artist will be created behind the scenes). Note that this call doesn't actually check if the track exists since no remote calls are dispatched - the object is only constructed.

tag($name)

Returns an WebService::Audioscrobbler::Tag object constructed using the given $name. Note that this call doesn't actually check if the tag exists since no remote calls are dispatched - the object is only constructed.

user($name)

Returns an WebService::Audioscrobbler::User object constructed using the given $name. Note that this call doesn't actually check if the user exists since no remote calls are dispatched - the object is only constructed.

AUTHOR

Top

Nilson Santos Figueiredo Júnior, <nilsonsfj at cpan.org>

BUGS

Top

Please report any bugs or feature requests to bug-webservice-audioscrobbler at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Audioscrobbler. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Top

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

    perldoc WebService::Audioscrobbler

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/WebService-Audioscrobbler

* CPAN Ratings

http://cpanratings.perl.org/d/WebService-Audioscrobbler

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-Audioscrobbler

* Search CPAN

http://search.cpan.org/dist/WebService-Audioscrobbler

COPYRIGHT & LICENSE

Top

Copyright 2006-2007 Nilson Santos Figueiredo Júnior, all rights reserved.

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

NOTE: The datafeed from audioscrobbler.net is for non-commercial use only. Please see http://www.audioscrobbler.net/data/webservices/ for more licensing information.

SEE ALSO

Top

* http://www.audioscrobbler.net/data/webservices/ and http://www.last.fm/
* WebService::LastFM::SimilarArtists, WebServices::LastFM, Audio::Scrobbler
* LWP::Simple, XML::Simple, Cache::FileCache, URI
WebService-Audioscrobbler documentation Contained in the WebService-Audioscrobbler distribution. 
package WebService::Audioscrobbler;
use warnings;
use strict;
use CLASS;

use base 'Class::Data::Accessor';
use base 'Class::Accessor::Fast';

use NEXT;
use UNIVERSAL::require;

use URI;


our $VERSION = '0.07';

CLASS->mk_classaccessor("base_url" => URI->new("http://ws.audioscrobbler.com/1.0/"));

# defining default classes
CLASS->mk_classaccessor("artist_class"       => CLASS . '::Artist');
CLASS->mk_classaccessor("track_class"        => CLASS . '::Track');
CLASS->mk_classaccessor("tag_class"          => CLASS . '::Tag');
CLASS->mk_classaccessor("user_class"         => CLASS . '::User');
CLASS->mk_classaccessor("data_fetcher_class" => CLASS . '::DataFetcher');

# requiring stuff
CLASS->artist_class->require         or die $@;
CLASS->track_class->require          or die $@;
CLASS->tag_class->require            or die $@;
CLASS->user_class->require           or die $@;
CLASS->data_fetcher_class->require   or die $@;

# object accessors
CLASS->mk_accessors(qw/data_fetcher/);


sub new {
    my $class = shift;
    my ($cache_root) = @_;

    my $self = bless {}, $class;
    
    # creates the data fetcher object which will be extensively used
    $self->data_fetcher( 
        $self->data_fetcher_class->new( {
            base_url    =>  $self->base_url,
            cache_root  =>  $cache_root
        } )
    );

    $self;
}


sub artist {
    my ($self, $artist) = @_;
    return $self->artist_class->new($artist, $self->data_fetcher);
}


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

    $artist = $self->artist($artist) 
        unless ref $artist; # assume the user knows what he's doing

    return $self->track_class->new($artist, $title, $self->data_fetcher);
}


sub tag {
    my ($self, $tag) = @_;
    return $self->tag_class->new($tag, $self->data_fetcher);
}


sub user {
    my ($self, $user) = @_;
    return $self->user_class->new($user, $self->data_fetcher);
}


1; # End of WebService::Audioscrobbler