CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head><script type="text/javascript" src="/_static/js/bundle-playback.js?v=HxkREWBo" charset="utf-8"></script> <script type="text/javascript" src="/_static/js/wombat.js?v=txqj7nKC" charset="utf-8"></script> <script>window.RufflePlayer=window.RufflePlayer||{};window.RufflePlayer.config={"autoplay":"on","unmuteOverlay":"hidden"};</script> <script type="text/javascript" src="/_static/js/ruffle/ruffle.js"></script> <script type="text/javascript"> __wm.init("https://web.archive.org/web"); __wm.wombat("http://musicbrainz.org:80/client_howto.html","20030413091923","https://web.archive.org/","web","/_static/", "1050225563"); </script> <link rel="stylesheet" type="text/css" href="/_static/css/banner-styles.css?v=S1zqJCYt" /> <link rel="stylesheet" type="text/css" href="/_static/css/iconochive.css?v=3PDvdIFv" />  <title>MusicBrainz Client Library HOWTO (MM 2.1)</title> <link rel="stylesheet" type="text/css" href="/web/20030413091923cs_/http://musicbrainz.org/brainz.css"> <link rel="shortcut icon" href="/web/20030413091923im_/http://musicbrainz.org/favicon.ico"> <meta http-equiv="expires" content="1"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head> <body> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td class="LogoBarCell"><img src="/web/20030413091923im_/http://musicbrainz.org/images/header_logo_a.gif" width="614" height="67" alt="" border="0"></td> </tr> </table> <p style="display: none"> <a href="#maincontent">Skip to main content >></a> </p> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td class="NavBarCell"><img src="/web/20030413091923im_/http://musicbrainz.org/images/header_logo_b.gif" width="98" height="21" alt="" border="0"></td> <td class="NavBarCell" align="right" valign="middle"> <span class="topmenu"> <a href="/web/20030413091923/http://musicbrainz.org/search.html">Search</a> | <a href="/web/20030413091923/http://musicbrainz.org/login.html">Login</a> | <a href="/web/20030413091923/http://musicbrainz.org/prefs.html">Prefs</a> | <a href="/web/20030413091923/http://musicbrainz.org/moderate.html">Moderate</a> | <a href="/web/20030413091923/http://musicbrainz.org/download.html">Download</a> | <a href="/web/20030413091923/http://musicbrainz.org/faq.html">FAQ</a> | <a href="/web/20030413091923/http://musicbrainz.org/cgi-bin/wiki/wiki.pl">Wiki</a> </span>  </td> </tr> </table> <table cellpadding="0" cellspacing="0" border="0"> <tr> <td width="141" class="SideBarCell" valign="top">  <table width="141" cellpadding="0" cellspacing="0" border="0"> <tr> <td width="131" height="20" bgcolor="#AAAAAA"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="5" height="1" alt="" border="0"> <span class="section"> Site Menu </span> </td> <td width="10" rowspan="2" bgcolor="#FFFFFF"><img src="/web/20030413091923im_/http://musicbrainz.org/images/sidemenu_end.gif" width="10" height="20" alt="" border="0"></td> </tr> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> </tr> </table>  <table cellpadding="3" cellspacing="0" border="0" width="131px"> <tr> <td> <script type="text/javascript" src="/web/20030413091923js_/http://musicbrainz.org/scripts/sitemenu.js"></script> <div class="sitemenu0"> <div class="menuitem" id="sitemenu1item"> <div class="menurow_c" id="sitemenu1row"> <a class="menunocontrol_c" id="sitemenu1control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/index.html">Home</a></div></div> <div class="menuitem" id="sitemenu2item"> <div class="menurow_c" id="sitemenu2row"> <a class="menucontrol_c" id="sitemenu2control" href="/web/20030413091923/http://musicbrainz.org/introduction.html" onclick="return smt("sitemenu2")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/introduction.html">About</a></div><div class="submenu_c" id="sitemenu2sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu3item"> <div class="menurow_c" id="sitemenu3row"> <a class="menunocontrol_c" id="sitemenu3control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/introduction.html">Introduction</a></div></div> <div class="menuitem" id="sitemenu4item"> <div class="menurow_c" id="sitemenu4row"> <a class="menunocontrol_c" id="sitemenu4control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/history.html">History</a></div></div> <div class="menuitem" id="sitemenu5item"> <div class="menurow_c" id="sitemenu5row"> <a class="menucontrol_c" id="sitemenu5control" href="/web/20030413091923/http://musicbrainz.org/bio.html" onclick="return smt("sitemenu5")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/bio.html">People</a></div><div class="submenu_c" id="sitemenu5sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu6item"> <div class="menurow_c" id="sitemenu6row"> <a class="menunocontrol_c" id="sitemenu6control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderator.html">Moderators</a></div></div> <div class="menuitem" id="sitemenu7item"> <div class="menurow_c" id="sitemenu7row"> <a class="menunocontrol_c" id="sitemenu7control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/topmods.html">Top Mods</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu8item"> <div class="menurow_c" id="sitemenu8row"> <a class="menunocontrol_c" id="sitemenu8control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/future.html">The Future</a></div></div> <div class="menuitem" id="sitemenu9item"> <div class="menurow_c" id="sitemenu9row"> <a class="menucontrol_c" id="sitemenu9control" href="/web/20030413091923/http://musicbrainz.org/sponsors.html" onclick="return smt("sitemenu9")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/sponsors.html">Finance</a></div><div class="submenu_c" id="sitemenu9sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu10item"> <div class="menurow_c" id="sitemenu10row"> <a class="menunocontrol_c" id="sitemenu10control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/sponsors.html">Sponsors</a></div></div> <div class="menuitem" id="sitemenu11item"> <div class="menurow_c" id="sitemenu11row"> <a class="menunocontrol_c" id="sitemenu11control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/finances.html">Finances</a></div></div> <div class="menuitem" id="sitemenu12item"> <div class="menurow_c" id="sitemenu12row"> <a class="menunocontrol_c" id="sitemenu12control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/contribute.html">Contribute</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu13item"> <div class="menurow_c" id="sitemenu13row"> <a class="menunocontrol_c" id="sitemenu13control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/news/licenses.html">Licenses</a></div></div> <div class="menuitem" id="sitemenu14item"> <div class="menurow_c" id="sitemenu14row"> <a class="menunocontrol_c" id="sitemenu14control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/contract.html">Contract</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu16item"> <div class="menurow_c" id="sitemenu16row"> <a class="menucontrol_c" id="sitemenu16control" href="/web/20030413091923/http://musicbrainz.org/news/index.html" onclick="return smt("sitemenu16")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/news/index.html">News</a></div><div class="submenu_c" id="sitemenu16sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu17item"> <div class="menurow_c" id="sitemenu17row"> <a class="menunocontrol_c" id="sitemenu17control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/news/index.html">Latest News</a></div></div> <div class="menuitem" id="sitemenu18item"> <div class="menurow_c" id="sitemenu18row"> <a class="menunocontrol_c" id="sitemenu18control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/press.html">In The Press</a></div></div> <div class="menuitem" id="sitemenu19item"> <div class="menurow_c" id="sitemenu19row"> <a class="menucontrol_c" id="sitemenu19control" href="/web/20030413091923/http://musicbrainz.org/papers/index.html" onclick="return smt("sitemenu19")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/papers/index.html">White Papers</a></div><div class="submenu_c" id="sitemenu19sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu20item"> <div class="menurow_c" id="sitemenu20row"> <a class="menunocontrol_c" id="sitemenu20control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/papers/mb_nonprofit.html">Non-Profit</a></div></div> <div class="menuitem" id="sitemenu21item"> <div class="menurow_c" id="sitemenu21row"> <a class="menunocontrol_c" id="sitemenu21control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/papers/mb_license.html">Licensing</a></div></div> </div> </div> </div> </div> </div> </div> <div class="menuitem" id="sitemenu25item"> <div class="menurow_c" id="sitemenu25row"> <a class="menucontrol_c" id="sitemenu25control" href="/web/20030413091923/http://musicbrainz.org/download.html" onclick="return smt("sitemenu25")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/download.html">Products</a></div><div class="submenu_c" id="sitemenu25sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu26item"> <div class="menurow_c" id="sitemenu26row"> <a class="menunocontrol_c" id="sitemenu26control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/download.html">Download</a></div></div> <div class="menuitem" id="sitemenu27item"> <div class="menurow_c" id="sitemenu27row"> <a class="menucontrol_c" id="sitemenu27control" href="/web/20030413091923/http://musicbrainz.org/tagger/index.html" onclick="return smt("sitemenu27")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/index.html">Tagger</a></div><div class="submenu_c" id="sitemenu27sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu28item"> <div class="menurow_c" id="sitemenu28row"> <a class="menunocontrol_c" id="sitemenu28control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/index.html">Introduction</a></div></div> <div class="menuitem" id="sitemenu29item"> <div class="menurow_c" id="sitemenu29row"> <a class="menunocontrol_c" id="sitemenu29control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/download.html">Download</a></div></div> <div class="menuitem" id="sitemenu30item"> <div class="menurow_c" id="sitemenu30row"> <a class="menunocontrol_c" id="sitemenu30control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/tutorial.html">Tutorial</a></div></div> <div class="menuitem" id="sitemenu31item"> <div class="menurow_c" id="sitemenu31row"> <a class="menunocontrol_c" id="sitemenu31control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/faq.html">FAQ</a></div></div> <div class="menuitem" id="sitemenu32item"> <div class="menurow_c" id="sitemenu32row"> <a class="menunocontrol_c" id="sitemenu32control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/donate.html">Donate</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu36item"> <div class="menurow_c" id="sitemenu36row"> <a class="menunocontrol_c" id="sitemenu36control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/cdlookup/download.html">CD Lookup</a></div></div> <div class="menuitem" id="sitemenu37item"> <div class="menurow_c" id="sitemenu37row"> <a class="menunocontrol_c" id="sitemenu37control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/trmgen/download.html">TRM Generator</a></div></div> <div class="menuitem" id="sitemenu38item"> <div class="menurow_c" id="sitemenu38row"> <a class="menucontrol_c" id="sitemenu38control" href="/web/20030413091923/http://musicbrainz.org/products/client/index.html" onclick="return smt("sitemenu38")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/client/index.html">Client / SDK</a></div><div class="submenu_c" id="sitemenu38sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu39item"> <div class="menurow_c" id="sitemenu39row"> <a class="menunocontrol_c" id="sitemenu39control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/client/index.html">Intro</a></div></div> <div class="menuitem" id="sitemenu40item"> <div class="menurow_c" id="sitemenu40row"> <a class="menunocontrol_c" id="sitemenu40control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/client/download.html">Download</a></div></div> <div class="menuitem" id="sitemenu41item"> <div class="menurow_c" id="sitemenu41row"> <a class="menunocontrol_c" id="sitemenu41control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/client_howto.html">HOWTO</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu42item"> <div class="menurow_c" id="sitemenu42row"> <a class="menucontrol_c" id="sitemenu42control" href="/web/20030413091923/http://musicbrainz.org/products/server/index.html" onclick="return smt("sitemenu42")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/server/index.html">Server / Data</a></div><div class="submenu_c" id="sitemenu42sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu43item"> <div class="menurow_c" id="sitemenu43row"> <a class="menunocontrol_c" id="sitemenu43control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/server/index.html">Intro</a></div></div> <div class="menuitem" id="sitemenu44item"> <div class="menurow_c" id="sitemenu44row"> <a class="menunocontrol_c" id="sitemenu44control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/server/download.html">Download</a></div></div> <div class="menuitem" id="sitemenu45item"> <div class="menurow_c" id="sitemenu45row"> <a class="menunocontrol_c" id="sitemenu45control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/db_structure.html">DB Structure</a></div></div> <div class="menuitem" id="sitemenu46item"> <div class="menurow_c" id="sitemenu46row"> <a class="menunocontrol_c" id="sitemenu46control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/products/server/import_howto.html">Import HOWTO</a></div></div> </div> </div> </div> </div> </div> </div> <div class="menuitem" id="sitemenu47item"> <div class="menurow_c" id="sitemenu47row"> <a class="menucontrol_c" id="sitemenu47control" href="/web/20030413091923/http://musicbrainz.org/search.html" onclick="return smt("sitemenu47")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/search.html">Search/Browse</a></div><div class="submenu_c" id="sitemenu47sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu48item"> <div class="menurow_c" id="sitemenu48row"> <a class="menunocontrol_c" id="sitemenu48control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/search.html">Search</a></div></div> <div class="menuitem" id="sitemenu49item"> <div class="menurow_c" id="sitemenu49row"> <a class="menunocontrol_c" id="sitemenu49control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/browseartists.html">Browse Artists</a></div></div> <div class="menuitem" id="sitemenu50item"> <div class="menurow_c" id="sitemenu50row"> <a class="menunocontrol_c" id="sitemenu50control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/browsevarious.html">Browse Albums</a></div></div> <div class="menuitem" id="sitemenu51item"> <div class="menurow_c" id="sitemenu51row"> <a class="menunocontrol_c" id="sitemenu51control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/engine.html">Search Links</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu53item"> <div class="menurow_c" id="sitemenu53row"> <a class="menucontrol_c" id="sitemenu53control" href="/web/20030413091923/http://musicbrainz.org/mod_intro.html" onclick="return smt("sitemenu53")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/mod_intro.html">Edit the Data</a></div><div class="submenu_c" id="sitemenu53sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu54item"> <div class="menurow_c" id="sitemenu54row"> <a class="menunocontrol_c" id="sitemenu54control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/mod_intro.html">About</a></div></div> <div class="menuitem" id="sitemenu55item"> <div class="menurow_c" id="sitemenu55row"> <a class="menucontrol_c" id="sitemenu55control" href="/web/20030413091923/http://musicbrainz.org/moderation/suggestions.html" onclick="return smt("sitemenu55")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderation/suggestions.html">Suggestions</a></div><div class="submenu_c" id="sitemenu55sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu56item"> <div class="menurow_c" id="sitemenu56row"> <a class="menunocontrol_c" id="sitemenu56control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/bad_entries.html">Odd Characters</a></div></div> <div class="menuitem" id="sitemenu57item"> <div class="menurow_c" id="sitemenu57row"> <a class="menunocontrol_c" id="sitemenu57control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/caps.html">Uppercase</a></div></div> <div class="menuitem" id="sitemenu58item"> <div class="menurow_c" id="sitemenu58row"> <a class="menunocontrol_c" id="sitemenu58control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/caps2.html">Lowercase</a></div></div> <div class="menuitem" id="sitemenu59item"> <div class="menurow_c" id="sitemenu59row"> <a class="menunocontrol_c" id="sitemenu59control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/unknown.html">'Unknown'</a></div></div> <div class="menuitem" id="sitemenu60item"> <div class="menurow_c" id="sitemenu60row"> <a class="menunocontrol_c" id="sitemenu60control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/wrong_charset.html">Wrong Charset</a></div></div> <div class="menuitem" id="sitemenu61item"> <div class="menurow_c" id="sitemenu61row"> <a class="menunocontrol_c" id="sitemenu61control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/DuplicateArtists.html">Duplicate Artists</a></div></div> <div class="menuitem" id="sitemenu62item"> <div class="menurow_c" id="sitemenu62row"> <a class="menunocontrol_c" id="sitemenu62control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/AlbumsToConvert.html">MAC Albums</a></div></div> <div class="menuitem" id="sitemenu63item"> <div class="menurow_c" id="sitemenu63row"> <a class="menunocontrol_c" id="sitemenu63control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/TRMsWithManyTracks.html">TRM Collisions</a></div></div> <div class="menuitem" id="sitemenu64item"> <div class="menurow_c" id="sitemenu64row"> <a class="menunocontrol_c" id="sitemenu64control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/TracksWithManyTRMs.html">Multiple TRMs</a></div></div> <div class="menuitem" id="sitemenu65item"> <div class="menurow_c" id="sitemenu65row"> <a class="menunocontrol_c" id="sitemenu65control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/reports/TracksNamedWithSequence.html">Track Numbers</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu66item"> <div class="menurow_c" id="sitemenu66row"> <a class="menunocontrol_c" id="sitemenu66control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/mod_faq.html">FAQ</a></div></div> <div class="menuitem" id="sitemenu67item"> <div class="menurow_c" id="sitemenu67row"> <a class="menunocontrol_c" id="sitemenu67control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/style.html">Style</a></div></div> <div class="menuitem" id="sitemenu68item"> <div class="menurow_c" id="sitemenu68row"> <a class="menucontrol_c" id="sitemenu68control" href="/web/20030413091923/http://musicbrainz.org/moderate.html" onclick="return smt("sitemenu68")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderate.html">Moderations</a></div><div class="submenu_c" id="sitemenu68sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu69item"> <div class="menurow_c" id="sitemenu69row"> <a class="menunocontrol_c" id="sitemenu69control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderate.html?type=1">New</a></div></div> <div class="menuitem" id="sitemenu70item"> <div class="menurow_c" id="sitemenu70row"> <a class="menunocontrol_c" id="sitemenu70control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderate.html?type=5">New (FreeDB)</a></div></div> <div class="menuitem" id="sitemenu71item"> <div class="menurow_c" id="sitemenu71row"> <a class="menunocontrol_c" id="sitemenu71control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderate.html?type=3">My Mods</a></div></div> <div class="menuitem" id="sitemenu72item"> <div class="menurow_c" id="sitemenu72row"> <a class="menunocontrol_c" id="sitemenu72control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/moderate.html?type=2">My Votes</a></div></div> <div class="menuitem" id="sitemenu73item"> <div class="menurow_c" id="sitemenu73row"> <a class="menunocontrol_c" id="sitemenu73control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/jumpmod.html">Jump to ID</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu75item"> <div class="menurow_c" id="sitemenu75row"> <a class="menucontrol_c" id="sitemenu75control" href="/web/20030413091923/http://musicbrainz.org/login.html" onclick="return smt("sitemenu75")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/login.html">Log In</a></div><div class="submenu_c" id="sitemenu75sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu76item"> <div class="menurow_c" id="sitemenu76row"> <a class="menucontrol_c" id="sitemenu76control" href="/web/20030413091923/http://musicbrainz.org/login.html" onclick="return smt("sitemenu76")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/login.html">Existing User</a></div><div class="submenu_c" id="sitemenu76sub"> <div class="sitemenu3"> <div class="menuitem" id="sitemenu77item"> <div class="menurow_c" id="sitemenu77row"> <a class="menunocontrol_c" id="sitemenu77control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/prefs.html">Preferences</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu78item"> <div class="menurow_c" id="sitemenu78row"> <a class="menunocontrol_c" id="sitemenu78control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/newlogin.html">New User</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu81item"> <div class="menurow_c" id="sitemenu81row"> <a class="menunocontrol_c" id="sitemenu81control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/addartist.html">Add Artist</a></div></div> <div class="menuitem" id="sitemenu82item"> <div class="menurow_c" id="sitemenu82row"> <a class="menunocontrol_c" id="sitemenu82control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/addalbum.html?artistid=0">Add Album</a></div></div> <div class="menuitem" id="sitemenu91item"> <div class="menurow_c" id="sitemenu91row"> <a class="menunocontrol_c" id="sitemenu91control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/addalbum.html?artistid=1">Add Album (VA)</a></div></div> <div class="menuitem" id="sitemenu94item"> <div class="menurow_c" id="sitemenu94row"> <a class="menunocontrol_c" id="sitemenu94control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/freedb/freedb.html">FreeDB Import</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu127item"> <div class="menurow_c" id="sitemenu127row"> <a class="menucontrol_c" id="sitemenu127control" href="/web/20030413091923/http://musicbrainz.org/contribute.html" onclick="return smt("sitemenu127")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/contribute.html">Help Us</a></div><div class="submenu_c" id="sitemenu127sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu128item"> <div class="menurow_c" id="sitemenu128row"> <a class="menunocontrol_c" id="sitemenu128control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/contribute.html">Contribute</a></div></div> <div class="menuitem" id="sitemenu129item"> <div class="menurow_c" id="sitemenu129row"> <a class="menunocontrol_c" id="sitemenu129control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/index.html">Tag</a></div></div> <div class="menuitem" id="sitemenu131item"> <div class="menurow_c" id="sitemenu131row"> <a class="menucontrol_c" id="sitemenu131control" href="/web/20030413091923/http://musicbrainz.org/development/index.html" onclick="return smt("sitemenu131")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/development/index.html">Development</a></div><div class="submenu_c" id="sitemenu131sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu132item"> <div class="menurow_c" id="sitemenu132row"> <a class="menunocontrol_c" id="sitemenu132control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/development/index.html">Introduction</a></div></div> <div class="menuitem" id="sitemenu133item"> <div class="menurow_c" id="sitemenu133row"> <a class="menunocontrol_c" id="sitemenu133control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/status.html">Project Status</a></div></div> <div class="menuitem" id="sitemenu134item"> <div class="menurow_c" id="sitemenu134row"> <a class="menunocontrol_c" id="sitemenu134control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/development/cvs.html">CVS Access</a></div></div> <div class="menuitem" id="sitemenu135item"> <div class="menurow_c" id="sitemenu135row"> <a class="menucontrol_c" id="sitemenu135control" href="/web/20030413091923/http://musicbrainz.org/todo.html" onclick="return smt("sitemenu135")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/todo.html">TODO</a></div><div class="submenu_c" id="sitemenu135sub"> <div class="sitemenu3"> <div class="menuitem" id="sitemenu136item"> <div class="menurow_c" id="sitemenu136row"> <a class="menunocontrol_c" id="sitemenu136control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/todo.html">TODO</a></div></div> <div class="menuitem" id="sitemenu137item"> <div class="menurow_c" id="sitemenu137row"> <a class="menunocontrol_c" id="sitemenu137control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/development/TODO.rob.html">Rob's TODO</a></div></div> <div class="menuitem" id="sitemenu138item"> <div class="menurow_c" id="sitemenu138row"> <a class="menunocontrol_c" id="sitemenu138control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/johan_todo.html">Johan's TODO</a></div></div> <div class="menuitem" id="sitemenu139item"> <div class="menurow_c" id="sitemenu139row"> <a class="menunocontrol_c" id="sitemenu139control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/development/TODO.dave.html">Dave's TODO</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu140item"> <div class="menurow_c" id="sitemenu140row"> <a class="menucontrol_c" id="sitemenu140control" href="/web/20030413091923/http://musicbrainz.org/MM/index.html" onclick="return smt("sitemenu140")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/MM/index.html">Metadata 2.1</a></div><div class="submenu_c" id="sitemenu140sub"> <div class="sitemenu3"> <div class="menuitem" id="sitemenu141item"> <div class="menurow_c" id="sitemenu141row"> <a class="menunocontrol_c" id="sitemenu141control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/MM/index.html">Introduction</a></div></div> <div class="menuitem" id="sitemenu142item"> <div class="menurow_c" id="sitemenu142row"> <a class="menunocontrol_c" id="sitemenu142control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/MM/mm_examples.html">mm</a></div></div> <div class="menuitem" id="sitemenu143item"> <div class="menurow_c" id="sitemenu143row"> <a class="menunocontrol_c" id="sitemenu143control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/MM/mq_examples.html">mq</a></div></div> </div> </div> </div> </div> </div> </div> </div> </div> </div> <div class="menuitem" id="sitemenu144item"> <div class="menurow_o" id="sitemenu144row"> <a class="menucontrol_o" id="sitemenu144control" href="/web/20030413091923/http://musicbrainz.org/information.html" onclick="return smt("sitemenu144")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/information.html">Support</a></div><div class="submenu_o" id="sitemenu144sub"> <div class="sitemenu1"> <div class="menuitem" id="sitemenu145item"> <div class="menurow_c" id="sitemenu145row"> <a class="menunocontrol_c" id="sitemenu145control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/faq.html">FAQ</a></div></div> <div class="menuitem" id="sitemenu146item"> <div class="menurow_o" id="sitemenu146row"> <a class="menucontrol_o" id="sitemenu146control" href="/web/20030413091923/http://musicbrainz.org/documentation.html" onclick="return smt("sitemenu146")"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/documentation.html">Docs</a></div><div class="submenu_o" id="sitemenu146sub"> <div class="sitemenu2"> <div class="menuitem" id="sitemenu147item"> <div class="menurow_c" id="sitemenu147row"> <a class="menunocontrol_c" id="sitemenu147control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/documentation.html">Introduction</a></div></div> <div class="menuitem" id="sitemenu148item"> <div class="menurow_c" id="sitemenu148row"> <a class="menunocontrol_c" id="sitemenu148control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/how.html">How</a></div></div> <div class="menuitem" id="sitemenu149item"> <div class="menurow_o" id="sitemenu149row"> <a class="menunocontrol_o" id="sitemenu149control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/client_howto.html">Client HOWTO</a></div></div> <div class="menuitem" id="sitemenu150item"> <div class="menurow_c" id="sitemenu150row"> <a class="menunocontrol_c" id="sitemenu150control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/">Client Docs</a></div></div> <div class="menuitem" id="sitemenu151item"> <div class="menurow_c" id="sitemenu151row"> <a class="menunocontrol_c" id="sitemenu151control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/cd_submission.html">CD Submission</a></div></div> <div class="menuitem" id="sitemenu152item"> <div class="menurow_c" id="sitemenu152row"> <a class="menunocontrol_c" id="sitemenu152control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/tagger/id-intro.html">About MB IDs</a></div></div> <div class="menuitem" id="sitemenu153item"> <div class="menurow_c" id="sitemenu153row"> <a class="menunocontrol_c" id="sitemenu153control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/disc.html">About Disc IDs</a></div></div> <div class="menuitem" id="sitemenu154item"> <div class="menurow_c" id="sitemenu154row"> <a class="menunocontrol_c" id="sitemenu154control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/docs/specs/metadata_tags.html">ID3 Tags</a></div></div> <div class="menuitem" id="sitemenu155item"> <div class="menurow_c" id="sitemenu155row"> <a class="menunocontrol_c" id="sitemenu155control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/db_structure.html">Database</a></div></div> <div class="menuitem" id="sitemenu156item"> <div class="menurow_c" id="sitemenu156row"> <a class="menunocontrol_c" id="sitemenu156control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/stats.html">Stats</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu157item"> <div class="menurow_c" id="sitemenu157row"> <a class="menunocontrol_c" id="sitemenu157control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/support/contact.html">Contact Us</a></div></div> <div class="menuitem" id="sitemenu158item"> <div class="menurow_c" id="sitemenu158row"> <a class="menunocontrol_c" id="sitemenu158control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/list.html">Mailing Lists</a></div></div> <div class="menuitem" id="sitemenu159item"> <div class="menurow_c" id="sitemenu159row"> <a class="menunocontrol_c" id="sitemenu159control"> </a><a class="menulink" href="https://web.archive.org/web/20030413091923/http://sourceforge.net/tracker/?func=add&group_id=19506&atid=119506">Report a Bug</a></div></div> </div> </div> </div> <div class="menuitem" id="sitemenu160item"> <div class="menurow_c" id="sitemenu160row"> <a class="menunocontrol_c" id="sitemenu160control"> </a><a class="menulink" href="/web/20030413091923/http://musicbrainz.org/cgi-bin/wiki/wiki.pl">Wiki</a></div></div> </div> </td> </tr> </table> <table width="141" cellpadding="0" cellspacing="0" border="0"> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> <td width="10" rowspan="3" bgcolor="#FFFFFF"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"><br><img src="/web/20030413091923im_/http://musicbrainz.org/images/sidemenu_end.gif" width="10" height="20" alt="" border="0"></td> </tr> <tr> <td width="131" height="20" bgcolor="#AAAAAA"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="5" height="1" alt="" border="0"> <span class="section"> Top Moderators </span> </td> </tr> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> </tr> </table> <div class="SideBarContentArea"> <div class="SideBarContentArea2"> <table cellpadding="2" cellspacing="0" border="0" class="statsb" width="110px"> <tr> <td align="right" valign="top" width="50%" class="statsb"> jmurphy </td> <td align="left" valign="top" width="50%" class="stats"> 26274 </td> </tr><tr> <td align="right" valign="top" width="50%" class="statsb"> schickel </td> <td align="left" valign="top" width="50%" class="stats"> 14705 </td> </tr><tr> <td align="right" valign="top" width="50%" class="statsb"> pLynx </td> <td align="left" valign="top" width="50%" class="stats"> 12807 </td> </tr><tr> <td align="right" valign="top" width="50%" class="statsb"> Go186K </td> <td align="left" valign="top" width="50%" class="stats"> 11690 </td> </tr><tr> <td align="right" valign="top" width="50%" class="statsb"> neil </td> <td align="left" valign="top" width="50%" class="stats"> 9845 </td> </tr> </table> <div class="SideBarMoreLink"> <span class="sidemenusmall"> <a href="/web/20030413091923/http://musicbrainz.org/topmods.html">more >></a> </span> </div>  </div> </div> <table width="141" cellpadding="0" cellspacing="0" border="0"> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> <td width="10" rowspan="3" bgcolor="#FFFFFF"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"><br><img src="/web/20030413091923im_/http://musicbrainz.org/images/sidemenu_end.gif" width="10" height="20" alt="" border="0"></td> </tr> <tr> <td width="131" height="20" bgcolor="#AAAAAA"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="5" height="1" alt="" border="0"> <span class="section"> Server Stats </span> </td> </tr> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> </tr> </table> <div class="SideBarContentArea"> <div class="SideBarContentArea2"> <table cellpadding="2" cellspacing="0" border="0" class="statsb" width="110px"> <col style="width: 50%"> <col style="width: 50%"> <tr><td valign="top" align="right" class="statsb">Artists</td><td valign="top" class="stats">52527</td></tr><tr><td valign="top" align="right" class="statsb">Albums</td><td valign="top" class="stats">71733</td></tr><tr><td valign="top" align="right" class="statsb">Tracks</td><td valign="top" class="stats">887880</td></tr><tr><td valign="top" align="right" class="statsb">Discids</td><td valign="top" class="stats">51172</td></tr><tr><td valign="top" align="right" class="statsb">TRM Ids</td><td valign="top" class="stats">420690</td></tr><tr><td valign="top" align="right" class="statsb">Mods</td><td valign="top" class="stats">259293</td></tr><tr><td valign="top" align="right" class="statsb">Users</td><td valign="top" class="stats">11026</td></tr> </table> <div class="SideBarMoreLink"> <span class="sidemenusmall"> <a href="/web/20030413091923/http://musicbrainz.org/stats.html">more >></a> </span> </div>  </div> </div> <table width="141" cellpadding="0" cellspacing="0" border="0"> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> <td width="10" rowspan="3" bgcolor="#FFFFFF"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"><br><img src="/web/20030413091923im_/http://musicbrainz.org/images/sidemenu_end.gif" width="10" height="20" alt="" border="0"></td> </tr> <tr> <td width="131" height="20" bgcolor="#AAAAAA"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="5" height="1" alt="" border="0"> <span class="section"> Sponsors </span> </td> </tr> <tr> <td width="131" height="1" bgcolor="#000000"><img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="1" height="1" alt="" border="0"></td> </tr> </table> <div class="SideBarContentArea"> <div class="SideBarContentArea2"> <div style="text-align: center; margin: 1em 0"> <a href="https://web.archive.org/web/20030413091923/http://www.relatable.com/"><img src="/web/20030413091923im_/http://musicbrainz.org/images/relatable.gif" border="0" alt="Relatable" title="Relatable"></a> </div> <div style="text-align: center; margin: 1em 0"> Hosting by: <a href="https://web.archive.org/web/20030413091923/http://www.communitycolo.net/"><img src="/web/20030413091923im_/http://musicbrainz.org/images/cccp.png" border="0" alt="CCCP" title="California Community Colocation Project"></a> </div> <div style="text-align: center; margin: 1em 0"> <form action="https://web.archive.org/web/20030413091923/https://www.paypal.com/cgi-bin/webscr" method="post"> <input type="hidden" name="cmd" value="_xclick"> <input type="hidden" name="business" value="donations@musicbrainz.org"> <input type="hidden" name="item_name" value="Donation to MusicBrainz"> <input type="image" src="/web/20030413091923im_/http://musicbrainz.org/images/paypal.gif" style="border: 0" name="submit" alt="Donate to MusicBrainz!"> </form> </div> <div class="SideBarMoreLink"> <span class="sidemenusmall"> <a href="/web/20030413091923/http://musicbrainz.org/sponsors.html">more >></a> </span> </div>  </div> </div> </td> <td bgcolor="FFFFFF" align="left" valign="top"> <table cellpadding="15" cellspacing="0" border="0" width="100%"> <tr> <td align="left" valign="top" class="body" width="100%"> <img src="/web/20030413091923im_/http://musicbrainz.org/images/pixel.gif" width="435" height="1" alt=""> <a id="maincontent"></a> <h1>MusicBrainz Client Library HOWTO (MM 2.1)</h1> <h2>Introduction</h2> <p> The <a href="/web/20030413091923/http://musicbrainz.org/download.html">MusicBrainz client library</a> serves as a tool to allow developers to integrate MusicBrainz searches and metadata exchange functionality into their applications. <p> The client library includes the following features: <ul> <li>Lookup Audio CD metadata using CD Index Discids <li>Calculate <a href="https://web.archive.org/web/20030413091923/http://www.relatable.com/">Relatable TRM</a> acoustic fingerprints <li>Search for artist/album/track titles <li>Lookup metadata by name, TRM ids or MusicBrainz Ids </ul> <p> The client library source distribution comes with the following example programs: <ul> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#cdlookup">cdlookup.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#findartist">findartist.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#findtrack">findtrack.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#getartist">getartist.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#getalbum">getalbum.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#gettrack">gettrack.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#gettrm">gettrm.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#submittrm">submittrm.c</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/examples.html#tagger">tagger.c</a> </ul> <p> If you prefer to read code than documentation in order to learn this client library, please check out these code samples. <p> The client library is released under the <a href="https://web.archive.org/web/20030413091923/http://www.gnu.org/copyleft/lesser.html">LGPL</a>, which means that even developers of closed source applications can use the client library, without having to open source their own code. <h2>Function & Query Reference</h2> <p> For details on the individual functions and queries mentioned in this HOWTO, please refer to the following pages: <ul> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/index.html">Online Reference</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html">Query Reference</a> <li><a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/mb_c_h.html">Function Reference</a> </ul> <h2>Overview</h2> <p> MusicBrainz provides a powerful web service API that uses <a href="https://web.archive.org/web/20030413091923/http://www.w3.org/RDF">RDF</a> for expressing queries and query responses. RDF is the Resource Description Framework as specified by World Wide Web Consortium, and it can be used for formally expressing metadata using an XML syntax. <p> RDF is powerful, but also complex, and thus the client library attempts to shield the end user from having to understand RDF. But in order to understand the Query/Select/Get interface that client library has, a brief overview of the data query process is in order. <p> To query the MusicBrainz server, the user must pass an RDF query to the server. You may decide to create your own queries if you are comfortable with RDF, or you can use the predefined queries in the client library. The predefined queries will require a number of arguments that will get substituted into the query before the query is sent to the server. <p> The mb_Query (MusicBrainz::Query in C++) function takes a query string and a number of other arguments that get substituted into the query. The queries are defined in queries.h, and you do not need to really know what the actual query strings mean -- all you need to do is to select the right query for your purpose and then provide the query function with the right arguments and the client library will do the rest. <p> Once the query function returns it will have retrieved the RDF response from the server. The returned RDF will get parsed and then the user can use the Select/Get/Data functions to extract information from the query result. <p> The RDF response will typically return a whole bunch of information, and you may only be interested in some of that information. In order to make the data extraction process reasonably easy, the user will need to Select a context (think of it as a subset) of the RDF response. You can then extract pieces of data from that context. <p> For example, if you look up a CD using the client library, you will get back a list of albums. Each MusicBrainz query will return a list of one kind or another, even if it only contains one item. So, you will need to select an album from the list, and in this case it will be the first album in the list. You'll do that with a call to Select. After calling Select, you can call the GetResultData or GetResultInt functions to extract string or integer values from the returned data. A code fragment to do this in C would look like: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> // Check to see how many items were returned from the server if (mb_GetResultInt(o, MBE_GetNumAlbums) < 1) { printf("This CD was not found.\n"); return 0; } // Select the first album mb_Select1(o, MBS_SelectAlbum, 1); // Get the number of tracks numTracks = mb_GetResultInt(o, MBE_AlbumGetNumTracks); printf(" NumTracks: %d\n", numTracks); </pre> </td> </tr> </table> </center> <p> Finally, a couple of other tidbits for the overview: The client library uses standard HTTP GET and POST queries to accomplish the communication with the server. Thus, the client library has support for using proxies to get across firewalls, and no special firewall arrangements have to be made. <p> The data that is extracted from the RDF response can either be in standard ISO-8859-1 format (the character encoding that Western European and US computers use) or in the UTF-8 format. However, at this point in time, the MusicBrainz server does not actually support UTF-8 data (we need to find an opensource database that _completely_ supports UTF-8 first). The server only supports ISO 8859-1 right now. <p> The MusicBrainz client library can also be used to create Relatable TRM acoustic fingerprints for audio files. In order to generate a TRM id, you will need to feed the client library the first 30 seconds worth of PCM data from your audio stream. Once you've fed it the 30 seconds of data, the client library will send the acoustic fingerprint information to the Relatable server and the server will assign and return a TRM ID to the given song. You can then use the TRM id to look up metadata for the song, and fill out the ID3 tags (or equivalent) automatically! <h2>Select & Get Documentation</h2> <p> The most non-obvious issues in dealing with the client library is having to extract data from the result that was returned by the server. If you are RDF savvy and would like deal with the result RDF itself, then call the mb_GetResultRDF function. Most people won't be interested in doing that, so here is a detailed explanation for what you need to do. <p> The server will return an artist list, album list, track list a trmid list or a lyrics list. Let's examine the artist list first, since it ends up as a good example for the rest of the select/get stuff. This piece of ASCII art shows the different objects returned as part of an artist list query: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> Graphical representation of an Artistlist query: Depth: +-------------+ [top level] | Artist List | [1] +-------------+ | | References to the Artists | | [2] | | +--------+ +--------+ MBS_SelectArtist 1 ---------------> | Artist | | Artist | [3] +--------+ +--------+ | | References to the Albums | | [4] | | +-------+ +-------+ MBS_SelectAlbum 1 ---------> | Album | | Album | [5] +-------+ +-------+ | | References to the Tracks | | [6] | | +-------+ +-------+ MBS_SelectTrack 1 ---> | Track | | Track | [7] +-------+ +-------+ </pre> </td> </tr> </table> </center> <p> If your artistlist query is successful then you can call do the following to find out the number of artists returned by the query: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> numArtists = mb_GetResultInt(o, MBE_GetNumArtists); </pre> </td> </tr> </table> </center> <p> Please note that the MBE_GetNumArtists is a MusicBrainzExtract (MBE_) query, which queries the result set, not the MusicBrainz server. All server queries that can be passed to mb_Query are MusicBrainzQueries that start with MBQ_. Then you also have MusicBrainz Select queries (MBS_) which are used to select a subset of a result from a the server. <p> Any of the mb_GetResult functions work on the current extract query context. Right after you call mb_Query the current context will be set to the top level query context, where you can get the number of items returned (as shown above) or select one of the returned items as a new context. <p> So, in our example, after you've determined the number of artists that were returned, you can select one of the artists using a the mb_Selection function. To select the first artist returned do this: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> mb_Select1(o, MBS_SelectArtist, 1); </pre> </td> </tr> </table> </center> <p> The third argument to the mb_Select1 function is an ordinal argument, that indicates which artist you'd like to select. Ordinals are 1 based, so to select the first artist, use 1, not 0. Select queries that select something out of a list require an ordinal argument, as shown above. Some select queries do not require ordinals, in which case you can call mb_Select (as opposed to mb_Select1). <p> Select queries can be arbitrarily complex, and sometimes you may need to pass a list of ordinals to make selections out of multiple lists at the same time. In that case call mb_SelectWithArgs and specify a list of ordinal arguments. <p> Let's go back to the example. After you select the context of the first artist, you can then use the MBE_ArtistXXXXX functions to extract information from the currently selected artist. To get the name of the artist, do this: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> mb_GetResultData(o, MBE_ArtistGetArtistName, data, 256); </pre> </td> </tr> </table> </center> <p> Which will extract the artist name and save it into data. The last argument specifies the number of bytes allocated in data. Check the query reference for the queries that you can do on a given artist. <p> A query that returns an artist list will also return the list of albums for that that given artist. So, from the Artist context you can find out how many albums have been returned for that artist: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> numAlbums = mb_GetResultInt(o, MBE_GetNumAlbums); </pre> </td> </tr> </table> </center> <p> To select the first album do this: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> mb_Select1(o, MBS_SelectAlbum, 1); </pre> </td> </tr> </table> </center> <p> Now you can use the MBE_AlbumXXXX functions to retrieve information about the selected album. Now, lets assume that you've extracted the needed information from the first album and you want to select the second album. It would make sense to just be able to repeat the above call with 2 as the ordinal. However, that won't work!!! In order to select an album you need to be in the artist context, which contains the list of albums for the given artist. The proper way to select the second album is to do: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> mb_Select(o, MBS_Back); mb_Select1(o, MBS_SelectAlbum, 2); </pre> </td> </tr> </table> </center> <p> The first select will back up the context to the previous context (which is the artist context) and then the second call selects the second album. You can now query information for the second album. There is one more special query: <center> <table width="95%" cellspacing="0" cellpadding="6" border="0" bgcolor="#efefff"> <tr> <td> <pre style="font-family: monospace"> mb_Select(o, MBS_Rewind); </pre> </td> </tr> </table> </center> <p> This will rewind the context to the top level context, just as it was right after the mb_Query function. This should give you a good idea on how to extract data from an artist list. <p> Using the other queries albumlist, tracklist and trmidlist, works much in the same way that the artistlist works. For the other queries an album will still contain a tracklist, and tracks will point to artists. For some more in-depth examples, check out the findartist.c and gettrack.c examples in the examples directory of the MusicBrainz client distribution. <h2>Query Depth</h2> One more thing that needs explaining is the depth of a query. In the graph above, there is a column that shows depth. The depth of the query determines the amount of data returned by the server. If you set the depth to 1, the server will only return the list of IDs to artists, but not the artists themselves. A depth of 2 will return the list, and all of the artists, but not the list of ids to the next albums. A depth of 3 will return all of the above and the albums that may be referenced in the artist. When you write code to access the server you should carefully select the depth of your query to make sure that you only retrieve as much information as you really need. <h2>MBIDs and mb_GetIDFromURL function</h2> All of the MBE_GetXXXXId functions will return web URLs that can be used to retrieve the RDF that describes the object in question. In order to extract the ID from the URL, use the mb_GetIDFromURL function. <h2>Writing a metadata tagger that uses MusicBrainz</h2> If you are interested in writing a metadata tagger (an application that edits the metadata in music files using MusicBrainz), you should use the <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a72">MBQ_TrackInfoFromTRMId</a> and <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a84">MBQ_FileInfoLookup</a> functions. <p> Your tagging application should carry out the following steps: <ol> <li>Generate a TRM Id for the file you are looking up. (see below) <li>Read the metadata from the file (e.g. ID3 or Vorbiscomment) <li>Use <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a72">MBQ_TrackInfoFromTRMId</a> to see if that TRM id is known to MusicBrainz. If so, all the relevant metadata will be returned by the server and that metadata can be written to the file in question. Note: This function may return more than one track, and the tagger application must let the user choose which is the correct track. <li>If the track is not known to MusicBrainz, the tagger must use the <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a84">MBQ_FileInfoLookup</a> function to attempt to match the file with its appropriate metadata in the server. <li>Once the tagger has made a match between a TRM id and a track on the server, the tagger should keep a list of TRM Id, Track Id pairs for submission to the server with <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a83">MBQ_SubmitTrackTRMId</a>. These pairs should be batched for a one-time submission to the server in order keep down the number of requests made to the server. </ol> The <a href="/web/20030413091923/http://musicbrainz.org/docs/mb_client/queries_h.html#a84">MBQ_FileInfoLookup</a> function should be explained in a bit more detail. In order to use this function, you need to provide the server with all the relevant metadata for the given track. This includes TRM Id, artist name, album name, track name, track number, duration (in milliseconds), file name, artist id, album id, and track id. <p> The idea is to have the server match as much information as possible from the provided artist, album and track names. The server will do its best to match an artist. If more than one matching artist is found, a list of artists is returned. The tagger must then present the list of artists to the user and have the user choose an artist. The artist id for the chosen artist should then be passed to the server in the artist id field. If an artist id is provided, the artist name is no longer used and can be omitted. <p> The same process applies to an album. However, if an artist was matched and a album name and track name was provided, the server will attempt to find the right track in the database, based on album name, track name, track number and duration. Possible matches will be returned to the tagger. The tagger must then provide these choices to the user and have the user choose the correct track. <p> Thats it! Once the user has chosen the correct track, the tagger should have everything it needs to write the metadata to the file in question. <p><b>Note:</b> Before you get starting writing a tagger, take a look at the client library (2.0.0-pre4 and later) tagger.c example. This example does a large chunk of the tagger work for you. You should be able to grab large chunks of that code and use it in our application (provided your app is LGPL/GPL compatible). <h2>Generating TRM Ids</h2> To create a TRM id, you should use the <a href="/web/20030413091923/http://musicbrainz.org/download.html">TRM application/library</a>. Why write new code if you can use a library? <p> And if for some reason you do not want to use the library, go read the code to figure out how to create TRM ids. :-) <div style="margin-top: 1em"> </div> </td> </tr> </table> </td> </tr> </table> <div id="FooterBar"> <table width="100%" cellpadding="2" cellspacing="0" border="0"> <tr> <td width="10%">   </td> <td width="15%"> <a href="https://web.archive.org/web/20030413091923/http://www.creativecommons.org/">Creative Commons</a> </td> <td width="15%"> <a href="https://web.archive.org/web/20030413091923/http://www.eff.org/"><abbr title="Electronic Frontier Foundation">EFF</abbr></a> </td> <td width="15%"> <a href="https://web.archive.org/web/20030413091923/http://www.gnu.org/copyleft/gpl.html"><abbr title="General Public License">GPL</abbr></a> </td> <td width="15%"> <a href="https://web.archive.org/web/20030413091923/http://www.gnu.org/copyleft/lesser.html"><abbr title="Lesser General Public License">LGPL</abbr></a> </td> <td width="15%"> <a href="https://web.archive.org/web/20030413091923/http://www.freshmeat.net/">Freshmeat</a> </td> <td width="10%">   </td> </tr> </table> </div> <div id="CreditsBar"> <table width="100%" cellpadding="2" cellspacing="0" border="0"> <tr> <td width="30%" style="text-align: left"> <a href="/web/20030413091923/http://musicbrainz.org/support/contact.html">contact details</a> </td> <td width="40%" style="text-align: center"> original design|<a href="https://web.archive.org/web/20030413091923/http://vacubomb.com/">vacubomb.com</a> </td> <td width="30%" style="text-align: right"> server version: 2003-04-05 </td> </tr> </table> </div> </body> </html>