Documentation

The libspotify C API package allows third party developers to write
applications that utilize the Spotify music streaming service.

Spotify is a really nice music streaming service, and being able to interact
with it in an API is awesome. libspotify itself is however written in C, making
it unavailable or cumbersome to use for many developers.

This project aims to allow Ruby developers access to all of the libspotify C API,
without needing to reach down to C. However, to use this library to its full extent
you will need to learn how to use the Ruby FFI API.

The Spotify gem has:

100% API coverage, including callback support. You’ll be able to use any function from the libspotify library.

example-audio_stream.rb: plays songs from Spotify with the plaything gem, using OpenAL.

example-console.rb: logs in to Spotfify, and initiates a pry session to allow experimentation with the spotify gem API.

example-listing_playlists.rb: list all playlists available for a certain user.

example-loading_object.rb: loads a track using polling and the spotify gem API.

example-random_related_artists.rb: looks up an artist and its similar artists on spotify, then it picks a similar artist at random and does the same to that artist, over and over. I have used this example file to test prolonged usage of the API.

Creating a Session, the first thing you should do

Almost all functions require you to have created a session before calling them. Forgetting to do so won’t work at best, and will segfault at worst. You'll also want to log in before doing things as well, or objects will never load.

libspotify is an asynchronous library

When creating objects in libspotify they are not populated with data instantly, instead libspotify schedules them for download from the Spotify backend. For libspotify to do it's work with downloading content, you need to call Spotify::API#session_process_events regularly.

Facebook vs Spotify Classic

Users who signed up to Spotify with their Facebook account will have numeric IDs as usernames, so a link to their profile looks like spotify:user:11101648092. Spotify Classic users instead have their usernames as canonical name, so a link to their profile looks like spotify:user:burgestrand.

Callbacks can be dangerous

libspotify allows you to pass callbacks that will be invoked by libspotify when events of interest occur, such as being logged out, or receiving audio data when playing a track.

Callbacks can be very tricky. They must never be garbage collected while they are in use by libspotify, or you may get very weird bugs with your Ruby interpreter randomly crashing. Do use them, but be careful.

Opinions and the Spotify gem

The Spotify gem has very few opinions. It is build to closely resemble the libspotify C API, and has very little
to aid you in terms of how to structure your application. It aims to make calling the libspotify C API frictionless,
but not much more. It is up to you to decide your own path.

A note about gem versioning

Given a version X.Y.Z, each segment corresponds to:

X reflects supported libspotify version (12.1.45 => 12). There are no guarantees of backwards-compatibility!

Y is for backwards-incompatible changes.

Z is for backwards-compatible changes.

You should use the following version constraint: gem "spotify", "~> 12.5.3".

Manually installing libspotify

By default, Spotify uses the libspotify gem which means you do
not need to install libspotify yourself. However, if your platform is not supported by the libspotify
gem you will need to install libspotify yourself.

Please note, that if your platform is not supported by the libspotify gem I’d very much appreciate it
if you could create an issue on libspotify gem issue tracker
so I can fix the build for your platform.