MusicBrainz::Client - MusicBrainz Client API

  use MusicBrainz::Client;
  use MusicBrainz::Queries qw(:all);

  my $mb = MusicBrainz::Client->new(); 
  if(! $mb->query_with_args( MBQ_FindArtistByName, [ "Pink Floyd" ]) ) {
    die("Query failed: ", $mb->get_query_error(), "\n");
  }
  print "Found ", $mb->get_result_int(MBE_GetNumArtists), " artists\n";

This module provides access to the musicbrainz client API using a perl-ish OO interface.

new

$mb->new(); Create a new handle to the MusicBrainz object.

get_version

($major, CW$minor, CW$revision) = CW$mb->get_version(); Get the version number of the libmusicbrainz library in use.

set_server

$success = CW$mb->set_server($serverAddr, CW$serverPort); Set the name and the port of the MusicBrainz server to use. If this function is not called, the default www.musicbrainz.org server on port 80 will be used. See also: set_proxy

set_debug

$mb->set_debug($debug); Enable debug out to stdout by sending a non-zero value to this function.

set_proxy

$success = CW$mb->set_proxy($serverAddr, CW$serverPort); Set the name of the HTTP Proxy to use. This function must be called anytime the client library must communicate via a proxy firewall. See also: set_server

authenticate

$success = CW$mb->authenticate($userName, CW$password); This function must be called if you want to submit data to the server and give the user credit for the submission. If you're looking up data from the server, you do not need to call authenticate. If you are submitting data to the MB server and you want your submissions be submitted anonymously, then do not call this function. returns true if the server authentication was correctly initiated. Note: the password is sent in plaintext.

set_device

$success = CW$mb->set_device($device); Call this function to set the CD-ROM drive device if you plan to use the client library to identify and look up CD-ROMs using MusicBrainz. Unix: specify a device such as /dev/cdrom. Defaults to /dev/cdrom Windows: specify a drive letter of a CD-ROM drive. e.g. E: Always returns true.

use_utf8

$mb->use_utf8( 1 ); Use this function to set the output returned by the Get function. The Get functions can return data in ISO-8859-1 encoding or in UTF-8. Defaults to ISO-8859-1.

set_depth

$mb->set_depth($depth); Set the search depth of the query. Please refer to the Query Depth section in the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html) for an explanation of this value. Defaults to 2.

set_max_items

$mb->set_max_items($maxItems); Set the maximum number of items to return to the client. If a search query yields more items than this max number, the server will omit the excess items and not return them to the client. This value defaults to 25. See also: query

query

$success = CW$mb->query($rdfObject); Query the MusicBrainz server. Use this function if your query requires no arguments other than the query itself. Please refer to the MusicBrainz::Queries module for the documentation on the available queries. Returns true if the query succeeded (even if no items are returned) and false if the query failed. Call CW$mb->get_query_error(); for details on the error that occurred.

 See also: L<get_query_error> , L<query_with_args>

query_with_args

$sucess = CW$mb->query_with_args($rdfObject, \@args); Query the MusicBrainz server. Use this function if your query requires one or more arguments. The arguments are as an anonymous array. $rdfObject is one of the exportable constants defined in MusicBrainz::Queries Returns true if the query succeeded (even if no items are returned) and false if the query failed. Call CW$mb->get_query_error(); for details on the error that occurred. See also: get_query_error , query

get_web_submit_url

$url = CW$mb->get_web_submit_url(); Use this function to query the current CD-ROM and to calculate the web submit URL that can be opened in a browser in order to start the web based CD-ROM Submission to MusicBrainz. The CD-ROM in the CD-ROM drive set by CW$mb->set_device(); will be queried. Returns true if the url was successfully generated, false if an error occurred. See also: set_device

get_query_error

$error = CW$mb->get_query_error(); Retrieve the error message that was generated during the last call to CW$mb->query(); or CW$mb->query_with_args(); See also: query , query_with_args

select

$success = CW$mb->select($selectQuery); Select a context in the result query. Use this function if your Select requires no ordinal arguments. Pass this function a select query (starts with MBS_) from MusicBrainz::Queries. Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html) for more details on why you need to do a Select and what types of Selects are available. Returns true if the select succeeded, false otherwise. See also: select1

select1

$success = CW$mb->select1($selectQuery, CW$ord); Select a context in the result query. Use this function if your Select requires one ordinal argument. Pass this function a selectQuery (usually start with MBS_) from MusicBrainz::Queries. Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html) for more details on why you need to do a Select and what types of Selects are available. Returns true if the select succeeded, false otherwise. See also: select

get_result_data

$data = CW$mb->get_result_data($resultName); Extract a piece of information from the data returned by a successful query. This function takes a resultName (usually named starting with MBE_) from MusicBrainz::Queries. Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html) Returns true if the correct piece of data was returned and found, false otherwise. See also: get_result_data1

get_result_data1

$data1 = CW$mb->get_result_data1($resultName, CW$ordinal); Extract a piece of information from the data returned by a successful query. This function takes a resultName (usually named starting with MBE_) from MusicBrainz::Queries. See the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html). CW$ordinal is the position of the data you wish to retrieve. Returns true if the correct piece of data was returned and found, false otherwise. See also: get_result_data

does_result_exist

$success = CW$mb->does_result_exist($resultName); Check to see if a piece of information exists in data returned by a successful query. This function takes the same resultName argument as get_result_data Returns true if the result data exists, false otherwise See also: get_result_data

does_result_exist1

$success CW$mb->does_result_exist1($resultName, CW$ordinal); Check to see if a piece of information exists in data returned by a successful query. This function takes the same resultName and ordinal arguments as get_result_data1 Returns true if the result data exists, false otherwise See also: get_result_data1

get_result_int

$result = CW$mb->get_result_int($resultName); Return the integer value of a result from the data returned by a successful Query. This function takes the same resultName argument as get_result_data Returns the integer value of the result See also: get_result_data

get_result_int1

$result = CW$mb->get_result_int1($resultName, CW$ordinal); Return the integer value of a result from the data returned by a successful Query. This function takes the same resultName and ordinal arguments as get_result_data1 Returns the integer value of the result See also: get_result_data1

get_result_rdf

$rdfstr = CW$mb->get_result_rdf(); Retrieve the RDF that was returned by the server. Most users will not want to use this function!

set_result_rdf

$success = CW$mb->set_result_rdf($rdfstr); Set an RDF object for so that the Get functions can be used to extract data from the RDF. Advanced users only! See also: get_result_rdf

get_id_from_url

$id = CW$mb->get_id_from_url($url); Extract the actual artist/album/track ID from a MBE_GETxxxxxId query. The MBE_GETxxxxxId functions return a URL to where the more RDF metadata for the given ID can be retrieved. Callers may wish to extract only the ID of an artist/album/track for reference elsewhere. See also: get_result_data

get_fragment_from_url

$fragment = CW$mb->get_fragment_from_url($url); Extract the identifier fragment from a URI. Given a URI this function will return the string that follows the # seperator. (e.g. when passed 'http://musicbrainz.org/mm/mq-1.1#ArtistResult', this function will return 'ArtistResult'

get_ordinal_from_list

$ord = CW$mb->get_ordinal_from_list($listType, CW$URI); Get the ordinal (list position) of an item in a list. This function is normally used to retrieve the track number out of a list of tracks in an album using a list query (usually MBE_AlbumGetTrackList) See also: MBE_AlbumGetTrackList in MusicBrainz::Queries

get_mp3_info

($duration, CW$bitrate, CW$stereo, CW$samplerate) = CW$mb->get_mp3_info($filename); This helper function calculates the crucial pieces of information for a MP3 files. CW$duration = duration of the MP3 in milliseconds, which is handy for passing the length of the track to the TRM generation routines. Beware: The TRM routines are expecting the duratin in SECONDS, so you will need to divide the duration returned by this function by 1000 before you pass it to the TRM routines.

Since this module makes use of Sockets, be sure to call CW$mb->WSAInit() and CW$mb->WSAStop().

For examples on how to use this API please see the test scripts provided and the C client library documentation at http://www.musicbrainz.org/client_howto.html

None by default.

  MB_CDINDEX_ID_LEN
  MB_ID_LEN

  MusicBrainz::Queries
  MusicBrainz::TRM
  http://www.musicbrainz.org/client_howto.html
  http://www.musicbrainz.org/
  perl(1)

Sander van Zoest <svanzoest@cpan.org>

Copyright 2003-2005 by Alexander van Zoest.

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