Low-level Ruby bindings for libspotify, the official Spotify C API

Caution: libspotify in its current form has been deprecated: https://developer.spotify.com/news-stories/2015/05/26/last-month-news/

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.
• Automatic garbage collection. Piggybacking on Ruby’s GC to manage pointer lifecycle.
• Parallell function call protection. libspotify is not thread-safe, but Spotify protects you by making all API calls in a specific background thread.
• Type conversion and type safety. Special pointers for every Spotify type, protecting you from accidental mix-ups.
• Support for Ruby, JRuby and Rubinius. Thanks to FFI, the gem runs fine on the main three Ruby implementations!

Contact details

• Got questions? Ask on the mailing list: [email protected] (https://groups.google.com/d/forum/ruby-spotify)
• Found a bug? Report an issue: https://github.com/Burgestrand/spotify/issues/new
• Have feedback? I ❤ feedback! Please send it to the mailing list.

Questions, notes and answers

Links to keep close at hand when using libspotify

• spotify gem API reference — YARDoc reference for the spotify gem, maps to the libspotify function list.
• libspotify C API reference — the one true source of documentation.
• libspotify FAQ — you should read this at least once.
• spotify gem examples — located in the spotify gem repository.
• spotify gem FAQ — this README section.

How to run the examples

You’ll need:

1. Your Spotify premium account credentials. If you sign in with Facebook, you’ll need your Facebook account e-mail and password.
2. Your Spotify application key. Download the binary key, and put it in the examples/ directory.

Running the examples is as simple as:

ruby example-audio_stream.rb

Available examples are:

• 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.

See Spotify::API#session_create for how to create a session. See Spotify::API#session_login for logging in.

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.

This matters, for example, when you use the function Spotify::API#session_publishedcontainer_for_user_create.

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.

Instructions on installing libspotify manually are in the wiki: How to install libspotify