/ 
WebService-FreeDB-0.63
River stage zero No dependents
/ WebService::FreeDB

NAME

WebService::FreeDB - retrieving entries from FreeDB by searching for keywords (artist,track,album,rest)

SYNOPSIS

use WebService::FreeDB;

Create an Object

$freedb = WebService::FreeDB->new();

Get a list of all discs matching 'Fury in the Slaughterhouse'

 %discs = $cddb->getdiscs(
	"Fury in the Slaughterhouse",
	['artist','rest']
 );

Asks user to select one or more of the found discs

@selecteddiscs = $cddb->ask4discurls(\%discs);

Get information of a disc

%discinfo = $cddb->getdiscinfo(@selecteddiscs[0]);

print disc-information to STDOUT - pretty nice formatted

$cddb->outstd(\%discinfo);

DESCRIPTION

WebService::FreeDB uses a FreeDB web interface (default is www.freedb.org) for searching of CD Information. Using the webinterface, WebService::FreeDB searches for artist, song, album name or the ''rest'' field.

The high level functions included in this modules makes it easy to search for an artist of a song, all songs of an artist, all CDs of an artist or whatever.

USING WebService::FreeDB

How to work with WebService::FreeDB

Creating a WebService::FreeDB object

This has to be the first step

my $cddb = WebService::FreeDB->new()

You can configure the behaviour of the Module giving new() optional parameters:

Usage is really simple. To set the debug level to 1, simply:

my $cddb = WebService::FreeDB->new( DEBUG => 1 )

optional prameters DEBUG: [0 to 3] - Debugging information,

0 is default (means no additional information), 3 gives a lot of stuff (hopefully) nobody needs. All debug information goes to STDERR.

HOST: FreeDB-Host where to connect to.

www.freedb.org is default - has to have a webinterface - no normal FreeDB-Server !

PATH: Path to the php-script (the webinterface)

/freedb_search.php is default - so working on www.freedb.org

DEFAULTVALUES: Values with will be set for every request.

allfields=NO&grouping=none is default, so the grouping feature is not supported until now.

Getting a list of all albums for keywords.

Now we retrieve a list of CDs, which match to your keywords in given fields. Available fields are artist,title,track,rest. Available categories are blues,classical,country,data,folk,jazz,misc,newage,reggae,rock,soundtrack For explanation see the webinterface.

%discs = $cddb->getdiscs(
    "Fury in the Slaughterhouse",
    [qw( artist rest )]
);

The returned hash includes as key the urls for retriving the concrete data and as value a array of the artist,the album name followed by the alternative disc-urls

Selecting discs from the big %discs hash.

After retrieving a huge list of possible matches we have to ask the user to select one or more CDs for retrieval of the disc-data.

@selecteddiscs = $cddb-E<gt>ask4discurls(\%discs);

The function returns an array of urls after asking user. (using STDERR) The user can select the discs by typing numbers and ranges (e.g. 23-42)

Retrieving the concrete disc informations

This functions gets a url and returns a hash including all disc information.

%discinfo = $cddb-E<gt>getdiscinfo(@selecteddiscs[0]);

So we have to call this function n-times if the user selects n cds. The hash includes the following keys url,artist,totaltime,genre,album,trackinfo,rest,tracks,year These are all string except trackinfo, this is a array of arrays. Every of these small arrays represent a track: first its name , second its time.

Please keep an eye on track vs. length of the trackinfo array. Some entries in FreeDB store an other number of tracks than they have stored !

Now the last step is to print the information to the user.

$cddb->outdumper(\%discinfo); # Like Data::Dumper
$cddb->outstd(\%discinfo); # nicely formatted to stdout
$cddb->outxml(\%discinfo); # XML format

These 3 functions print a retrieved disc out.

The XML format outputs according to example/cdcollection.dtd this method does not use every information. This Function also prints some additional information out, if given. This is, because it is used by other projects, such like music-moth (www.moth.de) I think this is the point for starting your work: Take %discinfo and write whhat ever you want.

NOTICE

Be aware this module is in BETA stage.

AUTHOR

Copyright 2002-2003, Henning Mersch All rights reserved.

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

Address bug reports and comments to: hm@mystical.de

BUGS

None known - but feel free to mail if you got some !

SEE ALSO

perl(1)

www.freedb.org