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.

• The source sticks around for 30 days. If your source ID is being stored for some reason, look at the possible errors for setting a source,
• The audio URL for that source is not available for 30 days, but only 1 hour or 5 minutes depending on the type.

 

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:

• A simultaneous stream violation: Requires a user to take control or defer the stream to another client.
• An idle timeout: When the client has been playing audio for a period of time without any interaction, thus requires explicit intent to continue playback.

In both cases the following will occur:

1. A PlaybackItem is inserted into the playback sequence, with the following properties:

• “type” is either SimStreamViolationItem or IdleTimeoutItem. See PlaybackItem.
• there is no “index” property, since it falls outside of the regular source sequence.
• “interactions” will contain “FORCE_ACTIVE” (this can be used by clients to detect the inactive stream and stop playback, instead of having to look for specific types).

2. No actions/events (setStarted, setEnded, progress, etc) should be sent by the client for this PlaybackItem.
3. If it contains an audioUrl, it can be played to the listener.
4. 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