How to Play a Karaoke Song

For this tutorial, we want to play a karaoke song with no lead vocals and an animated background. From the end-user's perspective, this is easily done by using the catalog search feature and then making a song selection.

The following steps describe the required endpoint calls for filtering the karaoke catalog, retrieving a specific 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: Finding a Karaoke Song ID

To find a karaoke song ID, we must first search the karaoke song catalog using the available filter options.

Using the following query parameters, we must make a call to GET /v2/search-songs:

• text: (Required) Enter text to match during the search. By default, the artist name, lyrics, and song title are included in the query. To narrow the search options, refer to the search-fields parameter below.
• genre-id: (Optional) Filter by genre.
• search-fields: (Optional) Select a specific field to consider when searching for the text string. The available values are:
  • title
  • artists
  • lyrics
• 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/search-songs?text=mercy&genre-id=3&search-fields=title&size=5&page=0

Note that we set the following query parameter values:

• text=mercy: Filter results for song titles that contain mercy.
• genre-id=3: Filter results for R&B/Hip-Hop.
• search-fields=title: Sets the text search area to song title.
• 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 R&B/Hip-Hop karaoke songs with songs titles that include mercy.

From the sample response shown in Figure 1, take note of the song ID for "Mercy Mercy Me (The Ecology)" KAR:G:899. We will be using the song ID in Step 2: Finding the Song URI.

Figure 1: Step 1 sample response

{
    "songs": [
        {
            "thumbnails": {
                "album": "{thumbnail filePath}" 
            },
            "id": "KAR:G:899", 
            "title": "Mercy Mercy Me (The Ecology)",
            "duration_sec": 191, 
            "genre": {
                "id": "3",
                "label": "R&B/Hip-Hop"
            },
            "release_year": 1971,
            "era": {
                "id": "70s",
                "label": "70s"
            },
            "singer_count": 1, 
            "key": "ENaturalMajor",
            "artist_display_name": "Marvin Gaye",
            "artists_display_placeholder": "@G:374",
            "bpm": 94,
            "parental_advisory": "G",
            "lead_gender": "Male",
            "added_date": "2004-08-05",
            "key_scale": "Major",
            "key_accidental": "Natural",
            "key_pitch": "E",
            "languages": [
                {
                    "id": "eng",
                    "label": "English"
                }
            ],
            "is_album_cover_generic": true,
            "popularity": 0.10675263516604902,
            "album_cover_generic": true,
            "is_blank": false
        },
        // other results
            ]
}

Step 2: 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 1.

Using the following parameters, we must make a call to GET /v2/songs/{id}:

• ids: (Required) The song ID.
• withPlayLink: (Optional) Select whether to include a URI in the response. 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:899?withPlayLink=true&videoCodec=

Note that we set the following parameter values:

• {id}: Replaced with song ID for "Mercy Mercy Me (The Ecology)" KAR:G:899.
• 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 "Mercy Mercy Me (The Ecology)":

• 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

{
//other parameters

    "is_album_cover_generic": true,
    "popularity": 0.10675263516604902,
    "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 3, we can find the URI for the a_mix with animated background.

Figure 3: a_mix with animated background

"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
        },

This URI can now be passed to a media player.