Class: MusicBrainz::Client

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

auth authenticate browser debug= depth= device= does_result_exist? error exists? fragment_from_url get_error get_fragment_from_url get_id_from_url get_mp3_info get_ordinal get_ordinal_from_list get_query_error get_rdf get_rdf_len get_result get_result_data get_result_int get_result_rdf get_result_rdf_len get_url get_version get_web_submit_url id_from_url launch launch_browser max_items= mp3_info new ordinal proxy= query rdf rdf= rdf_len result result_exists? result_int result_rdf result_rdf= result_rdf_len select server= set_depth set_device set_max_items set_proxy set_rdf set_result_rdf set_server set_use_utf8 url use_utf8= utf8= version

### Public Class methods

new()

Allocate and initialize a new MusicBrainz::Client object.

Example:

      mb = MusicBrainz::Client.new

### Public Instance methods

auth(p1, p2)

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

debug=(p1)

Enable debugging output for this MusicBrainz::Client object.

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

Example:

      mb.debug = true

depth=(p1)

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

device=(p1)

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?

error()

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

exists?(...)

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

fragment_from_url(p1)

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

id_from_url(p1)

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(p1, p2)

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

max_items=(p1)

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

mp3_info(p1)

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')

ordinal(p1, p2)

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

proxy=(...)

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(...)

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'

rdf()

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

rdf=(p1)

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

rdf_len()

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

result(...)

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?

result_int(...)

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(...)

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

server=(...)

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=

url()

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=

utf8=(p1)

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

version()

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]