NAME
WWW::EchoNest::Artist - Class definition for artist objects.
SYNOPSIS
use WWW::EchoNest::Artist;
METHODS
new
Returns a new WWW::EchoNest::Artist instance.
NOTE:
WWW::EchoNest also provides the artist() convenience method to create
new instances of WWW::EchoNest::Artist.
ARGUMENTS:
id => id of the new artist
name => name of the new artist
RETURNS:
A new WWW::EchoNest::Artist instance.
EXAMPLE:
use WWW::EchoNest::Artist;
my $artist1 = WWW::EchoNest::Artist->new({ id => 'ARH6W4X1187B99274F' });
my $artist2 = WWW::EchoNest::Artist->new({ name => 'pink floyd' });
# or...
use WWW::EchoNest;
my $artist1 = get_artist('ARH6W4X1187B99274F');
my $artist2 = get_artist('pink floyd');get_id
Returns the id of a WWW::EchoNest::Artist instance.
ARGUMENTS:
none
RETURNS:
The id of a WWW::EchoNest::Artist instance.
EXAMPLE:
use WWW::EchoNest;
my $ae = artist({ name => 'autechre' });
print $ae->get_id(), "\n";
# AR4GKTH1187FB4C8DEget_name
Returns the name of a WWW::EchoNest::Artist instance.
ARGUMENTS:
none
RETURNS:
The name of a WWW::EchoNest::Artist instance.
EXAMPLE:
use WWW::EchoNest;
my $ae = artist({ id => 'AR4GKTH1187FB4C8DE' });
print $ae->get_name(), "\n";
# Autechreget_audio
Get a list of audio documents found on the web related to an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
RETURNS:
A list of audio document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $ae = artist({ name => 'autechre' });
my @audio_docs = $ae->get_audio();
my %audio_doc = %{ $audio_docs[0] };
for (keys %audio_doc) {
print $_, " : ", $audio_doc{$_}, "\n";
}
######## Results may differ ########
#
# title : 01 - Gelk
# url : http://www.nogenremusic.com/wp-content/uploads/2011/05/Gelk.mp3
# artist : Autechre
# date : 2011-05-14T21:29:48
# length : 611.0
# link : http://www.nogenremusic.com
# release : Peel Session
# id : 1942e901ba6a07f8674916e547b2e539get_biographies
Get a list of artist biographies.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
license => A string specifying the desired license type
RETURNS:
A list of biography document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $ae = artist({ name => 'autechre' });
my @biography_docs = $ae->get_biographies();
my %biography_doc = %{ $biography_docs[0] };
print $biography_doc{'url'}, "\n";
######## Results may differ ########
#
# url : http://www.last.fm/music/Autechre/+wikiget_blogs
Get a list of blog articles related to an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An ingteger starting value for the result set
high_relevance => If true only items that are highly relevant for this artist will be returned
RETURNS:
A list of blog document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $rdj = artist({ name => 'aphex twin' });
my @blog_docs = $rdj->get_biographies();
my %blog_doc = %{ $blog_docs[0] };
print 'url : ', $blog_doc{'url'}, "\n";
######## Results may differ ########
#
# url : http://www.idmforums.com/showthread.php?t=82056&goto=newpostget_familiarity
Get Echo Nest's estimation of how familiar a given artist currently is to the world.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
RETURNS:
A float representing familiarity.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Daniel Johnston};
my $dj = artist({ name => $artist_name });
print $artist_name, "'s familiarity = ", $dj->get_familiarity(), "\n";
######## Results may differ ########
#
# Daniel Johnston's familiarity = 0.72026911075927047get_foreign_id
Get an artist's id for a given id-space. Default is MusicBrainz.
ARGUMENTS:
idspace => A string indicating the idspace to fetch a foreign id for.
RETURNS:
A foreign id string.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Daniel Johnston};
my $dj = artist({ name => $artist_name });
print $artist_name, "'s MusicBrainz id is ", $dj->get_foreign_id( q{musicbrainz} ), "\n";
######## Results may differ ########
#
# Daniel Johnston's MusicBrainz id is musicbrainz:artist:8a7ca8b0-d23c-4eff-8fe9-6220ba5c9c76get_hotttnesss
Get Echo Nest's numerical estimation of how hottt an artist is.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
RETURNS:
A float representing the artist's hotttnesss.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Fred Frith};
my $frith = artist({ name => $artist_name });
print $artist_name, "'s hotttnesss is ", $frith->get_hotttnesss(), "\n";
######## Results may differ ########
#
# Fred Frith's hotttnesss is 0.37745777314700002get_images
Get a list of artist images.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
license => A string specifying the desired license type
RETURNS:
An array of image document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Fred Frith};
my $frith = artist({ name => $artist_name });
my @image_docs = $frith->get_images();
my %image_doc = %{ $image_docs[0] };
print 'url : ', $image_doc{ 'url' }, "\n";
######## Results may differ ########
#
# url : http://userserve-ak.last.fm/serve/_/278303.jpgget_news
Get a list of news articles on the web related to an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
RETURNS:
An array of news document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Sun Ra};
my $ra = artist({ name => $artist_name });
my @news_docs = $ra->get_news();
my %news_doc = %{ $news_docs[0] };
print 'name : ', $news_doc{ 'name' }, "\n";
######## Results may differ ########
#
# name : This Week in Jazz Blogrollingget_reviews
Get reviews related to an artist's work.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
RETURNS:
An array of review document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my @review_docs = $ae->get_reviews();
my %review_doc = %{ $reviews_docs[0] };
print 'url : ', $review_doc{ 'url' }, "\n";
######## Results may differ ########
#
# url : http://www.ultimate-guitar.com/reviews/compact_discs/autechre/draft_730/index.htmlget_similar
Get similar artists.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
max_familiarity => A float specifying the max familiarity of artists to search for
min_familiarity => A float specifying the min familiarity of artists to search for
max_hotttnesss => A float specifying the max hotttnesss of artists to search for
min_hotttnesss => A float specifying the max hotttnesss of artists to search for
reverse => A boolean indicating whether or not to return dissimilar artists (wrecommender). Defaults to False.
RETURNS:
An array of WWW::EchoNest::Artist instances.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my @similar_artists = $ae->get_similar();
my $similar_artist = $similar_artists[0];
print 'name : ', $similar_artist->get_name() , "\n";
######## Results may differ ########
#
# name : Aphex Twinget_songs
Get the songs associated with an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
RETURNS:
An array of WWW::EchoNest::Song instances.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my @ae_songs = $ae->get_songs();
my $ae_song = $ae_songs[0];
print "$artist_name song : ", $ae_song->get_title() , "\n";
######## Results may differ ########
#
# Autechre song : Steelsget_terms
Get the terms associated with an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
sort => A string specifying the desired sorting type (weight or frequency)
RETURNS:
An array of term document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my @ae_terms = $ae->terms();
my %ae_term = %{ $ae_terms[0] };
foreach my $key (keys %ae_term) {
print $key, ' : ', $ae_term{$key}, "\n";
}
######## Results may differ ########
#
# frequency : 0.94989445652524185
# name : glitch
# weight : 1.0get_urls
Get the urls for an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
RETURNS:
A url document hash ref.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my $ae_urls = $ae->urls();
print $artist_name, "'s wikipedia site is ", $ae_urls->{ q{wikipedia_url} }, "\n";
######## Results may differ ########
#
# Autechre's wikipedia site is http://en.wikipedia.org/wiki/Autechreget_video
Get a list of video documents found on the web related to an artist.
ARGUMENTS:
cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results => An integer number of results to return
start => An integer starting value for the result set
RETURNS:
An array of video document hash refs.
EXAMPLE:
use WWW::EchoNest;
my $artist_name = q{Autechre};
my $ae = artist({ name => $artist_name });
my @ae_videos = $ae->videos();
my %ae_video = %{ $ae_videos[0] };
foreach my $key (keys %ae_video) {
print $key, ' : ', $ae_video{$key}, "\n";
}
######## Results may differ ########
#
# url : http://www.youtube.com/watch?v=as3jowB-2cM
# date_found : 2011-05-25T02:56:31
# title : DJ Freak - Autechre (Remix)
# id : e18a600edd9616522d20219abf183243
# site : youtubeFUNCTIONS
list_terms
Get a list of best terms to use with search.
ARGUMENTS:
type => the type of terms to list; either 'mood' or 'style'
RETURNS:
An array of hash refs.
EXAMPLE:
use WWW::EchoNest::Artist qw{ list_terms };
my @best_terms = list_terms( { type => q{mood} });
for (@best_terms) {
my %term_for = %{ $_ };
}
foreach my $k ( keys %term_for ) {
print $k, " : ", %term_for{$k}, "\n";
}
######## Results may differ ########
#
# name : aggressive
# name : ambient
# name : angry
# name : angst-ridden
# name : bouncy
# name : calming
# name : carefreesearch_artist
Search for artists by name, description, or constraint.
ARGUMENTS:
name => The name of an artist
description => A string describing the artist
style => A string describing the style/genre of the artist
mood => A string describing the mood of the artist
start => An integer starting value for the result set
results => An integer number of results to return
buckets => A list of strings specifying which buckets to retrieve
limit => A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
fuzzy_match => A boolean indicating whether or not to search for similar sounding matches (only works with name)
max_familiarity => A float specifying the max familiarity of artists to search for
min_familiarity => A float specifying the min familiarity of artists to search for
max_hotttnesss => A float specifying the max hotttnesss of artists to search for
min_hotttnesss => A float specifying the max hotttnesss of artists to search for
rank_type => A string denoting the desired ranking for description searches, either 'relevance' or 'familiarity'
RETURNS:
An array of WWW::EchoNest::Artist instances.
EXAMPLE:
use WWW::EchoNest::Artist qw{ search };
@results = search( { name => 't-pain' } );
for (@results) {
print $_->get_name(), "\n";
}
######## Results may differ ########
#
# T-Pain
# T-Pain & Lil Wayne
# T-Pain & 2 Pistolssimilar
Return artists similar to this one.
ARGUMENTS:
ids => An artist id or list of ids
names => An artist name or list of names
results => An integer number of results to return
buckets => A list of strings specifying which buckets to retrieve
limit => A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
start => An integer starting value for the result set
max_familiarity => A float specifying the max familiarity of artists to search for
min_familiarity => A float specifying the min familiarity of artists to search for
max_hotttnesss => A float specifying the max hotttnesss of artists to search for
min_hotttnesss => A float specifying the max hotttnesss of artists to search for
seed_catalog => A string specifying the catalog similar artists are restricted to
RETURNS:
An array of WWW::EchoNest::Artist instances.
EXAMPLE:
my @artist_list = ( artist('weezer'), artist('radiohead') );
my $id_list_ref = map { $_->id() } @artist_list;
my @similar_artists = similar( {
ids => $id_list_ref,
results => 5,
} );
for (@similar_artists) {
print $_->get_name(), "\n";
}
######## Results may differ ########
#
# The Smashing Pumpkins
# Biffy Clyro
# Death Cab for Cutie
# Jimmy Eat World
# Nerf Herdertop_hottt
Get the top hotttest artists, according to the Echo Nest
ARGUMENTS:
results => An integer number of results to return
start => An integer starting value for the result set
buckets => A list of strings specifying which buckets to retrieve
limit => A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
RETURNS:
An array of blessed references to WWW::EchoNest::Artist objects.
EXAMPLE:
use WWW::EchoNest::Artist qw{ top_hottt };
my @hotttest_artists = top_hottt();
for (@hotttest_artists) {
print $_->get_name(), "\n";
}
######## Results may differ ########
#
# Lady Gaga
# Rihanna
# Jennifer Lopez
# Adele
# Bruno Mars
# LMFAO
# Pit Bull
# Blake Sheltontop_terms
Get a list of the top overall terms.
ARGUMENTS:
results => an integer number of results to return
RETURNS:
An array of hash refs
EXAMPLE:
use WWW::EchoNest::Artist qw{ top_terms };
my @terms_list = top_terms({ results => 2 });
for (@terms_list) {
my %term_for = %{ $_ };
foreach my $k (keys %term_for) {
print $k, " : ", $term_for{$k}, "\n";
}
print "\n";
}
######## Results may differ ########
#
# frequency : 1.0
# name : rock
#
# frequency 0.98900693989606991
# name : electronicAUTHOR
Brian Sorahan, <bsorahan@gmail.com>
SUPPORT
Join the Google group: <http://groups.google.com/group/www-echonest>
ACKNOWLEDGEMENTS
Thanks to all the folks at The Echo Nest for providing access to their powerful API.
LICENSE
Copyright 2011 Brian Sorahan.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.