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:
docs
folder which contains the API Reference in HTML format.examples
with file samples using the eSDK in different contexts.include
with headers file for compiling.libs
which 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 settings 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.
CC = gcc
ESDK_HOME=path/to/your/esdk/folder
CFLAGS = -g -Wall -I$(ESDK_HOME)/include
LDFLAGS = -lm $(ESDK_HOME)/lib/libspotify_embedded_static.a
all: main
main: main.o
main.o: main.c
clean:
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:
#include <stdio.h>
#include <unistd.h>
#include <sys/time.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <signal.h>
#include "latest"
#include "spotify_embedded_log.h"
static void CallbackError(SpError error, void *context) {
printf("Error: %d\n", error);
}
int main(int argc, char *argv[]) {
SpError err;
struct SpConfig conf;
int buffer_size = SP_RECOMMENDED_MEMORY_BLOCK_SIZE;
enum SpDeviceType device_type = kSpDeviceTypeSpeaker;
const char *client_id = "my-client-id";
memset(&conf, 0, sizeof(conf));
conf.api_version = SP_API_VERSION;
conf.memory_block = malloc(buffer_size);
conf.memory_block_size = buffer_size;
conf.error_callback = CallbackError;
conf.error_callback_context = NULL;
conf.display_name = "Example";
conf.unique_id = "my-sample-unique-id";
conf.brand_name = "Example_Brand";
conf.model_name = "example_embedded";
conf.brand_display_name = "Example Brand";
conf.model_display_name = "example_embedded \u266C";
conf.device_type = device_type;
conf.zeroconf_serve = 1;
conf.zeroconf_port = 0;
conf.host_name = conf.unique_id;
conf.client_id = client_id;
conf.scope = SP_SCOPE_STREAMING;
if (kSpErrorOk != (err = SpInit(&conf))) {
printf("Error %d\n", err);
return 0;
}
SpFree();
return 0;
}
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:
make 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:
SpError error_occurred = kSpErrorOk;
static void CallbackError(SpError error, void *context) {
printf("Error: %d\n", error);
error_occurred = error;
}
int main(int argc, char *argv[]) {
SpError err;
struct SpConfig conf;
int buffer_size = SP_RECOMMENDED_MEMORY_BLOCK_SIZE;
enum SpDeviceType device_type = kSpDeviceTypeSpeaker;
const char *client_id = "my-client-id";
memset(&conf, 0, sizeof(conf));
conf.api_version = SP_API_VERSION;
conf.memory_block = malloc(buffer_size);
conf.memory_block_size = buffer_size;
conf.error_callback = CallbackError;
conf.error_callback_context = NULL;
conf.display_name = "Example";
conf.unique_id = "my-sample-unique-id";
conf.brand_name = "Example_Brand";
conf.model_name = "example_embedded";
conf.brand_display_name = "Example Brand";
conf.model_display_name = "example_embedded \u266C";
conf.device_type = device_type;
conf.zeroconf_serve = 1;
conf.zeroconf_port = 0;
conf.host_name = conf.unique_id;
conf.client_id = client_id;
conf.scope = SP_SCOPE_STREAMING;
if (kSpErrorOk != (err = SpInit(&conf))) {
printf("Error %d\n", err);
goto end;
}
err = SpConnectionLoginPassword("fake user", "fake password");
if (err != kSpErrorOk) {
printf("Error %d\n", err);
goto end;
}
while (1) {
err = SpPumpEvents();
if (kSpErrorOk != err || error_occurred) {
goto end;
}
}
end:
SpFree();
return 0;
}
What’s next?
You can follow the eSDK Developer Guides to read further about how to integrate the eSDK.