Path: | doc/README.rdoc |
Last Update: | Sat Feb 23 07:13:00 +0000 2019 |
RBrainz is a Ruby client library to access the MusicBrainz XML web service, which can be used to query the MusicBrainz database.
RBrainz is written in Ruby and follows the design of PythonMusicBrainz2, the reference implementation for a MusicBrainz client library. Developers used to PythonMusicBrainz2 should already know most of RBrainz’ interface. However, RBrainz differs from PythonMusicBrainz2 wherever it makes the library more Ruby like or easier to use.
RBrainz supports the MusicBrainz XML Metadata Version 1.4, including support for labels, extended release events, release groups and ratings.
The easiest way to install the latest release of RBrainz is using RubyGems by executing the following command:
gem install rbrainz
If you downloaded the RBRainz source package or checked out the latest version from SVN you can install it with
rake install
You still need RubyGems for the installation to succeed.
The most important classes in this library are the model classes MusicBrainz::Model::Artist, MusicBrainz::Model::Release, MusicBrainz::Model::Track and MusicBrainz::Model::Label together with MusicBrainz::Webservice::Query. The Query class provides an easy to use interface to query the MusicBrainz webservice. It will always return one of the model classes above or a MusicBrainz::Model::ScoredCollection of those classes. The example below should make the usage clear:
require 'rbrainz' include MusicBrainz # Create an MBID object which represents a MusicBrainz artist ID. mbid = Model::MBID.new('c0b2500e-0cef-4130-869d-732b23ed9df5', :artist) # With the ArtistInclude object we can control what kind of information # the MusicBrainz server will include in its answer. artist_includes = Webservice::ArtistIncludes.new( :aliases => true, :releases => ['Album', 'Official'], :artist_rels => true, :release_rels => true, :track_rels => true, :label_rels => true, :url_rels => true ) # Query the webservice for the artist with the above ID. The result # will contain all the information specified in artist_includes. query = Webservice::Query.new artist = query.get_artist_by_id(mbid, artist_includes) # Display the fetched artist data together with all unique release titles. print <<EOF ID : #{artist.id.uuid} Name : #{artist.name} Sort name : #{artist.sort_name} Disambiguation: #{artist.disambiguation} Type : #{artist.type} Begin date : #{artist.begin_date} End date : #{artist.end_date} Aliases : #{artist.aliases.to_a.join('; ')} Releases : #{artist.releases.map{|r| r.title}.uniq.join("\r\n ")} EOF
The MusicBrainz webservice returns all data in UTF-8 encoding. RBrainz does not change or modify the encoding. So if you are using RBrainz you should be aware that all strings returned by RBrainz are UTF-8 encoded as well. Furthermore all strings you pass to RBrainz need to be UTF-8 encoded as well.
For more information about the MusicBrainz webservice visit the following resources:
For more information about RBrainz visit rbrainz.rubyforge.org.
If you have any questions or suggestions regarding RBrainz please write to the rbrainz-user mailinglist. If you find bugs or if you have any feature requests please use the RBrainz bug tracker.
RBrainz is Copyright (c) 2007-2011 Philipp Wolfer and 2007 Nigel Graham. It is free softare distributed under a BSD style license. See LICENSE for details.
$Id: README.rdoc 322 2011-04-28 20:16:42Z phw $