API Reference eSDK 3.201.430

Main

#include "spotify_embedded.h"

• Macros and Constants
• Data Structures
• Typedefs
• Enumerations
• Functions

Macros and Constants

Return to header index

Data Structures

Return to header index

Typedefs

Return to header index

Enumerations

Return to header index

• SpError
• SpAPIReturnCode
• SpPlaybackBitrate
• SpPlaybackNotification
• SpConnectionNotification
• SpDeviceType
• SpMetadataTrack
• SpConnectivity
• SpContent
• SpMediaType
• SpAudioQuality
• SpDrmFormat
• SpReDeliveryMode

Functions

Return to header index

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

• SpInit

SP_RECOMMENDED_MEMORY_BLOCK_SIZE

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

• SpConfig

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

• SpConfig

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

• SpConfig

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

• SpConfig

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

• SpConfig

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

• SpSetDisplayName
• SpConfig
• SpZeroConfVars

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

• SpConfig

SP_MAX_USERNAME_LENGTH

Return to Main macros

#define SP_MAX_USERNAME_LENGTH 64

Maximum length of usernames (not counting terminating NULL)

See also

• SpZeroConfVars
• SpConnectionLoginZeroConf

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

• SpConfig::device_aliases

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

• SpConfig::device_aliases

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

• SpGetMetadata
• SpMetadata

Notes:

• It is possible that metadata will be truncated to less than this length. Applications requiring full length metadata should request it from the Spotify web APIs https://developer.spotify.com/documentation/web-api/

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

• SpGetMetadata
• SpMetadata

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

• SpGetMetadata
• SpMetadata

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

• SpGetMetadataImageURL

SP_PLAYER_COOKIE_LENGTH

Return to Main macros

#define SP_PLAYER_COOKIE_LENGTH 32

Length of player cookie (not counting terminating NULL)

See also

• SpGetPlayerCookie

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

• SpGetMetadata
• SpMetadata

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpZeroConfVars

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

• SpConnectionLoginZeroConf

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

• SpConnectionLoginZeroConf

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

• SpConnectionLoginZeroConf

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

• SpConnectionLoginZeroConf

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

• SpInit

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

• SpInit

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

• SpInit

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

• SpInit

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:

• SpSetDeviceIsGroup also sets group status, but only for the currently selected alias.

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

• SpFormat
• SpConfig::supported_drm_media_formats

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;
};

SpMetadata

Return to Main data structures

Track metadata.

See also

• SpGetMetadata

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;
};

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
…
}

SpFormat

Return to Main data structures

Mapping of which media formats are supported in which DRM.

See also

• SpConfig::supported_drm_media_formats

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

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

• SpZeroConfGetVars

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

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

• SpZeroConfGetVars

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;
};

SpSampleFormat

Return to Main data structures

Sample format of the audio data.

struct SpSampleFormat {
    int channels;
    int sample_rate;
};

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;
};

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;
};

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;
};

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;
};

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

• SpInit

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;
};

conf.global_attributes= SP_GLOBAL_ATTRIBUTE_VOICE |SP_GLOBAL_ATTRIBUTE_SOME_OTHER;

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;
};

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

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

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

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

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

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

See also

• SpConnectionLoginBlob

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

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

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

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

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,
};

SpAPIReturnCode

Return to Main enumerations

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

SpPlaybackBitrate

Return to Main enumerations

enum SpPlaybackBitrate {
    kSpPlaybackBitrateDefault,
    kSpPlaybackBitrateLow,
    kSpPlaybackBitrateNormal,
};

SpPlaybackNotification

Return to Main enumerations

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

SpConnectionNotification

Return to Main enumerations

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

SpDeviceType

Return to Main enumerations

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

SpMetadataTrack

Return to Main enumerations

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

SpConnectivity

Return to Main enumerations

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

SpContent

Return to Main enumerations

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

SpMediaType

Return to Main enumerations

enum SpMediaType {
    kSpMediaTypeAudio,
    kSpMediaTypeVideo,
};

SpAudioQuality

Return to Main enumerations

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

SpDrmFormat

Return to Main enumerations

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

SpReDeliveryMode

Return to Main enumerations

enum SpReDeliveryMode {
    kSpRedeliveryModeActivated,
    kSpRedeliveryModeDeactivated,
};

Functions

SpInit()

Return to Main functions

SpError SpInit(struct SpConfig *conf)

Initialize the library.

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

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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

• SpConnectionIsLoggedIn

Notes:

• The logout is performed asynchronously. The logout is complete when the callback SpCallbackConnectionNotify is called with the event kSpConnectionNotifyLoggedOut

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

• kSpConnectionNotifyLoggedIn
• kSpConnectionNotifyLoggedOut
• SpConnectionLoginBlob
• SpConnectionLogout

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

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

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

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

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

Returns

Returns an error code

SpRegisterPlaybackCallbacks()

Return to Main functions

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

Register playback-related callbacks.

Parameters

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

Returns

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

Notes:

• This API can be invoked from a callback.
• Be aware that many APIs that change the currently playing context are asynchronous, and the changes will not be immediately reflected in the metadata returned by SpGetMetadata For example, when calling SpPlaybackSkipToNext SpPlaybackEnableShuffle etc., the metadata returned by SpGetMetadata might be unchanged while the command is being processed (which involves network communication). The notification kSpPlaybackNotifyMetadataChanged will be sent as soon as SpGetMetadata would return a different result for any relative_index defined in the enum SpMetadataTrack

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

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

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

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

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

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

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

• kSpPlaybackNotifyPlay
• kSpPlaybackNotifyPause
• SpPlaybackPlay
• SpPlaybackPause

Notes:

• This API can be invoked from a callback.
• The result of this API is analogous to the playback notifications kSpPlaybackNotifyPlay and kSpPlaybackNotifyPause

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

• kSpPlaybackNotifyTrackChanged

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

• kSpPlaybackNotifyShuffleOn
• kSpPlaybackNotifyShuffleOff
• SpPlaybackEnableShuffle

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

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

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

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

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

• kSpPlaybackNotifyBecameActive
• kSpPlaybackNotifyBecameInactive

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

Returns

Returns an error code

See also

• SpPlaybackIsShuffled

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

Returns

Returns an error code

See also

• SpPlaybackIsRepeated

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

Returns

Returns an error code

SpPlaybackSetAvailableToPlay()

Return to Main functions

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

See also

• SpPlaybackIsAvailableToPlay

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

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

• SpPlaybackSetAvailableToPlay

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

• SpPlaybackIsActiveDevice

Notes:

• The device gets active and starts playing when integration calls SpPlaybackPlay or SpPlayUri

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

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

Returns

Returns an error code

See also

• SpPlaybackIsDeviceControllable

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

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

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

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:

• This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit

SpZeroConfAnnounceResume()

Return to Main functions

SpError SpZeroConfAnnounceResume(void)

Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause

Returns

Returns an error code

Notes:

• This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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

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

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

• SpInit
• SpConfig::supported_drm_media_formats

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

• SpFormat

Content

#include "spotify_embedded_content.h"

• Data Structures
• Typedefs
• Enumerations
• Functions

Data Structures

Return to header index

Typedefs

Return to header index

Enumerations

Return to header index

• SpContentType

Functions

Return to header index

’

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;
};

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

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

See also

• SpContentType

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

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

SpCallbackOnAvailableContainer()

Return to Content typedefs

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

Callback for each available container.

Parameters

Notes:

• Experimental, subject of change

Enumerations

SpContentType

Return to Content enumerations

enum SpContentType {
    kSpContentTrack,
    kSpContentTrackMetadata,
};

Functions

SpRegisterContentCallbacks()

Return to Content functions

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

Parameters

Returns

Returns an error code

Hal

#include "spotify_embedded_hal.h"

• Data Structures
• Typedefs
• Enumerations
• Functions

Data Structures

Return to header index

Typedefs

Return to header index

Enumerations

Return to header index

• SpIPFamily
• SpSocketPool
• SpSocketType
• SpSocketOptions

Functions

Return to header index

’

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;
};

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;
};

SpSocketHandle

Return to Hal data structures

Socket handle type.

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

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;
};

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

See also

• SpAPIReturnCode

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

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

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

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

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

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

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

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

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)