How to Play a Party Mix
Stingray provides curated karaoke Party Mixes. These mixes contain a list of songs curated by our content experts. End-users just need to find the right mix and start singing; no need to browse through the artists of song catalogs.
The following steps describe the required endpoint calls for finding a Party Mix, retrieving a specific 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: Finding a Party Mix
To find a Party Mix, we must make a call to GET /v2/party-mixes with the following optional query parameters:
- 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/party-mixes?size=5&page=0
Note that we set the following query parameter values:
size=5: Returns first 5 Party Mixes.page=0: Default value.
Step Result
The endpoint returns the first five Party Mixes along with their metadata and song IDs.
From the sample response shown in Figure 1, take note of the multiple song IDs for the "Party Time" mix. We will be using these song IDs in Step 2: Finding the Song URIs.
Figure 1: Step 1 sample response
[
{
"thumbnails": {
"background": "{thumbnail filePath}",
"transparent": "{thumbnail filePath}"
},
"title": "Party Time",
"id": "KPM:G:2602571",
"song_ids": [
"KAR:G:1804",
"KAR:G:3365",
"KAR:G:4148",
"KAR:G:9287",
"KAR:G:13860",
"KAR:G:2845325",
"KAR:G:2999898",
"KAR:G:3045407",
"KAR:G:3067429",
"KAR:G:3115008"
],
"is_featured": true,
"is_blank": false
},
// other reponses
]
Step 2: Finding the Song URIs
We will use the song IDs from step 1 to find their respective URIs to pass to a media player.
Using the following parameters, we must make a call to GET /v2/songs/{ids}:
- ids: (Required) The song IDs.
- withPlayLink: (Optional) Select whether to include a URI in the response. 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 an endpoint call for the first three song IDs:
GET /v2/songs/KAR:G:1804,KAR:G:3365,KAR:G:4148?withPlayLink=true&videoCodec=
Note that we set the following parameter values:
- {ids}: Replaced with first three song IDs: KAR:G:1804, KAR:G:3365, and KAR:G:4148.
withPlayLink=true: Returns a secure URI to pass to the media player.videoCodec=: Default value.
Step Result
The endpoint returns the karaoke song URIs and metadata for the mutliple versions of each song:
- 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
{
"KAR:G:1804": {
// other parameters including song title, artist, and more.
"resources": {
"video/mp4/a_mix/black/": {
"mime_type": "video/mp4",
"uri": "{a_mix black video filePath}",
"duration_sec": 256,
"checksum": "4D2FBBEA6A1A6CC38120B263884DB71D",
"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": 256,
"checksum": "9F78CACA93F4029F941A003905D120FC",
"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 black animated filePath}",
"duration_sec": 256,
"checksum": "9539D9C4E23E12E055CB57D0089E2EE7",
"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": 256,
"checksum": "4D817E8FA3F36499C88A22069CE5E0EE",
"background_theme": "BLACK",
"mix_type": "C_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
}
},
"album_cover_generic": false,
"is_blank": false
},
"KAR:G:3365": {
// other parameters including song title, artist, and more.
"resources": {
"video/mp4/a_mix/black/": {
"mime_type": "video/mp4",
"uri": "{a_mix black video filePath}",
"duration_sec": 265,
"checksum": "CAB109996932E7CFA4695004558DE1AB",
"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": 265,
"checksum": "EBA6D83F0B9979D036B19836C77D49DC",
"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": 265,
"checksum": "69A38D4FAD6B3526A70F1197065C3B4C",
"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": 265,
"checksum": "2F7E0E18971775BDC052544BA9E27AAC",
"background_theme": "BLACK",
"mix_type": "C_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
}
},
"album_cover_generic": false,
"is_blank": false
},
"KAR:G:4148": {
// other parameters including song title, artist, and more.
"resources": {
"video/mp4/a_mix/black/": {
"mime_type": "video/mp4",
"uri": "{a_mix black video filePath}",
"duration_sec": 404,
"checksum": "0BD228C785AD81781EB9B56069BC920F",
"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": 404,
"checksum": "CCFA0F576C3FE862C05203C451FC8000",
"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": 404,
"checksum": "2C696D8C24221D86BCF15D93059E2419",
"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": 404,
"checksum": "3069B0DDFB6FCA32D3B7D7F4D8448988",
"background_theme": "BLACK",
"mix_type": "C_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
}
},
"album_cover_generic": false,
"is_blank": false
}
}
Conclusion
As shown in Figure 3, we can find the song URIs for the a_mix with animated background.
Figure 3: a_mix with animated background
"KAR:G:4148": {
// other parameters including song title, artist, and more.
"resources": {
// other formats
"video/mp4/a_mix/animated/": {
"mime_type": "video/mp4",
"uri": "{a_mix animated video filePath}", // song URI
"duration_sec": 404,
"checksum": "CCFA0F576C3FE862C05203C451FC8000",
"background_theme": "ANIMATED",
"mix_type": "A_MIX",
"preroll_uri": "{preRoll filePath}",
"logos": [
{
"uri": "{logo filePath}",
"alignment": "bottom_right"
}
],
"is_sample": false
},
// other formats
},
"album_cover_generic": false,
"is_blank": false
}
These URIs can now be passed to a media player to play the Party Time mix.