How to Browse the Artists Catalog

For this tutorial, we want to browse the available artists catalog and then play a karaoke song with no lead vocals and a black background. From the end-user's perspective, this is easily done by browsing the catalog using one of the available filters (popularity, genre, era, and so on) and then making a song selection.

The following steps describe the required endpoint calls for browsing the karaoke artist catalog, finding a song by a specific artists, retrieving a song’s unique identifier, and selecting the appropriate song URI to send to the 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: Browsing the Karaoke Artist Catalog

To browse the artists catalog, we must make a call to GET /v2/artists. We have the option of using the following query parameters to filter the results:

• gender: (Optional) Filter by artists gender (male or female). By default, both genders are included in the search.
• genre: (Optional) Filter by genre.
• starting-letter: (Optional) Filter by the starting letter of the artist name.
• sort-type: (Optional) Filter the results by sort type (a-z or popularity).
• sort-direction: (Optional) Set the sort direction (ascending or descending) for sort-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?gender=&genre=3&starting-letter=t&sort-type=a-z&sort-direction=normal&size=5&page=0

Note that we set the following query parameter values:

• gender=: Default value. Searches for both male and female artists.
• genre=3: Filters results for R&B/Hip-Hop.
• starting-letter=t: Filters for artist names beginning with the letter t.
• sort-type=a-z: Sorts alphabetically.
• sort-direction=normal: Sorts in ascending direction.
• size=5: Returns first 5 karaoke songs.
• page=0: Default value.

Step Result

The endpoint returns the artist IDs and metadata for the first five R&B/Hip-Hop artists that beging with the letter t.

From the results shown in Figure 1, take note of the artist ID for The Youngbloods G:419933 and number of karaoke songs in the catalog (3). We will browse The Youngbloods' song catalog in the next step using the artist ID.

Figure 1: Step 1 sample response

[
// other responses
    {
        "id": "G:1654",
        "name": "The Youngbloods",
        "nb_karaoke_assets": 3, // number of karaoke songs
        "is_blank": false
    },
    {
        "id": "G:419933",
        "name": "The Dramatics",
        "nb_karaoke_assets": 2,
        "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, and MA.
• 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 or popularity).
• sort-direction: (Optional) Set the sort direction (ascending or descending) for sort-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:1654/songs

Note: We did not use any query parameters to filter the results.

Step Result

The endpoint returns song IDs and metadata associated to The Youngbloods three karaoke songs.

From Figure 2, take note of the song ID for "Get Together", KAR:G:3631. We will be using the ID in the next step to find the song URI.

Figure 2: Step 2 sample response

[
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:3631", // song ID
        "title": "Get Together",
        "duration_sec": 286,
        "genre": {
            "id": "2",
            "label": "Pop"
        },
        "release_year": 1967,
        "era": {
            "id": "60s",
            "label": "60s"
        },
        "singer_count": 1,
        "key": "ANaturalMajor",
        "artist_display_name": "The Youngbloods",
        "artists_display_placeholder": "@G:1654",
        "bpm": 97,
        "parental_advisory": "G",
        "lead_gender": "Male",
        "added_date": "2009-06-16",
        "key_scale": "Major",
        "key_accidental": "Natural",
        "key_pitch": "A",
        "languages": [
            {
                "id": "eng",
                "label": "English"
            }
        ],
        "is_album_cover_generic": false,
        "popularity": 0.09564929306507111,
        "album_cover_generic": false,
        "is_blank": false
    },
    // other responses
]

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:

• ids: (Required) The song ID.
• withPlayLink: (Optional) Select whether to include a URL in the respone. Default is true so that it returns a URI.
• videoCodec: (Optional) Select the video codec. Options are h.264 and h.265. Default value is h.264.

For this example we will make the following call:

GET /v2/songs/KAR:G:3631?withPlayLink=true&videoCodec=

Note that we set the following parameter values:

• {id}: Replaced with song ID for "Get Together" KAR:G:3631.
• 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 "Get Together":

• 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

{
// other parameters
    "resources": {
        "video/mp4/a_mix/black/": {
            "mime_type": "video/mp4",
            "uri": "{a_mix black video filePath}",
            "duration_sec": 192,
            "checksum": "44A042298C53A62A1A0B38751B0D8455",
            "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": 192,
            "checksum": "918A39ED447E83EBA5FDB2351A2BD933",
            "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": 192,
            "checksum": "6C78A2EDD589F97BFF129702286A012C",
            "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": 192,
            "checksum": "254B79198D8FFD3A5A6F371B8821B581",
            "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 URI for the a_mix with a black background.

Figure 4: a_mix with a black background sample

{
// other resources
    "resources": {
         "video/mp4/a_mix/black/": {
            "mime_type": "video/mp4",
            "uri": "{a_mix black video filePath}",
            "duration_sec": 192,
            "checksum": "44A042298C53A62A1A0B38751B0D8455",
            "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.