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
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!'
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:'
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
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'
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
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
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
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
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