Build Status Maintainability Test Coverage Gem Version Code Triagers Badge

The developer-friendly, opinionated Ruby SDK for Spotify. Works on Ruby 2.4+

๐ŸŽจ Website | ๐Ÿ’– Contributing | ๐Ÿ“– SDK Reference | ๐Ÿ”’ Code of Conduct



Hey! I'm a Developer Advocate at Spotify, and I wrote this Ruby SDK to explore how to build a SDK that is TADA:

  1. ๐Ÿง’ Thoughtfully inclusive for beginners. Everything we do should think about beginners from the start. From having an enforced Code of Conduct policy to building great documentation, tooling, and an empathetic feedback process. Designing for beginners is designing for longevity.

  2. โ˜๏ธ Agnostic to minor changes. APIs change all the time. We should be opinionated enough that our software should break with major changes, but flexible enough to work perfectly fine with minor changes. Our code should only depend on critical data, such as IDs.

  3. ๐ŸŒˆ Delightful for developers. Writing the SDK and using the SDK should be equally delightful. Granted, this is a challenging goal; but with solid information architecture, well-crafted opinions, clear and helpful error messages, and software that doesn't get in your way - we will create quite lovely software.

  4. โœจ A maintained production-level. It doesn't take experts to write production-level code; all it takes is considerate guidance from the community. We should write software that we and others trust to do what it is intended to do. We care about Semantic Versioning for clear version changes.

Disclaimer: This SDK is NOT owned or supported by Spotify. It remains a personal project of mine. If you are a commercial partner of Spotify and wish to use this SDK, be aware you are using it at your own risk.


With Bundler

Add this line to your application's Gemfile:

gem "spotify-ruby"

And then execute in your Terminal:

$ bundle install

Finally you can include the SDK via Bundler.require:

require "bundler"

Manual Install

Or, you can install manually by executing this in your Terminal:

$ gem install spotify-ruby

Then you can include the SDK in your Ruby project:

require "spotify-ruby"


You'll firstly need to register your client ID on You should receive a Client ID and Client Secret which we'll need to continue.

Your App Credentials

As mentioned above, you'll need to register your client ID. We recommend you that you use a different set of client IDs for development and production. We'll need to use those credentials in order to use any of Spotify's APIs.

To define your app credentials, you'll need to create an instance of Spotify::Accounts:

@accounts =
@accounts.client_id = "spotify client ID"
@accounts.client_secret = "spotify client secret"
@accounts.redirect_uri = "redirect URI"

Alternatively, these credentials can be supplied as environment variables when running your application:

@accounts = # fetches configuration from ENV

The respective environment variables you'll need to set are:

Environment Variable Description Required?
SPOTIFY_CLIENT_ID Your Spotify Client ID Yes
SPOTIFY_CLIENT_SECRET Your Spotify Client Secret Yes
SPOTIFY_REDIRECT_URI Your Spotify Redirect URI (must be exact) Yes


In order to use Spotify's APIs on a user's behalf, you'll need to use the Spotify Accounts API to redirect them to They will then need to explicitly approve your application and what data you're asking for (technically referred to as authorization scopes).

Recommended for production: To request specific data, read our Authorization Scopes reference, and then execute:

  scope: "user-read-private user-read-email user-top-read"
}) # => ""

Recommended for exploration / local development: Or, to request all data, you can execute:

@accounts.authorize_url # => ""

Creating a Session

Each session lasts 60 minutes. New sessions can be generated when you have a valid refresh_token (they become invalid if a user revokes your application).

After a user has authorized your application, they'll be sent to your redirect_uri defined in Your App Credentials with a code parameter. We can use this to create a Spotify::Session:

@session = @accounts.exchange_for_session(params[:code])

We can check when the session expires, and when we should refresh:

@session.expires_at # => 2018-07-08 22:40:15 +0200

if @session.expired?

You'll then be able to use @session in the Spotify::SDK object. See the Using the SDK section below.

Recreating a Session

We don't want to send the user to every time they want to use your application. For this case, we'll need to export the refresh_token and persist it somewhere:

@session.refresh_token # => "BQASNDMelPsTdJMNMZfWdbxsuuM1FiBxvVzasqWkwYtgpjXJO60Gm51R0LO_-3Q5MfzCU0xIrbIFs7ZlMQrVJeRwN1_Ffa3sIJn_KW6LO8vA44fYc85oz48TuBuZsT2gzr4L"

Then you can repeatedly create a session with just a refresh token and running refresh!:

@session = Spotify::Session.from_refresh_token(@accounts, "refresh_token here")
@session.expired? # => true
@session.expired? # => false

Using the SDK

To create an instance of the Spotify SDK, you'll need the @session from above and pass it to Spotify::SDK as follows:

@session = Spotify::Session.from_refresh_token(@accounts, "refresh_token here")

@sdk =

Spotify Connect API

With Spotify Connect, you can take your music experience anywhere on over 300 devices. And you can read and control most devices programmatically through the SDK:

Read your devices*

@sdk.connect.devices # => [#<Spotify::SDK::Connect::Device:...>, ...]


Read current playback*

@sdk.connect.playback.playing? # => true
@sdk.connect.playback.device.private_session? # => false
@sdk.connect.playback.shuffling? # => false
@sdk.connect.playback.repeat_mode # => :context
@sdk.connect.playback.position_percentage # => 4.53 # => "Ed Sheeran" # => "รท"

Control playback*

  uri: "spotify:track:0tgVpDi06FyKpA1z0VMD4v",
  position_ms: 0

@sdk.connect.devices[0].volume = 80
@sdk.connect.devices[0].position_ms = 3_000
@sdk.connect.devices[0].shuffle = false
@sdk.connect.devices[0].repeat_mode = :context

Transfer playback*

This will transfer state, and start playback.


Transfer state*

This will transfer state, and pause playback.



This allows you to perform specific actions on behalf of a user.

My information* # => false # => true # => 1980-01-01 # => true # => "ABC Smith"[0].url # => "" # => 4913313 # => "spotify:user:abcsmith" # => ""

Listening History API

My recently played tracks (up to last 50)* # => [#<Spotify::SDK::Item...>, ...] # => 10 # => [#<Spotify::SDK::Item...>, ...] # => 50

Following API

Follow an artist*


Unfollow an artist*


Check if following Spotify artists?* 6LuN9FCkKOj5PcnpouEgny 69GGBxA162lTqCwzJG5jLp))
# => {
#   "3TVXtAsR1Inumwj472S9r4" => false,
#   "6LuN9FCkKOj5PcnpouEgny" => true,
#   "69GGBxA162lTqCwzJG5jLp" => false
# }

Check if following Spotify users?* 6LuN9FCkKOj5PcnpouEgny 69GGBxA162lTqCwzJG5jLp))
# => {
#   "3TVXtAsR1Inumwj472S9r4" => false,
#   "6LuN9FCkKOj5PcnpouEgny" => true,
#   "69GGBxA162lTqCwzJG5jLp" => false
# }

See all followed artists* # => [#<Spotify::SDK::Artist...>, ...] # => 5 # => [#<Spotify::SDK::Artist...>, ...] # => 50

* Requires specific user permissions/scopes. See Authorization Scopes for more information.


On the website, we have a full guide on contributing for beginners.

Community Guidelines

Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Code of Conduct

Everyone interacting with this project's codebases, issue trackers, discussions, chat rooms, and mailing lists is required to follow the Code of Conduct.

Whilst we try to always assume good intentions, any clear violations or bad actors will be warned and subsequently banned from this project indefinitely.

Getting Started

Firstly, you'll need Git and Ruby installed. You can then install the dependencies as following:

$ git clone ssh://[email protected]/bih/spotify-ruby.git
$ bin/setup

You can run rake ci to validate your Ruby syntax, our RSpec tests, and code coverage.

For local development, you can run bin/console for an interactive prompt for experimentation.

Releasing a Change

  • To install this gem onto your local machine, run bundle exec rake install.
  • Ensure versions are in line with the Semantic Versioning convention.
  • To release a new version:
    • Update the version number in lib/spotify/version.rb
    • Run bundle exec rake release (which will create a git tag for the version)
    • Push git commits and tags
    • Push the .gem file to


The gem is available as open source under the terms of the MIT License.