Getting Started
This section shows you how to use the Spotify eSDK to write a simple Spotify Connect-enabled music player application.
The Spotify eSDK is a lightweight library with a C API that allows you to integrate Spotify into your devices and applications. It has been written from the ground up with the needs of device manufacturers in mind. The SDK provides an API that facilitates the integration and ensures high performance and low memory footprint on a wide range of hardware architectures.
Set up the environment
The first steps is to download an eSDK build from Certomato. Please refer to the Onboarding section if you don't have access to Certomato access yet.
Once you have the eSDK bundle locally stored, unzip it. A new folder will be created with the following contents:
docsfolder which contains the API Reference in HTML format.exampleswith file samples using the eSDK in different contexts.includewith headers file for compiling.libswhich contains a static and dynamic version of the eSDK library ready to be linked with.
The next step is to generate a valid client_id. Please follow the app guide to do so.
Let's create our workspace that will store our project. Create a new folder
called esdk-hello-world and add a file called Makefile.
A Makefile is a file which defines a set of rules (compile, link, clean, etc.)
to be executed by the make tool. There are other tools you could use to build
your sofrware software, such as cmake or
scons, but we will use make for the sake of
simplicity.
_14CC = gcc_14_14ESDK_HOME=path/to/your/esdk/folder_14_14CFLAGS = -g -Wall -I$(ESDK_HOME)/include_14LDFLAGS = -lm $(ESDK_HOME)/lib/libspotify_embedded_static.a_14_14all: main_14_14main: main.o_14main.o: main.c_14_14clean:_14 rm -rvf main.o main
Don't forget to replace the ESDK_HOME variable with the location of the unzipped eSDK folder.
Initializing the library
Create a new file called main.c with the following content, which contains a
simplified example of using the
SpInit()
function:
_50#include <stdio.h>_50#include <unistd.h>_50#include <sys/time.h>_50#include <stdlib.h>_50#include <string.h>_50#include <ctype.h>_50#include <signal.h>_50#include "latest"_50#include "spotify_embedded_log.h"_50_50static void CallbackError(SpError error, void *context) {_50 printf("Error: %d\n", error);_50}_50 _50int main(int argc, char *argv[]) {_50 SpError err;_50 struct SpConfig conf;_50 int buffer_size = SP_RECOMMENDED_MEMORY_BLOCK_SIZE;_50 enum SpDeviceType device_type = kSpDeviceTypeSpeaker;_50 const char *client_id = "my-client-id";_50 _50 memset(&conf, 0, sizeof(conf));_50 _50 conf.api_version = SP_API_VERSION;_50 conf.memory_block = malloc(buffer_size);_50 conf.memory_block_size = buffer_size;_50 conf.error_callback = CallbackError;_50 conf.error_callback_context = NULL;_50 conf.display_name = "Example";_50 conf.unique_id = "my-sample-unique-id";_50 conf.brand_name = "Example_Brand";_50 conf.model_name = "example_embedded";_50 conf.brand_display_name = "Example Brand";_50 conf.model_display_name = "example_embedded \u266C";_50 conf.device_type = device_type;_50 conf.zeroconf_serve = 1;_50 conf.zeroconf_port = 0;_50 conf.host_name = conf.unique_id;_50 conf.client_id = client_id;_50 conf.scope = SP_SCOPE_STREAMING;_50 _50 if (kSpErrorOk != (err = SpInit(&conf))) {_50 printf("Error %d\n", err);_50 return 0;_50 }_50 _50 SpFree();_50_50 return 0;_50}
The example calls the function SpInit() to perform the eSDK initialization. The function takes a struct of type SpConfig as a parameter.
Finally, compile and generate the binary with the following command:
_10make all
Adding a main event loop
In order to implement the main event loop, the function SpPumpEvents() must be called periodically. To show how this works, let's force a login error by calling the function SpConnectionLoginPassword() with an invalid username and password. After calling SpPumpEvents() a couple of times, the error callback will be invoked and the application quits.
Here is the new code that checks for login errors:
_58SpError error_occurred = kSpErrorOk;_58_58static void CallbackError(SpError error, void *context) {_58 printf("Error: %d\n", error);_58 error_occurred = error;_58}_58 _58int main(int argc, char *argv[]) {_58 SpError err;_58 struct SpConfig conf;_58 int buffer_size = SP_RECOMMENDED_MEMORY_BLOCK_SIZE;_58 enum SpDeviceType device_type = kSpDeviceTypeSpeaker;_58 const char *client_id = "my-client-id";_58 _58 memset(&conf, 0, sizeof(conf));_58 _58 conf.api_version = SP_API_VERSION;_58 conf.memory_block = malloc(buffer_size);_58 conf.memory_block_size = buffer_size;_58 conf.error_callback = CallbackError;_58 conf.error_callback_context = NULL;_58 conf.display_name = "Example";_58 conf.unique_id = "my-sample-unique-id";_58 conf.brand_name = "Example_Brand";_58 conf.model_name = "example_embedded";_58 conf.brand_display_name = "Example Brand";_58 conf.model_display_name = "example_embedded \u266C";_58 conf.device_type = device_type;_58 conf.zeroconf_serve = 1;_58 conf.zeroconf_port = 0;_58 conf.host_name = conf.unique_id;_58 conf.client_id = client_id;_58 conf.scope = SP_SCOPE_STREAMING;_58_58_58 if (kSpErrorOk != (err = SpInit(&conf))) {_58 printf("Error %d\n", err);_58 goto end;_58 }_58_58 err = SpConnectionLoginPassword("fake user", "fake password");_58 if (err != kSpErrorOk) {_58 printf("Error %d\n", err);_58 goto end;_58 }_58 _58 while (1) {_58 err = SpPumpEvents();_58 if (kSpErrorOk != err || error_occurred) {_58 goto end;_58 }_58 }_58_58end:_58 SpFree();_58_58 return 0;_58}
What's next?
You can follow the eSDK Developer Guides to read further about how to integrate the eSDK.