Class MusicBrainz::Client
In: musicbrainz.c  (CVS)
Parent: Object

Client query interface to the MusicBrainz music library. The easiest way to explain the code is probably with a simple example.

  # load the musicbrainz library
  require 'musicbrainz'

  # create a musicbrainz client handle
  mb = MusicBrainz::Client.new

  # create a musicbrainz client handle
  mb = MusicBrainz::Client.new

  # search for albums named "mirror conspiracy"
  album_name = 'Mirror Conspiracy'
  query_ok = mb.query(MusicBrainz::Query::FindAlbumByName, album_name)

  # if there weren't any errors, then print the number of matching albums
  if query_ok
    num_albums = mb.result(MusicBrainz::Query::GetNumAlbums).to_i
    puts "Number of Results: #{num_albums}"
  end

Methods

Public Class methods

Allocate and initialize a new MusicBrainz::Client object.

Example:

  mb = MusicBrainz::Client.new

Public Instance methods

Set user authentication for a MusicBrainz::Client object.

This method is optional. It only needs to be called if you want to submit data to the server and give the user credit for the submission. If you want to submit data anonymously, don’t call this method. Returns true if the authentication was successful.

Aliases:

  MusicBrainz::Client#authenticate

Examples:

  # connect as user "MrMusic", password "s3kr3tp455w0rd"
  mb.auth 'MrMusic', 's3kr3tp455w0rd'

  # connect as user "MBrox", password "hithere!"
  mb.authenticate 'MBrox', 'hithere!'
authenticate(p1, p2)

Alias for auth

browser(p1, p2)

Alias for launch

Enable debugging output for this MusicBrainz::Client object.

Note: Debugging output is sent to standard output, not standard error.

Example:

  mb.debug = true

Set the search depth for a MusicBrainz::Client object.

Note: Defaults to 2.

Aliases:

  MusicBrainz::Client#set_depth

Examples:

  mb.depth = 5
  mb.set_depth 5

Set CD-ROM device for a MusicBrainz::Client object.

On Unix systems, this is a path (eg "/dev/scd0") and defaults to "/dev/cdrom". On Win32 systems, it’s a drive letter (eg "E:"). This method always returns true.

Aliases:

  MusicBrainz::Client#set_device

Examples:

  # set device to "/dev/scd1"
  mb.device = '/dev/scd1'

  # set CD-ROM to "E:" on a Win32 system
  mb.set_device 'E:'
does_result_exist?(...)

Alias for exists?

Retrieve error from last call to MusicBrainz::Client#query with this MusicBrainz::Client object.

Aliases:

  MusicBrainz::Client#get_error
  MusicBrainz::Client#get_query_error

Example:

  # simple query and error return
  query = MusicBrainz::Query::GetStatus
  puts 'Error: ' << mb.error unless mb.query query

See if a piece of information exists in data returned by a successful query by a MusicBrainz::Client object.

Note: Certain result queries require an ordinal argument. See the MusicBrainz result query (MBE_*) documentation for additional information.

Aliases:

  MusicBrainz::Client#result_exists?
  MusicBrainz::Client#does_result_exist?

Examples:

  # does the current album have a name?
  puts 'named album' if mb.exists? MusicBrainz::Query::AlbumGetAlbumName

  # does the current album have a type?
  puts 'has a type' if mb.exists? MusicBrainz::Query::AlbumGetAlbumType

Extract an identifier fragment from a URL.

Given a URI, this method will return the string that follows the # separator (e.g. when passed "musicbrainz.org/mm/mq-1.1#ArtistResult", this method will return "ArtistResult").

Aliases:

  MusicBrainz::Client#get_fragment_from_url

Examples:

  # get the artist name of the first track on the album
  url = mb.result MusicBrainz::Query::AlbumGetArtistId, 1
  frag = mb.fragment_from_url url
get_error()

Alias for error

get_fragment_from_url(p1)

Alias for fragment_from_url

get_id_from_url(p1)

Alias for id_from_url

get_mp3_info(p1)

Alias for mp3_info

get_ordinal(p1, p2)

Alias for ordinal

get_ordinal_from_list(p1, p2)

Alias for ordinal

get_query_error()

Alias for error

get_rdf()

Alias for rdf

get_rdf_len()

Alias for rdf_len

get_result(...)

Alias for result

get_result_data(...)

Alias for result

get_result_int(...)

Alias for result_int

get_result_rdf()

Alias for rdf

get_result_rdf_len()

Alias for rdf_len

get_url()

Alias for url

get_version()

Alias for version

get_web_submit_url()

Alias for url

Extract the actual artist/album/track ID from a MBE_GetxxxxxId query.

The MBE_GETxxxxxId queries return a URL where additional RDF metadata for a given ID can be retrieved. Callers may wish to extract only the ID of an artist/album/track for reference.

Aliases:

  MusicBrainz::Client#get_id_from_url

Examples:

  # get the artist name of the first track on the album
  url = mb.result MusicBrainz::Query::AlbumGetArtistId, 1
  id = mb.id_from_url url

Launch a URL in the specified browser.

Aliases:

  MusicBrainz::Client#browser
  MusicBrainz::Client#launch_browser

Examples:

  mb.launch uri, 'galeon'
launch_browser(p1, p2)

Alias for launch

Set the maximum number of items for a MusicBrainz::Client object.

Set the maximum number of items to return from a query for a MusicBrainz::Client object. If the query yields more items than this number, the server will omit the excess results. Defaults to 25.

Aliases:

  MusicBrainz::Client#set_max_items

Examples:

  mb.max_items = 5
  mb.set_max_items 5

Calculate the crucial pieces of information for an MP3 file.

Note: This method returns the duration of the MP3 in milliseconds, so you’ll need to divide the duration by 1000 before passing it to MusicBrainz::TRM methods.

Aliases:

  MusicBrainz::Client#get_mp3_info

Examples:

  # get the duration and stereo of an MP3 named 'foo.mp3'
  info = mb.mp3_info 'foo.mp3'
  puts 'duration (ms): ' << info['duration'] << ', ' <<
       'stereo: ' << (info['stereo'] ? 'yes' : 'no')

Get the ordinal (list position) of an item in a list.

Normally used to retrieve the track number out of a list of tracks in an album.

Aliases:

  MusicBrainz::Client#get_ordinal
  MusicBrainz::Client#get_ordinal_from_list

Examples:

  # get the ordinal of a track based on the URI
  list = mb.result MusicBrainz::Query::AlbumGetTrackList
  uri  = mb.result MusicBrainz::Query::AlbumGetTrackId, 5
  ordinal = mb.ordinal list, uri

Set the proxy name and port for the MusicBrainz::Client object.

Returns false if MusicBrainz could not connect to the proxy.

Aliases:

  MusicBrainz::Client#set_proxy

Examples:

  # connect to 'proxy.localdomain', port 8080
  mb.proxy = 'proxy.localdomain'

  # connect to proxy.example.com, port 31337
  mb.proxy = 'proxy.example.com:31337'

  # connect to www.musicbrainz.org, port 8080
  mb.set_proxy 'www.musicbrainz.org'

  # connect to proxy.example.com, port 31337
  mb.set_proxy 'proxy.example.com', 31337

Query the MusicBrainz server with this MusicBrainz::Client object.

Returns true if the query was successful (even if it didn’t return any results).

See the MusicBrainz::Query documentation for information on various query types.

Examples:

  # get general return status of prior query
  mb.query MusicBrainz::Query::GetStatus

  # query the MusicBrainz server for an album titled "Airdrawndagger"
  # by an artist "Sasha"
  mb.query MusicBrainz::Query::AlbumFindAlbum,
           'Sasha',
           'Airdrawndagger'

Get the RDF that was returned by the server of a MusicBrainz::Client object.

Returns nil if a string could not be allocated or if there was an error.

Aliases:

  MusicBrainz::Client#get_rdf
  MusicBrainz::Client#result_rdf
  MusicBrainz::Client#get_result_rdf

Example:

  rdf = mb.rdf

Set the RDF to use for data extraction for a MusicBrainz::Client object.

Note: Advanced users only.

Aliases:

  MusicBrainz::Client#set_rdf
  MusicBrainz::Client#result_rdf=
  MusicBrainz::Client#set_result_rdf

Example:

  mb.rdf = result_rdf

Get the length of the RDF that was returned by the server of a MusicBrainz::Client object.

Aliases:

  MusicBrainz::Client#get_rdf_len
  MusicBrainz::Client#result_rdf_len
  MusicBrainz::Client#get_result_rdf_len

Example:

  rdf_len = mb.rdf_len

Extract a piece of information from the data returned by a successful query by a MusicBrainz::Client object.

Returns nil if there was an error or if the correct piece of data was not found.

Note: Certain result queries require an ordinal argument. See the MusicBrainz result query (MBE_*) documentation for additional information.

Aliases:

  MusicBrainz::Client#get_result
  MusicBrainz::Client#get_result_data

Examples:

  # get the name of the currently selected album
  album_name = mb.result MusicBrainz::Query::AlbumGetAlbumName

  # get the duration of the 5th track on the current album
  duration = mb.result MusicBrainz::Query::AlbumGetTrackDuration, 5
result_exists?(...)

Alias for exists?

Return the integer value of a query by a MusicBrainz::Client object.

Note: Certain result queries require an ordinal argument. See the MusicBrainz result query (MBE_*) documentation for additional information.

Aliases:

  MusicBrainz::Client#result_int
  MusicBrainz::Client#get_result_int

Examples:

  # get the name of the currently selected album
  album_name = mb.result MusicBrainz::Query::AlbumGetAlbumName

  # get the duration of the 5th track on the current album
  duration = mb.result MusicBrainz::Query::AlbumGetTrackDuration, 5
result_rdf()

Alias for rdf

result_rdf=(p1)

Alias for rdf=

result_rdf_len()

Alias for rdf_len

Select a context in the query result of this MusicBrainz::Client object.

Returns true if the select query was successful (even if it didn’t return any results).

See the MusicBrainz::Query documentation for information on various query types.

Examples:

  # return to the top-level context of the current query
  mb.select MusicBrainz::Query::Rewind

  # select the second artist from a query that returned a list of
  # artists
  mb.select MusicBrainz::Query::SelectArtist, 2

Set the server name and port for the MusicBrainz::Client object.

Returns false if MusicBrainz could not connect to the server. If this method is not called, the default server is ‘www.musicbrainz.org’, port 80.

Aliases:

  MusicBrainz::Client#set_server

Examples:

  # connect to www.musicbrainz.org, port 80
  mb.server = 'www.musicbrainz.org'

  # connect to www.example.com, port 31337
  mb.server = 'www.example.com:31337'

  # connect to www.musicbrainz.org, port 80
  mb.set_server 'www.musicbrainz.org'

  # connect to www.example.com, port 31337
  mb.set_server 'www.example.com', 31337
set_depth(p1)

Alias for depth=

set_device(p1)

Alias for device=

set_max_items(p1)

Alias for max_items=

set_proxy(...)

Alias for proxy=

set_rdf(p1)

Alias for rdf=

set_result_rdf(p1)

Alias for rdf=

set_server(...)

Alias for server=

set_use_utf8(p1)

Alias for utf8=

Get web-based MusicBrainz CD-ROM submission URL for CD-ROM device associated with this MusicBrainz::Client object.

Use MusicBrainz::Client#device to set the CD-ROM device. Returns nil on error.

Aliases:

  MusicBrainz::Client#get_url
  MusicBrainz::Client#get_web_submit_url

Examples:

  url = mb.url
  url = mb.get_url
  url = mb.get_web_submit_url
use_utf8=(p1)

Alias for utf8=

Enable UTF-8 output for a MusicBrainz::Client object.

Note: Defaults to ISO-8859-1 output. If this is set to true, then UTF-8 will be used instead.

Aliases:

  MusicBrainz::Client#use_utf8=
  MusicBrainz::Client#set_use_utf8

Examples:

  mb.utf8 = true
  mb.use_utf8 = true
  mb.set_use_utf8 true

Get the version of a MusicBrainz::Client object.

Note: this actually returns the version of the MusicBrainz library.

Example:

  puts 'MusicBrainz version: ' << mb.version

[Validate]