REPOSITORY OVERVIEW

Live repository statistics

★ 216Stars

⑂ 25Forks

◯ 12Open issues

◉ 216Watchers

README preview

Kotlin Spotify Web API

A Kotlin implementation of the Spotify Web API, supporting Kotlin/JS, Kotlin/Android, Kotlin/JVM, and Kotlin/Native (macOS, Windows, Linux).

This library has first-class support for Java and is a viable alternative for Java development. Please see the Java section for more details.

Use this library in Kotlin, Java, JavaScript, Swift, or native code! Because this library targets both iOS and Android, it can also be used in KMM (Kotlin Multiplatform Mobile) applications as a shared source.

Oerview and how to install
- JVM, Android, JS, Native
- Android information
  - Android sample app
Documentation
Need help, have a question, or want to contribute?
Creating a new api instance
Platform-specific wrappers and information
Tips
- Building the API
Notes
- LinkedResults, PagingObjects, and Cursor-based Paging Objects

Overview and how to install

Current version:

JVM, Android, JS, Native, Apple

repositories {
    mavenCentral()
}

implementation("com.adamratzman:spotify-api-kotlin-core:VERSION")

JS

Please see the JS Spotify Web Playback SDK wrapper to learn how to use Spotify's web playback SDK in a browser application.

Android

Note: For information on how to integrate implicit/PKCE authentication, Spotify app remote, and Spotify broadcast notifications into your application, please see the Android README.

If you declare any release types not named debug or release, you may see "Could not resolve com.adamratzman:spotify-api-kotlin-android:VERSION". You need to do the following for each release type not named debug or release:

android {
    buildTypes {
        yourReleaseType1 {
            // ...
            matchingFallbacks = ['release', 'debug'] 
        }
        yourReleaseType2 {
            // ...
            matchingFallbacks = ['release', 'debug'] 
        }
	...
    }
}

To successfully build, you might need to exclude kotlin_module files from the packaging. To do this, inside the android/buildTypes/release closure, you would put:

packagingOptions {
	exclude 'META-INF/*.kotlin_module'
}

Android sample application

You can find a simple sample application demonstrating how to use spotify-web-api-kotlin in a modern Android app, as well as how to integrate with the Spotify app, here.

Documentation

The spotify-web-api-kotlin JavaDocs are hosted here.

Have a question?

If you have a question, you can:

Create an issue
Join our Discord server
Contact me using Adam#9261 on Discord

Unsupported features on each platform:

Feature	JVM	Android	JS	Native (Mac/Windows/Linux)
Edit client playlist	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	Unsupported
Remove playlist tracks	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	Unsupported

Please feel free to open an issue/discussion on GitHub or Discord if you need access to one of these features or have an interest in implementing one, as direction can be provided.

Creating a new api instance

To decide which api you need (SpotifyAppApi, SpotifyClientApi, SpotifyImplicitGrantApi), you can refer to the sections below or the Spotify authorization guide. In general:

If you don't need client resources, use SpotifyAppApi
If you're using the api in a backend application, use SpotifyClientApi (with or without PKCE)
If you're using the api in Kotlin/JS browser, use SpotifyImplicitGrantApi
If you need access to client resources in an Android or other application, use SpotifyClientApi with PKCE

Note: You can use the online Spotify OAuth Token Generator tool to generate a client token for local testing.

SpotifyAppApi

This provides access only to public Spotify endpoints. Use this when you have a server-side application. Note that implicit grant authorization provides a higher api ratelimit, so consider using implicit grant if your application has significant usage.

By default, the SpotifyApi Token automatically regenerates when needed. This can be changed by overriding the automaticRefresh builder setting.

There are four exposed builders, depending on the level of control you need over api creation. Please see the spotifyAppApi builder docs for a full list of available builders.

You will need:

Spotify application client id
Spotify application client secret

Example creation (default settings)

val api = spotifyAppApi("clientId", "clientSecret").build() // create and build api
println(api.browse.getNewReleases()) // use it

Example creation, using an existing Token and setting automatic token refresh to false

val token = spotifyAppApi(spotifyClientId, spotifyClientSecret).build().token
val api = spotifyAppApi(
  "clientId",
  "clientSecret",
  token
) { 
  automaticRefresh = false 
}.build()

println(api.browse.getNewReleases()) // use it

SpotifyClientApi

The SpotifyClientApi is a superset of SpotifyApi; thus, nothing changes if you want to access public data. This library does not provide a method to retrieve the code from your callback url; instead, you must implement that with a web server. Automatic Token refresh is available only when building with an authorization code or a Token object. Otherwise, it will expire Token.expiresIn seconds after creation.

Make sure your application has requested the proper Scopes in order to ensure proper function of this library. The api option requiredScopes allows you to verify that a client has actually authorized with the scopes you are expecting.

You will need:

Spotify application client id
Spotify application client secret (if not using PKCE)
Spotify application redirect uri
To choose which client authorization method (PKCE or non-PKCE) to use

PKCE

Use the PKCE builders and helper methods if you are using the Spotify client authorization PKCE flow. Building via PKCE returns a SpotifyClientApi which has modified refresh logic.

Use cases:

You are using this library in an application (likely Android), or do not want to expose the client secret.

To learn more about the PKCE flow, please read the Spotify authorization guide. Some highlights about the flow are:

It is refreshable, but each refresh token can only be used once. This library handles token refresh automatically by default
It does not require a client secret; instead, a set redirect uri and a random code verifier are used to verify the authenticity of the authorization.
A code verifier is required. The code verifier is "a cryptographically random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes."
A code challenge is required. "In order to generate the code challenge, your app should hash the code verifier using the SHA256 algorithm. Then, base64url encode the hash that you generated."
When creating a pkce api instance, the code verifier is passed in by you and compared to the code challenge used to authorize the user.

This library contains helpful methods that can be used to simplify the PKCE authorization process. This includes getSpotifyPkceCodeChallenge, which SHA256 hashes and base64url encodes the code challenge, and getSpotifyPkceAuthorizationUrl, which allows you to generate an easy authorization url for PKCE flow.

Please see the spotifyClientPkceApi builder docs for a full list of available builders.

Takeaway: Use PKCE authorization flow in applications where you cannot secure the client secret.

To get a PKCE authorization url, to which you can redirect a user, you can use the getSpotifyPkceAuthorizationUrl top-level method. An example is shown below, requesting 4 different scopes.

val codeVerifier = "thisisaveryrandomalphanumericcodeverifierandisgreaterthan43characters"
val codeChallenge = getSpotifyPkceCodeChallenge(codeVerifier) // helper method
val url: String = getSpotifyPkceAuthorizationUrl(
    SpotifyScope.PLAYLIST_READ_PRIVATE,
    SpotifyScope.PLAYLIST_MODIFY_PRIVATE,
    SpotifyScope.USER_FOLLOW_READ,
    SpotifyScope.USER_LIBRARY_MODIFY,
    clientId = "clientId",
    redirectUri = "your-redirect-uri",
    codeChallenge = codeChallenge
)

There is also an optional parameter state, which helps you verify the authorization.

Note: If you want automatic token refresh, you need to pass in your application client id and redirect uri when using the spotifyClientPkceApi.

Example: A user has authorized your application. You now have the authorization code obtained after the user was redirected back to your application. You want to create a new `SpotifyClientApi`.

val codeVerifier = "thisisaveryrandomalphanumericcodeverifierandisgreaterthan43characters"
val code: String = ...
val api = spotifyClientPkceApi(
    "clientId", // optional. include for token refresh
    "your-redirect-uri", // optional. include fo

ALGORITHMICALLY RELATED

Similar Open-Source Projects

Selected from shared topics, language and repository description—not editorial ratings.

nubasu /