This module contains the constants used as parameters to the MusicBrainz::Client#query and MusicBrainz::Client#result methods.
Each constant is defined in two forms; with or without the type prefix. For
example, the MusicBrainz::Query::SelectArtist constant is defined as both
MusicBrainz::Query::SelectArtist and
MusicBrainz::Query::MBS_SelectArtist. This is done in order to keep the
Ruby API comparable to the C and C++ API.
The following sections contain a full list of defined constants, along with
a brief description of each one.
Select Queries
- MusicBrainz::Query::VARIOUS_ARTIST_ID: The MusicBrainz artist id used to indicate that
an album is a various artist album.
- MusicBrainz::Query::Rewind: Use this query to reset the current
context back to the top level of the response.
- MusicBrainz::Query::Back: Use this query to change the current
context back one level.
- MusicBrainz::Query::SelectArtist: Use this Select Query to select an artist from an query that returns
a list of artists. Giving the argument 1 for the ordinal selects the first
artist in the list, 2 the second and so on. Use
MusicBrainz::Query::ArtistXXXXXX queries to extract data after the select.
NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectAlbum: Use this Select Query to select an album from an query that returns a
list of albums. Giving the argument 1 for the ordinal selects the first
album in the list, 2 the second and so on. Use
MusicBrainz::Query::AlbumXXXXXX queries to extract data after the select.
NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectTrack: Use this Select Query to select a track from an query that returns a
list of tracks. Giving the argument 1 for the ordinal selects the first
track in the list, 2 the second and so on. Use
MusicBrainz::Query::TrackXXXXXX queries to extract data after the select.
NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectTrackArtist: Use this Select Query to select an the corresponding artist from a
track context. MusicBrainz::Query::ArtistXXXXXX queries to extract data
after the select. NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectTrackAlbum: Use this Select Query to select an the corresponding artist from a
track context. MusicBrainz::Query::ArtistXXXXXX queries to extract data
after the select. NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectTrmid: Use this Select Query to select a trmid from the list. NOTE: This
select requires one ordinal argument.
- MusicBrainz::Query::SelectCdindexid: Use this Select Query to select a CD Index id from the list. NOTE:
This select requires one ordinal argument.
- MusicBrainz::Query::SelectReleaseDate: Use this Select Query to select a Release date/country from the list.
NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::SelectLookupResult: Use this Select Query to select a result from a lookupResultList.
This select will be used in conjunction with
MusicBrainz::Query::FileLookup. NOTE: This select requires one ordinal
argument.
- MusicBrainz::Query::SelectLookupResultArtist: Use this Select Query to select the artist from a lookup result. This
select will be used in conjunction with MusicBrainz::Query::FileLookup.
- MusicBrainz::Query::SelectLookupResultAlbum: Use this Select Query to select the album from a lookup result. This
select will be used in conjunction with MusicBrainz::Query::FileLookup.
- MusicBrainz::Query::SelectLookupResultTrack: Use this Select Query to select the track from a lookup result. This
select will be used in conjunction with MusicBrainz::Query::FileLookup.
- MusicBrainz::Query::SelectRelationship: Use this Select Query to select a relationship from a list of
advanced relationships. NOTE: This select requires one ordinal argument.
NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
Internal Queries
- MusicBrainz::Query::QuerySubject: Internal use only.
- MusicBrainz::Query::GetError: Internal use only.
Top-Level Queries
The following queries are used with FileInfoLookup.
- MusicBrainz::Query::GetStatus: Get the general return status of
this query. Values for this include OK or fuzzy. Fuzzy is returned when the
server made a fuzzy match somewhere while handling the query.
Numeric Queries
Queries used to determine the number of items used by a query.
- MusicBrainz::Query::GetNumArtists: Return the number of artist
returned in this query.
- MusicBrainz::Query::GetNumAlbums: Return the number of albums
returned in this query.
- MusicBrainz::Query::GetNumTracks: Return the number of tracks
returned in this query.
- MusicBrainz::Query::GetNumTrmids: Return the number of trmids
returned in this query.
- MusicBrainz::Query::GetNumLookupResults: Return the number of
lookup results returned in this query.
Artist List Queries
- MusicBrainz::Query::ArtistGetArtistName: Return the name of the
currently selected Album
- MusicBrainz::Query::ArtistGetArtistSortName: Return the name of
the currently selected Album
- MusicBrainz::Query::ArtistGetArtistId: Return the ID of the
currently selected Album. The value of this query is indeed empty!
- MusicBrainz::Query::ArtistGetAlbumName: Return the name of the nth
album. Requires an ordinal argument to select an album from a list of
albums in the current artist NOTE: This select requires one ordinal
argument.
- MusicBrainz::Query::ArtistGetAlbumId: Return the ID of the nth
album. Requires an ordinal argument to select an album from a list of
albums in the current artist NOTE: This select requires one ordinal
argument.
Album List Queries
- MusicBrainz::Query::AlbumGetAlbumName: Return the name of the
currently selected Album
- MusicBrainz::Query::AlbumGetAlbumId: Return the ID of the
currently selected Album. The value of this
query is indeed empty!
- MusicBrainz::Query::AlbumGetAlbumStatus: Return the release status
of the currently selected Album.
- MusicBrainz::Query::AlbumGetAlbumType: Return the release type of
the currently selected Album.
- MusicBrainz::Query::AlbumGetAlbumAmazonAsin: Return the <a
href=’amazon.com/'>Amazon.con>
ASIN for the selected Album. NOTE: This query is only defined for MusicBrainz 2.1.0 and newer.
- MusicBrainz::Query::AlbumGetNumCdindexIds: Return the number of
cdindexds returned in this query.
- MusicBrainz::Query::AlbumGetNumReleaseDates: Return the number of
release dates returned in this query. NOTE: This query is only defined for
MusicBrainz 2.1.0 and newer.
- MusicBrainz::Query::AlbumGetAlbumArtistId: Return the Artist ID of
the currently selected Album. This may return the artist id for the Various
Artists’ artist, and then you should check the artist for each track
of the album seperately with MusicBrainz::Query::AlbumGetArtistName,
MusicBrainz::Query::AlbumGetArtistSortName, and
MusicBrainz::Query::AlbumGetArtistId.
- MusicBrainz::Query::AlbumGetNumTracks: Return the mumber of tracks
in the currently selected Album
- MusicBrainz::Query::AlbumGetTrackId: Return the Id of the nth
track in the album. Requires a track index ordinal. 1 for the first track,
etc… NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::AlbumGetTrackList: Return the track list of an
album. This extractor should only be used to specify a list for MusicBrainz::Client#ordinal.
- MusicBrainz::Query::AlbumGetTrackNum: Return the track number of
the nth track in the album. Requires a track index ordinal. 1 for the first
track, etc… NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::AlbumGetTrackName: Return the track name of
the nth track in the album. Requires a track index ordinal. 1 for the first
track, etc… NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::AlbumGetTrackDuration: Return the track
duration of the nth track in the album. Requires a track index ordinal. 1
for the first track, etc… NOTE: This select requires one ordinal
argument.
- MusicBrainz::Query::AlbumGetArtistName: Return the artist name of
the nth track in the album. Requires a track index ordinal. 1 for the first
track, etc… NOTE: This select requires one ordinal argument.
- MusicBrainz::Query::AlbumGetArtistSortName: Return the artist
sortname of the nth track in the album. Requires a track index ordinal. 1
for the first track, etc… NOTE: This select requires one ordinal
argument.
- MusicBrainz::Query::AlbumGetArtistId: Return the artist Id of the
nth track in the album. Requires a track index ordinal. 1 for the first
track, etc… NOTE: This select requires one ordinal argument.
Track List Queries
- MusicBrainz::Query::TrackGetTrackName: Return the name of the
currently selected track
- MusicBrainz::Query::TrackGetTrackId: Return the ID of the
currently selected track. The value of this query is indeed empty!
- MusicBrainz::Query::TrackGetTrackNum: Return the track number in
the currently selected track
- MusicBrainz::Query::TrackGetTrackDuration: Return the track
duration in the currently selected track
- MusicBrainz::Query::TrackGetArtistName: Return the name of the
artist for this track.
- MusicBrainz::Query::TrackGetArtistSortName: Return the sortname of
the artist for this track.
- MusicBrainz::Query::TrackGetArtistId: Return the Id of the artist
for this track.
Quick Track Queries
- MusicBrainz::Query::QuickGetArtistName: Return the name of the
aritst
- MusicBrainz::Query::QuickGetArtistSortName: Return the sortname of
the artist
- MusicBrainz::Query::QuickGetArtistId: Return the id of the artist
- MusicBrainz::Query::QuickGetAlbumName: Return the name of the
album.
- MusicBrainz::Query::QuickGetTrackName: Return the name of the
track.
- MusicBrainz::Query::QuickGetTrackNum: Return the track number in
the currently selected track.
- MusicBrainz::Query::QuickGetTrackId: Return the MB track id
- MusicBrainz::Query::QuickGetTrackDuration: Return the track
duration.
Release Queries
- MusicBrainz::Query::ReleaseGetDate: Return the release date
- MusicBrainz::Query::ReleaseGetCountry: Return the release country
File Lookup Queries
- MusicBrainz::Query::LookupGetType: Return the type of the lookup
result
- MusicBrainz::Query::LookupGetRelevance: Return the relevance of
the lookup result
- MusicBrainz::Query::LookupGetArtistId: Return the artist id of the
lookup result
- MusicBrainz::Query::LookupGetAlbumId: Return the album id of the
lookup result
- MusicBrainz::Query::LookupGetAlbumArtistId: Return the artist id
of the lookup result NOTE: This query is only defined for MusicBrainz 2.1.0 and newer.
- MusicBrainz::Query::LookupGetTrackId: Return the track id of the
lookup result
- MusicBrainz::Query::LookupGetTrackArtistId: Return the artist id
of the lookup result NOTE: This query is only defined for MusicBrainz 2.1.0 and newer.
Relationship Queries
Used to extract results from the MusicBrainz::Query::GetXXXXXRelationsById
queries.
- MusicBrainz::Query::GetRelationshipType: Get the type of an
advanced relationships link. Please note that these relationship types can
change over time! NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipDirection: Get the direction of
a link between two like entities. This data element will only be present
for links between like types (eg artist-artist links) and IFF the link
direction is reverse of what the RDF implies. NOTE: This query is only
defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipArtistId: Get the artist id
that this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipArtistName: Get the artist name
that this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipAlbumId: Get the album id that
this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipAlbumName: Get the album name
that this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipTrackId: Get the track id that
this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipTrackName: Get the track name
that this link points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipURL: Get the URL that this link
points to. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetRelationshipAttribute: Get the
vocal/instrument attributes. Must pass an ordinal to indicate which
attribute to get. NOTE: This query is only defined for MusicBrainz 2.1.2 and newer.
CD Table of Contents Queries
Used to extract results from the MusicBrainz::Query::GetCDTOC query.
- MusicBrainz::Query::TOCGetCDIndexId: Return the CDIndex ID from
the table of contents from the CD
- MusicBrainz::Query::TOCGetFirstTrack: Return the first track
number from the table of contents from the CD
- MusicBrainz::Query::TOCGetLastTrack: Return the last track number
(total number of tracks on the CD) from the table of contents from the CD
- MusicBrainz::Query::TOCGetTrackSectorOffset: Return the sector
offset from the nth track. One ordinal argument must be given to specify
the track. Track 1 is a special lead-out track, and the actual track 1 on a
CD can be retrieved as track 2 and so forth.
- MusicBrainz::Query::TOCGetTrackNumSectors: Return the number of
sectors for the nth track. One ordinal argument must be given to specify
the track. Track 1 is a special lead-out track, and the actual track 1 on a
CD can be retrieved as track 2 and so forth.
Authentication Queries
Used to extract results from the MusicBrainz::Query::AuthenticateQuery
query.
- MusicBrainz::Query::AuthGetSessionId: Return the Session Id from
the Auth Query. This query will be used internally
by the client library.
- MusicBrainz::Query::AuthGetChallenge: Return the Auth Challenge
data from the Auth Query. This query will be used
internally by the client library.
Local Queries
- MusicBrainz::Query::GetCDInfo: Use this query to look up a CD from
MusicBrainz. This query will examine the
CD-ROM in the CD-ROM drive specified by mb_SetDevice and then send the
CD-ROM data to the server. The server will then find any matching CDs and
return then as an albumList.
- MusicBrainz::Query::GetCDTOC: Use this query to examine the table
of contents of a CD. This query will examine the CD-ROM in the CD-ROM drive
specified by mb_SetDevice, and then let the use extract data from the table
of contents using the MBQ_TOCXXXXX functions. No live net connection is
required for this query. NOTE: This query is only defined for MusicBrainz 2.1.0 and newer.
- MusicBrainz::Query::AssociateCD: Internal use only. (For right
now)
Server Queries
The following queries must have argument(s) substituted in them.
- MusicBrainz::Query::Authenticate: This query is use to start an
authenticated session with the MB server. The username is sent to the
server, and the server responds with session id and a challenge sequence
that the client needs to use to create a session key. The session key and
session id need to be provided with the MusicBrainz::Query::SubmitXXXX
functions in order to give moderators/users credit for their submissions.
This query will be carried out by the client libary automatically —
you should not need to use it.
- MusicBrainz::Query::GetCDInfoFromCDIndexId: Use this query to
return an albumList for the given CD Index Id
- MusicBrainz::Query::TrackInfoFromTRMId: Use this query to return
the metadata information (artistname, albumname, trackname, tracknumber)
for a given trm id. Optionally, you can also specifiy the basic artist
metadata, so that if the server cannot match on the TRM id, it will attempt to match based on the basic
metadata. In case of a TRM collision (where one TRM may point to more than one track) this function
will return more than on track. The user (or tagging app) must decide which
track information is correct.
Parameters:
- trmid: The TRM id for the track to be looked up
- artistName: The name of the artist
- albumName: The name of the album
- trackName: The name of the track
- trackNum: The number of the track
- MusicBrainz::Query::QuickTrackInfoFromTrackId: Use this query to
return the basic metadata information (artistname, albumname, trackname,
tracknumber) for a given track mb id
- MusicBrainz::Query::FindArtistByName: Use this query to find
artists by name. This function returns an artistList for the given artist
name.
- MusicBrainz::Query::FindAlbumByName: Use this query to find albums
by name. This function returns an albumList for the given album name.
- MusicBrainz::Query::FindTrackByName: Use this query to find tracks
by name. This function returns a trackList for the given track name.
- MusicBrainz::Query::FindDistinctTRMId: Use this function to find
TRM Ids that match a given artistName and trackName,
This query returns a trmidList.
- MusicBrainz::Query::GetArtistById: Retrieve an artistList from a
given Artist id
- MusicBrainz::Query::GetAlbumById: Retrieve an albumList from a
given Album id
- MusicBrainz::Query::GetTrackById: Retrieve an trackList from a
given Track id
- MusicBrainz::Query::GetTrackByTRMId: Retrieve an trackList from a
given TRM Id
- MusicBrainz::Query::GetArtistRelationsById: Retrieve an artistList
with advanced relationships from a given artist id NOTE: This query is only
defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetAlbumRelationsById: Retrieve an albumList
with advanced relationships from a given album id NOTE: This query is only
defined for MusicBrainz 2.1.2 and newer.
- MusicBrainz::Query::GetTrackRelationsById: Retrieve a trackList
with advanced relationships from a given track id NOTE: This query is only
defined for MusicBrainz 2.1.2 and newer.
Internal Submission Queries
- MusicBrainz::Query::SubmitTrack: Internal use only.
- MusicBrainz::Query::SubmitTrackTRMId: Submit a single TrackId, TRM Id pair to MusicBrainz. This query can handle only one
pair at a time, which is inefficient. The user may wish to create the query
RDF text by hand and provide more than one pair in the rdf:Bag, since the
server can handle up to 1000 pairs in one query.
Parameters:
- TrackGID: The Global ID field of the track
- trmid: The TRM Id of the track.
- MusicBrainz::Query::FileInfoLookup: Lookup metadata for one file.
This function can be used by tagging applications to attempt to match a
given track with a track in the database. The server will attempt to match
an artist, album and track during three phases. If at any one lookup phase
the server finds ONE item only, it will move on to to the next phase. If no
items are returned, an error message is returned. If more then one item is
returned, the end-user will have to choose one from the returned list and
then make another call to the server. To express the choice made by a user,
the client should leave the artistName/albumName empty and provide the
artistId and/or albumId empty on the subsequent call. Once an artistId or
albumId is provided the server will pick up from the given Ids and attempt
to resolve the next phase.
Parameters:
- ArtistName: The name of the artist, gathered from ID3 tags or user input
- AlbumName: The name of the album, also from ID3 or user input
- TrackName: The name of the track
- TrackNum: The track number of the track being matched
- Duration: The duration of the track being matched
- FileName: The name of the file that is being matched. This will only be
used if the ArtistName, AlbumName or TrackName fields are blank.
- ArtistId: The AritstId resolved from an earlier call.
- AlbumId: The AlbumId resolved from an earlier call.
- MaxItems: The maximum number of items to return if the server cannot
determine an exact match.