How to Browse the Karaoke Song Catalog

When selecting a karaoke song, the end-user may not have a specific artist or song in mind and would prefer to browse the song catalog. This is can done by browsing the catalog using one of the available filters (sort-type, genre, era, and so on) and then making a song selection.

The following steps describe the required endpoint calls for browsing the karaoke song catalog, 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: Browsing the Karaoke Song Catalog

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

• era: (Optional) Filter for a specific era.
• language: (Optional) Filter by language.
• genre: (Optional) Filter by genre.
• starting-letter: (Optional) Filter by the starting letter of the artist name.
• 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 , popularity, date-added, or release-year).
• sort-direction: (Optional) Set the sort direction (normal or reverse) 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).
• ignore-default-lanuage-filter: (Optional) Select whether to ignore the language filter.

For this example we will make the following call:

GET /v2/songs?duets=true&sort-type=date-added&sort-direction=normal&size=5&page=0&ignore-default-language-filter=false

Note that we set the following query parameter values:

• duets=true: Filters for songs that have two lead vocalists.
• sort-type=date-added: Sorts by date the song was added to our system. In this case, the most recently added songs will appear first.
• sort-direction=normal: Sorts in ascending direction.
• size=5: Returns first 5 karaoke songs.
• page=0: Default value.

Step Result

The endpoint returns the song IDs and metadata for the first five duet songs.

From the results shown in Figure 1, take note of the song ID for "We Don't Talk About Bruno (Duet)" KAR:G:3259333. We will be using the ID in the next step to find the song URI.

Figure 1: Step 1 sample response

[
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:2411566",
        "title": "What's It Gonna Be",
        "duration_sec": 321,
        "genre": {
            "id": "3",
            "label": "R&B/Hip-Hop"
        },
        // other paramaters
        "added_date": "2022-04-25",
      // other parameters
    },
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:3259333",
        "title": "We Don't Talk About Bruno (Duet)",
        "duration_sec": 213,
        "genre": {
            "id": "12",
            "label": "Disney"
        },
        // other parameters
        "added_date": "2022-04-08",
       // other parameters
    },
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:3583",
        "title": "From This Moment On (Duet)",
        "duration_sec": 225,
        "genre": {
            "id": "6",
            "label": "Country"
        },
        // other parameters
        "added_date": "2022-03-03",
       // other parameters
    },
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:7556",
        "title": "That's Another Story (Duet)",
        "duration_sec": 210,
        "genre": {
            "id": "6",
            "label": "Country"
        },
        // other parameters
        "added_date": "2021-12-01",
       // other parameters
    },
    {
        "thumbnails": {
            "album": "{thumbnail filePath}"
        },
        "id": "KAR:G:2542509",
        "title": "Have Yourself A Merry Little Christmas",
        "duration_sec": 217,
        "genre": {
            "id": "1",
            "label": "Holiday"
        },
       // other parameters
        "added_date": "2021-08-20",
      // other parameters
    }
]

Step 2: Finding the Song URI

To find a song URI to pass to the media player, we must search the song catalog using the song ID from Step 1.

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 true so that it returns a URI.
• videoCodec: (Optional) Select the video codec. Options are h264 and h265. Default value is h264.

For this example we will make the following call:

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

Note that we set the following parameter values:

• {id}: Replaced with song ID for "We Don't Talk About Bruno (Duet)" KAR:G:3259333.
• 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 "We Don't Talk About Bruno (Duet)":

• 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 2: Step 2 sample response

{
    "thumbnails": {
        "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:3259333",
    "title": "We Don't Talk About Bruno (Duet)",
    "duration_sec": 213,
    "genre": {
        "id": "12",
        "label": "Disney"
    },
   // other parameters
    "resources": {
        "video/mp4/a_mix/black/": {
            "mime_type": "video/mp4",
            "uri": "{a_mix black video filePath}",
            "duration_sec": 221,
            "checksum": "2DFA26A66C6495D76B03E4D99B1E285F",
            "background_theme": "BLACK",
            "mix_type": "A_MIX",
            "preroll_uri": "{preRoll filePath}",
            "logos": [
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_right"
                },
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_left"
                }
            ],
            "is_sample": false
        },
        "video/mp4/a_mix/animated/": {
            "mime_type": "video/mp4",
            "uri": "{a_mix animated video filePath}",
            "duration_sec": 221,
            "checksum": "40FAB65A8CBB3C032F9425B361C14923",
            "background_theme": "ANIMATED",
            "mix_type": "A_MIX",
            "preroll_uri": "{preRoll filePath}",
            "logos": [
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_right"
                },
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_left"
                }
            ],
            "is_sample": false
        },
        "video/mp4/c_mix/animated/": {
            "mime_type": "video/mp4",
            "uri": "{c_mix animated video filePath}",
            "duration_sec": 221,
            "checksum": "79001498306868A5630E23B33A27F86C",
            "background_theme": "ANIMATED",
            "mix_type": "C_MIX",
            "preroll_uri": "{preRoll filePath}",
            "logos": [
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_right"
                },
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_left"
                }
            ],
            "is_sample": false
        },
        "video/mp4/c_mix/black/": {
            "mime_type": "video/mp4",
            "uri": "{c_mix black video filePath}",
            "duration_sec": 221,
            "checksum": "C97273F1AA86D39B1D1F9543DA8DAB87",
            "background_theme": "BLACK",
            "mix_type": "C_MIX",
            "preroll_uri": "{preRoll filePath}",
            "logos": [
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_right"
                },
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_left"
                }
            ],
            "is_sample": false
        }
    },
    "album_cover_generic": true,
    "is_blank": false
}

Conclusion

As shown in Figure 3, we can find the URI for the a_mix with a black background.

Figure 3: 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}", // URI path
            "duration_sec": 221,
            "checksum": "2DFA26A66C6495D76B03E4D99B1E285F",
            "background_theme": "BLACK",
            "mix_type": "A_MIX",
            "preroll_uri": "{preRoll filePath}",
            "logos": [
                {
                    "uri": "{logo filePath}", 
                    "alignment": "bottom_right"
                },
                {
                    "uri": "{logo filePath}",
                    "alignment": "bottom_left"
                }
            ],
            "is_sample": false
        },
        // other responses

This URI can now be passed to a media player.