Class MusicBrainz::Client
In: musicbrainz.c
Parent: Object
Methods
auth    bitprint    debug=    depth=    device=    error    exists?    fragment_from_url    id_from_url    initialize    launch    max_items=    mp3_info    new    ordinal    proxy=    query    rdf    rdf=    rdf_len    result    result_int    select    server=    sha1    url    utf8=    version   
Public Class methods
new(VALUE klass)

Allocate and initialize a new MusicBrainz::Client object.

Example:

  mb = MusicBrainz::Client.new
initialize(VALUE self)

Constructor for MusicBrainz::Client object.

This method is currently empty. You should never call this method directly unless you're instantiating a derived class (ie, you know what you're doing).

Public Instance methods
version(VALUE self)

Get the version of a MusicBrainz::Client object.

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

Example:

  puts 'MusicBrainz version: ' << mb.version
server=(int argc, VALUE *argv, VALUE self)

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
debug=(VALUE self, VALUE debug)

Enable debugging output for this MusicBrainz::Client object.

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

Example:

  mb.debug = true
proxy=(int argc, VALUE *argv, VALUE self)

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
auth(VALUE self, VALUE user, VALUE pass)

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!'
device=(VALUE self, VALUE device)

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:'
utf8=(VALUE self, VALUE use_utf8)

Enable UTF8 output for a MusicBrainz::Client object.

Note: Defaults to ISO-8859-1 output. If this is set to true, then UTF8 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
depth=(VALUE self, VALUE depth)

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
max_items=(VALUE self, VALUE max_items)

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
query(int argc, VALUE *argv, VALUE self)

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

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

TODO: See the MusicBrainz 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'
url(VALUE self)

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
error(VALUE self)

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
select(int argc, VALUE *argv, VALUE self)

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

TODO: This method uses select queries (MBS_*). See the MusicBrainz 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
result(int argc, VALUE *argv, VALUE self)

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_int(...)
exists?(int argc, VALUE *argv, VALUE self)

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
rdf(VALUE self)

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_len(VALUE self)

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
rdf=(VALUE self, VALUE 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
id_from_url(VALUE self, VALUE 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
fragment_from_url(VALUE self, VALUE url)

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
ordinal(VALUE self, VALUE list, VALUE uri)

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
sha1(VALUE self, VALUE path)

Calculate the SHA1 hash for a given filename.

Aliases:

  MusicBrainz::Client#calculate_sha1

Examples:

  sha1 = mb.sha1 'foo.mp3'
bitprint(VALUE self, VALUE path)

Calculate the Bitzi bitprint info for a given filename.

Aliases:

  MusicBrainz::Client#calculate_bitprint

Examples:

  # print the bitprint for a file called 'foo.mp3'
  bp = mb.bitprint 'foo.mp3'
  puts 'foo.mp3 bitprint: ' << bp['bitprint']
mp3_info(VALUE self, VALUE path)

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')
launch(VALUE self, VALUE url, VALUE browser)

Launch a URL in the specified browser.

Aliases:

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

Examples:

  mb.launch uri, 'galeon'