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.
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
A few restrictions apply to the libspotify library. These may be changed (or fixed) in future versions of the library.
In this section, you will find the overall philosophy of the library with regard to memory management and error handling.
All functions that have some form of useful error state returns an sp_error. The actual result value is returned in an
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
Reference counting is used for all domain objects in libspotify. Functions including the string create will return an object with a pre-incremented reference count. Thus, each
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 library itself uses multiple threads internally. To allow for synchronization between these threads, you must implement the sp_session_callbacks::notify_main_thread callback. Whenever called (from some internal thread), the application must wake up the main loop so the sp_session_process_events() function can be run.
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.
All objects (tracks, albums, artists, etc) are loaded asynchronously. Therefore the API user must query the object via the _is_loaded() functions to check that the object data has been populated. There is currently no way of finding out when data has been updated for a specific object. Rather, the user need to iterate all objects of interest upon invokation of the metadata_updated() callback.
Also, objects are not populated when created as a result of a sp_link_as_...() method.
Currently the disk cache can only be opened by one process at a time. It is preferrable not to put the cache in a network file system. To avoid clashes, we recommend you to put set the cache location to
/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 on UNIX-like systems or
%appdata%\appname\libspotify\ on Windows.
Before running any application you will need an application key. An application key allows Spotify to identify your application and should be unique per application. You will find more information about the application keys on our developer website. We have choosen not to distribute the example programs with an application key, as that might cause the key to be misused. We encourage you to get a valid application key, and put it in a file called
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.
Images are identified with a
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.
It is also possible to get references to images as URIs (see the sp_link type). This might be favourable if you need to store a reference to an image for later use but want to release the originating object.
Images will always be given to the application compressed using a image compression format. Currently only JPEG encoded images are delivered. See sp_image_format(). The API user should use sp_image_data() to get the encoded data and the application need to do the decoding of the image by itself.
The audio is delivered through a push-callback called by libspotify when data is available. Your callback may eat all data, or just enough to fill some constant-sized buffer. The callback will be called from a libspotify internal thread, so if you share state between the audio callback and the main thread, be sure to add adequate thread synchronization.
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.
Included in the distribution are a couple of example files designed to get you started easily.