NAME

WWW::Discogs - get music related information and images

DESCRIPTION

Interface with www.discogs.com API to get music related information and images. Discogs is a user-built database containing information on artists, labels, and their recordings.

SYNOPSIS

use WWW::Discogs;

my $client = WWW::Discogs->new;

# --
# print all vinyl (12") releases from label 'Drumcode'
# --
my $label = $client->label(name => 'Drumcode', releases => 1);
my @vinyls = grep { $_->{format} =~ /12\"/ } $label->releases;

for my $rel (@vinyls) {
    print join("\t",
               $rel->{catno},
               $rel->{artist},
               $rel->{title},
               $rel->{format},
        );
    print "\n";
}

# --
# print all covers for records by Nima Khak
# --
my @all_rels = $client->artist(name => 'Nima Khak', releases => 1)->releases;
my @main_rels = grep { $_->{role} eq 'Main' } @all_rels;

RELEASE:
for my $r (@main_rels) {
    my $release;

    if ($r->{type} eq 'master') {
        my $master = $client->master(id => $r->{id});
        $release = $client->release(id => $master->main_release);
    }
    elsif ($r->{type} eq 'release') {
        $release = $client->release(id => $r->{id});
    }

    my @images = $release->images(type => 'primary');
    next RELEASE unless scalar(@images);
    print join("\t", $release->title, $images[0]->{uri}), "\n";
}

METHODS

search( q => $search_string )

search( q => $search_string, type => $search_type )

search( q => $search_string, type => $search_type, page => $page )

Returns a WWW::Discogs::Search object. If you want to narrow down search results then provide $search_type which can be one of 'all' (the default), 'releases' (also returns masters), 'artists' or 'labels'. Search results are paginated (20 results per page) and default is page => 1. You can check how many search results pages are there by calling pages method on WWW::Discogs::Search object.

release( id => $release_id )

Returns a WWW::Discogs::Release object. You can get a $release_id from a search, artist, or label.

master( id => $master_id )

Returns a WWW::Discogs::Master object. You can get a $master_id from a search or release.

artist( name => $artist_name )

artist( name => $artist_name, releases => 1 )

Returns a WWW::Discogs::Artist object. You can get the exact name of an artist from a search result's title.

label( name => $label_name )

label( name => $label_name, releases => 1 )

Returns a WWW::Discogs::Label object. You can get the exact name of a label from a search result's title.

OBJECTS CREATED AND THEIR METHODS

WWW::Discogs::Search

$search->exactresults

Returns list of hash references containing results exactly matching search query. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $search = $client->search(q => 'adam beyer');

for my $result ($search->exactresults) {
    print join(" - ", $result->{type}, $result->{title}, $result->{uri});
    print "\n";
}

$search->searchresults

Returns list of hash references containing search results.

$search->numresults

Returns a number of search results (counted without exact results).

$search->pages

Returns number of search results' pages. Each page contains max 20 search results.

WWW::Discogs::Release

$release->id

Returns release ID.

$release->title

Returns title of the release.

$release->images

$release->images( type => $image_type )

Returns a list of hash references containing information about images for a release. $image_type can be one of 'primary' or 'secondary'. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 797674);

for my $img ( $release->images(type => 'primary') ) {
    print join(" - ",
               $img->{width}, $img->{height}, $img->{uri},
               $img->{uri150}, $img->{type},
        );
    print "\n";
}

$release->released

Returns release date in ISO 8601 format (YYYY-MM-DD).

$release->released_formatted

Returns formatted release date ('06 Oct 2006', 'Mar 2006' etc.)

$release->labels

Returns a list of hash references containing labels information. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 797674);

for my $label ($release->labels) {
    print join(" - ", $label->{name}, $label->{catno});
}

$release->country

Returns country.

$release->formats

Returns a list of hash references containing formats information. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 797674);

for my $format ($release->formats) {
    printf("%d x %s, %s\n",
           $format->{qty},
           $format->{name},
           join(", ", @{ $format->{descriptions } }),
        );
}

Prints:

1 x CD, Album, Partially Mixed
1 x CD, Compilation, Limited Edition

$release->status

Returns status.

$release->master_id

Returns master release ID associated with a release.

$release->year

Returns release year.

$release->notes

Returns release notes.

$release->styles

Returns a list of styles.

$release->genres

Returns a list of genres.

$release->artists

Returns a list of hash references containing artists information.

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 18618);

for my $artist ($release->artists) {
    print join(" - ", $artist->{name}, $artist->{anv}, $artist->{role});
    print "\n";
}

$release->extraartists

Returns a list of hash references containing extra artists information.

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 18618);

for my $exart ($release->extraartists) {
    print join(" - ", $exart->{name}, $exart->{anv}, $exart->{role});
    print "\n";
}

$release->tracklist

Returns tracklist as a list containing hash references. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $release = $client->release(id => 830189);

my @tracklist = $release->tracklist;
for my $track (sort { $a->{position} <=> $b->{position} } @tracklist) {
    printf("%d. %s (%s)\n",
           $track->{position}, $track->{title}, $track->{duration},
        );
}

WWW::Discogs::Master

$master->id

Returns master ID.

$master->main_release

Returns main release ID.

$master->versions

Returns a list of hash references containing versions information. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $master = $client->master(id => 104330);

for my $version ( $master->versions ) {
    printf("%9d %7s %15s %18s %7s %15s\n",
           $version->{id}, $version->{country}, $version->{title},
           $version->{format}, $version->{catno}, $version->{label});
}

Prints:

 116934  Sweden   Chaos & Order          CD, Album  HPCD20 H. Productions
  11168  Sweden   Chaos & Order        2xLP, Album  HPLP20 H. Productions
2307050  Sweden   Chaos & Order 2xLP, Album, W/Lbl  HPLP20 H. Productions

Other available keys in $version besides the ones in example above are $version->{status} and $version->{released}.

$master->images

$master->images( type => $image_type )

Returns a list of hash references containing information about images for a release. $image_type can be one of 'primary' or 'secondary'. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $master = $client->master(id => 23992);

for my $img ( $master->images(type => 'secondary') ) {
    print join(" - ",
             $img->{width}, $img->{height}, $img->{uri},
             $img->{uri150}, $img->{type},
        );
    print "\n";
}

$master->year

Returns release year.

$master->notes

Returns release notes.

$master->styles

Returns a list of styles.

$master->genres

Returns a list of genres.

$master->artists

Returns a list of hash references containing artists information. See $release->artists for an example.

$master->extraartists

Returns a list of hash references containing extra artists information. See $release->extraartists for an example.

$master->tracklist

Returns tracklist. See $release->tracklist for an example.

WWW::Discogs::Artist

$artist->name

Returns artist name.

$artist->realname

Returns artist's real name

$artist->aliases

Returns a list of aliases used by the artist.

$artist->namevariations

Returns a list of name variations for the artist.

$artist->profile

Returns artist's profile information.

$artist->urls

Returns a list of site's URLs linked to the artist.

$artist->images

$artist->images( type => $image_type )

Returns a list of hash references containing images information. See $release->images for an example.

$artist->releases

If $client->artist method creating a new WWW::Discogs::Artist object was called with releases => 1 parameter you can get the list of artist's releases by calling this method. The result will be a list of hash references containing releases/master releases information. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $artist = $client->artist(name => "Adam Beyer", releases => 1);

foreach my $r ($artist->releases) {
  printf("%8d %7s %17s %s\n", $r->{id}, $r->{type}, $r->{role}, $r->{title});
}

$r->{id} will contain release/master release ID
$r->{type} will contain release type ('release' or 'master')
$r->{role} will contain artist's role in release ('Main', 'Remix', 'Producer', 'Appearance', 'TrackAppearance' etc.)
$r->{title} will contain release/master release title

For releases with 'master' type you can get main release ID by checking the value of $r->{main_release}. Use Data::Dumper to find out more about this structure as results differ depending on artist's role and release type.

WWW::Discogs::Label

$label->name

Returns label's name.

$label->releases

If $client->label method creating a new WWW::Discogs::Label object was called with releases => 1 parameter you can get the list of label's releases by calling this method. The result will be a list of hash references containing releases information. See example below:

use WWW::Discogs;

my $client = WWW::Discogs->new;
my $label = $client->label(name => 'Southsoul Appendix', releases => 1);

for my $r ($label->releases) {
    print join("\t", $r->{id}, $r->{catno}, $r->{artist},
               $r->{title}, $r->{format}
        );
    print "\n";
}

$label->contactinfo

Returns contact info to the label.

$label->sublabels

Returns a list containing names of sublabels.

$label->parentlabel

Returns the name of parent label.

$label->images

$label->images( type => $images_type)

Returns a list of hash references containing images information. See $release->images for an example.

AUTHOR

0.11+: Michal Gasek <michal@gasek.eu>

0.01-0.10: Lee Aylward <lee@laylward.com>

LICENSE

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

To install WWW::Discogs, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Discogs

CPAN shell

perl -MCPAN -e shell
install WWW::Discogs

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)