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

Contents

Introduction

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.

Install

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"
Bundler.require

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"

Configuration

You'll firstly need to register your client ID on developer.spotify.com. 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 = Spotify::Accounts.new
@accounts.client_id = ENV["SPOTIFY_CLIENT_ID"]
@accounts.client_secret = ENV["SPOTIFY_CLIENT_SECRET"]
@accounts.redirect_uri = ENV["SPOTIFY_REDIRECT_URI"]

Authorization

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 https://accounts.spotify.com. 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:

@accounts.authorize_url({
  scope: "user-read-private user-read-email user-top-read"
}) # => "https://accounts.spotify.com/oauth/authorize?..."

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

@accounts.authorize_url # => "https://accounts.spotify.com/oauth/authorize?..."

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?
  @session.refresh!
end

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 https://accounts.spotify.com/... 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.refresh!
@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")
@session.refresh!

@sdk = Spotify::SDK.new(@session)

Spotify Connect

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:...>, ...]

@sdk.connect.devices[0].active?
@sdk.connect.devices[0].private_session?
@sdk.connect.devices[0].volume
@sdk.connect.devices[0].restricted?

Read current playback*

@sdk.connect.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
@sdk.connect.playback.artist.name # => "Ed Sheeran"
@sdk.connect.playback.item.album.name # => "รท"

Control playback*

@sdk.connect.devices[0].play!({
  uri: "spotify:track:0tgVpDi06FyKpA1z0VMD4v"
})

@sdk.connect.devices[0].pause!
@sdk.connect.devices[0].resume!
@sdk.connect.devices[0].volume = 80
@sdk.connect.devices[0].previous!
@sdk.connect.devices[0].next!
@sdk.connect.devices[0].position_ms = 3_000
@sdk.connect.devices[0].shuffle = false
@sdk.connect.devices[0].repeat_mode = :context

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

Contributing

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

Community Guidelines

Bug reports and pull requests are welcome on GitHub at https://github.com/bih/spotify-ruby. 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://git@github.com/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 rubygems.org.

Changelog

[2018-07-21] (0.2.1) First major release.
- Support for Connect and User API endpoints.
- Transitioned to YARD for documentation.
- Website built using Jekyll with Contributing guide.
- Removed Coveralls in favour for CodeClimate

License

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