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.
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.
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:
PlaybackItemis inserted into the playback sequence, with the following properties:
- “type” is either
- 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).
- No actions/events (setStarted, setEnded, progress, etc) should be sent by the client for this
- If it contains an
audioUrl, it can be played to the listener.
- It will also have an
errorDescriptionfield 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.
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
Possible values include:
|SKIP||This item can be skipped|
|THUMB||This item can be thumbed up or down (also known as feedback)|
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|