Skip to main content

Getting a Song

Song Structure​

Before jumping in the calls, let's take a look at the song structure provided by the API.

{
  "thumbnails": {
    album": "https://file-repository.com/file-path"
  },
  "id": "KAR:G:XXXXXXX",
  "title": "Shake It Off",
  "durationSec": 216,
  "genre": {},
  "releaseYear": 2014,
  "era": {},
  "singerCount": 1,
  "key": "GNaturalMajor",
  "artistDisplayName": "Taylor Swift",
  "artistsDisplayPlaceholder": "@G:XX",
  "bpm": 160,
  "parentalAdvisory": "NR",
  "leadGender": "Female",
  "addedDate": "2014-12-23",
  "keyScale": "Major",
  "keyAccidental": "Natural",
  "keyPitch": "G",
  "languages": [],
  "popularity": 0,
  "resources": {},
  "isBlank": false
}

Song Structure Rundown​

  • thumbnails - contains the links to the images associated to the song.
  • id - the unique identifier of the song
  • General information about the song - (title, duration_sec, genre, release_year, era ,singer_count, etc.)
  • is_blank - if the song exist or not
  • resources - contains the links to play the karaoke asset (video/mp3/etc)

Song resources structure​

Let's take a closer look to the resources field:

"video/mp4/a_mix/black/" : {
  "mimeType": "video/mp4",
  "uri": "https://file-repository.com/file-path",
  "durationSec": 150,
  "checksum": "CFF1479284BB14694E09C433F594EF5C",
  "backgroundTheme": "ANIMATED",
  "mixType": "A_MIX",
  "prerollUri": "https://file-repository.com/file-path",
  "videoCodec": "H265",
  "logos": [
    {
      "uri": "https://file-repository.com/file-path",
      "alignment": "bottom_right"
    }
  ],
  "isSample": false
}
  • mime_type - nature and format of the asset
  • uri - the link of to play the asset
  • duration_sec - the duration of the song in seconds
  • background_theme - the background theme of the asset (animated or no background)
  • mix_type - this is the field that represents if there are lead vocals or not
  • isSample - if the asset corresponds to a 30 seconds sample
note

You might have noticed that the resources field is a map, where the key is a string representing an overview of the asset associated to it. However, it should not be used to identify the asset. Please use the fields inside the object instead.

note

The links generatd by the API are only valid for 24 hours.

Get a song by ID​

Each song asset has its own unique identifier. With this id, it is possible to retrieve the song and its resources through the endpoint /songs/{id}.

curl -X GET "https://karaoke-api-service-prod.stingray.com:443/v2/songs/KAR%3AG%3A2774223" -H "Authorization: Bearer foo" -H "accept: application/json"

But... How do you figure out what the id of a song is ?

Karaoke API offers multiple ways to browse our catalog and retrieve a song's id:

  • By searching
  • By looking up songs by an artist
  • By using different type of filters
  • Through our curated playlists (Party Mixes)

We will be exploring these solutions in the following pages.