How to Browse a Specific Artist's Catalog
To find a karaoke song, an end-user may prefer to browse their favorite artist’s catalog. For this tutorial, we want to browse a specific artist's catalog and then play a karaoke song with no lead vocals and a black background.
The following steps describe the required endpoint calls for browsing an artist's catalog, finding a song, retrieving a song’s unique identifier, and selecting the appropriate song URI to send to a media player.
Audience
This tutorial is designed for people familiar with JavaScript programming.
Requirements
You must have a valid API key and Bearer Token. For information on how to get the token, refer to Generating Access Tokens.
To run the tutorial, you must download the full OpenAPI specification and then import it into a API testing platform. For this tutorial, we will be using Postman API. For information on how to use Postman, refer to their documentation.
Step 1: Searching the Karaoke Artist Catalog
To search for a specific artist, we must make a call to GET /v2/search-artists. We have the option of using the following query parameters to filter the results:
- name: (Optional) Enter the text to match during the search.
- size: (Optional) Set the number of entries to return in the results. By default, 10 artists are returned.
- page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).
For this example we will make the following call:
GET /v2/search-artists?name=Order&size=3&page=0
Note that we set the following query parameter values:
name=Order: We are searching for artists with Order in their name.size=3: Returns first 3 artists.page=0: Default value.
Step Result
The endpoint returns the artist ID for the artist in the karaoke catalog with Order in their name, New Order.
From the results shown in Figure 1, take note of the artist ID for New Order G:2665. We will browse New Order's song catalog in the next step using the artist ID.
Figure 1: Step 1 sample response
{
"artists": [
{
"id": "G:2665",
"name": "New Order",
"is_blank": false
}
]
}
Step 2: Browsing an Artist's Catalog
To browse an artist's karaoke song catalog, we must make a call to GET /v2/artists/{ids}/songs with the following parameters:
- ids: (Required) The artist ID.
- era: (Optional) Filter for a specific era.
- language: (Optional) Filter by language.
- genre: (Optional) Filter by genre.
- starting-letter: (Optional) Filter by starting letter of the song title.
- duets: (Optional) Filter to return songs with two lead vocalists.
- rating: (Optional) Filter by content rating. Available options are
NR,14,G, andMA. - gender: (Optional) Filter by artists gender (male or female). By default, both genders are included in the search.
- sort-type: (Optional) Filter the results by sort type (
a-z,popularity,date-added, orrelease-year). - sort-direction: (Optional) Set the sort direction (
normalorreverse) forsort-type. - size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
- page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).
For this example we will make the following call:
GET /v2/artists/G:2665/songs?genre=5
Note that we set the following parameter values:
- {ids}: We entered the artist ID G:2665.
genre=5: We are searching for songs in the Rock genre.
Step Result
The endpoint returns song IDs and metadata for songs by New Order defined as "Rock". As shown in Figure 2, the only song that matches this criteria is "Blue Monday".
We will be using song ID for Blue Monday, KAR:G:17475, in the next step to find the song URI.
Figure 2: Step 2 sample response
[
{
"thumbnails": {
"album": "{thumbnail filePath}"
},
"id": "KAR:G:17475", // song ID
"title": "Blue Monday",
"duration_sec": 440,
"genre": {
"id": "5",
"label": "Rock"
},
"release_year": 1983,
"era": {
"id": "80s",
"label": "80s"
},
"singer_count": 1,
"key": "DNaturalMinor",
"artist_display_name": "New Order",
"artists_display_placeholder": "@G:2665",
"bpm": 130,
"parental_advisory": "G",
"lead_gender": "Male",
"added_date": "2017-03-31",
"key_scale": "Minor",
"key_accidental": "Natural",
"key_pitch": "D",
"languages": [
{
"id": "eng",
"label": "English"
}
],
"is_album_cover_generic": true,
"popularity": 0.11994456152121227,
"album_cover_generic": true,
"is_blank": false
}
]
Step 3: Finding the Song URI
To find a song URI to pass to a media player, we must search the song catalog using the song ID from Step 2.
We must make a call to GET /v2/songs/{id} with following parameter values:
- id: (Required) The song ID.
- withPlayLink: (Optional) Select whether to include a URL in the respone. Default is
trueso that it returns a URI. - videoCodec: (Optional) Select the video codec. Options are
h264andh265. Default value ish264.
For this example we will make the following call:
GET /v2/songs/KAR:G:17475?withPlayLink=true&videoCodec=
Note that we set the following parameter values:
- {id}: Replaced with song ID for "Blue Monday"
KAR:G:17475. withPlayLink=true: Returns a secure URI to pass to the media player.videoCodec=: Default value.
Step Result
The endpoint returns the karaoke song URI and metadata for the mutliple versions of "Blue Monday":
- a_mix: No lead vocal version with either a black or animated background.
- c_mix: Includes lead vocal with either a black or animated background.
important
When selecting a video, it is good practice to review the mix_type and background_theme fields to verify the video type.
Figure 3: Step 3 sample response
{
"thumbnails": {
"album": "{thumbnail filePath}"
},
"id": "KAR:G:17475",
"title": "Blue Monday",
// other parameters
"resources": {
"video/mp4/a_mix/black/": {
"mime_type": "video/mp4",
"uri": "{a_mix black video filePath}",
"duration_sec": 446,
"checksum": "DB026B56C33BD27C2256DBCDC5087A3C",
"background_theme": "BLACK",
"mix_type": "A_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
},
"video/mp4/a_mix/animated/": {
"mime_type": "video/mp4",
"uri": "{a_mix animated video filePath}",
"duration_sec": 446,
"checksum": "1EEB1F8505EC8152BA7CB652EDBF77CB",
"background_theme": "ANIMATED",
"mix_type": "A_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
},
"video/mp4/c_mix/animated/": {
"mime_type": "video/mp4",
"uri": "{c_mix animated video filePath}",
"duration_sec": 446,
"checksum": "5FDD2D17A692552EF89B7FF3A3F4EA1E",
"background_theme": "ANIMATED",
"mix_type": "C_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
},
"video/mp4/c_mix/black/": {
"mime_type": "video/mp4",
"uri": "{c_mix black video filePath}",
"duration_sec": 446,
"checksum": "03F090E3F31915302AC826915438432D",
"background_theme": "BLACK",
"mix_type": "C_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
}
},
"album_cover_generic": true,
"is_blank": false
}
Conclusion
As shown in Figure 4, we can find the "Blue Monday" URI for the a_mix with a black background.
Figure 4: a_mix with a black background sample
{
// other parameters
"video/mp4/a_mix/black/": {
"mime_type": "video/mp4",
"uri": "{a_mix black video filePath}",// song URI
"duration_sec": 446,
"checksum": "DB026B56C33BD27C2256DBCDC5087A3C",
"background_theme": "BLACK",
"mix_type": "A_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
},
// other responses
This URI can now be passed to a media player.