This documentation explains how you can make use of the libspotify C API within an application of your own.
The documentation was generated with Doxygen. You will find a list of submodules in the Modules section. The list of modules are ordered in a reasonable reading order. It begins with some simple types used throughout the rest of the modules, continues with basic error handling and the functions required to manage sessions.
The rest of the modules are specfic parts of libspotify for accessing information about artists, albums, tracks, and playlists. Separate modules are available to handle searches and images.
This initial chapter of libspotify will focus on the general design of the library, and things to take into consideration once you start working with it.
For most of the functionality, there are examples available in share/libspotify/examples/
.
Currently, the library will only work with 32-bit x86 code.
out
pointer in these cases. Some functions return pointers where you must check for NULL
before using the returned value. Those places should be documented next to each function.In addition to functions returning an sp_error, some request objects (browse and search objects) have an error accessor. When the object has been loaded, the error code will be set to reflect the success or failure of the request.
A trivial error code to string mapper function exists that works just like strerror(3)
.
create
must have a corresponding release
when the value is no longer needed.Other accessor functions (including sp_link_as_artist et al.), on the other hand, returns a reference borrowed from the object it was retrieved from. Retrieving an sp_album from an sp_link would make the album object survive until the link object is freed, unless its reference count is explicitly incremented.
The API itself is not thread-safe. Thus, you must take care not to call the API functions from more than one of your own threads.
/var/tmp/username/appname/
and to add some kind of lock. The appname would be a mangled user-agent string.While you could simply remove the cache when the application exits to avoid the locking issue, your application will be slower as music, playlists and other metadata will have to be loaded from the server on each login. You are strongly encouraged to use a persistent cache.
Settings should be stored in the users home directory, but they should also be kept separate per application. We would recommend ~/.config/appname/libspotify/
for these files.
appkey.c
and compile the examples using the included makefile.In order to ensure all data is correctly synced to disk, we encourage you to actually use sp_session_logout() before terminating your application. Efter logout, you will receive a callback call in which you could display a login box, or terminate.
const byte*
value, returned by various functions in the API (such as sp_album_cover()). The pointers are valid until the object is freed, thus you should keep a reference to the objects until you are no longer using the image ID.Images will always be given to the application as pixel buffers. The format, however, can vary depending on the platform and how libspotify handles the images internally.
The sp_imageformat type and sp_image_format() function should be used to at least assert the image format returned is what was expected. The geometry of images is available once the image has been loaded, and to get the pixel buffers, you call sp_image_lock_pixels() with a configurable pitch/stride. Remember to always unlock the pixel buffers once you are done.
Samples are delivered as integers, see sp_audioformat. One frame consists of the same number of samples as there are channels. I.e. interleaving is on the sample level.
session
directory. This example simply logs in to Spotify and then logs out again. Before running any examples, you will need to acquire an application key for your project, and put it in a file called appkey.c
in the example directories.