gondolav / spotify4s   0.1.1

MIT License Website GitHub

An intuitive and lightweight Scala library for the Spotify Web API

Scala versions: 2.13

spotify4s

Scala CI Join the chat at https://gitter.im/spotify4s/community

An intuitive and lightweight Scala library for the Spotify Web API.

Features

spotify4s supports all the features of the Spotify Web API, with the sole exception of the Player API (in beta).

The whole API is exposed through the Spotify class, modeling a Spotify API client. Every method returns an Either monad containing either the result or an error.

Installation

spotify4s requires Scala 2.13. Add the following dependency to your SBT project:

libraryDependencies += "com.github.gondolav" %% "spotify4s" % "0.1.1"

Documentation

The full API reference is available at spotify4s documentation.

Usage

To get started, install spotify4s and create an app on Spotify. Since all methods (and endpoints) require user authorization, you will need the app's credentials (client id and client secret), generated upon registration.

The library supports two authorization flows:

  • Client Credentials: this flow makes it possible to authenticate your requests to the Spotify Web API and to obtain a higher rate limit than you would get with the Authorization code flow. However, only endpoints that do not access user information can be accessed;
  • Authorization Code: this flow is suitable for long-running applications in which the user grants permission only once. It provides an access token that can be refreshed. It requires you to add a redirect URI to your app at the dashboard.

Without user authentication (Client Credentials flow)

import com.github.gondolav.spotify4s._

val sp = Spotify(clientID, clientSecret)

sp.getCurrentUserProfile match {
  case Left(error) => // handle error
  case Right(user) => println(user.displayName) // for example
}

With user authentication (Authorization Code flow)

import com.github.gondolav.spotify4s._

val sp = Spotify(clientID, clientSecret, redirectURI, scopes = List("user-read-email", "user-read-private"))

sp.getCurrentUserProfile match {
  case Left(error) => // handle error
  case Right(user) => println(user.displayName) // for example
}

Contributing

Contributions are very welcome! A good place to start is the Issues page.

Acknowledgements

spotify4s is partially inspired by spotipy.

License

This project is licensed under the MIT License - see the LICENSE file for details.