Documentation

GraphQL API

Things every developer should know

Short-lived audio URLs

Audio URLs are short-lived and therefore may expire before they are used by the client. This can happen with long audio tracks or clients that cache URLs too early.

Audio URLs for radio stations are valid for up to 1 hour, but audio URLs for on-demand tracks have a very short expiration time of 5 minutes. This means that you must account for the timing between when URLs are sent to the client and when they are used.

How to handle:
To manage an expired audio URL, the client should get a new audio URL from the playback current query.

 

Lifetime

A (playback) source when used for a specific device will be available for a limited time period.

 

Inactive Streams

There are times when the APS system will prevent the client from advancing to the next track until a user interaction is performed:

In both cases the following will occur:

  1. A PlaybackItem is inserted into the playback sequence, with the following properties:
  1. No actions/events (setStarted, setEnded, progress, etc) should be sent by the client for this PlaybackItem.
  2. If it contains an audioUrl, it can be played to the listener.
  3. It will also have an errorHeader and errorDescription field to display a notification to the listener, although it is up to the developer to decide how they want to handle this scenario.

 

Station and Station Factory

A StationFactory (SF) is used to create a station. A Station (ST) is specific to a user.  Once playback starts with an SF source, the station is created for that user and added to their collection.  If you were to start playback on a source of type ST that does not belong to the current user, you will get an error that it does not exist.

 

Track Rights

Tracks have specific rights that could limit the actions available for the track. For example, even if the listener subscription allows for a replay, the track rights might not allow for it. To know what you should allow for on a track, you can look at the interactions field on the PlaybackItem

Possible values include:

SKIP This item can be skipped
THUMB This item can be thumbed up or down (also known as feedback)
FORCE_ACTIVITY

Force this item to be active in the case of a simultaneous streaming violation

REPLAY This item can be replayed
FORWARD_15_SECONDS  This item can be advanced 15 seconds
BACK_15_SECONDS This item can be rewound 15 seconds
SEEK Seek is allowed on this item
PREVIOUS Skipping back to the previous item is allowed