nodebrainz

Another Musicbrainz Node Client

NodeBrainz is a thin wrapper that gives you full access to the MusicBrainz API (Version 2). This includes search, lookup and browse. It has zero dependences, consumes only JSON (no blocking XML parsing), and includes a powerful Lucene search feature.

Example Usage

MusicBrainz asks that you identifying your application so be sure to set the userAgent. You may consider following the conventions of RFC 1945

var NB = require('nodebrainz');
 
// Initialize NodeBrainz
var nb = new NB({userAgent:'my-awesome-app/0.0.1 ( http://my-awesome-app.com )'});

Setting a custom host, basePath, port and defaultLimit (if not set, the defaultLimit is 25 and port is 80);

var nb = new NB({host:'localhost', port:8080, basePath:'/path/to/data/', defaultLimit:50});

Also supported are automatic retries for Musicbrainz rate-limiting.

var nb = new NB({retryOn: true, retryDelay: 3000, retryCount: 3});

MusicBrainz Entities

There are eight entities: artist, label, recording, release, release-group, work, area, url

Lookup

Lookups can be preformed on any of the eight entities.

Lookup an artist and include their releases, release-groups and aliases

nb.artist('e0140a67-e4d1-4f13-8a01-364355bee46e', {inc:'releases+release-groups+aliases'}, function(err, response){
    console.log(response);
});

Lookup a release-group with no filtering or subqueries

nb.releaseGroup('df46f245-7f62-4982-9d2c-e83d7be91cbf', function(err, response){
    console.log(response);
});

There are different subqueries you can include depending on the entities.

• Arists - recordings, releases, release-groups, works
• Label - releases
• Recording - artists, releases
• Release - artists, labels, recordings, release-groups
• Release-group - artists, releases

Check out the some of the additional subqueries. Note that the number of linked entities returned is always limited to 25, if you need the remaining results, you will have to perform a browse or search.

Browse

Browse requests are a direct lookup of all the entities directly linked to another entity. For example, if you wanted to look up all the release-groups for a particularly talented artist:

nb.browse('release-group', {artist:'e0140a67-e4d1-4f13-8a01-364355bee46e'}, function(err, response){
    console.log(response);
});

Browsed entities are always ordered alphabetically by gid. If you need to sort the entities, you will have to fetch all entities and sort them yourself. For pagination, set a limit and offset.

nb.browse('release-group', {artist:'e0140a67-e4d1-4f13-8a01-364355bee46e', type:'album', limit:2, offset:1}, function(err, response){
    console.log(response);
});

Note that browse requests are not searches, in order to browse all the releases-groups for an artist, you need to provide the MBID for the artist.

Search

Provides a way to search for entities. Behind the scenes, results are provided by a search server using Lucene technology.

nb.search('artist', {artist:'tool', country:'US'}, function(err, response){
    console.log(response);
});

Search Fields

There are different search fields depending on the entity.

• Artist
• Label
• Recording
• Release
• Release-group
• Work
• Area

Search for all releases for the artists named pink floyd. Limited to 20 and offset by 5

nb.search('release', {artist:'pink floyd', limit:20, offset:5}, function(err, response){
  console.log(response);
});

Search for all the studio albums for a specific artist (identified by their artist ID)

nb.search('release-group', {arid:'e0140a67-e4d1-4f13-8a01-364355bee46e', type:"album"}, function(err, response){
  console.log(response);
});

Lucene Search

Create powerful queries using luceneSearch. View the syntax guide

nb.luceneSearch('artist',{query:'artist:t??l AND -artist:"Jethro Tull"', limit: 2, offset: 1}, function(err, response){
  console.log(response);
});