Spotify Connect Basics

Spotify Connect allows users to control hardware devices from the Spotify mobile app. For example, by selecting a wireless speaker in the Connect menu of the Spotify mobile app, playback will be transferred from the phone to the wireless speaker. The phone continues to work as a remote control, so the user can pause playback, skip tracks, or change the volume on the speaker by using the Spotify mobile app.

The application that runs on the wireless speaker receives notifications through the callbacks defined in the Spotify Embedded SDK. In these callbacks, the application updates the speaker's UI (if any) and plays the audio data that it receives.

For example, when the user transfers playback to the speaker, one of the callbacks that is invoked is SpCallbackPlaybackNotify() with the event kSpPlaybackNotifyBecameActive. When the user pauses playback using the Spotify mobile app, the application receives the event kSpPlaybackNotifyPause.

Note: In order to test Connect, log in to the Spotify mobile app while on the same WiFi as your Spotify Embedded application. Alternatively, if you don't have ZeroConf working, log in with the same user account on your Spotify Embedded application. When you tap the "Devices available" button in the mobile app or the speaker icon in the desktop app, the Spotify Embedded application appears in the list of available speakers under the name that you specified in SpConfig::display_name.

The application is responsible for applying the desired volume level to the audio data that is delivered in the audio data callback.

Whenever the user changes the playback volume of the speaker using Spotify Connect, the callback SpCallbackPlaybackApplyVolume() is invoked. The application can then either set the volume level in the audio driver or apply the volume to the samples when decoding them from the data that eSDK delivers.

In addition, the application is expected to inform the library if the output volume changes without having received a volume change event through Connect. For example, the speaker might have a volume knob that changes the master volume of the device. When this happens, the application should call the function SpPlaybackUpdateVolume() so that Connect-enabled remote control apps can update the volume of the speaker in their UIs.

Note: When the library is initialized, it assumes a volume level of 65535 (maximum volume). The application must invoke SpPlaybackUpdateVolume() at some point after calling SpInit() to inform the library of the actual volume level of the device's audio output.

The following example shows how to do this:

If the device has a UI, it should display information about the currently playing track, such as the track name and artist name, the length of the track, and the current playback position within the track.

It will also want to display the playback status ("playing" or "paused") and whether "shuffle" and "repeat" are enabled.

The Embedded SDK invokes callbacks when any of this information changes. Here is an example that shows how to use two of them, SpCallbackPlaybackNotify() and SpCallbackPlaybackSeek():

In addition to these callbacks, the library contains functions to retrieve the current status of playback. Using these functions, the previous example can be rewritten without callbacks as follows.

Notes

• The notifications kSpPlaybackNotifyNext and kSpPlaybackNotifyPrev cannot be replaced.

• These functions reflect the state of the playback among all Connect-enabled devices, even if the device is not the active playback device.

The playback restrictions are part of the metadata for the current track. Whenever the restrictions change, the application will receive the notification (kSpPlaybackNotifyMetadataChanged). To retrieve the restrictions, call SpGetMetadata() with relative_index set to (kSpMetadataTrackCurrent), and look at the fields in SpMetadata::playback_restrictions:

• A value of 0 means the action is allowed.
• A value other than 0 means the action is not allowed. (See SP_PLAYBACK_RESTRICTION_UNKNOWN for a special case).

The corresponding playback API will most likely fail. For example, when the field "disallow_skipping_next_reasons" is not 0, and the application invokes SpPlaybackSkipToNext(), the API call will either fail with an error or have no effect.

The UI of the application should update according to the restrictions to grey-out/disable any action that is currently not allowed. This is done in order to make clear to the user what is clickable and what is not to avoid confusion.

Restrictions are useful only for the current track. You should not look at the restrictions of the previous or upcoming tracks.

You must not build any solution that assumes some behaviour, because any current behaviour can change in the future if our licences change. For example advertisements might be skippable one day.

If the application wants to check the particular reason why an action is not allowed, it can check which bits of the field are set. For example:

Sometimes the "disallow_XXX_reasons" field for an action can be set to SP_PLAYBACK_RESTRICTION_UNKNOWN. This means that eSDK has not retrieved the restrictions from the backend yet. As soon as eSDK retrieves the information, the notification kSpPlaybackNotifyMetadataChanged will be sent again, and the application can check the field again. Until then treat the action as disallowed.

For example, here is a sequence of events:

• When a new track has just started playing, kSpPlaybackNotifyMetadataChanged is sent.
• When looking at the metadata, the track and artist names might already have changed, but the field disallow_skipping_next_reasons might be set to SP_PLAYBACK_RESTRICTION_UNKNOWN.

This means the eSDK has not received the information about whether there is another track after the one that just started playing. After a short while, the backend sends the information and kSpPlaybackNotifyMetadataChanged is sent again. This time, disallow_skipping_next_reasons might be set to 0.

In the Spotify UI, the "Repeat" button usually cycles through three states: "Don’t repeat", "Repeat", and "Repeat Track". These states are reflected in the eSDK API as follows:

	Don't repeat	Repeat	Repeat Track
Changing	SpPlaybackEnableRepeat(0)	SpPlaybackEnableRepeat(1)	SpPlaybackEnableRepeat(2)
Querying	SpPlaybackGetRepeatMode == 0	SpPlaybackGetRepeatMode == 1	SpPlaybackGetRepeatMode == 2
Restricted?		disallow_toggling_repeat_context_reasons != 0	disallow_toggling_repeat_track_reasons != 0

When implementing the UI in your application, make sure users don’t get stuck in a state when attempting to cycle through the states. For example, if "Repeat Track" is not allowed, the application can’t go from "Repeat" to "Repeat Track", and it must go to "Don’t repeat" directly.

There are additional playback events that the application can react to. Please see the enum SpPlaybackNotification for a complete list.

Important here is to actively listen for the audio playback state. You will have to pause (kSpPlaybackNotifyPause) and unpause (kSpPlaybackNotifyPlay) independently of the audio data arriving from the audio callback.

Audio data may be delivered while you are paused, and you might have to start playback even though no samples have arrived since the last pause - these samples are then already delivered to you and must be kept in your audio pipeline.

Similarly, you should keep track of if you are the active device or not. Only the active device plays audio. You must receive kSpPlaybackNotifyBecameActive in order to be allowed to play audio. It can be received while paused, so that once kSpPlaybackNotifyPlay is then received, you should start playing.

The following code shows how these events can be used.