WWW::AllMusicGuide - A Perl module to search the All Music Guide (www.allmusic.com)
use WWW::AllMusicGuide; my $amg = new WWW::AllMusicGuide(); my $result = $amg->search_artist(-name => "The Beatles"); if (ref($result) eq "ARRAY") { # process search results } else { # process parsed artist information } $result = $amg->search_album(-name => "Abbey Road"); $result = $amg->lookup_object($object_id);
The WWW::AllMusicGuide module provides an object that you can use to search the All Music Guide (http://www.allmusic.com). Currently, you can search for artists and albums. Artist and album pages are parsed into hash references containing the information (e.g. name, year, group members, etc). This information is useful in writing tools to maintain large collections of MP3 files, their ID3 tags and metadata.
NOTE: (from the website)
"The All Music Guide is protected by a unique data fingerprinting process to insure that the data and its format can be identified. This data cannot be distributed in any form without the express written permission of the AEC One Stop Group, Inc."
new %params
Creates a WWW::AllMusicGuide object. The following parameters are recognized:
-progress => File handle on which to send progress messages -url => URL of the All Music Guide (defaults to "http://www.allmusic.com"). Useful for testing to redirect traffic to a local server so you can see what\'s going on. -agent => User agent string to send in requests (defaults to "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0)")
search_artist %params
Searches for an artist matching the specified parameters. Valid parameters:
-name => The name of the artist as typed into the AMG search box. -id => Find the artist with the specified AMG id. -auto => Automatically select a likely match (if possible) when multiple search results are returned.
You must specify one of -name or -id. AMG id\'s are obtained in the return values for many methods. The return value is either a hash reference containing artist info OR a list reference containing search results. See "RETURN VALUES" below for more info.
If -auto is specified, search results will be analyzed and if a reasonable guess can be made as to what was intended, the method will automatically navigate to that artist page. The algorithm is simple:
* If there is only one artist that is highlighted in the search results, that is the likely match. * If there is more than one highlighted artist in the search results and one of them case-insensitively matches the passed-in -name use the matching one. * Otherwise return search results.
search_album %params
Searches for an album matching the specified parameters. Valid parameters:
-name => The name of the album as typed into the AMG search box. -id => Find the album with the specified AMG id.
You must specify one of -name or -id. AMG id\'s are obtained in the return values for many methods. The return value is either a hash reference containing album info OR a list reference containing search results. See "RETURN VALUES" below for more info.
In general data is returned in hash references with ALLCAPS keys. Search results are returned as list references containing a hash reference describing each search result. Most keys are optional and values are strings unless otherwise specified. The format for date strings varies.
Contains the following keys:
FORMED_DATE, FORMED_LOCATION, DISBANDED_DATE, DISBANDED_LOCATION BORN_DATE, BORN_LOCATION, DIED_DATE, DIED_LOCATION, IMAGE_URL, BIO YEARS_ACTIVE (listref, e.g. [ '70s', '80s', '90s' ]) MEMBERS (listref of hashrefs) example: [{'NAME' => 'Donald Fagen', 'ARTIST_ID' => 'Bjgjyeat04'}, {'NAME' => 'Walter Becker', 'ARTIST_ID' => 'B9pec97l7k'}] GENRES (listref, e.g. [ 'ROCK' ]) STYLES (listref, e.g. [ 'Album Rock', 'Jazz-Rock' ]) LABELS (listref, e.g. [ 'MCA', 'Magnum', 'Giant' ]) TONES (listref, e.g. [ 'Irreverent', 'Humorous', 'Snide' ] INSTRUMENTS (listref, e.g. [ 'Vocals','Keyboards', 'Synthesizer' ] DISCOGRAPHY (listref of hashrefs) In the discography, each album/single/compilation is represented as a hash reference with the following keys: YEAR ALBUM_ID AMG_RATING (number of stars) AMG_PICK (0/1) LABEL TYPE (album/boxset/compilation/ep/single/bootleg/video) IN_PRINT (0/1) TITLE Name of the album/single/etc.
Each Album Info hashref may contain the following keys:
ARTIST, ARTIST_ID, ALBUM_TITLE, INPRINT, RELEASE_DATE, AMG_RATING, MARC_ID, TIME, COVER_URL, REVIEW, REVIEWER GENRE (listref, e.g. [ 'Rock' ]) STYLES (listref, e.g. [ 'Jazz-Rock', 'Pop/Rock' ]) TONES (listref, e.g. [ 'Lush', 'Refined/Mannered' ]) TRACKS (listref of hashrefs) Each track hashref may contain the following keys: NAME The track name NUMBER The position of the track in the album AMG_PICK (0/1) CREDIT Songwriting credit CREDITS (listref of hashrefs) Each credit hashref may contain the following keys: ARTIST ARTIST_ID ROLES (comma-separated list of roles, e.g. "Sax (Baritone), Sax (Tenor)")
Documentation not written yet. Use Data::Dumper to see result structure.
Mohamed Hendawi (moe334578-amg AT yahoo DOT com)
Updated by David Gubitosi, 2003.
The API and format of structures may change between subsequent versions.
Copyright (c) 2004 Mohamed Hendawi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Initial checkin to SourceForge project.
Added prereq check for HTML::TreeBuilder to Makefile.PL and in AllMusicGuide.pm.
Fixes to parse_album_search_results() parsing.
Incorporated changes and fixes from Dave Gubitosi:
added artist image URL
added artist bio
added album review
added album reviewer
some fixes to track credit parser
some fixes to the logging function, for testing :)
fixed some other minor things because Allmusic.com keeps changing their structure slightly
sub analyze_album_tracks_columns { my ($self, $table) = @_;
foreach my $table_row ($table->look_down("_tag", "tr", "class", $TRACK_LIST_ROW_CLASS)) { my @cells = $table_row->look_down("_tag", "td"); next if (@cells < 5); if (@cells > 6) { $table_row = $table_row->look_down("_tag", "td")->look_down("_tag", "tr"); @cells = $table_row->look_down("_tag", "td"); } for (my $i=0; $i<@cells; $i++) { my $cell = $cells[$i]; if ($cell->as_text() =~ m/review/i) { my $link = $cell->look_down("_tag", "a"); $track->{ "REVIEW_ID" } = extract_object_id($link->attr("href")); } else { # maybe pick/nopick $self->parse_images($cell, $track); }
}
To install WWW::AllMusicGuide, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::AllMusicGuide
CPAN shell
perl -MCPAN -e shell install WWW::AllMusicGuide
For more information on module installation, please visit the detailed CPAN module installation guide.