bts / mbws forked from bpot/mbws

Ruby library for MusicBrainz Web Service (www.musicbrainz.org)

This URL has Read+Write access

mbws /
name age
history
message
file COPYING Sun May 04 12:15:26 -0700 2008 * Move from rubyforge. [Bobby Potter]
file INSTALL Sun May 04 12:15:26 -0700 2008 * Move from rubyforge. [Bobby Potter]
file README Sun May 04 12:15:26 -0700 2008 * Move from rubyforge. [Bobby Potter]
file Rakefile Thu Sep 24 12:16:20 -0700 2009 create gemspec [bts]
file TODO Sun May 04 12:15:26 -0700 2008 * Move from rubyforge. [Bobby Potter]
directory bin/ Sun May 04 12:15:26 -0700 2008 * Move from rubyforge. [Bobby Potter]
directory lib/ Mon Sep 28 10:15:53 -0700 2009 fail gracefully when a query doesn't return a list [bts]
file mbws.gemspec Mon Sep 28 10:16:46 -0700 2009 mbws 0.0.1.1 [bts]
directory test/ Sat May 17 17:10:46 -0700 2008 * Limit ourselves to 13 requests every 10 secon... [Bobby Potter]
README
= MBWS

MBWS is a Ruby library for accessing MusicBrainz's (http://www.musicbrainz.org) XML Web Service. This library is 
currently in development, it is missing some features and is lacking a lot of documention.

== Introduction

MusicBrainz's Web Service (http://musicbrainz.org/doc/XMLWebService) offers four resources Artist, Label, Release, and 
Track. You can access each object individually by their MBID (unique identifier) or you can search each resource as a 
collection either by specific parameters (name,date, title, etc.) or with a lucene query 
(http://musicbrainz.org/doc/TextSearchSyntax).

When accessing a specific object by its MBID you can also have the query return extra information (an artist's releases, 
a release's tracks and so on).

Access to these resources is provided by matching Ruby classes: MBWS::Artist, MBWS::Release, MBWS::Track, and 
MBWS::Label.

== Usage

=== Finding an individual object

If you know an object's MBID you can find it directly.

  artist = Artist.find("c0b2500e-0cef-4130-869d-732b23ed9df5")

You can also include extended information. For example, if you want to returnan artist's aliases and their 'Official' 
single artist albums.

  artist = Artist.find("c0b2500e-0cef-4130-869d-732b23ed9df5",:inc => [:aliases, :sa-Official])

=== Searching a collection

You can search for an object, in this case the class will return an array.

  releases = Release.find(:title => "Hour", :artist => "Jaw")

It is also possible to use a text search using the lucene query syntax.

  releases = Release.find(:query => '"the understanding" AND artist:royksopp')

This type of search is describe here http://musicbrainz.org/doc/TextSearchSyntax. Note that when using either of these 
search methods, it is not possible to include extended information via the :inc parameter. Also, all other parameters 
are ignored if the query parameter is set.

=== Relations between objects

The classes are related (hopefully) as you would expect. For example, you can retrieve all of an artists's releases from 
an artist object.

  artist = Artist.find("c0b2500e-0cef-4130-869d-732b23ed9df5")
  releases = @artist.releases

Further documentation can be found in each Classes individual documentation: MBWS::Artist, MBWS::Release, MBWS::Label.