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 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

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

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",
	[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

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); # 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 (missing are total-time,tracktime,rest). I think this is the point for starting your work: Take %discinfo and write where 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).