NAME

WebService::FreeDB - retrieving entrys 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 a disc
%discinfo = $cddb->getdiscinfo(@selecteddiscs[0]);
   print disc-information to STDOUT - pretty nice formated
$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

1. 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: e.g.

my $cddb = WebService::FreeDB->new(DEBUG =>1) sets the debuglevel to 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.

2. 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",(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

3. 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->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)

4. Retrieving the concrete disc informations

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

%discinfo = $cddb->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 !

5. print out disc information.

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

$cddb->outdumper(\%discinfo);

or

$cddb->outstd(\%discinfo);

or

$cddb->outxml(\%discinfo);

These 3 functions print a retrieved disc out.

The 1st simply uses the Data::Dumper-Module. The 2nd does a pretty nice output to the users STDOUT. The 3rd does a output in XML-Format accourding to example/cdcollection.dtd this method does not use every information (missing are total-time,tracktime,rest) I think this is the point for starting your work: Take %discinfo and write whereever you want.

NOTICE

Be aware this module is in BETA stage.

AUTHOR

Copyright 2002, 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).