Tutorials
Playback with Pandora
Playback is the most important feature of Pandora’s GraphQL API. Once you have access to the rich library of over 30 million tracks, you would probably want to play some music.
This tutorial will guide you through these steps:
- Setting a source for playback
- Playing a source
- Moving from one track to the next
- Giving feedback on a track
The tutorial will link to the reference documentation for each query/mutation that you can use to test it out in the API Explorer. If you prefer to test with command-line, you can look at this curl command example to test the queries.
1. Setting a source for playback
A source is used for playback. Once you set a source for playback, this source is your current source. This source is set for the listener account linked to the access token in the header as well as the device UUID supplied as a parameter. It is possible to query the current source if a new session is started by providing your device UUID or you can set a new source for playback. Feedback and playback actions like pause, skip, etc. are all performed on the current source.
There are 2 ways to start playback, you either get your current source or you set a new source.
Getting the current source
Get the current source by supplying your listener OAuth access token in the header and your device UUID as a parameter. The playback current query is used for this.
Here is an example of the response:
{
"data": {
"playback": {
"current": {
"audioUrl": "https://t3-4.p-cdn.us/access/4801370763899556419?version=5&lid=1375438868&token=LUZc3vC8xvkGaQdrq/0xBMGDAjY/a8dmJfou5L987iBzw9lAhC0Z8kAY5HX3f+VVFQSfhbOMYR4UT2/7AzCO5unIJ7FB+w+98no8Q/TTOE5CG2+ku0X5ERhkHEHW1D3YB6vclvUw8FKSBKKo99+5u80EANpHFSGymakJ+PY8g0pDYeLerxaKh/lBrIlL94xlcJ0Y+MGzFzXyMvNTggRxr476Z1hpgZ6laGjhUHt1zfOI6B09dvba4f4jR1wGU9Ll+L22aBIPnmMifMsxzqZuqaKiHTVn/n2pJLy5RW08Gs+IT3zbJfcGiUFeSq4FXzukpuov1FOUQkj3BViQ3B8I+w==",
"interactions": [
"SKIP",
"REPLAY",
"THUMB"
],
"index": 1,
"trackToken": "P8q7bU-LSkOkouJlpPz4KYHlxV0EZ2D7J4_lo0MAQJXK-rq7vhAbsIZMs7AJAVLagIB9JlMb2sEBFNQuSrSvuODO4yO6Rm66e",
"track": {
"duration": 157,
"art": {
"url": "https://dyn-images.p-cdn.com/?l=images%2Fpublic%2Fint%2F4%2F2%2F5%2F9%2F081227889524%3Acover()&w=150&h=150"
},
"artist": {
"name": "The Cure"
}
}
}
}
}
}
As mentioned in the reference documentation, you will get an error if a source has not been set previously for this device and listener or if the source has expired.
In this case you will move on to the next section to set a new source.
Set a new source
Set a new source by supplying your listener access token in the header as well as your device UUID and source ID as a parameter of the mutation. The playback setSource mutation is used.
The following features of the API will supply you with sources to get a source ID for playback:
Let’s use search as an example. Perform a search as described in the reference documentation.
query {
search(query:"cranberries", types:[SF], pagination: { limit: 2 }) {
items {
... on StationFactory {
id
name
}
}
}
}
* Add your OAuth bearer token to the Authorization header
curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{"operationName":null,"variables":{},"query":"{ search(query: \"cranberries\", types: [SF], pagination: {limit: 2}) { items { ... on StationFactory { id name } } }}"}'
{
"data": {
"search": {
"items": [
{
"id": "SF:16722:777",
"name": "The Cranberries"
},
{
"id": "SF:21586:14399",
"name": "Zombie"
}
]
}
}
}
You can now use the first item as a playback source by providing your device UUID and this source ID (SF:16722:777) to the setSource playback mutation. Look at the setSource reference documentation. Take note that your source ID will be different to the one used in this example. Read more about stations and station factories here.
When running the mutation, the response should look like this:
{
"data": {
"playback": {
"setSource": {
"id": "ST:0:4370482112453380116",
"type": "ST",
"current": {
"index": 0,
"trackToken": "PeXBEYIrRP5X4D-E-D0yszobpEVvU1tPaRcKPdMkOl3r_pil26L-b0OWcjowVYHSF9wiGv4q6f2Bo99a-LCuBsWu7P8BX2zGJ",
"audioUrl": "https://audio-sv5-t3-2-v4v6.pandora.com/access/?version=5&lid=1375438868&token=J8gXRwKBAhdLxH6F2Zr9f3NKifFKMW5sTZIOc4IhXCkmtwc67YQl5SOO/GvB0xO+0FBGvnJEBvEiPc3QoFqGoOXgPQ5JbiRUYwGFMvOjuj1fcpRnKSFVFP3NCJBOR6rN7+SQA+rWzJWmwXB2XwEGdg37/Ml7ylVlPLcz5M1SbcC9oGnV9x4vurN2sTyIgYqi75BavEHiWfEpY40pqJVBDpdFw2/fj3W3o22PKezgZ42CA6tuTopePL6VJx8grK63RWny9bfRYtkpSIBHxTRVT42kgcEI09zcjkvC3S+bZFnSQ3Ce5V7n57DNRt9/Ki3RNDlIkCwxylXzxlRsLSUjjQ==",
"interactions": [
"SKIP",
"REPLAY",
"THUMB"
],
"track": {
"duration": 307,
"art": {
"url": "https://dyn-images.p-cdn.com/?l=images%2Fpublic%2Fint%2F0%2F2%2F0%2F1%2F00602498841020%3Acover()&w=150&h=150"
},
"artist": {
"name": "The Cranberries"
}
}
}
}
}
}
}
With both getting a current source and setting a new source, the response will contain metadata of the track as well as the audio URL. You will use the audio URL to start playback and the metadata to display information about the track currently playing, if you have an interface.
2. Playing a source
Now that you have a source to play, you should start sending events to the API to notify the server that your source has started, its progress, or that it has ended.
The first action will be to notify that the track has started playing. This is done by the setStarted mutation.
Continuing with the source that you set in the previous step, this is how you would notify that this has started playing:
mutation {
playback {
setStarted(deviceUuid: "deviceXYZ", sourceId: "ST:0:4370482112453380116",
index: 0, elapsedTime: 200) {
status
}
}
}
* Add your OAuth bearer token to the Authorization header
curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{"operationName":null,"variables":{},"query":"mutation { playback { setStarted(deviceUuid: \"deviceXYZ\", sourceId: \"ST:0:4370482112453380116\", index: 0, elapsedTime: 200) { status } }}"}'
You should also send progress on the elapsed time of the track. This is done with the setProgress mutation.
We will look at how to end a track next.
3. Moving from one track to the next
Once your track has ended you would want the next track to start. To get the next track you will first need to notify via the API that the track has ended. This is done with the setEnded mutation.
mutation {
playback {
setEnded(deviceUuid: "deviceXYZ", sourceId: "ST:0:4370482112453380116",
index: 0, elapsedTime: 200, reason: NORMAL) {
status
current {
... on TrackItem {
track {
name
}
}
}
}
}
}
* Add your OAuth bearer token to the Authorization header
curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{"operationName":null,"variables":{},"query":"mutation { playback { setEnded(deviceUuid: \"deviceXYZ\", sourceId: \"ST:0:4370482112453380116\", index: 0, elapsedTime: 200, reason: NORMAL) { status current { ... on TrackItem { track { name } } } } }}"}'
The result will contain the next track in the current field. Using this field is recommended to prevent unecessary network calls. Alternatively you can query the current source, which will have the next track of the source. Your response should look similar to this:
{
"data": {
"playback": {
"current": {
"sourceId": "ST:0:4370482112453380116",
"audioUrl": "https://audio-dc6-t3-2-v4v6.pandora.com/access/4615047660178624107?version=5&lid=1375438868&token=QN1O/lGusGgVaOsCgrQQ8/W85kbuFuu9/14+gaVWqcLICyjEGfOLRMugYMqJOP5v3GWRhPHJgHAtLvkRkeaD8ncgi/77cYtKkaueQrM2GOWuzz55SymIr3NjIFLSvNhET4jXh0nQFhD95JSljV/6X8aI6jkb7SfqysBO9bmUfFNNbykCm5CDczgv/n7aY5KJc/WxqtyS/1P3LB2fS/Pb6M7kne+Rv3UlgjPiBbzYgEYn5eDbmaRfCbQJdzGLGanbXuKT5SQV1W3cHRTbCeRSQYGE/uH78RL+X/nY2Lw5TbgHkt63xmRcJ0VWko4Q0vo5fLTF1dAmWorkGrxOTXnNPg==",
"interactions": [
"SKIP",
"REPLAY",
"THUMB"
],
"index": 1,
"trackToken": "PLU2OqRVY3dv4D-E-D0yszk6eR-p5OJVRHMmNi9ktAQwaQeV-ZgHiFuWcjowVYHSF-tUHHiWqObmAHu5gYmiZzRQdh2Q78mBl",
"track": {
"id": "TR:113047",
"duration": 313,
"art": {
"url": "https://dyn-images.p-cdn.com/?l=images%2Fpublic%2Fint%2F8%2F2%2F5%2F5%2F606949005528%3Acover()&w=150&h=150"
},
"artist": {
"name": "The Wallflowers"
}
}
}
}
}
}
4. Giving feedback on a track
To set feedback on your current track, you would use the setFeedback mutation. For the track retrieved in step 3, it will look like this:
mutation {
feedback {
setFeedback
(
targetId: "TR:113047",
sourceContextId: "ST:0:4370482112453380116",
value: UP,
trackToken: "PLU2OqRVY3dv4D-E-D0yszk6eR-p5OJVRHMmNi9ktAQwaQeV-ZgHiFuWcjowVYHSF-tUHHiWqObmAHu5gYmiZzRQdh2Q78mBl",
deviceUuid: "deviceXYZ",
elapsedTime: 200
)
{
status
current {
... on TrackItem {
audioUrl
interactions
index
track {
name
artist{
name
}
}
}
}
}
}
}
* Add your OAuth bearer token to the Authorization header
curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{"operationName":null,"variables":{},"query":"mutation { feedback { setFeedback(targetId: \"TR:113047\", sourceContextId: \"ST:0:4370482112453380116\", value: UP, trackToken: \"PLU2OqRVY3dv4D-E-D0yszk6eR-p5OJVRHMmNi9ktAQwaQeV-ZgHiFuWcjowVYHSF-tUHHiWqObmAHu5gYmiZzRQdh2Q78mBl\", deviceUuid: \"deviceXYZ\", elapsedTime: 200) { status current { ... on TrackItem { audioUrl interactions index track { name artist { name } } } } } }}"}'
This was just a short introduction to some of the features available for playback via the API. Read more about other features in the playback reference articles.