Playing a Resource

This tutorial covers how to utilize the Music API to play various resources such as stations, audiobooks, and podcasts.

Prerequisites

Before you begin, make sure you have:

• The authentication credentials required to access the API.
• Familiarity with HTTP methods and response codes.
• Familiarity with HLS and how to play it.

Playing a Linear Resource

Linear resources are resources that have a beginning and an end, such as our audiobook chapters or our podcast episodes. Audiobooks and Podcasts are grouped in this section together because of the similarities between both of them.

Endpoint Overview

The API provides multiple /audiobooks and /podcasts endpoints that allow you to retrieve audiobooks, chapters, podcasts and episodes:

• GET /api/v2/audiobooks/{id}
• GET /api/v2/audiobooks/{id}/chapters/{chapterId}
• GET /api/v2/podcasts/{id}
• GET /api/v2/podcasts/{id}/episodes/{episodeId}
• POST /api/v2/audiobooks/{id}/chapters/{chapterId}/play
• POST /api/v2/podcasts/{id}/episodes/{episodeId}/play
• POST /api/v2/audiobooks/{id}/continue
• POST /api/v2/podcasts/{id}/continue
• GET /api/v2/audiobooks/{id}/continue
• GET /api/v2/podcasts/{id}/continue

Playing an Audiobook or a Podcast

Getting an Audiobook or a Podcast

To play an audiobook or a podcast you must first know what chapter or episode you want to play. You can get this information using our browse endpoints or by using our different get endpoints. Using the basic get can tell you what audiobook or podcast you want to play, and then you can use the chapters or episodes get endpoints to get the information about the chapter or episode you want to play.

Get audiobook by id:

curl -X GET 'https://music-service.stingray.com/api/v2/audiobooks/123' -H 'Authorization: Bearer YOUR_JWT'

Get audiobook chapter by id:

curl -X GET 'https://music-service.stingray.com/api/v2/audiobooks/123/chapters/456' -H 'Authorization: Bearer YOUR_JWT'

Get podcast by id:

curl -X GET 'https://music-service.stingray.com/api/v2/podcasts/123' -H 'Authorization: Bearer YOUR_JWT'

Get podcast episode by id:

curl -X GET 'https://music-service.stingray.com/api/v2/audiobooks/123/episodes/456' -H 'Authorization: Bearer YOUR_JWT'

Playing an Audiobook or a Podcast

To actually play the chapter or episode you can use these endpoints to obtains a streaming link:

Play audiobook chapter:

curl -X POST 'https://music-service.stingray.com/api/v2/audiobooks/123/chapters/456/play' -H 'Authorization: Bearer YOUR_JWT'

Play podcast episode:

curl -X POST 'https://music-service.stingray.com/api/v2/podcasts/123/episodes/456/play' -H 'Authorization: Bearer YOUR_JWT'

Those two endpoints will return an url that then returns a m3u8 file that you can use to play the chapter or episode in any HLS player.

Continuing a Linear Resource

Saving Progress

To save the progress of a linear resource you can use the following endpoints:

Save the progress of an audiobook:

curl -X POST 'https://music-service.stingray.com/api/v2/audiobooks/123/continue' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
  "chapterId": "456",
  "resumePointSec": 1200
}'

Save the progress of a podcast:

curl -X POST 'https://music-service.stingray.com/api/v2/podcasts/123/continue' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
  "episodeId": "456",
  "resumePointSec": 1200
}'

Retrieving Saved Progress

To then get the saved progress you can use the following endpoints:

Get the saved progress of an audiobook:

curl -X 'GET' \
  'https://music-service.stingray.com/api/v2/audiobooks/123/continue' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_JWT'

Get the saved progress of a podcast:

curl -X 'GET' \
  'https://music-service.stingray.com/api/v2/podcasts/123/continue' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_JWT'

With the response of those endpoints you can then use the play endpoints and seek to that point in your player.

Playing a Non-Linear Resource

A non-linear resource is a resource that doesn't have a beginning or an end, such as a stations.

Endpoint Overview

The API provides multiple /stations endpoints that allow you to retrieve stations, play them and see what's playing on them:

• POST /api/v2/stations/{stationId}/play/{playId}/skip
• POST /api/v2/stations/{id}/play
• GET /api/v2/stations/{stationIs}/play/{playId}/songs
• GET /api/v2/stations/{id}

Playing a Station

To play a station you must first know which one you want to play. You can get this information using our browse endpoints or by using our get endpoints.

Get a station by id

curl -X GET 'https://music-service.stingray.com/api/v2/stations/123' -H 'Authorization: Bearer YOUR_JWT'

Once you know what station you want to play you can use the play endpoint to start playing it:

curl -X 'POST' \
  'https://music-service.stingray.com/api/v2/stations/223/play' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_JWT' 

That endpoint returns a playId which is crucial to use the skip functions and obtains what's playing. The endpoint also returns the stream link that you can use to play the station in any HLS player. This is what the response body looks like:

{
  "playId": "c9e47324-cd4b-4f0e-a3f8-e7dbc73b8329",
  "streamLink": "https://lotus.stingray.com/manifest/223/STINGRAY/master.m3u8?playlist-id=a5168e63-6903-4cf9-a313-68d0915b637a&suid=ae459c6a-06b5-4bda-b660-eac508b06f49"
}

Skipping Songs

To skip songs in a station you can use the following endpoint:

curl -X 'POST' \
  'https://music-service.stingray.com/api/v2/stations/123/play/c9e47324-cd4b-4f0e-a3f8-e7dbc73b8329/skip' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_JWT'

The response is similar to the play endpoint, but the stream link will have been slightly modified to skip the currently playing song. To complete the skip process, simply play the new link in an HLS player.

See What's Playing

To see what's playing in a station you've played before you may use the following endpoint:

curl -X 'GET' \
  'https://music-api-service-test.stingray.com/api/v2/stations/123/play/c9e47324-cd4b-4f0e-a3f8-e7dbc73b8329/songs?size=5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_JWT'

In this example you would be checking the currently playing song and the 4 next ones. The response body returned is an array of the songs.

[
  {
    "id": "123",
    "title": "Move",
    "artists": [
      {
        "id": "456",
        "name": "Idina Menzel"
      }
    ],
    "artistDisplay": "Idina Menzel",
    "thumbnail": "https://img.stingray.com/v3/123",
    "albumTitle": ""
  },
  ...
]

Keep in mind that Music API streams music without continuously tracking what the user is listening to. This can cause mismatches between the music being played and what the 'What's Playing' endpoint shows. To keep the playlist accurate, you can use the fromSongId query parameter in the endpoint. This parameter should include the identifier of the song currently playing, which you can find in the stream's metadata tags. For more details on how to find this identifier, refer to this tutorial.