Skip to main content

General Information

The Karaoke API allows you to develop an interactive karaoke application using the Stingray Karaoke catalogue. This section details the different resources and endpoints you can access using the Karaoke API.

Glossary​

For more information about the vocabulary used in the API, please refer to the Glossary.

Logs​

It is important take into account user statuses, as follows:

  • Free user
  • Trial user
  • Paying user

Stingray is required to report and pay royalties on all song plays.

Please refer to the /play-log endpoint for more information.

note

As of this version, the different type of statuses will be determined by the provided username/password combos. In an upcoming update version of the API, it will be possible (and required) to distinguish the different type of accounts during the login request.

Playing Songs​

Songs are returned with media links based on the available media formats. Since players may support the following features, many links are provided:

  • With visual or black background.
  • With or without lead vocals.
  • Mime type (ex. video/mp4)
  • With or without pre or post-rolls
note

All video links may not be available for all songs. For example, certain songs may only have been produced without lead vocals.

Buffering​

Songs are protected using a signed URL link. Hence, after some time, which can range anything from 15 minutes to few hours, the URI becomes invalid for security reasons. If a link becomes expired, simply request the resource again, and an updated link will be provided.

This approach allows the device/player to buffer media files in advance after fetching the song links.

Lead vocals​

When switching the playback of songs from a version without lead vocals to a version with lead vocals (or vice-versa), the playback position is maintained rather than restarting the video.

Query Parameters​

In API calls, the following query parameters can be used to refine the results.

Filters​

You can use filter query parameters such as genre, gender and language. The filter values for these parameters can be found under the filters section or the /filters endpoint documentation.

Sorting​

You can use sorting parameters based on popularity, titles or names (a-z), etc. Note you can only apply one sorting algorithm at a time.

Pagination​

You can specify page size and number. Take note of the following guidelines:

  • There is a maximum number of items (100) to be returned per request. Any items over the maximum number are ignored.
  • Specify reasonable size values for performance and availability reasons.

Search Recommendations​

It is recommended to follow these guidelines when using query parameters:

  • Throttle the number of calls per client to a maximum of one per 100ms.
  • Only send search requests with three characters or more.
  • There is a maximum length for search text (40 characters). Any characters over the maximum number are ignored.

Thumbnails​

Thumbnails are provided for the following resources:

  • Songs : Album cover is provided
  • Eras : With background, and transparent thumbnails are provided
  • Genres : 2 categories are provided for this resource. First one is a generic art (again with background, and transparent). Second one is intended to be used as a filter of artist for a particular genre.
  • Languages : With background, and transparent thumbnails are provided

Versioning​

The Karaoke API is versioned with a new release every year. To ensure the stability of your app, you must specify a supported version in the URL.

Status and Error Codes​

All API queries return HTTP status codes that contain information regarding the response. Note the following when handling errors:

note

Follow documentation when specifying path and query parameter values.

CodeDescription
200The request was successful.
4xx and 5xx Status Codes
400 Bad RequestThe server cannot process the request.
401 InvalidThe API key is missing or invalid.
5xx ErrorsAn unexpected error occured.