Main

#include "spotify_embedded.h"

Macros and Constants

Return to header index

Define Value
SP_API_VERSION 77
SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024
SP_MAX_BRAND_NAME_LENGTH 32
SP_MAX_MODEL_NAME_LENGTH 30
SP_MAX_PLATFORM_NAME_LENGTH 64
SP_MAX_CLIENT_ID_LENGTH 32
SP_MAX_OS_VERSION_LENGTH 64
SP_MAX_DISPLAY_NAME_LENGTH 64
SP_MAX_UNIQUE_ID_LENGTH 64
SP_MAX_USERNAME_LENGTH 64
SP_MAX_DEVICE_ALIASES 8
SP_NO_ALIAS_SELECTED -1
SP_MAX_METADATA_NAME_LENGTH 255
SP_MAX_METADATA_URI_LENGTH 127
SP_MAX_TRACK_UID_LENGTH 64
SP_MAX_METADATA_IMAGE_URL_LENGTH 255
SP_PLAYER_COOKIE_LENGTH 32
SP_MAX_PLAYBACK_ID_LENGTH 32
SP_MAX_PUBLIC_KEY_LENGTH 149
SP_MAX_DEVICE_ID_LENGTH 64
SP_MAX_DEVICE_TYPE_LENGTH 15
SP_MAX_VERSION_LENGTH 30
SP_MAX_GROUP_STATUS_LENGTH 15
SP_MAX_TOKEN_TYPE_LENGTH 30
SP_MAX_SCOPE_LENGTH 64
SP_MAX_CLIENT_KEY_LENGTH 511
SP_MAX_ZEROCONF_BLOB_LENGTH 2047
SP_MAX_LOGIN_ID_LENGTH 64
SP_MAX_AVAILABILITY_LENGTH 15
SP_MAX_PARTNER_NAME_LENGTH 48
SP_MAX_FILENAME_LENGTH 63
SP_ZEROCONF_DISABLED 0
SP_ZEROCONF_SERVE 1
SP_ZEROCONF_SERVE_HTTP_ONLY 2
SP_ZEROCONF_SERVE_MDNS_ONLY 3
SP_SCOPE_STREAMING “streaming”
SP_DEVICE_ALIAS_ATTRIBUTE_GROUP 1
SP_GLOBAL_ATTRIBUTE_VOICE 2
SP_MAX_SUPPORTED_FORMATS 8
SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1
SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2
SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4
SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8
SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK 16
SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK 32
SP_PLAYBACK_RESTRICTION_UNKNOWN 64
SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128

Data Structures

Return to header index

Data Structure Description
SpPlaybackRestrictions Playback restrictions.
SpMetadata Track metadata.
SpFormat Mapping of which media formats are supported in which DRM.
SpZeroConfDeviceAlias ZeroConf DeviceAlias.
SpZeroConfVars ZeroConf variables.
SpSampleFormat Sample format of the audio data.
SpPlaybackCallbacks Callbacks to be registered with SpRegisterPlaybackCallbacks
SpDebugCallbacks Callbacks to be registered with SpRegisterDebugCallbacks
SpConnectionCallbacks Callbacks to be registered with SpRegisterConnectionCallbacks
SpDeviceAlias Device alias definition.
SpConfig Configuration.
SpDeviceAliasCallbacks Callbacks to be registered with SpRegisterDeviceAliasCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackError Callback for reporting errors to the application.
SpCallbackPlaybackNotify Callback for notifying the application about playback-related events.
SpCallbackPlaybackSeek Callback to notify the application of a change in the playback position.
SpCallbackPlaybackApplyVolume Callback to notify the application of a volume change using Spotify Connect.
SpCallbackConnectionNotify Callback for notifying the application about events related to the connection to Spotify
SpCallbackConnectionNewCredentials Callback for passing a login blob to the application.
SpCallbackConnectionMessage Callback for sending a message to the user.
SpCallbackDebugMessage Callback for sending debug messages/trace logs.
SpCallbackSelectedDeviceAliasChanged Callback for receiving the selected device alias from the backend.
SpCallbackDeviceAliasesUpdateDone Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases

Enumerations

Return to header index

Functions

Return to header index

Function Description
SpInit Initialize the library.
SpFree Shut down the library.
SpGetLibraryVersion Retrieve a version string for the library.
SpConnectionSetConnectivity Set the type of network connection of the device.
SpConnectionGetConnectivity Get the connectivity that was set with SpConnectionSetConnectivity
SpConnectionLoginBlob Log in a user to Spotify using a credentials blob.
SpConnectionLoginPassword Log in a user to Spotify using a password.
SpConnectionLoginOauthToken Log in a user to Spotify using a Spotify OAuth token.
SpConnectionLogout Log the user out of Spotify
SpConnectionIsLoggedIn Is the user logged in to Spotify
SpConnectionGetAckId Get the last Ack ID.
SpGetCanonicalUsername Get the canonical username of the logged in user.
SpSetDisplayName Set the display name for the device or application.
SpSetVolumeSteps Set the volume steps the device is capable of.
SpSetDeviceIsGroup Control if the device represents a group.
SpEnableConnect Enable Connect functionality for this device.
SpDisableConnect Disable Connect functionality for this device.
SpGetSelectedDeviceAlias Return the currently selected device alias.
SpPumpEvents Allow the library to perform asynchronous tasks and process events.
SpRegisterConnectionCallbacks Register callbacks related to the connection to Spotify
SpRegisterDebugCallbacks Register a callback that receives debug messages/trace logs.
SpRegisterPlaybackCallbacks Register playback-related callbacks.
SpGetMetadata Retrieve metadata for a track in the current track list.
SpGetMetadataImageURL Return the HTTP URL to an image file from a spotify:image: URI.
SpGetPlayerCookie Obtain player cookie for current playback.
SpPlaybackPlay Start or resume playback.
SpPlaybackPause Pause playback.
SpPlaybackSkipToNext Skip playback to the next track in the track list.
SpPlaybackSkipToPrev Skip playback to the previous track in the track list.
SpPlaybackSeek Seek to a position within the current track.
SpPlaybackSeekRelative Seek a relative amount of time within the current track.
SpPlaybackGetPosition Get the current playback position within the track.
SpPlaybackUpdateVolume Request a change to the playback volume.
SpPlaybackGetVolume Get the playback volume level.
SpPlaybackIsPlaying Is the playback status playing or paused.
SpPlaybackIsAdPlaying Is the current track an Ad or not.
SpPlaybackIsShuffled Is “shuffle” mode enabled.
SpPlaybackIsRepeated Is “repeat” mode enabled.
SpPlaybackGetRepeatMode Which “repeat” mode is on.
SpPlaybackIsActiveDevice Is the device the active playback device.
SpPlaybackEnableShuffle Enable or disable “shuffle” mode.
SpPlaybackEnableRepeat Enable or disable “repeat” mode.
SpPlaybackCycleRepeatMode Cycle through the available repeat modes.
SpPlaybackSetBitrate Change the bitrate at which compressed audio data is delivered.
SpPlaybackSetAvailableToPlay Allow or disallow the device to start playback.
SpPlaybackIsAvailableToPlay Is the device available for playback.
SpPlaybackSetDeviceInactive Set the device inactive.
SpPlaybackIsDeviceControllable Is the device controllable.
SpPlaybackSetDeviceControllable Allow or disallow the device to be controllable.
SpPlaybackIncreaseUnderrunCount Increase the underrun counter of the current track.
SpPlaybackSetBandwidthLimit Set a limit on the download speed.
SpPlaybackSetRedeliveryMode Activates redelivery of audio data on play or resume playback.
SpPlaybackIsRedeliveryModeActivated Gets the status of redelivery mode.
SpZeroConfGetVars Get variables for ZeroConf, mainly the “getInfo” request.
SpZeroConfAnnouncePause Temporarily pause ZeroConf mDNS announcements.
SpZeroConfAnnounceResume Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause
SpConnectionLoginZeroConf Log in a user to Spotify using a ZeroConf credentials blob.
SpGetBrandName  
SpGetModelName  
SpRegisterDeviceAliasCallbacks Register callbacks related to device aliases.
SpSetDeviceAliases Update the device alias definitions.
SpRestrictDrmMediaFormats  
SpRestoreDrmMediaFormats  

Macros and Constants

SP_API_VERSION

Return to Main macros

#define SP_API_VERSION 77

The version of the API defined in this header file.

See also

Return to Main macros

#define SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024

Minimum recommended size of the buffer SpConfig::memory_block

SP_MAX_BRAND_NAME_LENGTH

Return to Main macros

#define SP_MAX_BRAND_NAME_LENGTH 32

Maximum length of the brand name string (not counting terminating NULL)

See also

SP_MAX_MODEL_NAME_LENGTH

Return to Main macros

#define SP_MAX_MODEL_NAME_LENGTH 30

Maximum length of the model name string (not counting terminating NULL)

See also

SP_MAX_PLATFORM_NAME_LENGTH

Return to Main macros

#define SP_MAX_PLATFORM_NAME_LENGTH 64

Maximum length of the platform_name string (not counting terminating NULL)

See also

SP_MAX_CLIENT_ID_LENGTH

Return to Main macros

#define SP_MAX_CLIENT_ID_LENGTH 32

Maximum length of the client id string (not counting terminating NULL)

See also

SP_MAX_OS_VERSION_LENGTH

Return to Main macros

#define SP_MAX_OS_VERSION_LENGTH 64

Maximum length of the os version string (not counting terminating NULL)

See also

SP_MAX_DISPLAY_NAME_LENGTH

Return to Main macros

#define SP_MAX_DISPLAY_NAME_LENGTH 64

Maximum length of the device display name (not counting terminating NULL)

See also

SP_MAX_UNIQUE_ID_LENGTH

Return to Main macros

#define SP_MAX_UNIQUE_ID_LENGTH 64

Maximum length of the device's unique ID (not counting terminating NULL)

See also

SP_MAX_USERNAME_LENGTH

Return to Main macros

#define SP_MAX_USERNAME_LENGTH 64

Maximum length of usernames (not counting terminating NULL)

See also

SP_MAX_DEVICE_ALIASES

Return to Main macros

#define SP_MAX_DEVICE_ALIASES 8

Maximum number of device aliases that can be configured.

See also

SP_NO_ALIAS_SELECTED

Return to Main macros

#define SP_NO_ALIAS_SELECTED -1

A value to use for alias_index when aliases are not used.

See also

SP_MAX_METADATA_NAME_LENGTH

Return to Main macros

#define SP_MAX_METADATA_NAME_LENGTH 255

Maximum length of display names in track metadata (not counting terminating NULL)

See also

Notes:

SP_MAX_METADATA_URI_LENGTH

Return to Main macros

#define SP_MAX_METADATA_URI_LENGTH 127

Maximum length of URIs in track metadata (not counting terminating NULL)

See also

SP_MAX_TRACK_UID_LENGTH

Return to Main macros

#define SP_MAX_TRACK_UID_LENGTH 64

Maximum length of Track UID in track metadata (not counting terminating NULL)

See also

SP_MAX_METADATA_IMAGE_URL_LENGTH

Return to Main macros

#define SP_MAX_METADATA_IMAGE_URL_LENGTH 255

Maximum length of URLs (not counting terminating NULL)

See also

Return to Main macros

#define SP_PLAYER_COOKIE_LENGTH 32

Length of player cookie (not counting terminating NULL)

See also

SP_MAX_PLAYBACK_ID_LENGTH

Return to Main macros

#define SP_MAX_PLAYBACK_ID_LENGTH 32

Maximum length of Playback-Id (not counting terminating NULL)

See also

SP_MAX_PUBLIC_KEY_LENGTH

Return to Main macros

#define SP_MAX_PUBLIC_KEY_LENGTH 149

Maximum length of the public key used in ZeroConf logins (not counting terminating NULL)

See also

SP_MAX_DEVICE_ID_LENGTH

Return to Main macros

#define SP_MAX_DEVICE_ID_LENGTH 64

Maximum length of the device ID used for ZeroConf logins (not counting terminating NULL)

See also

SP_MAX_DEVICE_TYPE_LENGTH

Return to Main macros

#define SP_MAX_DEVICE_TYPE_LENGTH 15

Maximum length of the device type string (not counting terminating NULL)

See also

SP_MAX_VERSION_LENGTH

Return to Main macros

#define SP_MAX_VERSION_LENGTH 30

Maximum length of the library version string (not counting terminating NULL)

See also

SP_MAX_GROUP_STATUS_LENGTH

Return to Main macros

#define SP_MAX_GROUP_STATUS_LENGTH 15

Maximum length of the group status string (not counting terminating NULL)

See also

SP_MAX_TOKEN_TYPE_LENGTH

Return to Main macros

#define SP_MAX_TOKEN_TYPE_LENGTH 30

Maximum length of the token type used for OAuth logins (not counting terminating NULL)

See also

SP_MAX_SCOPE_LENGTH

Return to Main macros

#define SP_MAX_SCOPE_LENGTH 64

Maximum length of the scope used for OAuth login (not counting terminating NULL)

See also

SP_MAX_CLIENT_KEY_LENGTH

Return to Main macros

#define SP_MAX_CLIENT_KEY_LENGTH 511

Maximum length of the client key (not counting terminating NULL)

See also

SP_MAX_ZEROCONF_BLOB_LENGTH

Return to Main macros

#define SP_MAX_ZEROCONF_BLOB_LENGTH 2047

Maximum length of the ZeroConf blob (not counting terminating NULL)

See also

SP_MAX_LOGIN_ID_LENGTH

Return to Main macros

#define SP_MAX_LOGIN_ID_LENGTH 64

Maximum length of the login ID used for ZeroConf logins (not counting terminating NULL)

See also

SP_MAX_AVAILABILITY_LENGTH

Return to Main macros

#define SP_MAX_AVAILABILITY_LENGTH 15

Maximum length of the availability string (not counting terminating NULL)

See also

SP_MAX_PARTNER_NAME_LENGTH

Return to Main macros

#define SP_MAX_PARTNER_NAME_LENGTH 48

Maximum length of the Partner Name (TSP_PARTNER_NAME) (not counting terminating NULL) The longest partner name when this was written was "imagination_technologies_mips" at 29 characters.

SP_MAX_FILENAME_LENGTH

Return to Main macros

#define SP_MAX_FILENAME_LENGTH 63

Maximum length of filename fields (not counting terminating NULL)

SP_ZEROCONF_DISABLED

Return to Main macros

#define SP_ZEROCONF_DISABLED 0

Value for SpConfig::zeroconf_serve when disabling built-in ZeroConf stack. Complete ZeroConf stack has to run externally.

See also

SP_ZEROCONF_SERVE

Return to Main macros

#define SP_ZEROCONF_SERVE 1

Value for SpConfig::zeroconf_serve when activating complete built-in ZeroConf stack (both mDNS and http server).

See also

SP_ZEROCONF_SERVE_HTTP_ONLY

Return to Main macros

#define SP_ZEROCONF_SERVE_HTTP_ONLY 2

Value for SpConfig::zeroconf_serve when activating built-in ZeroConf http server only while running the ZeroConf mDNS server externally.

See also

SP_ZEROCONF_SERVE_MDNS_ONLY

Return to Main macros

#define SP_ZEROCONF_SERVE_MDNS_ONLY 3

Value for SpConfig::zeroconf_serve when activating built-in ZeroConf mDNS server only while running the ZeroConf http server externally.

See also

SP_SCOPE_STREAMING

Return to Main macros

#define SP_SCOPE_STREAMING "streaming"

Value for SpConfig::scope when implementing a basic streaming device.

SP_DEVICE_ALIAS_ATTRIBUTE_GROUP

Return to Main macros

#define SP_DEVICE_ALIAS_ATTRIBUTE_GROUP 1

Set this bit in the device alias attributes integer (SpDeviceAlias::attributes) to mark a device alias as representing a group.

Notes:

SP_GLOBAL_ATTRIBUTE_VOICE

Return to Main macros

#define SP_GLOBAL_ATTRIBUTE_VOICE 2

Set this bit in the global attributes integer (SpConfig::global_attributes) to mark that this device supports voice.

SP_MAX_SUPPORTED_FORMATS

Return to Main macros

#define SP_MAX_SUPPORTED_FORMATS 8

See also

SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1

The track is already paused.

SP_PLAYBACK_RESTRICTION_NOT_PAUSED

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2

The track is already playing.

SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4

Licensing rules disallow this action.

SP_PLAYBACK_RESTRICTION_AD_DISALLOW

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8

Action can't be performed while an ad is playing.

SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK 16

There is no track before the current one in the currently playing context.

SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK 32

There is no track after the current one in the currently playing context.

SP_PLAYBACK_RESTRICTION_UNKNOWN

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_UNKNOWN 64

The action is restricted, but no reason is provided.

This means that eSDK has not retrieved the restrictions from the backend yet and therefore the action is not allowed right now. As soon as eSDK retrieves the information, the notification kSpPlaybackNotifyMetadataChanged will be sent, and the application can check the field again.

SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT

Return to Main macros

#define SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128

The action is restricted for context level reasons.

Data Structures

SpPlaybackRestrictions

Return to Main data structures

Playback restrictions.

struct SpPlaybackRestrictions {
    uint32_t disallow_pausing_reasons;
    uint32_t disallow_resuming_reasons;
    uint32_t disallow_seeking_reasons;
    uint32_t disallow_peeking_prev_reasons;
    uint32_t disallow_peeking_next_reasons;
    uint32_t disallow_skipping_prev_reasons;
    uint32_t disallow_skipping_next_reasons;
    uint32_t disallow_toggling_repeat_context_reasons;
    uint32_t disallow_toggling_repeat_track_reasons;
    uint32_t disallow_toggling_shuffle_reasons;
};
uint32_t disallow_pausing_reasons

Bitfield of reasons the pause action is not allowed.

uint32_t disallow_resuming_reasons

Bitfield of reasons the resume action is not allowed.

uint32_t disallow_seeking_reasons

Bitfield of reasons seeking is not allowed.

uint32_t disallow_peeking_prev_reasons

Bitfield of reasons peeking on the previous track is not allowed.

uint32_t disallow_peeking_next_reasons

Bitfield of reasons peeking on the next track is not allowed.

uint32_t disallow_skipping_prev_reasons

Bitfield of reasons skipping to the previous track is not allowed.

uint32_t disallow_skipping_next_reasons

Bitfield of reasons skipping to the next track is not allowed.

uint32_t disallow_toggling_repeat_context_reasons

Bitfield of reasons setting repeat context is not allowed.

uint32_t disallow_toggling_repeat_track_reasons

Bitfield of reasons setting repeat track is not allowed.

uint32_t disallow_toggling_shuffle_reasons

Bitfield of reasons toggling shuffle is not allowed.

SpMetadata

Return to Main data structures

Track metadata.

See also

struct SpMetadata {
    char playback_source;
    char playback_source_uri;
    char track;
    char track_uri;
    char artist;
    char artist_uri;
    char album;
    char album_uri;
    char album_cover_uri;
    char original_track_uri;
    uint32_t duration_ms;
    int32_t index;
    char track_uid;
    uint32_t original_index;
    uint32_t bitrate;
    struct SpPlaybackRestrictions playback_restrictions;
    char playback_id;
    enum SpContent content_type;
    enum SpMediaType media_type;
    enum SpAudioQuality audio_quality;
};
char playback_source

Display name of the playback source. E.g., the name of the playlist from which playback was initiated (UTF-8-encoded)

char playback_source_uri

Spotify URI of the playback source (in the form "spotify:xxxxxx:xxxxxxx...")

Notes:
char track

Display name of the track (UTF-8-encoded)

char track_uri

Spotify URI of the track (in the form "spotify:track:xxxxxxx...")

Notes:
char artist

Display name of the artist of the track (UTF-8-encoded)

char artist_uri

Spotify URI of the artist of the track (in the form "spotify:artist:xxxxxxx...")

Notes:
char album

Display name of the track's album (UTF-8-encoded)

char album_uri

Spotify URI of the track's album (in the form "spotify:album:xxxxxxx...")

Notes:
char album_cover_uri

Spotify URI of the album's cover art image (in the form "spotify:image:xxxxxxx...")

Use the function SpGetMetadataImageURL to convert this to an HTTP URL to the actual image file.

char original_track_uri

Spotify URI of the original track before relinking (in the form "spotify:track:xxxxxxx...")

If the track was relinked this field would contain the Spotify URI of the original track before relinking. If track was not relinked this would be equal to the track_uri. This field is helpful to identify whether the track is already in the user collection.

Notes:
  • Typical use case would be: user adds track to the collection, later on platform integration code wants to check if the current track is in the user collection. Due to track relinking the track_uri might differ from the one that was saved in the collection previously. In order to mitigate this issue, integration should use original_track_uri for that purpose. For more info about track relinking refer to track relinking guide on developer.spotify.com
  • Applications can use the Spotify Web APIs https://developer.spotify.com/documentation/web-api/ to get detailed information about the item.
uint32_t duration_ms

Playback duration of the track in milliseconds.

int32_t index

Index of the track in the currently playing context.

This is the index of the track in the currently playing context (eg. playlist, artist, radio, etc). Since the contents of the underlying context can change, the index is correct from the time when the track is loaded, but may occasionally be out of date if the context is actively changing.

Notes:
  • Index is less than zero if the track is from a different context.
char track_uid

Track UID of the track in the currently playing context.

See also
uint32_t original_index

Index of the track in the original (unchanged) playing context.

It's not affected by shuffle logic.

uint32_t bitrate

The bitrate of the track in kbps. 0 means "unplayable".

struct SpPlaybackRestrictions playback_restrictions

Restrictions that apply to playback and transitions related to this track.

Restriction reasons are provided as bitfields inside this struct. Each member of this struct represents one individual action that might be restricted, and its value is a combination of the reasons that are currently in effect. A value of zero means that the action is not currently restricted in any way.

Notes:
  • This functionality is supported only from version 3.0 of the Spotify Embedded SDK and higher. Older versions will never report restriction reasons for any action.
Example:

SpMetadata metadata;
SpGetMetadata(&metadata,0);
if (metadata.playback_restrictions.disallow_skipping_next_reasons !=0){
//Generalcaseforskippingtonexttracknotbeingallowed
…
}
If(metadata.playback_restrictions.disallow_skipping_next_reasons &
SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW !=0){
//Specificcaseofnotallowedtoskipduetolicensingrules
…
}
char playback_id

Playback-id of this playback of this specific track.

Playback-id uniquely identifies a single playback of a track. If the same track exists twice in a context, each instance will have a unique playback-id. It is valid for only one playback of a track and once the track is played or skipped-over, the playback-id is no longer valid e.g if you skip a track and then come back to it using skip-prev, the playback-id changes.

enum SpContent content_type

Content type of this track.

See also
enum SpMediaType media_type

Media type of this track.

See also
enum SpAudioQuality audio_quality

Audio quality of this track.

See also

SpFormat

Return to Main data structures

Mapping of which media formats are supported in which DRM.

See also

struct SpFormat {
    enum SpDrmFormat drm;
    uint64_t media;
};
enum SpDrmFormat drm

DRM format which the integration supports.

uint64_t media

Supported media formats for a DRM.

Bitmask of media formats that the integration supports for this DRM format. The list of known media formats is in SpMediaFormat enumeration. Integration needs to fill this bitmask with the formats that it can decode and play. This field is used to determine which media formats will be delivered to the integration. For example, if the integration supports both Spotify ogg/vorbis and mp3, the bitmask would be:

Example:

media =(1 kSpMediaFormatSpotifyOggVorbis)|(1 kSpMediaFormatMp3);

SpZeroConfDeviceAlias

Return to Main data structures

ZeroConf DeviceAlias.

This structure contains information about a single device alias, as returned by SpZeroConfGetVars

See also

struct SpZeroConfDeviceAlias {
    uint32_t id;
    int is_group;
    char display_name;
};
uint32_t id

String to be sent in the "id" field of the alias in the "getInfo" response.

int is_group

Boolean (0 = "false", 1 = "true") to be sent in the "isGroup" field of the alias in the "getInfo" response.

char display_name

String to be sent in the "name" field of the alias in the "getInfo" response.

SpZeroConfVars

Return to Main data structures

ZeroConf variables.

This structure contains the fields that the application needs for ZeroConf, mainly what to send in the response to the "getInfo" request. See the ZeroConf manual for more information.

See also

struct SpZeroConfVars {
    char public_key;
    char device_id;
    char remote_name;
    char device_type;
    char library_version;
    int resolver_version;
    char group_status;
    int webserver_current_port;
    char token_type;
    char client_id;
    char scope;
    char availability;
    uint32_t product_id;
    struct SpZeroConfDeviceAlias aliases;
    uint32_t alias_count;
    struct SpFormat supported_drm_media_formats;
    uint64_t supported_capabilities;
};
char public_key

String to be sent in the "publicKey" field of the "getInfo" response[*].

char device_id

String to be sent in the "deviceID" field of the "getInfo" response[*].

char remote_name

String to be sent in the "remoteName" field of the "getInfo" response[*].

char device_type

String to be sent in the "deviceType" field of the "getInfo" response[*].

char library_version

String to be sent in the "libraryVersion" field of the "getInfo" response[*].

int resolver_version

Integer to be sent as string in the "resolverVersion" field of the "getInfo" response[*].

char group_status

String to be sent in the "groupStatus" field of the "getInfo" response[*].

int webserver_current_port

Current internal ZeroConf webserver port number. To be used when running an external mDNS server together with an internal webserver.

char token_type

String to be sent in the "tokenType" field of the "getInfo" response[*].

char client_id

String to be sent in the "clientID" field of the "getInfo" response[*].

char scope

String to be sent in the "scope" field of the "getInfo" response[*].

char availability

String to be sent in the "availability" field of the "getInfo" response[*].

uint32_t product_id

Integer to be sent in the "productID" field of the "getInfo" response[*].

struct SpZeroConfDeviceAlias aliases

Array of SpZeroConfDeviceAlias to be sent in the "aliases" field of the "getInfo" response[*].

uint32_t alias_count

Number of valid items in aliases array.

struct SpFormat supported_drm_media_formats

Array of SpFormat to be sent in the "supported_drm_media_formats" field of the "getInfo" response[*].

uint64_t supported_capabilities

Integer representing a bitmask to be sent in the "supported_capabilities" field of the "getInfo" response[*].

SpSampleFormat

Return to Main data structures

Sample format of the audio data.

struct SpSampleFormat {
    int channels;
    int sample_rate;
};
int channels

Number of channels (1 = mono, 2 = stereo)

int sample_rate

Sample rate in Hz (such as 22050, 44100 or 48000)

SpPlaybackCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterPlaybackCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpPlaybackCallbacks {
    SpCallbackPlaybackNotify on_notify;
    SpCallbackPlaybackSeek on_seek;
    SpCallbackPlaybackApplyVolume on_apply_volume;
};
SpCallbackPlaybackNotify on_notify

Notification callback.

SpCallbackPlaybackSeek on_seek

Seek position callback.

SpCallbackPlaybackApplyVolume on_apply_volume

Apply volume callback.

SpDebugCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterDebugCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpDebugCallbacks {
    SpCallbackDebugMessage on_message;
};
SpCallbackDebugMessage on_message

Debug message callback.

SpConnectionCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterConnectionCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpConnectionCallbacks {
    SpCallbackConnectionNotify on_notify;
    SpCallbackConnectionNewCredentials on_new_credentials;
    SpCallbackConnectionMessage on_message;
};
SpCallbackConnectionNotify on_notify

Notification callback.

SpCallbackConnectionNewCredentials on_new_credentials

Credentials blob callback.

SpCallbackConnectionMessage on_message

Connection message callback.

SpDeviceAlias

Return to Main data structures

Device alias definition.

This struct is used to define (optional) device aliases. It's a part of the SpConfig struct which will be passed to SpInit to initialize the eSDK.

struct SpDeviceAlias {
    const char *display_name;
    uint32_t attributes;
};
const char * display_name

A UTF-8 encoded display name for an alias of the application/device.

The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL.

uint32_t attributes

Attributes for this device alias.

Attributes is an unsigned integer interpreted as a bitfield. Different attributes ar OR:ed together and stored in the integer.

Example:

SpDeviceAlias alias={0}; //ormemset()
aliases.display_name = "Mygroup" ;
aliases.attributes= SP_DEVICE_ALIAS_ATTRIBUTE_GROUP |SP_DEVICE_ALIAS_SOME_OTHER_ATTRIBUTE;

SpConfig

Return to Main data structures

Configuration.

See also

struct SpConfig {
    int api_version;
    void *memory_block;
    uint32_t memory_block_size;
    const char *unique_id;
    const char *display_name;
    uint32_t global_attributes;
    struct SpDeviceAlias device_aliases;
    const char *brand_name;
    const char *brand_display_name;
    const char *model_name;
    const char *model_display_name;
    const char *platform_name;
    const char *client_id;
    uint32_t product_id;
    const char *scope;
    const char *os_version;
    enum SpDeviceType device_type;
    enum SpPlaybackBitrate max_bitrate;
    SpCallbackError error_callback;
    void *error_callback_context;
    int zeroconf_serve;
    const char *host_name;
    int zeroconf_port;
    int zeroconf_port_range;
    struct SpFormat supported_drm_media_formats;
};
int api_version

The version of the API contained in this header file. Must be set to SP_API_VERSION.

void * memory_block

Pointer to a memory block to be used by the library.

The block is suggested to be at least SP_RECOMMENDED_MEMORY_BLOCK_SIZE bytes in size. Smaller values are accepted, but may lead to degraded performance, or playback failure.

uint32_t memory_block_size

Size of the memory_block buffer in bytes.

const char * unique_id

A NULL-terminated character string that uniquely identifies the device (such as a MAC address)

The string will be truncated to SP_MAX_UNIQUE_ID_LENGTH characters, not counting the terminating NULL. The library may use this to distinguish this device from other Spotify Connect-enabled devices that the users has. On any given device, the ID should not change between calls to SpInit

const char * display_name

A UTF-8-encoded display name for the application/device.

When using Spotify Connect, this is the name that the Spotify app will use in the UI to refer to this instance of the application/this device. The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL. The display name can be changed later with SpSetDisplayName

Notes:
  • If device aliases are used, display_name must be set to NULL. If device aliases are not used, display_name must be defined and not empty.
uint32_t global_attributes

The global attributes is a bitfield where each attribute is OR:ed together and stored in this integer.

These attributes must be valid for each device alias.

Example:

conf.global_attributes= SP_GLOBAL_ATTRIBUTE_VOICE |SP_GLOBAL_ATTRIBUTE_SOME_OTHER;
struct SpDeviceAlias device_aliases

Device alias definitions. These are optional, if you don't want to define aliases this array must be zeroed.

A user could switch between these aliases by selecting a different alias for playback through the Spotify apps (or by other means where applicable like through voice control), and let an integration perform different audio routing depending on which alias was selected, without disrupting the current session or any ongoing streaming. The array has SP_MAX_DEVICE_ALIASES slots. Any slot which contains NULL as the alias name is ignored.

See also Notes:
const char * brand_name

A NULL-terminated string containing the brand name of the hardware device (for hardware integrations)

This should be an ASCII string containing only letters, digits, "_" (underscore), "-" (hyphen) and "." (period). SpInit returns kSpErrorInvalidArgument if this is not specified or if the string is longer than SP_MAX_BRAND_NAME_LENGTH characters.

const char * brand_display_name

A UTF-8-encoded brand name of the hardware device (for hardware integrations). Should be very similar to brand_name.

The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL.

const char * model_name

A NULL-terminated string containing the model name of the hardware device (for hardware integrations)

This should be an ASCII string containing only letters, digits, "_" (underscore), "-" (hyphen) and "." (period). SpInit returns kSpErrorInvalidArgument if this is not specified or if the string is longer than SP_MAX_MODEL_NAME_LENGTH characters.

const char * model_display_name

A UTF-8-encoded model name of the hardware device (for hardware integrations)

The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL.

const char * platform_name

A NULL-terminated string containing the platform identifier.

SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_PLATFORM_NAME_LENGTH characters.

const char * client_id

A NULL-terminated string containing the client id of the application.

The Client ID identifies the application using Spotify, Register your application here. This can be an ASCII string containing only hexadecimal characters, or NULL SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_CLIENT_ID_LENGTH characters.

uint32_t product_id

An integer enumerating the product for this partner.

The (Client ID, Product ID) pair will uniquely identify this product in the Spotify backend. That could determine things like license, icons, and other behaviour as needed.

const char * scope

A NULL-terminated string containing the OAuth scope requested when authenticating with the Spotify backend.

This can be a comma-separated string of Spotify scopes, or NULL (which would mean the default SP_SCOPE_STREAMING = "streaming") SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_SCOPE_LENGTH characters.

const char * os_version

A NULL-terminated string containing the os version running on the hardware.

This should be an ASCII string containing only printable characters or NULL. SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_OS_VERSION_LENGTH characters.

enum SpDeviceType device_type

The device type that best describes this product.

This device type will be reported to client applications and might result in a suitable icon being shown, etc. SpInit returns kSpErrorInvalidArgument if this is invalid

enum SpPlaybackBitrate max_bitrate

The maximum bitrate to use for playback.

Leave as default to use the maximum available bitrate (high). The bitrate may drop automatically to compensate for low network speeds. Use SpSetPlaybackBitrate to change the bitrate.

SpCallbackError error_callback

Pointer to a callback function that will receive error notifications.

void * error_callback_context

Application-defined pointer that will be passed unchanged as the context argument to the error_callback callback.

int zeroconf_serve

Not applicable in this eSDK configuration.

const char * host_name

Not applicable in this eSDK configuration.

int zeroconf_port

Not applicable in this eSDK configuration.

int zeroconf_port_range

Not applicable in this eSDK configuration.

struct SpFormat supported_drm_media_formats

Mapping of DRM formats and media formats that the integration supports.

See also Example:

struct  SpFormat supported_drm_media_formats[SP_MAX_SUPPORTED_FORMATS];
memset(supported_drm_media_formats,0, sizeof (supported_drm_media_formats));
supported_drm_media_formats[0].drm = kSpDrmFormatUnencrypted;
supported_drm_media_formats[0].media =
(1 kSpMediaFormatSpotifyOggVorbis)|(1 kSpMediaFormatMp3);
supported_drm_media_formats[1].drm = kSpDrmFormatFairPlay;
supported_drm_media_formats[1].media =(1 kSpMediaFormatMp4AAC);

SpDeviceAliasCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterDeviceAliasCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpDeviceAliasCallbacks {
    SpCallbackSelectedDeviceAliasChanged on_selected_device_alias_changed;
    SpCallbackDeviceAliasesUpdateDone on_device_aliases_update_done;
};
SpCallbackSelectedDeviceAliasChanged on_selected_device_alias_changed

Selected device alias updated callback.

SpCallbackDeviceAliasesUpdateDone on_device_aliases_update_done

Device alias list updated.

Typedefs

SpCallbackError()

Return to Main typedefs

typedef void(* SpCallbackError)(SpError error, void *context)

Callback for reporting errors to the application.

To register this callback, set the field SpConfig::error_callback when invoking the function SpInit

Parameters

     
[in] SpError error Error code
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackNotify()

Return to Main typedefs

typedef void(* SpCallbackPlaybackNotify)(enum SpPlaybackNotification event, void *context)

Callback for notifying the application about playback-related events.

To register this callback, use the function SpRegisterPlaybackCallbacks

Parameters

     
[in] enum SpPlaybackNotification event Type of event
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackSeek()

Return to Main typedefs

typedef void(* SpCallbackPlaybackSeek)(uint32_t position_ms, void *context)

Callback to notify the application of a change in the playback position.

To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked when SpPlaybackSeek is invoked or when the user seeks to a position within the track using Spotify Connect.

Parameters

     
[in] uint32_t position_ms New position within the track in milliseconds
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackApplyVolume()

Return to Main typedefs

typedef void(* SpCallbackPlaybackApplyVolume)(uint16_t volume, uint8_t remote, void *context)

Callback to notify the application of a volume change using Spotify Connect.

To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked in two cases: When the user changes the playback volume using Spotify Connect. When the application invoked SpPlaybackUpdateVolume In both cases, the application is responsible for applying the new volume to its audio output. The application should never invoke SpPlaybackUpdateVolume from this callback, as this might result in an endless loop.

Parameters

     
[in] uint16_t volume Volume in the range 0 (silence) to 65535 (max volume)
[in] uint8_t remote Set to 1 if the volume was changed using Spotify Connect, 0 otherwise
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionNotify()

Return to Main typedefs

typedef void(* SpCallbackConnectionNotify)(enum SpConnectionNotification event, void *context)

Callback for notifying the application about events related to the connection to Spotify

To register this callback, use the function SpRegisterConnectionCallbacks

Parameters

     
[in] enum SpConnectionNotification event Type of event
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionNewCredentials()

Return to Main typedefs

typedef void(* SpCallbackConnectionNewCredentials)(const char *credentials_blob, const char *username, void *context)

Callback for passing a login blob to the application.

To register this callback, use the function SpRegisterConnectionCallbacks The application may save the credentials_blob for subsequent logins using the function SpConnectionLoginBlob The application should also discard any credentials blobs for this user that it received previously, either through this callback or through ZeroConf (see the ZeroConf manual). Note: If credentials_blob is an empty string, the application MUST delete any existing saved credentials for the account, and must not attempt to login again with the empty credentials. This happens when a permanent logout is requested.

Parameters

     
[in] const char * credentials_blob Credentials to be passed to SpConnectionLoginBlob
[in] const char * username user name to be passed to SpConnectionLoginBlob
[in] void * context Context pointer that was passed when registering the callback

See also

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionMessage()

Return to Main typedefs

typedef void(* SpCallbackConnectionMessage)(const char *message, void *context)

Callback for sending a message to the user.

To register this callback, use the function SpRegisterConnectionCallbacks This callback is invoked when Spotify wants to display a message to the user. The message is meant to be displayed to the user as-is and should not be interpreted by the application (the format of the messages may change without notice). If the application does not have a graphical user interface, it can safely ignore this callback.

Parameters

     
[in] const char * message Message to be displayed to the user.
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackDebugMessage()

Return to Main typedefs

typedef void(* SpCallbackDebugMessage)(const char *debug_message, void *context)

Callback for sending debug messages/trace logs.

To register this callback, use the function SpRegisterDebugCallbacks In special builds of the library, this callback receives debug messages that the application may write to its logs. The application should not interpret the messages (the format of the messages may change without notice).

Parameters

     
[in] const char * debug_message Message to be logged
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackSelectedDeviceAliasChanged()

Return to Main typedefs

typedef void(* SpCallbackSelectedDeviceAliasChanged)(uint32_t alias_index, void *context)

Callback for receiving the selected device alias from the backend.

To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked whenever the selected device alias is updated. This can happen when, for example, the user selects an alias from Spotify Connect device picker.

Parameters

     
[in] uint32_t alias_index Index of the device alias which was selected
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackDeviceAliasesUpdateDone()

Return to Main typedefs

typedef void(* SpCallbackDeviceAliasesUpdateDone)(SpError error_code, void *context)

Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases

To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked when the operation started by SpSetDeviceAliases has finished.

Parameters

     
[in] SpError error_code if the update was successful, the value is kSpErrorOk
[in] void * context Context pointer that was passed when registering the callback

Notes:

  • The application should not block or call API functions that are not allowed in the callback.

Enumerations

SpError

Return to Main enumerations

enum SpError {
    kSpErrorOk,
    kSpErrorFailed,
    kSpErrorInitFailed,
    kSpErrorWrongAPIVersion,
    kSpErrorNullArgument,
    kSpErrorInvalidArgument,
    kSpErrorUninitialized,
    kSpErrorAlreadyInitialized,
    kSpErrorLoginBadCredentials,
    kSpErrorNeedsPremium,
    kSpErrorTravelRestriction,
    kSpErrorApplicationBanned,
    kSpErrorGeneralLoginError,
    kSpErrorUnsupported,
    kSpErrorNotActiveDevice,
    kSpErrorAPIRateLimited,
    kSpErrorReentrancyDetected,
    kSpErrorMultiThreadingDetected,
    kSpErrorTryAgain,
    kSpErrorDuringLogout,
    kSpErrorPermanentConnectionError,
    kSpErrorEntropyFailure,
    kSpErrorZeroConfErrorStart,
    kSpErrorZeroConfBadRequest,
    kSpErrorZeroConfUnknown,
    kSpErrorZeroConfNotImplemented,
    kSpErrorZeroConfNotInstalled,
    kSpErrorZeroConfNotLoaded,
    kSpErrorZeroConfNotAuthorized,
    kSpErrorZeroConfCannotLoad,
    kSpErrorZeroConfSystemUpdateRequired,
    kSpErrorZeroConfSpotifyUpdateRequired,
    kSpErrorZeroConfLoginFailed,
    kSpErrorZeroConfInvalidPublicKey,
    kSpErrorZeroConfMissingAction,
    kSpErrorZeroConfInvalidAction,
    kSpErrorZeroConfInvalidArguments,
    kSpErrorZeroConfNoSpotifySession,
    kSpErrorZeroConfSpotifyError,
    kSpErrorPlaybackErrorStart,
    kSpErrorGeneralPlaybackError,
    kSpErrorPlaybackRateLimited,
    kSpErrorPlaybackCappingLimitReached,
    kSpErrorAdIsPlaying,
    kSpErrorCorruptTrack,
    kSpErrorContextFailed,
    kSpErrorPrefetchItemUnavailable,
    kSpAlreadyPrefetching,
    kSpStorageReadError,
    kSpStorageWriteError,
    kSpPrefetchDownloadFailed,
    kSpErrorBusy,
    kSpErrorUnavailable,
    kSpErrorNotAllowed,
    kSpErrorNetworkRequired,
    kSpErrorNotLoggedIn,
    kSpErrorInProgress,
    kSpErrorPlaybackInitiation,
    kSpErrorPresetFailed,
    kSpErrorInvalidRequest,
    kSpErrorInvalidTrackId,
    kSpErrorIncorrectMsPlayed,
    kSpErrorDeviceNotControllable,
    kSpErrorPlaybackInitiationTimeout,
    kSpErrorGeneralDownloadError,
};
kSpErrorOk

The operation was successful.

kSpErrorFailed

The operation failed due to an unspecified issue.

kSpErrorInitFailed

The library could not be initialized.

See also
kSpErrorWrongAPIVersion

The library could not be initialized because of an incompatible API version.

When calling SpInit you are required to set the field SpConfig::api_version to SP_API_VERSION. This error indicates that the library that the application is linked against was built for a different SP_API_VERSION. There might be an issue with the include or library paths in the build environment, or the wrong Embedded SDK shared object is loaded at runtime.

See also
kSpErrorNullArgument

An unexpected NULL pointer was passed as an argument to a function.

kSpErrorInvalidArgument

An unexpected argument value was passed to a function.

kSpErrorUninitialized

A function was invoked before SpInit or after SpFree was called.

kSpErrorAlreadyInitialized

SpInit was called more than once.

kSpErrorLoginBadCredentials

Login to Spotify failed because of invalid credentials.

See also
kSpErrorNeedsPremium

The operation requires a Spotify Premium account.

kSpErrorTravelRestriction

The Spotify user is not allowed to log in from this country.

kSpErrorApplicationBanned

The application has been banned by Spotify

This most likely means that the client_id specified in SpConfig::client_id has been denylisted.

kSpErrorGeneralLoginError

An unspecified login error occurred.

In order to help debug the issue, the application should register the callback SpCallbackDebugMessage which receives additional information about the error.

kSpErrorUnsupported

The operation is not supported.

kSpErrorNotActiveDevice

The operation is not supported if the device is not the active playback device.

See also
kSpErrorAPIRateLimited

The API has been rate-limited.

The API is rate-limited if it is asked to perform too many actions in a short amount of time.

kSpErrorReentrancyDetected

The eSDK API was used from a callback.

This eSDK API function cannot be used from callbacks.

kSpErrorMultiThreadingDetected

The eSDK API was used from multiple threads.

This eSDK API function does not support multi-threading.

kSpErrorTryAgain

The eSDK API cannot be performed right now.

This eSDK API cannot be performed right now, but you are free to retry.

kSpErrorDuringLogout

Logout failed during SpFree call.

kSpErrorPermanentConnectionError

Permanent connection error. eSDK ceased attempts to reconnect.

kSpErrorEntropyFailure

Failed to get cryptographic random data from the platform.

kSpErrorZeroConfErrorStart

Error range reserved for ZeroConf-related errors.

kSpErrorZeroConfBadRequest

ZeroConf Web server problem or critically malformed request.

kSpErrorZeroConfUnknown

Fallback when no other ZeroConf error applies.

kSpErrorZeroConfNotImplemented

ZeroConf device does not implement this feature.

kSpErrorZeroConfNotInstalled

Spotify not installed (where applicable)

kSpErrorZeroConfNotLoaded

Spotify not loaded (where applicable)

kSpErrorZeroConfNotAuthorized

Spotify client not authorized to play.

kSpErrorZeroConfCannotLoad

Spotify cannot be loaded (where applicable)

kSpErrorZeroConfSystemUpdateRequired

Device system needs update (where applicable)

kSpErrorZeroConfSpotifyUpdateRequired

Spotify requires an update.

kSpErrorZeroConfLoginFailed

Spotify returned an error when trying to login.

kSpErrorZeroConfInvalidPublicKey

ZeroConf login failed due to an invalid public key.

kSpErrorZeroConfMissingAction

ZeroConf HTTP request has no action parameter.

kSpErrorZeroConfInvalidAction

ZeroConf HTTP request has an unrecognized action parameter.

kSpErrorZeroConfInvalidArguments

Incorrect or insufficient ZeroConf arguments supplied for requested action.

kSpErrorZeroConfNoSpotifySession

No valid Spotify session for requested Spotify action (where applicable)

kSpErrorZeroConfSpotifyError

A Spotify API call returned an error not covered by other error messages.

kSpErrorPlaybackErrorStart

Error range reserved for playback-related errors.

kSpErrorGeneralPlaybackError

An unspecified playback error occurred.

Notes:
  • When SpCallbackError was called with this error code no action is required. eSDK will try to progress to the next track.
kSpErrorPlaybackRateLimited

The application has been rate-limited.

The application is rate-limited if it requests the playback of too many tracks within a given amount of time.

kSpErrorPlaybackCappingLimitReached

The Spotify user has reached a capping limit that is in effect in this country and/or for this track.

kSpErrorAdIsPlaying

Cannot change track while ad is playing.

kSpErrorCorruptTrack

The track is (temporarily) corrupted in the Spotify catalogue.

This track will be skipped because it cannot be downloaded. This is a temporary issue with the Spotify catalogue that will be resolved. The error is for informational purposes only. No action is required.

kSpErrorContextFailed

Unable to read all tracks from the playing context.

Playback of the Spotify context (playlist, album, artist, radio, etc) will stop early because eSDK is unable to retrieve more tracks. This could be caused by temporary communication or server problems, or by the underlying context being removed or shortened during playback (for instance, the user deleted all tracks in the playlist while listening).

kSpErrorPrefetchItemUnavailable

The item that was being prefetched was unavailable, and cannot be fetched. This could be due to an invalid URI, changes in track availability, or geographical limitations. This is a permanent error, and the item should not be tried again.

kSpAlreadyPrefetching

An item is already actively being prefetched. You must stop the current prefetch request to start another one. This error is only relevant for builds with offline storage enabled.

kSpStorageReadError

A permanent error was encountered while reading to a registered file storage callback. This error is only relevant for builds with offline storage enabled.

kSpStorageWriteError

A permanent error was encountered while writing to a registered file storage callback. This error is only relevant for builds with offline storage enabled.

kSpPrefetchDownloadFailed

The prefetched item was not fully downloaded or failed. If error happens prefetch can be retried. This error is only relevant for builds with offline storage enabled.

kSpErrorBusy

The current API call cannot be completed because eSDK is busy. Same API call should be done sometime later with the same arguments.

kSpErrorUnavailable

The current API call cannot be completed because the requested operation is not available at the moment.

kSpErrorNotAllowed

This eSDK API is not allowed due to current license restrictions.

kSpErrorNetworkRequired

The current API call cannot be completed without connection to the Spotify backend.

kSpErrorNotLoggedIn

The current API call cannot be completed without being logged in.

kSpErrorInProgress

Used in callbacks to notify the application that the action is not yet complete.

kSpErrorPlaybackInitiation

Used in SpCallbackError callback to notify the application that playback initiation failed.

kSpErrorPresetFailed

Used in SpCallbackError callback to notify the application that recalling and playing a preset failed.

Notes:
  • No longer used as preset support is removed from eSDK.
kSpErrorInvalidRequest

The queued track was rejected.

This error is the opposite of kSpPlaybackNotifyQueuedTrackAccepted and occurs when a call to SpQueueUri failed. That might happen e.g. when queuing of several tracks was done within a very short time period and therefore was rate-limited.

See also
kSpErrorInvalidTrackId

Used in SpCallbackError callback to notify the application that an invalid track_id was used.

kSpErrorIncorrectMsPlayed

Used in SpCallbackError callback to notify the application that an incorrect value for ms_played was reported.

kSpErrorDeviceNotControllable

The operation is not allowed since the device is not controllable.

See also
kSpErrorPlaybackInitiationTimeout

The playback initiation operation timed out.

kSpErrorGeneralDownloadError

Failed to download the requested track.

See also Notes:
  • When SpCallbackError was called with this error code no action is required. eSDK will try to progress to the next track.

SpAPIReturnCode

Return to Main enumerations

enum SpAPIReturnCode {
    kSpAPINoError,
    kSpAPITryAgain,
    kSpAPIDNSLookupError,
    kSpAPIGenericError,
    kSpAPINotSupported,
    kSpAPIEOF,
    kSpAPINotFound,
};
kSpAPINoError

This code should be used when the API call was successful.

kSpAPITryAgain

This code means operation cannot be performed right now. Same API call should be done sometime later with the same arguments.

kSpAPIDNSLookupError

Use to notify about any DNS lookup error that cannot be retried.

kSpAPIGenericError

API call has failed.

kSpAPINotSupported

Requested feature is not supported by platform.

kSpAPIEOF

End of file/socket reached.

kSpAPINotFound

Requested resource does not exist.

SpPlaybackBitrate

Return to Main enumerations

enum SpPlaybackBitrate {
    kSpPlaybackBitrateDefault,
    kSpPlaybackBitrateLow,
    kSpPlaybackBitrateNormal,
};
kSpPlaybackBitrateDefault

Set the bitrate to the default (currently High).

kSpPlaybackBitrateLow

Set the bitrate to low. Corresponds to e.g. 96 kbit/s ogg/vorbis.

kSpPlaybackBitrateNormal

Set the bitrate to normal. Corresponds to e.g. 160 kbit/s ogg/vorbis.

SpPlaybackNotification

Return to Main enumerations

enum SpPlaybackNotification {
    kSpPlaybackNotifyPlay,
    kSpPlaybackNotifyPause,
    kSpPlaybackNotifyTrackChanged,
    kSpPlaybackNotifyNext,
    kSpPlaybackNotifyPrev,
    kSpPlaybackNotifyShuffleOn,
    kSpPlaybackNotifyShuffleOff,
    kSpPlaybackNotifyRepeatOn,
    kSpPlaybackNotifyRepeatOff,
    kSpPlaybackNotifyBecameActive,
    kSpPlaybackNotifyBecameInactive,
    kSpPlaybackNotifyAudioDeliveryDone,
    kSpPlaybackNotifyContextChanged,
    kSpPlaybackNotifyMetadataChanged,
    kSpPlaybackNotifyNetworkRequired,
    kSpPlaybackNotifyTrackDownloadStalled,
    kSpPlaybackNotifyQueuedTrackAccepted,
};
kSpPlaybackNotifyPlay

Playback has started or has resumed.

If the device is the active speaker (according to SpPlaybackIsActiveDevice and it has audio data that was delivered by audio data callback function left in its buffers, the application must resume playing the audio data. If the device is not the active speaker, it means that another device that is being observed has resumed playback. See observing.

See also
kSpPlaybackNotifyPause

Playback has been paused.

If the device is the active speaker (according to SpPlaybackIsActiveDevice the application must stop playing audio immediately. If the device is not the active speaker, it means that another device that is being observed has paused. See observing.

See also Notes:
  • The application is not supposed to discard audio data that has been delivered by audio data callback function but that has not been played yet. This audio data still needs to be played when playback resumes by calling SpPlaybackPlay (kSpPlaybackNotifyPlay).
kSpPlaybackNotifyTrackChanged

The current track or its metadata has changed.

This event occurs in several cases: When SpPlayUri is called When SpPlaybackSkipToNext is called When SpPlaybackSkipToPrev is called Once any of the above actions were issued over connect Once a track has progressed naturally It should not happen: on pause and resume on seek in-track bitrate changes for any reason If your application displays metadata of the current track, use SpGetMetadata to reload the metadata when you receive this event. Applications that allow free users to login can check if the current track is an advertisement using SpPlaybackIsAdPlaying This information can be used to change the display or available controls for advertisements.

See also Notes:
kSpPlaybackNotifyNext

Playback has skipped to the next track.

This event occurs when SpPlaybackSkipToNext was invoked or when the user skipped to the next track using Spotify Connect. It does not occur when playback goes to a new track after the previous track has reached the end.

See also
kSpPlaybackNotifyPrev

Playback has skipped to the previous track.

See also
kSpPlaybackNotifyShuffleOn

"Shuffle" was switched on

See also
kSpPlaybackNotifyShuffleOff

"Shuffle" was switched off

See also
kSpPlaybackNotifyRepeatOn

"Repeat" was switched on

See also
kSpPlaybackNotifyRepeatOff

"Repeat" was switched off

See also
kSpPlaybackNotifyBecameActive

This device has become the active playback device.

This event occurs when the user moves playback to this device using Spotify Connect, or when playback is moved to this device as a side-effect of invoking one of the SpPlayback functions. When this event occurs, it may be a good time to initialize the audio pipeline of the application. You should not unpause when you receive this event wait for kSpPlaybackNotifyPlay

See also
kSpPlaybackNotifyBecameInactive

This device is no longer the active playback device.

This event occurs when the user moves playback to a different device using Spotify Connect. When this event occurs, the application must stop producing audio immediately. The application should not take any other action. Specifically, the application must not invoke any of the SpPlayback functions unless requested by some subsequent user interaction.

See also
kSpPlaybackNotifyAudioDeliveryDone

The library will not send any more audio data.

This event occurs when the library reaches the end of a playback context and has no more audio to deliver. This occurs, for instance, at the end of a playlist when repeat is disabled. When the application receives this event, it should finish playing out all of its buffered audio.

kSpPlaybackNotifyContextChanged

Playback changed to a different Spotify context.

This event occurs when playback starts or changes to a different context than was playing before, such as a change in album or playlist. This is an informational event that does not require action, but may be used to update the UI display. DeprecatedUse kSpPlaybackNotifyMetadataChanged instead.

kSpPlaybackNotifyMetadataChanged

Metadata is changed.

This event occurs when playback starts or changes to a different context, when a track switch occurs, etc. This is an informational event that does not require action, but should be used to keep the UI display updated with the latest metadata information. Applications that allow free users to login can check if the current track is an advertisement using SpPlaybackIsAdPlaying This information can be used to change the display or available controls for advertisements.

kSpPlaybackNotifyNetworkRequired

Playback is not allowed without network connection.

This event occurs when there has been no connection to Spotify for a period of time. When this event occurs, the application should stop producing audio immediately. The application should not take any other action. If the user takes any action to affect playback, kSpErrorNetworkRequired will be returned. Once network connection is restored (see kSpConnectionNotifyReconnect), the application can resume playback by calling SpPlaybackPlay Playback is not resumed automatically.

kSpPlaybackNotifyTrackDownloadStalled

Download of the current track stalled due to network outage.

This event occurs when the currently playing track has run out of data to play due to network outage. This is an informative event that indicates that there is no more data to play for the current track until network connections are re-established. If network connection is not available within a certain amount of time playback will be automatically paused, this is to prevent startling effects for the user when track playback resumes unexpectedly after a long time period of silence. Once network connection is restored (see kSpConnectionNotifyReconnect), playback should resume automatically (unless kSpPlaybackNotifyPause occurred due to timeout).

kSpPlaybackNotifyQueuedTrackAccepted

The queued track was accepted.

This event occurs when a call to SpQueueUri has been accepted. Normally there is no need to monitor specifically for this as kSpPlaybackNotifyMetadataChanged is enough to detect UI related changes. A distinct use case for this notification is if one wants to queue several tracks within a very short time period where waiting for this notification between each call will help avoid getting rate-limited.

See also

SpConnectionNotification

Return to Main enumerations

enum SpConnectionNotification {
    kSpConnectionNotifyLoggedIn,
    kSpConnectionNotifyLoggedOut,
    kSpConnectionNotifyTemporaryError,
    kSpConnectionNotifyDisconnect,
    kSpConnectionNotifyReconnect,
    kSpConnectionNotifyProductTypeChanged,
    kSpConnectionNotifyZeroConfVarsChanged,
    kSpConnectionNotifyTransmittingData,
};
kSpConnectionNotifyLoggedIn

The user has successfully logged in to Spotify

See also
kSpConnectionNotifyLoggedOut

The user has been logged out of Spotify

This can occur as a result of invoking SpConnectionLogout or because of a permanent connection error. To log in again, the application must invoke SpConnectionLoginBlob

See also Notes:
kSpConnectionNotifyTemporaryError

A temporary connection error occurred. The library will automatically retry.

A temporary error can be due to lost network connectivity. The library will try to reconnect from time to time. If the application is able to detect that the network has become unavailable (e.g., when the network cable is unplugged), it should call SpConnectionSetConnectivity with kSpConnectivityNone When the network becomes available again, it should invoke SpConnectionSetConnectivity with a value other than kSpConnectivityNone, which will cause the library to try to reconnect immediately. In order to help debug the issue, the application should register the callback SpCallbackDebugMessage which receives additional information about the error.

kSpConnectionNotifyDisconnect

The connection to Spotify has been lost.

The application can use this to indicate a connectivity issue. No other action is necessary. In particular, the application is not supposed to re-login the user.

Notes:
kSpConnectionNotifyReconnect

The connection to Spotify has been (re-)established.

This notification will be sent when the connection to Spotify has been re-established after a prior kSpConnectionNotifyDisconnect or the first time a connection is established to Spotify

kSpConnectionNotifyProductTypeChanged

The connected user account type has changed (became premium, for example).

No action is necessary, but new features may be available if used in conjunction with the Spotify Web API.

kSpConnectionNotifyZeroConfVarsChanged

The SpZeroConfVars has changed.

Retrieve the new values using SpZeroConfGetVars

kSpConnectionNotifyTransmittingData

The eSDK is transmitting data.

This notification is sent every time the eSDK begins sending data. It can be used to trigger integration-specific data transmissions to coincide with the eSDK transmissions, to save energy for wireless applications.

Notes:
  • This notification will not be sent more than about once per second.

SpDeviceType

Return to Main enumerations

enum SpDeviceType {
    kSpDeviceTypeComputer,
    kSpDeviceTypeTablet,
    kSpDeviceTypeSmartphone,
    kSpDeviceTypeSpeaker,
    kSpDeviceTypeTV,
    kSpDeviceTypeAVR,
    kSpDeviceTypeSTB,
    kSpDeviceTypeAudioDongle,
    kSpDeviceTypeGameConsole,
    kSpDeviceTypeCastVideo,
    kSpDeviceTypeCastAudio,
    kSpDeviceTypeAutomobile,
    kSpDeviceTypeSmartwatch,
    kSpDeviceTypeChromebook,
};
kSpDeviceTypeComputer

Laptop or desktop computer device.

kSpDeviceTypeTablet

Tablet PC device.

kSpDeviceTypeSmartphone

Smartphone device.

kSpDeviceTypeSpeaker

Speaker device.

kSpDeviceTypeTV

Television device.

kSpDeviceTypeAVR

Audio/Video receiver device.

kSpDeviceTypeSTB

Set-Top Box device.

kSpDeviceTypeAudioDongle

Audio dongle device.

kSpDeviceTypeGameConsole

Game console device.

kSpDeviceTypeCastVideo

Chromecast Video.

kSpDeviceTypeCastAudio

Chromecast Audio.

kSpDeviceTypeAutomobile

Automobile.

kSpDeviceTypeSmartwatch

Smartwatch.

kSpDeviceTypeChromebook

Chromebook.

SpMetadataTrack

Return to Main enumerations

enum SpMetadataTrack {
    kSpMetadataTrackBeforePrevious,
    kSpMetadataTrackPrevious,
    kSpMetadataTrackCurrent,
    kSpMetadataTrackNext,
    kSpMetadataTrackAfterNext,
};
kSpMetadataTrackBeforePrevious

Index of the before previous track in the track list.

kSpMetadataTrackPrevious

Index of the previous track in the track list.

kSpMetadataTrackCurrent

Index of the current track in the track list.

kSpMetadataTrackNext

Index of the next track in the track list.

kSpMetadataTrackAfterNext

Index of the after next track in the track list.

SpConnectivity

Return to Main enumerations

enum SpConnectivity {
    kSpConnectivityNone,
    kSpConnectivityWired,
    kSpConnectivityWireless,
    kSpConnectivityMobile,
};
kSpConnectivityNone

The device is not connected to the network.

kSpConnectivityWired

The device is connected to a wired network.

kSpConnectivityWireless

The device is connected to a wireless network.

kSpConnectivityMobile

The device uses a mobile data connection.

SpContent

Return to Main enumerations

enum SpContent {
    kSpContentUnknown,
    kSpContentMusicTrack,
    kSpContentShowEpisode,
    kSpContentAd,
};
kSpContentUnknown

Unknown content type.

kSpContentMusicTrack

Music track.

kSpContentShowEpisode

Podcast show episode.

kSpContentAd

Advertisement.

SpMediaType

Return to Main enumerations

enum SpMediaType {
    kSpMediaTypeAudio,
    kSpMediaTypeVideo,
};
kSpMediaTypeAudio

Audio media type.

kSpMediaTypeVideo

Video media type.

SpAudioQuality

Return to Main enumerations

enum SpAudioQuality {
    kSpAudioQualityUnknown,
    kSpAudioQualityLow,
    kSpAudioQualityNormal,
    kSpAudioQualityHigh,
    kSpAudioQualityVeryHigh,
};
kSpAudioQualityUnknown

Unknown audio quality.

kSpAudioQualityLow

Low audio quality.

kSpAudioQualityNormal

Normal audio quality (e.g. 96 kbps ogg/vorbis)

kSpAudioQualityHigh

High audio quality (e.g. 160 kbps ogg/vorbis)

kSpAudioQualityVeryHigh

Very high audio quality (e.g. 320 kbps ogg/vorbis)

SpDrmFormat

Return to Main enumerations

enum SpDrmFormat {
    kSpDrmFormatUnknown,
    kSpDrmFormatUnencrypted,
    kSpDrmFormatFairPlay,
    kSpDrmFormatWidevine,
    kSpDrmFormatPlayReady,
};
kSpDrmFormatUnknown

Unknown DRM.

kSpDrmFormatUnencrypted

No DRM, unencrypted.

kSpDrmFormatFairPlay

FairPlay.

kSpDrmFormatWidevine

Widevine.

kSpDrmFormatPlayReady

PlayReady.

SpReDeliveryMode

Return to Main enumerations

enum SpReDeliveryMode {
    kSpRedeliveryModeActivated,
    kSpRedeliveryModeDeactivated,
};
kSpRedeliveryModeActivated

Redelivery is activated.

kSpRedeliveryModeDeactivated

Redelivery is deactivated.

Functions

SpInit()

Return to Main functions

SpError SpInit(struct SpConfig *conf)

Initialize the library.

Parameters

     
[in] struct SpConfig * conf Configuration parameters

Returns

Returns an error code

SpFree()

Return to Main functions

SpError SpFree(void)

Shut down the library.

If a user is currently logged in, the application should first call SpConnectionLogout and wait for the kSpConnectionNotifyLoggedOut event, otherwise SpFree may take several seconds.

Returns

Returns an error code

SpGetLibraryVersion()

Return to Main functions

const char * SpGetLibraryVersion(void)

Retrieve a version string for the library.

Returns

Version string

Notes:

  • This API can be invoked from a callback.

SpConnectionSetConnectivity()

Return to Main functions

SpError SpConnectionSetConnectivity(enum SpConnectivity connectivity)

Set the type of network connection of the device.

When the application detects that the device has lost network connection, it should call this function with kSpConnectivityNone When network connection is restored, the application should call this function with one of the other values of SpConnectivity The library will then immediately retry to reconnect to Spotify (rather than waiting for the next retry timeout). The library may use the type of network connection to adapt its streaming and buffering strategies. Currently, however, all types of network connection are treated the same.

Parameters

     
[in] enum SpConnectivity connectivity Type of connection

Returns

Returns an error code

SpConnectionGetConnectivity()

Return to Main functions

enum SpConnectivity SpConnectionGetConnectivity(void)

Get the connectivity that was set with SpConnectionSetConnectivity

The library does not detect the type of network connection by itself. It only updates it if the application calls SpConnectionSetConnectivity If SpConnectionSetConnectivity was never called, the connection defaults to kSpConnectivityWired

Returns

Type of connection

Notes:

  • This API can be invoked from a callback.

SpConnectionLoginBlob()

Return to Main functions

SpError SpConnectionLoginBlob(const char *username, const char *credentials_blob)

Log in a user to Spotify using a credentials blob.

Parameters

     
[in] const char * username Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.)
[in] const char * credentials_blob Credentials blob received via ZeroConf or in the callback SpCallbackConnectionNewCredentials Note: if the credentials_blob is an empty string, this function should not be called or it will return kSpErrorFailed

Returns

Returns an error code

See also

Notes:

  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • The blob can only be used for subsequent logins as long as the value of SpConfig::unique_id does not change. If SpConfig::unique_id has changed since the blob was received, this function returns an error and you will receive a debug message similar to "Parsing ZeroConf blob failed with code -3".

SpConnectionLoginPassword()

Return to Main functions

This function is deprecated and should not be used. See alternatives:
SpError SpConnectionLoginPassword(const char *username, const char *password)

Log in a user to Spotify using a password.

Returns kSpErrorGeneralLoginError if a connection is not present. For logging in offline please use SpConnectionLoginBlob Applications must not store the password. Instead, they should implement the callback SpCallbackConnectionNewCredentials and store the credentials blob that they receive for subsequent logins using the function SpConnectionLoginBlob

Parameters

     
[in] const char * username Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.)
[in] const char * password Password

Returns

Returns an error code

See also

Notes:

  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • Spotify Connect-enabled hardware devices must not use this function. Such devices must implement the ZeroConf and use the function SpConnectionLoginBlob instead.

SpConnectionLoginOauthToken()

Return to Main functions

SpError SpConnectionLoginOauthToken(const char *oauth_token)

Log in a user to Spotify using a Spotify OAuth token.

For subsequent logins the SpCallbackConnectionNewCredentials callback should be implemented and the received credentials blob should be stored and used. (Note that the OAuth access token itself expires after a short time. The credentials blob returned by the callback allows you to re-login even after the token has expired.)

Parameters

     
[in] const char * oauth_token Spotify OAuth access token with “streaming” scope. See https://developer.spotify.com/documentation/general/guides/authorization-guide/

Returns

Returns an error code

See also

Notes:

  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • Spotify Connect-enabled hardware devices that implement the ZeroConf stack must use the function SpConnectionLoginBlob instead.

SpConnectionLogout()

Return to Main functions

SpError SpConnectionLogout(void)

Log the user out of Spotify

Returns

Returns an error code

See also

Notes:

SpConnectionIsLoggedIn()

Return to Main functions

uint8_t SpConnectionIsLoggedIn(void)

Is the user logged in to Spotify

Returns

1: The user is logged in 0: The user is not logged in

See also

Notes:

  • This API can be invoked from a callback.

SpConnectionGetAckId()

Return to Main functions

const char * SpConnectionGetAckId(void)

Get the last Ack ID.

Notes:

  • This function is deprecated and should not be used.

SpGetCanonicalUsername()

Return to Main functions

const char * SpGetCanonicalUsername(void)

Get the canonical username of the logged in user.

This function returns the canonical username of the logged in user, which is the unique username used for identifying a specific user for things like playlists and the Spotify Web API. This username might differ from the username used to login. A user can login with an e-mail address or non-canonical unicode. This function will return the canonicalized version of the username after a successful login.

Returns

Returns a string containing the username, or NULL if no user is logged in.

Notes:

  • The canonical username should not be stored persistently. Always store the username as provided by the user, not the canonicalized version.
  • This API can be invoked from a callback.

SpSetDisplayName()

Return to Main functions

SpError SpSetDisplayName(const char *display_name)

Set the display name for the device or application.

This function can be used to change the display name that was passed to SpInit in the field SpConfig::display_name

Parameters

     
[in] const char * display_name A UTF-8-encoded display name

Returns

Returns an error code

Notes:

  • The display name is not allowed to be an empty string.

SpSetVolumeSteps()

Return to Main functions

SpError SpSetVolumeSteps(uint32_t steps)

Set the volume steps the device is capable of.

This function will indicate the number of intermediate steps from min_volume to max_volume that the device supports. If there's no volume control ability it must be set to zero to inform that no volume control is possible at all. The default number of steps if this function is not called is 16.

Parameters

     
[in] uint32_t steps the number of volume steps the device can support. 0 means no volume steps at all. The max value that is possible to set is 65535.

Returns

Returns an error code

Notes:

  • There's no commitment from the other Connect clients to respect the volume steps. It's important to call this function passing zero if no volume control is possible though.

SpSetDeviceIsGroup()

Return to Main functions

SpError SpSetDeviceIsGroup(int is_group)

Control if the device represents a group.

A group is a number of devices all playing back the same sound synchronized. Setting this status correctly will allow Spotify clients to display the correct metadata for this device.

Parameters

     
[in] int is_group 0: Indicate that this device is a single stand-alone device. 1: Indicate that this device represents a group.

Notes:

  • If device aliases are used, this function should not be used to set the group status. Instead, SpSetDeviceAliases should be used to update group status individually for each alias.

SpEnableConnect()

Return to Main functions

SpError SpEnableConnect(void)

Enable Connect functionality for this device.

A device with enabled Connect functionality will show up in other devices' Connect pickers, and will be able to both control them and be controlled. The Spotify embedded library will enable Connect functionality by default

SpDisableConnect()

Return to Main functions

SpError SpDisableConnect(void)

Disable Connect functionality for this device.

A device that disables Connect will not be able to control playback on other devices, or be controlled by them.

SpGetSelectedDeviceAlias()

Return to Main functions

int SpGetSelectedDeviceAlias(void)

Return the currently selected device alias.

Returns

The currently selected device alias or SP_NO_ALIAS_SELECTED if no alias is selected.

SpPumpEvents()

Return to Main functions

SpError SpPumpEvents(void)

Allow the library to perform asynchronous tasks and process events.

Note: The suggested time interval to call this function is 10ms. This function should not be called from a callback. A typical usage pattern looks like this:

Returns

Returns an error code

SpRegisterConnectionCallbacks()

Return to Main functions

SpError SpRegisterConnectionCallbacks(struct SpConnectionCallbacks *cb, void *context)

Register callbacks related to the connection to Spotify

Parameters

     
[in] struct SpConnectionCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpRegisterDebugCallbacks()

Return to Main functions

SpError SpRegisterDebugCallbacks(struct SpDebugCallbacks *cb, void *context)

Register a callback that receives debug messages/trace logs.

These callbacks can be registered before SpInit has been called, in order to receive debug logs that occur during initialization.

Parameters

     
[in] struct SpDebugCallbacks * cb Structure with pointers to individual callback functions.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callback.

Returns

Returns an error code

SpRegisterPlaybackCallbacks()

Return to Main functions

SpError SpRegisterPlaybackCallbacks(struct SpPlaybackCallbacks *cb, void *context)

Register playback-related callbacks.

Parameters

     
[in] struct SpPlaybackCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpGetMetadata()

Return to Main functions

SpError SpGetMetadata(struct SpMetadata *metadata, int relative_index)

Retrieve metadata for a track in the current track list.

Parameters

     
[out] struct SpMetadata * metadata Structure to be filled with the metadata for the track
[in] int relative_index Track index relative to the current track. Some relative indices are defined in the enum SpMetadataTrack

Returns

Returns an error code. Returns kSpErrorFailed if relative_index is out of range.

Notes:

SpGetMetadataImageURL()

Return to Main functions

SpError SpGetMetadataImageURL(const char *image_uri, char *image_url, size_t image_url_size)

Return the HTTP URL to an image file from a spotify:image: URI.

Parameters

     
[in] const char * image_uri image URI returned in SpMetadata::album_cover_uri
[out] char * image_url Pointer to a buffer that will be filled with HTTP URL.
[in] size_t image_url_size size of the image_url buffer. SP_MAX_METADATA_IMAGE_URL_LENGTH is the max amount of data that can be returned in image_url.

Returns

Returns an error code. Returns kSpErrorFailed if the buffer is not big enough.

Notes:

  • This API can be invoked from a callback.

SpGetPlayerCookie()

Return to Main functions

SpError SpGetPlayerCookie(char *player_cookie, size_t player_cookie_size)

Obtain player cookie for current playback.

The obtained player cookie can then be used to get more detailed metadata for current playback from Spotify's backend using Spotify Web API.

Parameters

     
[out] char * player_cookie Pointer to a buffer where the player cookie will be copied. This buffer will be reset even if there is no player cookie available.
[in] size_t player_cookie_size Size of the player_cookie buffer. Player cookie length is defined SP_PLAYER_COOKIE_LENGTH and the buffer should be at least SP_PLAYER_COOKIE_LENGTH+1 in size.

Returns

Returns an error code. Returns kSpErrorUnsupported if the build configuration doesn’t support player cookies.

Notes:

  • Experimental, subject to change

SpPlaybackPlay()

Return to Main functions

SpError SpPlaybackPlay(int alias_index)

Start or resume playback.

Parameters

     
[in] int alias_index The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

SpPlaybackPause()

Return to Main functions

SpError SpPlaybackPause(void)

Pause playback.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

SpPlaybackSkipToNext()

Return to Main functions

SpError SpPlaybackSkipToNext(void)

Skip playback to the next track in the track list.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

SpPlaybackSkipToPrev()

Return to Main functions

SpError SpPlaybackSkipToPrev(void)

Skip playback to the previous track in the track list.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

Notes:

  • This function will try to skip to the previous track regardless of the current playback position. If the desired behaviour is to only skip to the previous track UNLESS the current playback position is beyond 3 seconds, the following code example is suggested as a base: if(SpPlaybackGetPosition()/1000=3) SpPlaybackSeek(0); else SpPlaybackSkipToPrev

SpPlaybackSeek()

Return to Main functions

SpError SpPlaybackSeek(uint32_t position_ms)

Seek to a position within the current track.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

     
[in] uint32_t position_ms Position within the track in milliseconds

Returns

Returns an error code

SpPlaybackSeekRelative()

Return to Main functions

SpError SpPlaybackSeekRelative(int32_t time_ms)

Seek a relative amount of time within the current track.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

     
[in] int32_t time_ms Amount of time to seek within the current track, negative values seek backwards and positive values seek forward.

Returns

Returns an error code

SpPlaybackGetPosition()

Return to Main functions

uint32_t SpPlaybackGetPosition(void)

Get the current playback position within the track.

Returns

Playback position in milliseconds

Notes:

  • This API can be invoked from a callback.

SpPlaybackUpdateVolume()

Return to Main functions

SpError SpPlaybackUpdateVolume(uint16_t volume)

Request a change to the playback volume.

It is the application's responsibility to apply the volume change to its audio output. This function merely notifies the library of the volume change, so that the library can inform other Spotify Connect-enabled devices. Calling this function invokes the SpCallbackPlaybackApplyVolume callback, which the application can use to apply the actual volume change.

Parameters

     
[in] uint16_t volume Volume in the range 0 (silence) to 65535 (full volume)

Returns

Returns an error code

Notes:

  • When the library is initialized, it assumes a volume level of 32768 (50% 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.

SpPlaybackGetVolume()

Return to Main functions

uint16_t SpPlaybackGetVolume(void)

Get the playback volume level.

This returns the last volume level that the application set using SpPlaybackUpdateVolume or that was reported to the application using SpCallbackPlaybackApplyVolume

Returns

Volume level in the range 0 (silence) to 65535 (full volume).

Notes:

  • This API can be invoked from a callback.

SpPlaybackIsPlaying()

Return to Main functions

uint8_t SpPlaybackIsPlaying(void)

Is the playback status playing or paused.

Returns

1: Playback status is playing 0: Playback status is paused (or no playback has been started at all)

See also

Notes:

SpPlaybackIsAdPlaying()

Return to Main functions

uint8_t SpPlaybackIsAdPlaying(void)

Is the current track an Ad or not.

Returns

1: The current playing track is an Ad 0: The current playing track is not an Ad.

See also

Notes:

  • This API can be invoked from a callback.

SpPlaybackIsShuffled()

Return to Main functions

uint8_t SpPlaybackIsShuffled(void)

Is "shuffle" mode enabled.

Returns

1: Shuffle is enabled 0: Shuffle is disabled

See also

Notes:

  • This API can be invoked from a callback.

SpPlaybackIsRepeated()

Return to Main functions

uint8_t SpPlaybackIsRepeated(void)

Is "repeat" mode enabled.

Returns

1: Repeat is enabled 0: Repeat is disabled

See also

Notes:

  • This API can be invoked from a callback.

SpPlaybackGetRepeatMode()

Return to Main functions

uint8_t SpPlaybackGetRepeatMode(void)

Which "repeat" mode is on.

Returns

0: Repeat is disabled 1: Repeat Context is enabled 2: Repeat Track is enabled

See also

Notes:

  • This API can be invoked from a callback.

SpPlaybackIsActiveDevice()

Return to Main functions

uint8_t SpPlaybackIsActiveDevice(void)

Is the device the active playback device.

Returns

1: The device is the active playback device 0: Another device is the active playback device

See also

Notes:

  • This API can be invoked from a callback.

SpPlaybackEnableShuffle()

Return to Main functions

SpError SpPlaybackEnableShuffle(uint8_t enable)

Enable or disable "shuffle" mode.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

     
[in] uint8_t enable 1 to enable, 0 to disable

Returns

Returns an error code

See also

Notes:

  • The change to the shuffle mode might not take effect if the API is invoked in the time window between requesting playback of a new context (e.g., by calling SpPlayUri and playback of the new context actually starting.

SpPlaybackEnableRepeat()

Return to Main functions

SpError SpPlaybackEnableRepeat(uint8_t enable)

Enable or disable "repeat" mode.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

     
[in] uint8_t enable 0 to disable, 1 to Repeat Context, 2 to Repeat Track The Repeat values were previously called Repeat and Repeat-1.

Returns

Returns an error code

See also

SpPlaybackCycleRepeatMode()

Return to Main functions

SpError SpPlaybackCycleRepeatMode(void)

Cycle through the available repeat modes.

Cycles through repeat modes (repeat off, repeat context, repeat track) given their current availability. If for example repeat context is enabled and repeat track is disallowed due to restrictions, this API will go directly to repeat off.

Returns

Returns an error code.

SpPlaybackSetBitrate()

Return to Main functions

SpError SpPlaybackSetBitrate(enum SpPlaybackBitrate bitrate)

Change the bitrate at which compressed audio data is delivered.

This will take effect for the next chunk of audio data that is streamed from the backend. The format or sample rate of the audio data that is received does not change.

Parameters

     
[in] enum SpPlaybackBitrate bitrate The bitrate to be set

Returns

Returns an error code

SpPlaybackSetAvailableToPlay()

Return to Main functions

This function is deprecated and should not be used. See alternatives:
SpError SpPlaybackSetAvailableToPlay(uint8_t can_play)

Allow or disallow the device to start playback.

On some platforms, there might be certain situations in which playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.

Parameters

     
[in] uint8_t can_play 2 to allow playback (default), 1 to disallow playback without becoming inactive, the playback will be paused, 0 to disallow playback and become inactive.

See also

Notes:

  • This functionality is reserved for specific integration scenarios. In most cases, when integrating the SDK into a device, this API must not be used. If the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall log out, shut down the library, and stop announcing the device via the ZeroConf.)
  • If the device is currently the active device setting can_play to 0 will cause the notification kSpPlaybackNotifyBecameInactive to be sent. Playback-related APIs (SpPlaybackPlay(), ...) will return an error code. This setting will persist across logout/login.

SpPlaybackIsAvailableToPlay()

Return to Main functions

This function is deprecated and should not be used. See alternatives:
uint8_t SpPlaybackIsAvailableToPlay(void)

Is the device available for playback.

Returns

1: The device is available for playback 0: The device cannot accept playback requests nor start playback either.

See also

SpPlaybackSetDeviceInactive()

Return to Main functions

SpError SpPlaybackSetDeviceInactive(void)

Set the device inactive.

If the device is currently the active device, this function stops the playback if playing, sets the device inactive, and sends the notification kSpPlaybackNotifyBecameInactive If the device is already inactive, the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

See also

Notes:

SpPlaybackIsDeviceControllable()

Return to Main functions

uint8_t SpPlaybackIsDeviceControllable(void)

Is the device controllable.

Returns

1: The device is controllable. 0: The device is not controllable so it cannot accept playback requests nor start playback either.

See also

SpPlaybackSetDeviceControllable()

Return to Main functions

SpError SpPlaybackSetDeviceControllable(uint8_t is_controllable)

Allow or disallow the device to be controllable.

On some platforms, there might be certain situations in which the control of the playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.

Parameters

     
[in] uint8_t is_controllable When set to 0, eSDK will pause the playback and won’t accept local and remote playback commands, the device gets grayed off in the picker. Set to 1 to allow device control, eSDK will accept both local and remote playback commands and the device becomes available in the picker.

Returns

Returns an error code

See also

Notes:

  • This functionality is reserved for specific integration scenarios. It can be used to temporarily forbid playback when for example playing cutscenes in video games or taking a phone call while driving a car. This API should not be used if the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall then instead log out, shut down the library, and stop announcing the device via the ZeroConf.

SpPlaybackIncreaseUnderrunCount()

Return to Main functions

SpError SpPlaybackIncreaseUnderrunCount(uint32_t count)

Increase the underrun counter of the current track.

If playback underruns have been detected in the current track, use this API to report it to eSDK. This should only be called when there was no data to play at all and there was an audible glitch or gap for the user. It should only be called if audio was expected to be played and there was audio before. For example if eSDK is active and playing, but there is an underrun, report it. If eSDK is active and was requested to play something, but it never started, do not report it. If eSDK is active and playing and user skips, there is an expected gap, so report an underrun only if audio data started being delivered from eSDK and then stopped.

Parameters

     
[in] uint32_t count A counter of how many underruns happened. More than one could have occurred since the last one.

Returns

Returns an error code

SpPlaybackSetBandwidthLimit()

Return to Main functions

SpError SpPlaybackSetBandwidthLimit(uint32_t max_bytes_per_sec)

Set a limit on the download speed.

By calling this function eSDK will attempt to limit how fast it downloads a track. In some use cases it is preferred to not use the full bandwidth. At the beginning of a download eSDK will do a burst download and then try to obey the limit.

Parameters

     
[in] uint32_t max_bytes_per_sec approximate bandwidth budget for downloads. To use default bandwidth specify 0.

Returns

Returns an error code

Notes:

  • eSDK is not guaranteed to stay strictly below the limit but will not exceed it by much. It is also not guaranteed to use all available bandwidth.

SpPlaybackSetRedeliveryMode()

Return to Main functions

SpError SpPlaybackSetRedeliveryMode(SpReDeliveryMode mode)

Activates redelivery of audio data on play or resume playback.

This function should be called to activate or deactivate audio redelivery for the next calls to SpPlaybackPlay When the client application can't keep unplayed audio in its playback buffers (for example when audio from some other source was played while Spotify was paused) the eSDK should be notified that redelivery of audio data is needed. The audio data is redelivered from the last playback position reported by the integration with the same precision as seek. eSDK will need to redownload the data that was already delivered to the integration and therefore there will be a penalty of increased data consumption and latencies. Only use this function when unplayed audio is discarded.

Returns

Returns an error code

SpPlaybackIsRedeliveryModeActivated()

Return to Main functions

SpReDeliveryMode SpPlaybackIsRedeliveryModeActivated(void)

Gets the status of redelivery mode.

When redelivery mode is activated or deactivated through the API SpPlaybackSetRedeliveryMode an internal state is updated to keep track of the redelivery behavior. This API exposes this internal state.

Returns

Returns redelivery mode status: kSpRedeliveryModeActivated or kSpRedeliveryModeDeactivated

SpZeroConfGetVars()

Return to Main functions

SpError SpZeroConfGetVars(struct SpZeroConfVars *vars)

Get variables for ZeroConf, mainly the "getInfo" request.

The application should use this function to retrieve the data that it should send in the response to the "getInfo" request. See the ZeroConf manual for more information. There are also other fields here that might be needed for ZeroConf.

Parameters

     
[out] struct SpZeroConfVars * vars Structure to be filled with the variables

Notes:

  • This API can be invoked from a callback.

SpZeroConfAnnouncePause()

Return to Main functions

SpError SpZeroConfAnnouncePause(void)

Temporarily pause ZeroConf mDNS announcements.

Returns

Returns an error code

Notes:

SpZeroConfAnnounceResume()

Return to Main functions

SpError SpZeroConfAnnounceResume(void)

Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause

Returns

Returns an error code

Notes:

SpConnectionLoginZeroConf()

Return to Main functions

SpError SpConnectionLoginZeroConf(const char *username, const char *zero_conf_blob, const char *client_key, const char *login_id, const char *token_type)

Log in a user to Spotify using a ZeroConf credentials blob.

This function logs in with the information that the application receives in the "addUser" ZeroConf request. See the ZeroConf manual.

Parameters

     
[in] const char * username Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL.
[in] const char * zero_conf_blob Credentials blob from the “blob” field of the request. Must not be longer than SP_MAX_ZEROCONF_BLOB_LENGTH bytes, not counting the terminating NULL.
[in] const char * client_key Client key from the “clientKey” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_CLIENT_KEY_LENGTH bytes, not counting the terminating NULL.
[in] const char * login_id Login ID from the “loginId” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_LOGIN_ID_LENGTH bytes, not counting the terminating NULL.
[in] const char * token_type Token type from the “tokenType” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_TOKEN_TYPE_LENGTH bytes, not counting the terminating NULL.

Returns

Returns an error code

See also

Notes:

  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:

SpGetBrandName()

Return to Main functions

const char * SpGetBrandName(void)

This function can be used to get the brand name. If the field SpConfig::brand_display_name was set at SpInit function returns its value, otherwise it returns what was set in the mandatory field SpConfig::brand_name

Returns

The UTF-8-encoded brand name

Notes:

  • This API can be invoked from a callback.

SpGetModelName()

Return to Main functions

const char * SpGetModelName(void)

This function can be used to get the model name. If the field SpConfig::model_display_name was set at SpInit function returns its value, otherwise it returns what was set in the mandatory field SpConfig::model_name

Returns

The UTF-8-encoded model name

Notes:

  • This API can be invoked from a callback.

SpRegisterDeviceAliasCallbacks()

Return to Main functions

SpError SpRegisterDeviceAliasCallbacks(struct SpDeviceAliasCallbacks *cb, void *context)

Register callbacks related to device aliases.

Parameters

     
[in] struct SpDeviceAliasCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpSetDeviceAliases()

Return to Main functions

SpError SpSetDeviceAliases(const struct SpDeviceAlias *aliases)

Update the device alias definitions.

Call this whenever the current alias definitions are updated. The id values for the aliases must be unique within the array. aliases Pointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES.

Parameters

     
[in] const struct SpDeviceAlias * aliases Pointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES.

SpRestrictDrmMediaFormats()

Return to Main functions

SpError SpRestrictDrmMediaFormats(const struct SpFormat formats[SP_MAX_SUPPORTED_FORMATS])

Restricts the list of DRM and media formats to a subset of the formats registered in SpInit To lift the restrictions use SpRestoreDrmMediaFormats

See also

SpRestoreDrmMediaFormats()

Return to Main functions

SpError SpRestoreDrmMediaFormats(void)

Resets the list of DRM formats and media formats to the ones registered in SpInit

See also

Content

#include "spotify_embedded_content.h"

Data Structures

Return to header index

Data Structure Description
SpContentCallbacks Callbacks to be registered with SpRegisterContentCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackTrackCacheState This callback, if set by the client, is called by eSDK to inform how many percent of the particular track are cached. It is measured from the beginning of the track. E.g. if 60 is reported it means that 60% of the track is cached starting from the beginning.
SpCallbackStorageKeyContentMapping This callback, if set by the client, is called by eSDK to notify how the storage_key is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means that the descriptor’s representation is spotify:track:[base62].
SpCallbackTrackRelinked This callback, if set by the client, is called by eSDK to notify about the fact that requested track is substituted with another (relinked) one during prefetch/offline process.
SpCallbackTrackRemoved This callback, if set by the client, is called by eSDK to notify that the track is removed.
SpCallbackOnAvailableContainer Callback for each available container.

Enumerations

Return to header index

Functions

Return to header index

Function Description
SpRegisterContentCallbacks  

Data Structures

SpContentCallbacks

Return to Content data structures

Callbacks to be registered with SpRegisterContentCallbacks

Any of the pointers may be NULL.

Notes:

  • See the documentation of the callback typedefs for information about the individual callbacks.
struct SpContentCallbacks {
    SpCallbackTrackCacheState track_state_callback;
    SpCallbackStorageKeyContentMapping store_key_map_callback;
    SpCallbackTrackRelinked track_relink_callback;
    SpCallbackTrackRemoved track_removed_callback;
    SpCallbackOnAvailableContainer on_available_container;
};
SpCallbackTrackCacheState track_state_callback

Track cached state callback.

See also
SpCallbackStorageKeyContentMapping store_key_map_callback

Content mapping callback.

See also
SpCallbackTrackRelinked track_relink_callback

Notify about track relink during prefetch/offline.

SpCallbackTrackRemoved track_removed_callback

Notify about track removal.

SpCallbackOnAvailableContainer on_available_container

Notify about an available container item.

Typedefs

SpCallbackTrackCacheState()

Return to Content typedefs

typedef void(* SpCallbackTrackCacheState)(const char *track_uri, uint32_t percents, void *context)

This callback, if set by the client, is called by eSDK to inform how many percent of the particular track are cached. It is measured from the beginning of the track. E.g. if 60 is reported it means that 60% of the track is cached starting from the beginning.

Parameters

     
[in] const char * track_uri Track URI which status is reported.
[in] uint32_t percents How much data is cached in percent. Range: [0 - 100%]
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback. This callback is called before each track delivery is started.

SpCallbackStorageKeyContentMapping()

Return to Content typedefs

typedef void(* SpCallbackStorageKeyContentMapping)(const char *storage_key, const char *descriptor, enum SpContentType hint, void *context)

This callback, if set by the client, is called by eSDK to notify how the storage_key is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means that the descriptor's representation is spotify:track:[base62].

Parameters

     
[in] const char * storage_key Storage key that was used in Alloc/Read/Write API.
[in] const char * descriptor Content descriptor. Value depends on hint.

See also

Notes:

  • The application should not block or call other API functions in the callback. This callback is called as soon as possible after Alloc callback of Storage API has been called and succeeds.

SpCallbackTrackRelinked()

Return to Content typedefs

typedef void(* SpCallbackTrackRelinked)(const char *original_uri, const char *new_uri, void *context)

This callback, if set by the client, is called by eSDK to notify about the fact that requested track is substituted with another (relinked) one during prefetch/offline process.

Parameters

     
[in] const char * original_uri Initial URI passed into eSDK PrefetchURI/OfflineURI function calls.
[in] const char * new_uri URI that is obtained after relink has happened.
[in] void * context Context provided in callback register procedure.

SpCallbackTrackRemoved()

Return to Content typedefs

typedef void(* SpCallbackTrackRemoved)(const char *track_uri, void *context)

This callback, if set by the client, is called by eSDK to notify that the track is removed.

track_uri URI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls. context Context provided in callback register procedure.

Parameters

     
[in] const char * track_uri URI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls.
[in] void * context Context provided in callback register procedure.

SpCallbackOnAvailableContainer()

Return to Content typedefs

typedef void(* SpCallbackOnAvailableContainer)(const char *uri, int total, void *context)

Callback for each available container.

Parameters

     
[in] const char * uri URI of a container
[in] int total Total number of containers
[in] void * context Context provided in callback register procedure.

Notes:

  • Experimental, subject of change

Enumerations

SpContentType

Return to Content enumerations

enum SpContentType {
    kSpContentTrack,
    kSpContentTrackMetadata,
};
kSpContentTrack

Content pointed by descriptor is spotify playable item URI (track or episode)

kSpContentTrackMetadata

Content pointed by descriptor is spotify playable item URI for which metadata is saved.

Functions

SpRegisterContentCallbacks()

Return to Content functions

SpError SpRegisterContentCallbacks(struct SpContentCallbacks *callbacks, void *context)

Parameters

     
[in] struct SpContentCallbacks * callbacks Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Hal

#include "spotify_embedded_hal.h"

Data Structures

Return to header index

Data Structure Description
SpSockaddr Struct contains resolved hostname IP address and its family.
SpDnsHALCallbacks Callbacks to be registered with SpRegisterDnsHALCallbacks
SpSocketHandle Socket handle type.
SpSocketHALCallbacks Callbacks to be registered with SpRegisterSocketHALCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackPerformDNSLookup This callback, if set by the client, is called by eSDK to perform DNS lookups. It should be robust against slow name resolutions (e.g. poor network conditions) by performing lookups asynchronously. Otherwise SpPumpEvents might block for too long and cause audio stutters. See documentation for return value for more recommendations w.r.t. asynchronous implementation.
SpCallbackSocketCreate This callback, if set by the client, is called by eSDK to create a socket of a certain type and family.
SpCallbackSocketSetOption This callback, if set by the client, is called by eSDK to set specific options on the previously created socket.
SpCallbackSocketClose This callback, if set by the client, is called by eSDK to close the previously opened socket.
SpCallbackSocketBind This callback, if set by the client, is called by eSDK to bind to the provided socket.
SpCallbackSocketListen This callback, if set by the client, is called by eSDK to start listening on the provided socket. This callback has no effect on UDP sockets.
SpCallbackSocketConnect This callback, if set by the client, is called by eSDK to connect to the specified address and remote port.
SpCallbackSocketAccept This callback, if set by the client, is called by eSDK to accept connection on the provided socket.
SpCallbackSocketRead This callback, if set by the client, is called by eSDK to read data from the socket.
SpCallbackSocketWrite This callback, if set by the client, is called by eSDK to write data to the socket.
SpCallbackSocketReadFrom This callback, if set by the client, is called by eSDK to read data from the socket addressed by the SpSockaddr instance.
SpCallbackSocketWriteTo This callback, if set by the client, is called by eSDK to write data to the socket addressed by the SpSockaddr instance.
SpCallbackSocketError This callback, if set by the client, is called by eSDK to get the underlying OS error code.
SpCallbackSocketReadable This callback, if set by the client, is called by eSDK to figure out if the socket is readable.
SpCallbackSocketWriteable This callback, if set by the client, is called by eSDK to figure out if the socket is writable.
SpCallbackLocalAddresses This callback, if set by the client, is called by eSDK to get local interface addresses.
SpCallbackPump This callback, if set by the client, is called by eSDK to pump the network layer.

Enumerations

Return to header index

Functions

Return to header index

Function Description
SpRegisterDnsHALCallbacks Register HAL-related callbacks. Should be called right after SpInit
SpGetDefaultDnsHALCallbacks Get eSDK’s default DNS callbacks.
SpRegisterSocketHALCallbacks Register socket HAL-related callbacks. To remove callbacks, call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros.
SpGetDefaultSocketHALCallbacks Get eSDK’s default socket callbacks.

Data Structures

SpSockaddr

Return to Hal data structures

Struct contains resolved hostname IP address and its family.

struct SpSockaddr {
    enum SpIPFamily family;
    uint8_t addr;
    int port;
};
enum SpIPFamily family

IP protocol family for which lookup is requested.

uint8_t addr

Ip address. Network byte order.

int port

Contains port value if applicable. Host byte order.

SpDnsHALCallbacks

Return to Hal data structures

Callbacks to be registered with SpRegisterDnsHALCallbacks

Any of the pointers may be NULL. To remove DNS callback at any time call SpRegisterDnsHALCallbacks with SpDnsHALCallbacks::dns_lookup_callback set to NULL.

Notes:

  • See the documentation of the callback typedefs for information about the individual callbacks.
struct SpDnsHALCallbacks {
    SpCallbackPerformDNSLookup dns_lookup_callback;
};
SpCallbackPerformDNSLookup dns_lookup_callback

DNS lookup callback. If NULL eSDK will use its internal DNS resolve mechanism.

SpSocketHandle

Return to Hal data structures

Socket handle type.

struct SpSocketHandle {
    void *handle;
    void *tls;
};
void * handle

Platform defined socket representation.

void * tls

Can be used by the TLS implementation to store connection specific state.

SpSocketHALCallbacks

Return to Hal data structures

Callbacks to be registered with SpRegisterSocketHALCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpSocketHALCallbacks {
    SpCallbackSocketCreate socket_create;
    SpCallbackSocketSetOption socket_set_option;
    SpCallbackSocketClose socket_close;
    SpCallbackSocketBind socket_bind;
    SpCallbackSocketListen socket_listen;
    SpCallbackSocketConnect socket_connect;
    SpCallbackSocketAccept socket_accept;
    SpCallbackSocketRead socket_read;
    SpCallbackSocketWrite socket_write;
    SpCallbackSocketReadFrom socket_read_from;
    SpCallbackSocketWriteTo socket_write_to;
    SpCallbackSocketError socket_error;
    SpCallbackSocketReadable socket_readable;
    SpCallbackSocketWriteable socket_writable;
    SpCallbackLocalAddresses local_addresses;
    SpCallbackSocketAddress socket_address;
    SpCallbackPump on_pump;
};
SpCallbackSocketCreate socket_create

Callback to create socket instance.

SpCallbackSocketSetOption socket_set_option

Callback to set options on created socket.

SpCallbackSocketClose socket_close

Callback to close the socket.

SpCallbackSocketBind socket_bind

Callback to bind to socket.

SpCallbackSocketListen socket_listen

Callback to start listening the socket.

SpCallbackSocketConnect socket_connect

Callback to connect to socket.

SpCallbackSocketAccept socket_accept

Callback to accept connection on socket.

SpCallbackSocketRead socket_read

Callback to read data from socket.

SpCallbackSocketWrite socket_write

Callback to write data to socket.

SpCallbackSocketReadFrom socket_read_from

Callback to read data from socket pointed by address.

SpCallbackSocketWriteTo socket_write_to

Callback to write data to socket pointed by address.

SpCallbackSocketError socket_error

Callback to get OS error on socket.

SpCallbackSocketReadable socket_readable

Callback to get readable state on socket.

SpCallbackSocketWriteable socket_writable

Callback to get writable state on socket.

SpCallbackLocalAddresses local_addresses

Callback to get local interface addresses.

SpCallbackSocketAddress socket_address

Callback to platform address representation.

SpCallbackPump on_pump

Callback to pump network layer.

Typedefs

SpCallbackPerformDNSLookup()

Return to Hal typedefs

typedef enum  SpCallbackPerformDNSLookup)(const char *hostname, struct SpSockaddr *sockaddr, void *context)

This callback, if set by the client, is called by eSDK to perform DNS lookups. It should be robust against slow name resolutions (e.g. poor network conditions) by performing lookups asynchronously. Otherwise SpPumpEvents might block for too long and cause audio stutters. See documentation for return value for more recommendations w.r.t. asynchronous implementation.

Parameters

     
[in] const char * hostname Name to be resolved.
[out] struct SpSockaddr * sockaddr Pointer to SpSockaddr structure. DNS lookup can result in a single instance of SpSockaddr structure only. If the underlying implementation (getaddrinfo(), getaddrinfo_a() etc) returns multiple addresses (IPv6, IPv4, …) this callback is responsible for choosing the best suitable one. Port value of SpSockaddr is ignored.
[inout] void * context Context provided in callback register procedure.

See also

Notes:

  • See SpRegisterDnsHALCallbacks for recommendation when it makes sense to provide a custom DNS callback.
  • The application should not block or call other API functions in the callback.

SpCallbackSocketCreate()

Return to Hal typedefs

typedef enum  SpCallbackSocketCreate)(enum SpIPFamily family, enum SpSocketType type, enum SpSocketPool pool_id, struct SpSocketHandle **socket, void *context)

This callback, if set by the client, is called by eSDK to create a socket of a certain type and family.

Parameters

     
[in] enum SpIPFamily family Socket family as specified in SpIPFamily
[in] enum SpSocketType type Socket type as specified in SpSocketType
[in] enum SpSocketPool pool_id Socket pool ID to create the new socket from
[in] struct SpSocketHandle ** socket Pointer to valid SpSocketHandle instance in case of success. Unchanged in case of failure.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketSetOption()

Return to Hal typedefs

typedef enum  SpCallbackSocketSetOption)(struct SpSocketHandle *socket, enum SpSocketOptions option, void *value, void *context)

This callback, if set by the client, is called by eSDK to set specific options on the previously created socket.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] enum SpSocketOptions option One of SpSocketOptions options.
[in] void * value Option value. Depends on the particular SpSocketOptions option.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketClose()

Return to Hal typedefs

typedef enum  SpCallbackSocketClose)(struct SpSocketHandle *socket, void *context)

This callback, if set by the client, is called by eSDK to close the previously opened socket.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketBind()

Return to Hal typedefs

typedef enum  SpCallbackSocketBind)(struct SpSocketHandle *socket, int *port, void *context)

This callback, if set by the client, is called by eSDK to bind to the provided socket.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] int * port Port which eSDK would listen to (host byte order). If the referenced value is zero, port has to be used to return the actual bound port.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketListen()

Return to Hal typedefs

typedef enum  SpCallbackSocketListen)(struct SpSocketHandle *socket, int backlog, void *context)

This callback, if set by the client, is called by eSDK to start listening on the provided socket. This callback has no effect on UDP sockets.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] int backlog Parameter defines the maximum length for the queue of pending connections.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketConnect()

Return to Hal typedefs

typedef enum  SpCallbackSocketConnect)(struct SpSocketHandle *socket, const struct SpSockaddr *addr, void *context)

This callback, if set by the client, is called by eSDK to connect to the specified address and remote port.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] const struct SpSockaddr * addr Address to connect to.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketAccept()

Return to Hal typedefs

typedef enum  SpCallbackSocketAccept)(struct SpSocketHandle *socket, enum SpSocketPool pool_id, struct SpSocketHandle **out_socket, void *context)

This callback, if set by the client, is called by eSDK to accept connection on the provided socket.

Parameters

     
[in] struct SpSocketHandle **out_ socket Socket instance to perform action with.
[in] enum SpSocketPool pool_id Socket pool ID to create the new socket from
[in] struct SpSocketHandle ** out_socket Socket created by accepting connection.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketRead()

Return to Hal typedefs

typedef enum  SpCallbackSocketRead)(struct SpSocketHandle *socket, void *data, int data_size, int *bytes_read, void *context)

This callback, if set by the client, is called by eSDK to read data from the socket.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] void * data Buffer to read data into.
[in] int data_size Amount of requested data to read.
[in] int * bytes_read Pointer to store how many bytes were actually read. If NULL, the read operation is still performed. Should stay unchanged if the read operation has failed.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketWrite()

Return to Hal typedefs

typedef enum  SpCallbackSocketWrite)(struct SpSocketHandle *socket, const void *data, int data_size, int *bytes_written, void *context)

This callback, if set by the client, is called by eSDK to write data to the socket.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] const void * data Buffer with data to be written.
[in] int data_size Amount of data to write.
[in] int * bytes_written Pointer to store how many bytes were actually written. If NULL, the write operation is still performed. Should stay unchanged if the write operation has failed.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadFrom()

Return to Hal typedefs

typedef enum  SpCallbackSocketReadFrom)(struct SpSocketHandle *socket, void *data, int data_size, const void **addr, int *bytes_read, void *context)

This callback, if set by the client, is called by eSDK to read data from the socket addressed by the SpSockaddr instance.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] void * data Buffer to read data into.
[in] int data_size Amount of requested data to read.
[in] const void ** addr Platform defined address representation. See SpCallbackSocketAddress
[in] int * bytes_read Pointer to store how many bytes were actually read. If NULL, read is still performed. Should stay unchanged if reading has failed.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback. This callback should mirror the behavior of recvfrom() for connected/non-connected sockets.

SpCallbackSocketWriteTo()

Return to Hal typedefs

typedef enum  SpCallbackSocketWriteTo)(struct SpSocketHandle *socket, const void *data, int data_size, const void *addr, int *bytes_written, void *context)

This callback, if set by the client, is called by eSDK to write data to the socket addressed by the SpSockaddr instance.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] const void * data Buffer with data to be written.
[in] int data_size Amount of data to write.
[in] const void * addr Platform defined address representation. See SpCallbackSocketAddress
[in] int * bytes_written Pointer to store how many bytes were actually written. If NULL, write is still performed. Should stay unchanged if writing has failed.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback. This callback should mirror the behavior of sendto() for connected/non-connected sockets.

SpCallbackSocketError()

Return to Hal typedefs

typedef int(* SpCallbackSocketError)(struct SpSocketHandle *socket, void *context)

This callback, if set by the client, is called by eSDK to get the underlying OS error code.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance for which error code is requested.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadable()

Return to Hal typedefs

typedef int(* SpCallbackSocketReadable)(struct SpSocketHandle *socket, void *context)

This callback, if set by the client, is called by eSDK to figure out if the socket is readable.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackSocketWriteable()

Return to Hal typedefs

typedef int(* SpCallbackSocketWriteable)(struct SpSocketHandle *socket, void *context)

This callback, if set by the client, is called by eSDK to figure out if the socket is writable.

Parameters

     
[in] struct SpSocketHandle * socket Socket instance to perform action with.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackLocalAddresses()

Return to Hal typedefs

typedef void(* SpCallbackLocalAddresses)(struct SpSockaddr *addrs, int *num_addrs, void *context)

This callback, if set by the client, is called by eSDK to get local interface addresses.

Parameters

     
[in] int *num_ addrs Pointer to array of SpSockaddr to store the data. Data in network byte order.
[in] int * num_addrs eSDK will invoke this callback with a max capacity of the given array. The callback has to set the value to the actual number of returned items. If the client can’t get local interfaces, implementation should fill num_addrs with 0.
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackPump()

Return to Hal typedefs

typedef enum  SpCallbackPump)(unsigned max_wait_ms, void *context)

This callback, if set by the client, is called by eSDK to pump the network layer.

Parameters

     
[in] unsigned max_wait_ms Maximum time to wait in one pump call
[in] void * context Context provided in callback register procedure.

Notes:

  • The application should not block or call other API functions in the callback.

Enumerations

SpIPFamily

Return to Hal enumerations

enum SpIPFamily {
    kSpIPV4,
    kSpIPV6,
};
kSpIPV4

IP v4 family.

kSpIPV6

IP v6 family.

SpSocketPool

Return to Hal enumerations

enum SpSocketPool {
    kSpSocketPoolGeneral,
    kSpSocketPoolZeroConf,
};
kSpSocketPoolGeneral

Sockets used for backend, streaming, etc.

kSpSocketPoolZeroConf

Sockets used for ZeroConf.

SpSocketType

Return to Hal enumerations

enum SpSocketType {
    kSpSocketStream,
    kSpSocketDgram,
};
kSpSocketStream

Stream socket type.

kSpSocketDgram

Datagram socket type.

SpSocketOptions

Return to Hal enumerations

enum SpSocketOptions {
    kSpSocketNonBlocking,
    kSpSocketReuseAddr,
    kSpSocketReusePort,
    kSpSocketMulticastTTL,
    kSpSocketMulticastLoop,
    kSpSocketMembership,
    kSpSocketMcastSendIf,
};
kSpSocketNonBlocking

Nonblocking mode has to be set by the implementation if possible. POSIX analog: TCP_NODELAY. Option is passed as an intptr_t in a range [0, 1].

kSpSocketReuseAddr

Reuse address mode has to be set if possible. POSIX analog: SO_REUSEADDR. Option is passed as an intptr_t in a range [0, 1].

kSpSocketReusePort

Reuse port mode has to be set if possible. POSIX analog: SO_REUSEPORT. Option is passed an intptr_t in a range [0, 1].

kSpSocketMulticastTTL

Multicast TTL has to be set if possible. POSIX analog: IP_MULTICAST_TTL. Option is passed as an intptr_t in a range [0, 255].

kSpSocketMulticastLoop

Multicast loop has to be set if possible. POSIX analog: IP_MULTICAST_LOOP. Option is passed as an intptr_t in a range [0, 1].

kSpSocketMembership

Set group address if possible. POSIX analog: IP_ADD_MEMBERSHIP. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable.

kSpSocketMcastSendIf

Set outgoing multicast interface. POSIX analog: IP_MULTICAST_IF. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable.

Functions

SpRegisterDnsHALCallbacks()

Return to Hal functions

SpError SpRegisterDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks, void *context)

Register HAL-related callbacks. Should be called right after SpInit

Parameters

     
[in] struct SpDnsHALCallbacks * callbacks Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code.

Notes:

  • To remove DNS callback at any time call SpRegisterDnsHALCallbacks with SpDnsHALCallbacks::dns_lookup_callback set to NULL.
  • eSDK provides built-in implementation for DNS lookups. For integrations built with glibc = 2.2.3 DNS lookups will be implemented via getaddrinfo_a() and therefore will be done asynchronously. Such integrations have to link libanl (-lanl). Remaining builds will use blocking DNS lookups (e.g. getaddrinfo() for POSIX). Depending on the platform's timeout settings they might cause SpPumpEvents to block for a long time and result in audio stutters. For affected platforms it's recommended to provide an asynchronous implementation instead.

SpGetDefaultDnsHALCallbacks()

Return to Hal functions

SpError SpGetDefaultDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks)

Get eSDK's default DNS callbacks.

Parameters

     
[in] struct SpDnsHALCallbacks * callbacks SpDnsHALCallbacks struct to be populated with pointers to callback functions

Returns

Returns an error code.

Notes:

SpRegisterSocketHALCallbacks()

Return to Hal functions

SpError SpRegisterSocketHALCallbacks(struct SpSocketHALCallbacks *callbacks, void *context)

Register socket HAL-related callbacks. To remove callbacks, call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros.

Parameters

     
[in] struct SpSocketHALCallbacks * callbacks Structure with pointers to individual callback functions. Either all pointers are NULL or all are valid.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Notes:

SpGetDefaultSocketHALCallbacks()

Return to Hal functions

SpError SpGetDefaultSocketHALCallbacks(struct SpSocketHALCallbacks *callbacks, void **context)

Get eSDK's default socket callbacks.

Parameters

     
[in] struct SpSocketHALCallbacks * callbacks SpSocketHALCallbacks struct to be populated with pointers to callback functions
[in] void ** context the default context that is being used.

Returns

Returns an error code.

Notes:

Log

#include "spotify_embedded_log.h"

Macros and Constants

Return to header index

Define Value
SP_FILE_NAME FILE
SP_LOG_DEFAULT_LEVEL SP_LOG_LEVEL_INFO
SP_LOG_DEFINE_TRACE_OBJ struct
SP_LOG_DECLARE_TRACE_OBJ extern struct
SP_LOG_REGISTER_TRACE_OBJ See macro below
SP_LOG See macro below
SpLogFatal See macro below
SpLogError See macro below
SpLogWarning See macro below
SpLogInfo See macro below
SpLogDebug See macro below
SpLogTrace See macro below

Data Structures

Return to header index

Data Structure Description
SpLogTraceObject Trace object.

Enumerations

Return to header index

Functions

Return to header index

Function Description
SpLogRegisterTraceObject Register a defined trace object with eSDK.
SpLog Output a debug message via eSDK.
SpLogSetLevel Control the current logging level.
SpLogGetLevels Get registered trace objects and log levels.

Macros and Constants

SP_FILE_NAME

Return to Log macros

#define SP_FILE_NAME __FILE__

Preferred macro to log the file name, you might redefine SP_FILE_NAME using basename() or use -ffile-prefix-map.

SP_LOG_DEFAULT_LEVEL

Return to Log macros

#define SP_LOG_DEFAULT_LEVEL SP_LOG_LEVEL_INFO

Default trace log level.

SP_LOG_DEFINE_TRACE_OBJ

Return to Log macros

#define SP_LOG_DEFINE_TRACE_OBJ struct

Macro to define a trace object.

obj Name of the trace object

SP_LOG_DECLARE_TRACE_OBJ

Return to Log macros

#define SP_LOG_DECLARE_TRACE_OBJ extern struct

Macro to declare a previously defined trace object.

obj Name of the trace object

SP_LOG_REGISTER_TRACE_OBJ

Return to Log macros

#define SP_LOG_REGISTER_TRACE_OBJ SpLogRegisterTraceObject(&trace_obj_##obj)

Macro to register a previously defined trace object.

obj Name of the trace object

SP_LOG

Return to Log macros

#define SP_LOG 	do { \
	if (trace_obj_##obj.level >= lvl) { \
		

Macro that outputs a trace message.

obj Trace object name lvl Trace level for the message file Source file name func Calling function name line Line number in the source file

SpLogFatal

Return to Log macros

#define SpLogFatal SP_LOG(obj, SP_LOG_LEVEL_FATAL, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_FATAL.

SpLogError

Return to Log macros

#define SpLogError SP_LOG(obj, SP_LOG_LEVEL_ERROR, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_ERROR.

SpLogWarning

Return to Log macros

#define SpLogWarning SP_LOG(obj, SP_LOG_LEVEL_WARNING, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_WARNING.

SpLogInfo

Return to Log macros

#define SpLogInfo SP_LOG(obj, SP_LOG_LEVEL_INFO, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_INFO.

SpLogDebug

Return to Log macros

#define SpLogDebug SP_LOG(obj, SP_LOG_LEVEL_DEBUG, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_DEBUG.

SpLogTrace

Return to Log macros

#define SpLogTrace SP_LOG(obj, SP_LOG_LEVEL_TRACE, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_TRACE.

Data Structures

SpLogTraceObject

Return to Log data structures

Trace object.

The trace object is an abstraction of a specific trace message category and an associated log level. The level can be changed freely for individual trace objects.

struct SpLogTraceObject {
    SpLogLevel level;
    const char *name;
};
SpLogLevel level

The current debug level for this trace object.

const char * name

The trace category name describing this trace object.

Enumerations

SpLogLevel

Return to Log enumerations

enum SpLogLevel {
    SP_LOG_LEVEL_FATAL,
    SP_LOG_LEVEL_ERROR,
    SP_LOG_LEVEL_WARNING,
    SP_LOG_LEVEL_INFO,
    SP_LOG_LEVEL_DEBUG,
    SP_LOG_LEVEL_TRACE,
};
SP_LOG_LEVEL_FATAL

Indicates a severe abnormal condition and program termination.

SP_LOG_LEVEL_ERROR

Indicates an abnormal condition that could result in degraded functionality.

SP_LOG_LEVEL_WARNING

Indicates a condition that probably has some impact on execution or performance.

SP_LOG_LEVEL_INFO

Informational message.

SP_LOG_LEVEL_DEBUG

Debug message.

SP_LOG_LEVEL_TRACE

Trace message.

Functions

SpLogRegisterTraceObject()

Return to Log functions

SpError SpLogRegisterTraceObject(struct SpLogTraceObject *obj)

Register a defined trace object with eSDK.

Parameters

     
[in] struct SpLogTraceObject * obj Pointer to trace object

Returns

Return kSpErrorOk on success, or error code on failure.

SpLog()

Return to Log functions

void SpLog(const struct SpLogTraceObject *obj, SpLogLevel level, const char *file, const char *func, int line, const char *format,...)

Output a debug message via eSDK.

obj Pointer to trace object level The log level associated this this message file The source file from where the call is made, see SP_FILE_NAME. func The function name from where the call is made, typically __func__. line The line number from where the call is made, typically __LINE__. format A printf style format string followed by arguments.

Parameters

     
[in] const struct SpLogTraceObject * obj Pointer to trace object
[in] SpLogLevel level The log level associated this this message
[in] const char * file The source file from where the call is made, see SP_FILE_NAME.
[in] const char * func The function name from where the call is made, typically func.
[in] int line The line number from where the call is made, typically LINE.
[in] const char * format A printf style format string followed by arguments.

SpLogSetLevel()

Return to Log functions

SpError SpLogSetLevel(const char *category, SpLogLevel level)

Control the current logging level.

Control the logging level for a particular category. If the current configured log level is greater than or equal to the level associated with the message, the log message will be passed to the debug log callback. Each log message is also associated with a category. The category is a string that is included in the log message output. Each individual category has a separate current log level. The log messages produced by the eSDK are formatted as: LEVEL CATEGORY MESSAGE where LEVEL is a single letter indicating the log level (E=Error, I=Info, etc.), CATEGORY is a short string that identifies the log category, for example 'api' and MESSAGE is the actual debug message. As an example, a debug output string with level set to SP_LOG_LEVEL_ERROR (letter "E") and the category "api" could look something like this (the timestamp is not actually part of the debug message from eSDK, but added by the SpCallbackDebugMessage Therefore, the format may not exactly match the example below).

Parameters

     
[in] const char * category Identifies the log category for which to set the logging level. If NULL is passed in this parameter, the level will be applied to all categories.
[in] SpLogLevel level The log level defined by SpLogLevel

Returns

Returns an error code if the category is not a valid log category.

SpLogGetLevels()

Return to Log functions

SpError SpLogGetLevels(char *buffer, int buffer_len)

Get registered trace objects and log levels.

The information about trace objects and levels is represented as a string containing comma separated tuples level:trace obj, e.g. "4:app,4:esdk,4:audio".

Parameters

     
[in] char * buffer A buffer to copy the string to.
[in] int buffer_len Length of the buffer

Returns

Returns an error code if the buffer is not big enough.

Media

#include "spotify_embedded_media.h"

Data Structures

Return to header index

Data Structure Description
SpStreamInfo Stream Parameters.
SpStreamCallbacks Callbacks to be registered with SpRegisterStreamCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackStreamStart Callback to provide track details to the application.
SpCallbackStreamData Callback for delivering data to the integration.
SpCallbackStreamEnd Callback to tell integration that all data was delivered.
SpCallbackStreamGetPosition Callback to get the playback position in milliseconds.
SpCallbackStreamSeekToPosition Callback to tell the integration to seek to a position.
SpCallbackStreamFlush Callback to tell the integration to flush.

Enumerations

Return to header index

Functions

Return to header index

Function Description
SpRegisterStreamCallbacks Register callbacks related to the delivery API.
SpNotifySeekComplete API to notify eSDK of the completion of seek operation.
SpNotifyTrackLength API to notify eSDK of the track length in milliseconds.
SpNotifyTrackError API to notify eSDK of any track errors with last played position.
SpNotifyStreamPlaybackStarted Notify eSDK that the first audio sample of the delivery has been played.
SpNotifyStreamPlaybackContinued Notify eSDK that the first audio sample after a flush of a delivery has been played.
SpNotifyStreamPlaybackFinishedNaturally Notify eSDK that the delivery playback finished by playing the last sample of the delivery.
SpSetDownloadPosition API to instruct eSDK to start downloading from a given byte offset.

Data Structures

SpStreamInfo

Return to Media data structures

Stream Parameters.

struct SpStreamInfo {
    uint32_t size;
    int32_t gain_mdb;
    uint32_t start_position_ms;
    const char *resource;
};
uint32_t size

Size of the stream in bytes. If the size is unknown, 0 is used.

int32_t gain_mdb

Audio normalization gain (in mdB) to apply to the stream.

uint32_t start_position_ms

Reserved for internal use.

const char * resource

Reserved for internal use.

SpStreamCallbacks

Return to Media data structures

Callbacks to be registered with SpRegisterStreamCallbacks

struct SpStreamCallbacks {
    SpCallbackStreamStart on_start;
    SpCallbackStreamData on_data;
    SpCallbackStreamEnd on_end;
    SpCallbackStreamGetPosition on_get_position;
    SpCallbackStreamSeekToPosition on_seek_position;
    SpCallbackStreamFlush on_flush;
};
SpCallbackStreamStart on_start

Start of delivery callback.

SpCallbackStreamData on_data

Data delivery callback.

SpCallbackStreamEnd on_end

End of delivery callback.

SpCallbackStreamGetPosition on_get_position

Current playback position callback.

SpCallbackStreamSeekToPosition on_seek_position

Seek to position callback.

SpCallbackStreamFlush on_flush

Flush callback.

Typedefs

SpCallbackStreamStart()

Return to Media typedefs

typedef void(* SpCallbackStreamStart)(unsigned int stream_id, enum SpMediaFormat media_format, enum SpDrmFormat drm_format, const struct SpStreamInfo *stream_info, void *context)

Callback to provide track details to the application.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] enum SpMediaFormat media_format Information about the format of the audio data
[in] enum SpDrmFormat drm_format Information about the used DRM method
[in] const struct SpStreamInfo * stream_info Additional information related to the stream

See also

SpCallbackStreamData()

Return to Media typedefs

typedef size_t(* SpCallbackStreamData)(unsigned int stream_id, const void *buf, size_t len, uint32_t offset, void *context)

Callback for delivering data to the integration.

To register this callback, use the function SpRegisterStreamCallbacks This callback is called up to 4 times in a single pump until the integration accepts data less than buffer length or when all data from the download buffer is exhausted.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] const void * buf Block of data (it can be audio or video data)
[in] size_t len Size of the data
[in] uint32_t offset Byte offset in the data stream (relative to the start)
[in] void * context Context pointer that was passed when registering the callback

SpCallbackStreamEnd()

Return to Media typedefs

typedef void(* SpCallbackStreamEnd)(unsigned int stream_id, void *context)

Callback to tell integration that all data was delivered.

To register this callback, use the function SpRegisterStreamCallbacks stream_id Unique identifier to identify tracks context Context pointer that was passed when registering the callback

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] void * context Context pointer that was passed when registering the callback

SpCallbackStreamGetPosition()

Return to Media typedefs

typedef uint32_t(* SpCallbackStreamGetPosition)(unsigned int stream_id, void *context)

Callback to get the playback position in milliseconds.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] void * context Context pointer that was passed when registering the callback

SpCallbackStreamSeekToPosition()

Return to Media typedefs

typedef void(* SpCallbackStreamSeekToPosition)(unsigned int stream_id, uint32_t position_ms, void *context)

Callback to tell the integration to seek to a position.

To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should start to seek to the given position. The integration is expected to call SpSetDownloadPosition to instruct eSDK to start downloading from a byte offset corresponding to the position given in this callback. If the position exceeds the length of the track the integration is expected to seek as close as possible to the end. stream_id Unique identifier to identify tracks position_ms Position in time within the track where to seek to context Context pointer that was passed when registering the callback

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] uint32_t position_ms Position in time within the track where to seek to
[in] void * context Context pointer that was passed when registering the callback

SpCallbackStreamFlush()

Return to Media typedefs

typedef uint32_t(* SpCallbackStreamFlush)(unsigned int *playing_stream_id, void *context)

Callback to tell the integration to flush.

To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should forget all queued audio and compressed data.

Parameters

     
[out] unsigned int * playing_stream_id The delivery of the track which is currently playing. If nothing is playing, zero should be used
[in] void * context Context pointer that was passed when registering the callback

Enumerations

SpMediaFormat

Return to Media enumerations

enum SpMediaFormat {
    kSpMediaFormatSpotifyOggVorbis,
    kSpMediaFormatMp3,
    kSpMediaFormatMp4AAC,
    kSpMediaFormatSpacAAC,
    kSpMediaFormatSpotifyManifestId,
};
kSpMediaFormatSpotifyOggVorbis

ogg/vorbis 44.1 kHz stereo audio format with Spotify metadata page

kSpMediaFormatMp3

mp3

kSpMediaFormatMp4AAC

mp4/aac-lc

kSpMediaFormatSpacAAC

spac/aac-he-v2

kSpMediaFormatSpotifyManifestId

Spotify video manifest id.

Functions

SpRegisterStreamCallbacks()

Return to Media functions

SpError SpRegisterStreamCallbacks(struct SpStreamCallbacks *cb, void *context)

Register callbacks related to the delivery API.

Parameters

     
[in] struct SpStreamCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpNotifySeekComplete()

Return to Media functions

SpError SpNotifySeekComplete(unsigned int stream_id)

API to notify eSDK of the completion of seek operation.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks

Returns

Returns an error code

SpNotifyTrackLength()

Return to Media functions

SpError SpNotifyTrackLength(unsigned int stream_id, uint32_t length_ms)

API to notify eSDK of the track length in milliseconds.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] uint32_t length_ms Position in milliseconds of the track

Returns

Returns an error code

SpNotifyTrackError()

Return to Media functions

SpError SpNotifyTrackError(unsigned int stream_id, uint32_t position_ms, const char *reason)

API to notify eSDK of any track errors with last played position.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] uint32_t position_ms Position in milliseconds of the track
[in] const char * reason The reason for the error

Returns

Returns an error code

SpNotifyStreamPlaybackStarted()

Return to Media functions

SpError SpNotifyStreamPlaybackStarted(unsigned int stream_id)

Notify eSDK that the first audio sample of the delivery has been played.

This is used by the eSDK to measure playback latency.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks

Returns

Returns an error code. Returns kSpErrorAlreadyInitialized if SpNotifyStreamPlaybackStarted() has already been called for this delivery.

SpNotifyStreamPlaybackContinued()

Return to Media functions

SpError SpNotifyStreamPlaybackContinued(unsigned int stream_id)

Notify eSDK that the first audio sample after a flush of a delivery has been played.

This is used by the eSDK to measure seek latency.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks

Returns

Returns an error code

SpNotifyStreamPlaybackFinishedNaturally()

Return to Media functions

SpError SpNotifyStreamPlaybackFinishedNaturally(unsigned int stream_id, uint32_t last_pos_ms)

Notify eSDK that the delivery playback finished by playing the last sample of the delivery.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] uint32_t last_pos_ms Position in milliseconds of the track

Returns

Returns an error code

SpSetDownloadPosition()

Return to Media functions

SpError SpSetDownloadPosition(unsigned int stream_id, uint32_t byte_offset)

API to instruct eSDK to start downloading from a given byte offset.

Parameters

     
[in] unsigned int stream_id Unique identifier to identify tracks
[in] uint32_t byte_offset New download byte offset (relative to the start of the stream) where downloading could continue.

Returns

Returns an error code

Play

#include "spotify_embedded_play_api.h"

Macros and Constants

Return to header index

Define Value
SP_NO_INDEX -1
SP_MAX_UUID_LENGTH 36
SP_MAX_SOURCE_TYPE_LENGTH 63
SP_MAX_SOURCE_URI_LENGTH 511
SP_MAX_REFERRER_LENGTH 16
SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS  
SP_PLAYOPTIONS_INITIALIZER See macro below

Data Structures

Return to header index

Data Structure Description
SpSourceInfo Metadata for identifying where a playback request originated from.
SpPlayOptions PlayOptions passed to SpPlayUriWithOptions Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values.

Functions

Return to header index

Function Description
SpPlayUri Start local playback of the given Spotify URI.
SpPlayUriWithOptions Start local playback of the given Spotify URI with additional options.
SpPlayContextUri Start local playback of the given Spotify URI with an optional track UID.
SpQueueUri Queue a URI. The track will be in queue only after kSpPlaybackNotifyQueuedTrackAccepted event is raised, but for UI purposes one can choose to monitor for kSpPlaybackNotifyMetadataChanged instead.
SpPlaybackBecomeActiveDevice Become active without starting to play.

Macros and Constants

SP_NO_INDEX

Return to Play macros

#define SP_NO_INDEX -1

Indicates that the index value is not set. Note: Can only be used with eSDK 3.

See also

SP_MAX_UUID_LENGTH

Return to Play macros

#define SP_MAX_UUID_LENGTH 36

Maximum length of a UUID.

A 128 bit UUID containing 32 hexadecimal digits in five groups separated by hyphens.

SP_MAX_SOURCE_TYPE_LENGTH

Return to Play macros

#define SP_MAX_SOURCE_TYPE_LENGTH 63

Maximum length of the type of playback source.

See also

SP_MAX_SOURCE_URI_LENGTH

Return to Play macros

#define SP_MAX_SOURCE_URI_LENGTH 511

Maximum length of the source URIs.

See also

SP_MAX_REFERRER_LENGTH

Return to Play macros

#define SP_MAX_REFERRER_LENGTH 16

Maximum length of the referrer.

See also

SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS

Return to Play macros

#define SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS 

Internal macro.

See also

SP_PLAYOPTIONS_INITIALIZER

Return to Play macros

#define SP_PLAYOPTIONS_INITIALIZER 	{							\
		/*.from_index =*/

Macro for initialization of struct SpPlayOptions Use it instead of memset() due to the fact that some fields are optional and encoded as non-zero values.

Data Structures

SpSourceInfo

Return to Play data structures

Metadata for identifying where a playback request originated from.

See also

struct SpSourceInfo {
    char type;
    char uri;
    char expected_track_uri;
    char referrer;
};
char type

The type of playlist/context/UI view that caused this playback to start. Note: If set, this MUST be one of the following strings (unless told otherwise):

"album" "artist" "playlist" "playlistfolder" "radio" "search" "toplist" "unknown" Please contact Spotify if you have a common play source that is not obviously represented in this list.

char uri

The URI of the parent container, if there is one.

For example, if the user selects an album from an artist view, the URI passed to SpPlayUri is the album to play, and the URI in this source field should be the URI of the artist.

char expected_track_uri

The URI of the track that is expected to play.

If the URI to play is a container of multiple tracks (ex: playlist, artist, album), this field can optionally be filled with the track URI that is expected to play. This can be used to adjust the index when the context has changed or when tracks are unavailable.

char referrer

The view you were in prior to initiating playback.

The acceptable values are: "home" "search" "collection" "browse" (this is for older clients) "radio" (this is for older clients) "other"

SpPlayOptions

Return to Play data structures

PlayOptions passed to SpPlayUriWithOptions Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values.

Example:


struct  SpPlayOptions options= SP_PLAYOPTIONS_INITIALIZER;
struct SpPlayOptions {
    int from_index;
    const char *from_uid;
    int offset_ms;
    int shuffle_context;
    int repeat_mode;
    const struct SpSourceInfo *source_info;
};
int from_index

Track index in the Context from which playback should start. Use SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in the first track of the context being played whereas in shuffled context this will result in a random track being played.

const char * from_uid

The UID to identify a unique track in the context.

int offset_ms

The time offset to start playing specified track from.

int shuffle_context

Set to enable or disable shuffle mode for the requested playback command.

Setting this to 1 means shuffling is enabled, 0 means it is disabled, all remaining values will leave shuffling settings unchanged.

Notes:
  • There is no guarantee that requested shuffle mode will be applied. E.g. intended shuffle mode might be overwritten by limitations of the user's licence.
  • This is the recommended way of enabling a "play with shuffle" action, instead of chaining SpPlaybackEnableShuffle with SpPlayUri
  • Enabling or disabling this option does not change shuffle for the whole session, but only for this specific playback request.
int repeat_mode

Set to enable or disable repeat mode for the requested playback command.

Setting it to 0 disables repeat mode, 1 enables repeat for all tracks in the requested context, 2 enables repeat of a single track. All remaining values will leave repeating settings unchanged.

Notes:
  • There is no guarantee that requested repeat mode will be applied. E.g. intended repeat mode might be overwritten by limitations of the user's licence.
  • This is the recommended way of enabling a "play with repeat" action, instead of chaining SpPlaybackEnableRepeat with SpPlayUri
  • Enabling or disabling this option doesn't affect repeat mode for the whole session, but only for this specific playback request.
const struct SpSourceInfo * source_info

Metadata about what user action caused this playback event, and the expected result.

See also

Functions

SpPlayUri()

Return to Play functions

SpError SpPlayUri(const char *uri, int index, int offset_ms, const struct SpSourceInfo *source, int alias_index)

Start local playback of the given Spotify URI.

This call starts playback of a Spotify URI, such as a playlist, album, artist, or track. Valid Spotify URIs can be obtained via the Spotify Web API. Using this call will 'pull' playback from any other Spotify Connect client active on the same account. Note that there may be a lag between the introduction of new URI types and support for playing them with this call.

Parameters

     
[in] const char * uri URI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in] int alias_ index The zero based index of the item to start playing in the resource (for instance, ‘4’ would play the 5th track in a playlist). Set to zero if the resource does not have multiple items. In eSDK 3, this can be set to SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in the first track of the context being played whereas in shuffled context this will result in a random track being played.
[in] int offset_ms The time offset to start playing specified track from. Set to zero to start from the beginning.
[in] const struct SpSourceInfo * source Metadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn’t possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience.
[in] int alias_index The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

See also

SpPlayUriWithOptions()

Return to Play functions

SpError SpPlayUriWithOptions(const char *uri, const struct SpPlayOptions *opts, int alias_index)

Start local playback of the given Spotify URI with additional options.

Parameters

     
[in] const char * uri The context URI to play.
[in] const struct SpPlayOptions * opts The options to apply to the play command.
[in] int alias_index Device alias index. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

SpPlayContextUri()

Return to Play functions

SpError SpPlayContextUri(const char *uri, const char *from_uid, int offset_ms, const struct SpSourceInfo *source, int alias_index)

Start local playback of the given Spotify URI with an optional track UID.

This call will start playback of any Spotify context URI. In addition, it allows the client to provide a UID to start the playback from a given track in the context. The main difference between UIDs and the field SpSourceInfo::expected_track_uri is that while one track URI can occur more than once in the context, UIDs are unique for each track in it. Valid Spotify URIs can be obtained via the Spotify Web API. Track UIDs are currently available when resolving contexts from a small subset of services. Using this call will 'pull' playback from any other Spotify Connect client active on the same account.

Parameters

     
[in] const char * uri URI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in] const char * from_uid The UID to identify a unique track in the context.
[in] int offset_ms The time offset to start playing specified track from. Set to zero to start from the beginning.
[in] const struct SpSourceInfo * source Metadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn’t possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience.
[in] int alias_index The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

See also

SpQueueUri()

Return to Play functions

SpError SpQueueUri(const char *uri)

Queue a URI. The track will be in queue only after kSpPlaybackNotifyQueuedTrackAccepted event is raised, but for UI purposes one can choose to monitor for kSpPlaybackNotifyMetadataChanged instead.

Parameters

     
[in] const char * uri URI to queue.

Returns

Returns an error code.

See also

SpPlaybackBecomeActiveDevice()

Return to Play functions

SpError SpPlaybackBecomeActiveDevice(int alias_index)

Become active without starting to play.

alias_index The index of the device alias that should become active. If aliases aren't used, pass SP_NO_ALIAS_SELECTED. This call makes the device active, without starting to play anything, if playback is paused or no device is active. The device is active after the kSpPlaybackNotifyBecameActive event is received. If another Connect-enabled device was active and playing, it will be interrupted. If the currently active device is playing, this call behaves like SpPlaybackPlay If device aliases are used, this function will switch the selected alias. If the selected alias was changed during playback, the playback will continue uninterrupted with the new alias.

Parameters

     
[in] int alias_index The index of the device alias that should become active. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

Storage

#include "spotify_embedded_storage.h"

Data Structures

Return to header index

Data Structure Description
SpDiskStorageCallbacks Callbacks to be registered with SpRegisterStorageCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackStorageAlloc Callback to allocate space for the resource being stored. Each successful alloc call is accompanied with a corresponding close call. It is obligatory for the user to use this callback to reserve actual space on device media for the key specified.
SpCallbackStorageWrite Callback for writing the data into storage. Before writing to the storage eSDK does one of two things: call alloc to reserve space for future write or call read to get the data. After that eSDK writes the data into storage. Once write is fully complete eSDK calls close callback.
SpCallbackStorageRead Callback for reading the data. Once eSDK reads all required data, the close callback is called to notify the user that the data handle referenced by storage_key can be closed.
SpCallbackStorageClose Callback to inform the user that the data handle referenced by storage_key can be closed.
SpCallbackStorageDelete Callback to inform the user that data referenced by storage_key should be deleted from storage.
SpCallbackThrottleRequest eSDK calls this callback to figure out if it needs to limit write access to the storage.

Functions

Return to header index

Function Description
SpRegisterStorageCallbacks Register storage callbacks.

Data Structures

SpDiskStorageCallbacks

Return to Storage data structures

Callbacks to be registered with SpRegisterStorageCallbacks

Storage callbacks must be either all NULLs or all valid pointers. Throttle callback may be NULL regardless of storage callbacks. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpDiskStorageCallbacks {
    SpCallbackStorageAlloc alloc_storage;
    SpCallbackStorageWrite write_storage;
    SpCallbackStorageRead read_storage;
    SpCallbackStorageClose close_storage;
    SpCallbackStorageDelete delete_storage;
    SpCallbackThrottleRequest throttle_request;
};
SpCallbackStorageAlloc alloc_storage

Alloc storage record callback.

SpCallbackStorageWrite write_storage

Write storage data callback.

SpCallbackStorageRead read_storage

Read storage data callback.

SpCallbackStorageClose close_storage

Close storage record callback.

SpCallbackStorageDelete delete_storage

Delete storage record callback.

SpCallbackThrottleRequest throttle_request

Asks the client if disk writes need to be throttled.

Typedefs

SpCallbackStorageAlloc()

Return to Storage typedefs

typedef enum  SpCallbackStorageAlloc)(const char *storage_key, uint32_t total_size, void *context)

Callback to allocate space for the resource being stored. Each successful alloc call is accompanied with a corresponding close call. It is obligatory for the user to use this callback to reserve actual space on device media for the key specified.

To register this callback, use the function SpRegisterStorageCallbacks

Parameters

     
[in] const char * storage_key Storage key identifying the record
[in] uint32_t total_size The full resource size in bytes or 0 if size is not known.
[in] void * context Context pointer that was passed when registering the callback.

See also

Notes:

  • The allocation of space should be done in the way that following read and write operations will succeed within the specified resource size.

SpCallbackStorageWrite()

Return to Storage typedefs

typedef int(* SpCallbackStorageWrite)(const char *storage_key, uint32_t offset, const void *data, uint32_t data_size, void *context)

Callback for writing the data into storage. Before writing to the storage eSDK does one of two things: call alloc to reserve space for future write or call read to get the data. After that eSDK writes the data into storage. Once write is fully complete eSDK calls close callback.

To register this callback, use the function SpRegisterStorageCallbacks

Parameters

     
[in] const char * storage_key Storage key identifying the record
[in] uint32_t offset The offset in bytes in the resource we are writing to.
[in] const void * data A pointer to the buffer containing the data to be written to storage.
[in] uint32_t data_size The number of bytes to be written to the storage.
[in] void * context Context pointer that was passed when registering the callback.

See also

Notes:

  • The application should not block or call other API functions in the callback. Offset field must always be respected on write operation. Application should consume whole data in the call.

SpCallbackStorageRead()

Return to Storage typedefs

typedef int(* SpCallbackStorageRead)(const char *storage_key, uint32_t offset, void *data, uint32_t data_size, void *context)

Callback for reading the data. Once eSDK reads all required data, the close callback is called to notify the user that the data handle referenced by storage_key can be closed.

To register this callback, use the function SpRegisterStorageCallbacks

Parameters

     
[in] const char * storage_key Storage key identifying the record
[in] uint32_t offset The offset eSDK is reading from.
[out] void * data A pointer to the buffer that receives the data read from storage.
[in] uint32_t data_size The number bytes to read.
[in] void * context Context pointer that was passed when registering the callback

See also

Notes:

  • The application should not block or call other API functions in the callback. If no storage read is possible, just return 0.

SpCallbackStorageClose()

Return to Storage typedefs

typedef void(* SpCallbackStorageClose)(const char *storage_key, void *context)

Callback to inform the user that the data handle referenced by storage_key can be closed.

To register this callback, use the function SpRegisterStorageCallbacks

Parameters

     
[in] const char * storage_key Storage key identifying the record
[in] void * context Context pointer that was passed when registering the callback.

Notes:

  • The application should not block or call other API functions in the callback. This callback would be called for any successful alloc. For any resource open caused by Read/Write API calls.

SpCallbackStorageDelete()

Return to Storage typedefs

typedef enum  SpCallbackStorageDelete)(const char *storage_key, void *context)

Callback to inform the user that data referenced by storage_key should be deleted from storage.

To register this callback, use the function SpRegisterStorageCallbacks

Parameters

     
[in] const char * storage_key Storage key identifying the record.
[in] void * context Context pointer that was passed when registering the callback.

Notes:

  • The application should not block or call other API functions in the callback.
  • If the deletion operation is expected to take some time the application shall return kSpAPITryAgain for the duration of the operation and kSpAPINoError once it has been completed. It is important to not block execution of eSDK for prolonged periods (ideally less than 10ms). This callback can be called for literally any storage_key.

SpCallbackThrottleRequest()

Return to Storage typedefs

typedef int(* SpCallbackThrottleRequest)(const char *storage_key, void *context)

eSDK calls this callback to figure out if it needs to limit write access to the storage.

Parameters

     
[in] const char * storage_key Storage key identifying the record.
[in] void * context Context pointer that was passed when registering the callback.

Notes:

  • The application should not block or call other API functions in the callback.

Functions

SpRegisterStorageCallbacks()

Return to Storage functions

SpError SpRegisterStorageCallbacks(struct SpDiskStorageCallbacks *cb, void *context)

Register storage callbacks.

Parameters

     
[in] struct SpDiskStorageCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Tls

#include "spotify_embedded_tls.h"

Data Structures

Return to header index

Data Structure Description
SpTLSCallbacks Callbacks to be registered with SpRegisterTLSCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackTLSInit This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization.
SpCallbackTLSDeinit This callback is invoked by eSDK to let the TLS library integration perform deallocation of resources during teardown.
SpCallbackTLSCreate This callback is invoked once in the beginning of every TLS connection.
SpCallbackTLSHandshake This callback is invoked by eSDK to perform the TLS handshake.
SpCallbackTLSRead This callback is invoked by eSDK to read data on a TLS connection.
SpCallbackTLSWrite This callback is invoked by eSDK to write data on a TLS connection.
SpCallbackTLSClose This callback should clean up any resources allocated in the connect callback.
SpCallbackTLSGetError Callback invoked to get an error message for the last error.

Functions

Return to header index

Function Description
SpRegisterTLSCallbacks Register TLS-related callbacks.
SpTLSAddCARootCert Add root certificate to the eSDK TLS stack.
SpTLSFreeCARootCerts Remove all certificates loaded on the TLS stack and free the memory used by them.

Data Structures

SpTLSCallbacks

Return to Tls data structures

Callbacks to be registered with SpRegisterTLSCallbacks

None of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpTLSCallbacks {
    SpCallbackTLSInit init;
    SpCallbackTLSDeinit deinit;
    SpCallbackTLSCreate create;
    SpCallbackTLSHandshake handshake;
    SpCallbackTLSRead read;
    SpCallbackTLSWrite write;
    SpCallbackTLSClose close;
    SpCallbackTLSGetError get_error;
};
SpCallbackTLSInit init

Callback that performs one-time initialization.

SpCallbackTLSDeinit deinit

Callback that performs release of resources allocated during init.

SpCallbackTLSCreate create

Callback invoked once per connection to initialize TLS context.

SpCallbackTLSHandshake handshake

Callback invoked repeatedly to perform the TLS handshake.

SpCallbackTLSRead read

Callback for reading from the TLS data stream.

SpCallbackTLSWrite write

Callback for writing to the TLS data stream.

SpCallbackTLSClose close

Callback invoked to cleanup any TLS context before closing the socket.

SpCallbackTLSGetError get_error

Callback invoked to get an error message for the last error.

Typedefs

SpCallbackTLSInit()

Return to Tls typedefs

typedef enum  SpCallbackTLSInit)(void *context)

This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization.

Parameters

     
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSDeinit()

Return to Tls typedefs

typedef enum  SpCallbackTLSDeinit)(void *context)

This callback is invoked by eSDK to let the TLS library integration perform deallocation of resources during teardown.

Parameters

     
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSCreate()

Return to Tls typedefs

typedef enum  SpCallbackTLSCreate)(struct SpSocketHandle *socket, const char *hostname, void *context)

This callback is invoked once in the beginning of every TLS connection.

The callback receives a socket via the pointer to SpSocketHandle that is already connected to the remote peer. This callback should typically allocate and set up all TLS related resources. The tls field of the SpSocketHandle should be used to store any connection specific state that is needed.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] const char * hostname Hostname of the remote peer.
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSHandshake()

Return to Tls typedefs

typedef enum  SpCallbackTLSHandshake)(struct SpSocketHandle *socket, void *context)

This callback is invoked by eSDK to perform the TLS handshake.

The callback is invoked repeatedly to perform the handshake. This callback is invoked repeatedly as long as it returns kSpAPITryAgain The peer verification is mandatory and the implementation of this callback must validate the peer certificate against a list of trusted CA certificates. Should return kSpAPIGenericError if the handshake failed. Any specific information about the reason for the failure will be returned in the SpCallbackTLSGetError call.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] void * context Context provided in callback register function.

Notes:

  • The application must not block or call other API functions in the callback.

SpCallbackTLSRead()

Return to Tls typedefs

typedef enum  SpCallbackTLSRead)(struct SpSocketHandle *socket, void *buf, size_t len, size_t *actual, void *context)

This callback is invoked by eSDK to read data on a TLS connection.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] void * buf Pointer to buffer for the data to be received.
[in] size_t len The size of the buffer (in bytes).
[out] size_t * actual Actual number of bytes received.
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSWrite()

Return to Tls typedefs

typedef enum  SpCallbackTLSWrite)(struct SpSocketHandle *socket, const void *buf, size_t len, size_t *actual, void *context)

This callback is invoked by eSDK to write data on a TLS connection.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] const void * buf Pointer to buffer with data to be written.
[in] size_t len Number of bytes of data in buffer.
[out] size_t * actual Number of bytes actually written.
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSClose()

Return to Tls typedefs

typedef void(* SpCallbackTLSClose)(struct SpSocketHandle *socket, void *context)

This callback should clean up any resources allocated in the connect callback.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

SpCallbackTLSGetError()

Return to Tls typedefs

typedef int(* SpCallbackTLSGetError)(struct SpSocketHandle *socket, char *buf, size_t len, void *context)

Callback invoked to get an error message for the last error.

The implementation of this callback should put an error message in the form of a zero-terminated string in the buffer pointed to by buf. This error message should describe the latest error returned by any of the other callback functions.

Parameters

     
[in] struct SpSocketHandle * socket Pointer to eSDK socket already connected to the remote peer.
[in] char * buf Pointer to buffer that will receive the error message.
[in] size_t len Length of the buffer.
[in] void * context Context provided in callback register function.

Notes:

  • The application should not block or call other API functions in the callback.

Functions

SpRegisterTLSCallbacks()

Return to Tls functions

SpError SpRegisterTLSCallbacks(struct SpTLSCallbacks *callbacks, void *context)

Register TLS-related callbacks.

Parameters

     
[in] struct SpTLSCallbacks * callbacks Structure with pointers to individual callback functions. All pointers must be valid.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Notes:

SpTLSAddCARootCert()

Return to Tls functions

This function is deprecated and should not be used. See alternatives:
SpError SpTLSAddCARootCert(const uint8_t *certificate, size_t length, int *underlying_error)

Add root certificate to the eSDK TLS stack.

eSDK uses TLS secured HTTPS connections to download media files from CDN (Content Delivery Network) servers. All CDN servers are using certificates from common Certificate Authorities (CA). eSDK cannot read Certificate Authority (CA) root certificates from the operating system. The purpose of this function is to provide eSDK the CA root certificates which eSDK needs. As an example, integration can use the CA certificate bundle from Mozilla: https://curl.se/docs/caextract.html This API is cumulative and can be called several times until the integration has loaded all the certificates. This API allocates and owns the memory to store the certificates. The integration can reuse the memory used to pass the certificates (first parameter)

Parameters

     
[in] const uint8_t * certificate Either a binary DER certificate or a string with a PEM-format certificate.

Returns

Returns kSpErrorInvalidArgument if the certificate could not be parsed kSpErrorAlreadyInitialized if the function is called between SpInit() and SpFree(). If the return value is kSpErrorInvalidArgument and underlying_error is non-NULL, there will be an error code from the underlying TLS stack (currently MbedTLS) returned in *underlying_error.

Notes:

  • If the buffer is a PEM-format certificate, it must be NULL-terminated.
  • If the buffer is a PEM-format certificate, this length must include the NULL termination.
  • Calls to this function have to be performed before SpInit is called or after SpFree

SpTLSFreeCARootCerts()

Return to Tls functions

This function is deprecated and should not be used. See alternatives:
SpError SpTLSFreeCARootCerts(void)

Remove all certificates loaded on the TLS stack and free the memory used by them.

This API must be called before calling SpInit or after SpFree

Returns

kSpErrorUnavailable if the function is called between SpInit() and SpFree().

Token

#include "spotify_embedded_token.h"

Data Structures

Return to header index

Data Structure Description
SpTokenCallbacks Callbacks to be registered with SpRegisterTokenCallbacks

Typedefs

Return to header index

Typedef Description
SpCallbackConnectionReceiveAccessToken Callback to deliver the access token requested by SpConnectionRequestAccessToken
SpCallbackConnectionReceiveAuthCode Callback to deliver the access token requested by SpConnectionRequestAuthCode

Functions

Return to header index

Function Description
SpRegisterTokenCallbacks Register token callbacks.
SpConnectionRequestAccessToken Request an access token for the logged in user.
SpConnectionRequestAuthCode Request an authorization code for the logged in user.

Data Structures

SpTokenCallbacks

Return to Token data structures

Callbacks to be registered with SpRegisterTokenCallbacks

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

struct SpTokenCallbacks {
    SpCallbackConnectionReceiveAccessToken on_access_token;
    SpCallbackConnectionReceiveAuthCode on_auth_code;
};
SpCallbackConnectionReceiveAccessToken on_access_token

Access token event callbacks.

SpCallbackConnectionReceiveAuthCode on_auth_code

Authorization code event callbacks.

Typedefs

SpCallbackConnectionReceiveAccessToken()

Return to Token typedefs

typedef void(* SpCallbackConnectionReceiveAccessToken)(const char *token_json, int error, void *context)

Callback to deliver the access token requested by SpConnectionRequestAccessToken

Parameters

     
[in] const char * token_json A serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in] int error An internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in] void * context Context pointer that was passed then the callback was registered.

Notes:

  • The JSON object looks as following: {"accessToken":"tokendata", "expiresIn":expiryinseconds,//typically3600 "tokenType":"tokentype"}//typically"Bearer"

SpCallbackConnectionReceiveAuthCode()

Return to Token typedefs

typedef void(* SpCallbackConnectionReceiveAuthCode)(const char *token_json, int error, void *context)

Callback to deliver the access token requested by SpConnectionRequestAuthCode

Parameters

     
[in] const char * token_json A serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in] int error An internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in] void * context Context pointer that was passed then the callback was registered.

Notes:

  • The JSON object looks as following: {"code":"tokendata", "redirectUri":"someUri"

Functions

SpRegisterTokenCallbacks()

Return to Token functions

SpError SpRegisterTokenCallbacks(struct SpTokenCallbacks *cb, void *context)

Register token callbacks.

Parameters

     
[in] struct SpTokenCallbacks * cb Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in] void * context Application-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpConnectionRequestAccessToken()

Return to Token functions

SpError SpConnectionRequestAccessToken(const char *scope)

Request an access token for the logged in user.

scope A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/

Parameters

     
[in] const char * scope A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/

SpConnectionRequestAuthCode()

Return to Token functions

SpError SpConnectionRequestAuthCode(const char *scope)

Request an authorization code for the logged in user.

Parameters

     
[in] const char * scope A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/

Notes:

  • The string scope must not be longer than 425 characters.