WebServ...icBrainz(3)

💖 WebService::MusicBrainz 💖

okay bestie, gather round, because this is the Perl module that lets you go absolutely feral in the musicbrainz.org database. it's a section 3 manual page, user contributed Perl documentation, and it's giving extremely useful. no cap. 🎀

---

✨ SYNOPSIS ✨

use WebService::MusicBrainz;

my $mb = WebService::MusicBrainz->new();

my $result = $mb->search($resource => { $search_key => 'search value' });
my $result = $mb->search($resource => { $search_key => 'search value', fmt => 'json' });  # fmt => 'json' is default

my $result_dom = $mb->search($resource => { $search_key => 'search value', fmt => 'xml' });

like, that's it. that's the whole vibe. 🦋

---

🌸 DESCRIPTION 🌸

it's an API to search the musicbrainz.org database. periodt. 💅

---

👑 VERSION 👑

⚠️ bestie listen. Version 1.0 and future releases are not backward compatible with pre-1.0 releases. this is a complete re-write using version 2.0 of the MusicBrainz API and Mojolicious. so if you're on an old one… yeah. it's not gonna work the same. iykyk. 💀

---

🧚 METHODS 🧚

new

my $mb = WebService::MusicBrainz->new();

just make the thing. iconic. ✨

search

my $result_list = $mb->search($resource => { param1 => 'value1' });

my $result = $mb->search($resource => { mbid => 'mbid' });

my $result_more = $mb->search($resource => { mbid => 'mbid', inc => 'extra stuff' });

okay so the valid values for $resource are literally these, no more no less:

area, artist, event, instrument, label, recording, release, release-group, series, work, url

the default is to return decoded JSON as a perl data structure — super chill, very demure. if you want the other thing, specify format => 'xml' and you'll get the results back as an instance of Mojo::DOM. your choice bestie 🫶

Search by MBID

my $result = $mb->search($resource => { mbid => 'xxxxxx' });

🚨 important: the "inc" search parameter is only allowed when searching for any particular "mbid". that's the rule. don't try it anywhere else. 🙈

Search area

my $area_list_results = $mb_ws->search(area => { iso => 'US-OH' });
my $area_list_results = $mb_ws->search(area => { area => 'cincinnati' });
my $area_list_results = $mb_ws->search(area => { alias => 'new york' });
my $area_list_results = $mb_ws->search(area => { sortname => 'new york' });
my $area_list_results = $mb_ws->search(area => { area => 'new york', type => 'city' });

my $area_result = $mb_ws->search(area => { mbid => '0573177b-9ff9-4643-80bc-ed2513419267' });
my $area_result = $mb_ws->search(area => { mbid => '0573177b-9ff9-4643-80bc-ed2513419267', inc => 'area-rels' });

look at all those ways to find a place. main character energy fr fr. 🌈

Search artist

# JSON example
my $artists = $mb->search(artist => { artist => 'Ryan Adams' });
my $artists = $mb->search(artist => { artist => 'Ryan Adams', type => 'person' });

my $artist_country = $artists->{artists}->[0]->{country};

# XML example
my $artists = $mb->search(artist => { artist => 'Ryan Adams', type => 'person', fmt => 'xml' });

my $artist_country = $artists->at('country')->text;

# find this particular artist
my $artist = $mb->search(artist => { mbid => '5c2d2520-950b-4c78-84fc-78a9328172a3' });

# find this particular artist and include release and artist relations (members of the band)
my $artist = $mb->search(artist => { mbid => '5c2d2520-950b-4c78-84fc-78a9328172a3', inc => ['releases','artist-rels'] });

# artists that started in Cincinnati
my $artists = $mb->search(artist => { beginarea => 'Cincinnati' });

the way that you can grab releases and artist-rels together to find the members of the band?? ate. 💅

Search label

my $labels = $mb->search(label => { label => 'Death' });

Search recording

my $recordings = $mb->search(recording => { artist => 'Taylor Swift' });

Search release

my $releases = $mb->search(release => { release => 'Love Is Hell', status => 'official' });
print "RELEASE COUNT: ", $releases->{count}, "\n";

---

🔥 DEBUG 🔥

set the environment variable MUSICBRAINZ_DEBUG=1 and boom, you're in the group chat with the internals:

• The URL that is generated for the search will output to STDOUT.
• The formatted output (JSON or XML) will be output to STDOUT.

lowkey the best way to figure out what's going on. 👑

---

🎀 AUTHOR 🎀

Bob Faist <bob.faist@gmail.com> — the legend. we love him. 🫶

---

💜 COPYRIGHT AND LICENSE 💜

Copyright 2006-2017 by Bob Faist

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

---

🌟 SEE ALSO 🌟

https://musicbrainz.org/doc/MusicBrainz_API — go read it bestie, it's the source of truth ⭐

---

and that's the whole page!! this was perl v5.42.3, dated 2026-10-01, from the WebServ...icBrainz(3) era — mwah, slay, bye 💖🦋✨