• Stars
    star
    609
  • Rank 70,477 (Top 2 %)
  • Language
    Objective-C
  • Created about 6 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Spotify SDK for iOS

Spotify iOS SDK

Overview

The Spotify iOS framework allows your application to interact with the Spotify app running in the background on a user's device. Capabilities include authorizing, getting metadata for the currently playing track and context, as well as issuing playback commands.

Please Note: By using Spotify developer tools you accept our Developer Terms of Use.

The Spotify iOS SDK is a set of lightweight objects that connect with the Spotify app and let you control it while all the heavy lifting of playback is offloaded to the Spotify app itself. The Spotify app takes care of playback, networking, offline caching and OS music integration, leaving you to focus on your user experience. Moving from your app to the Spotify app and vice versa is a streamlined experience where playback and metadata always stay in sync.

Key Features

Filing Bugs

Components

How Do App Remote Calls Work?

Terms of Use

Tutorial

Frequently Asked Questions

Key Features

  • Playback is always in sync with Spotify app
  • Playback, networking, and caching is all accounted for by the Spotify app
  • Works offline and online and does not require Web API calls to get metadata for player state
  • Allows authentication through the Spotify app so users don't have to type in their credentials

Filing Bugs

We love feedback from the developer community, so please feel free to file missing features or bugs over at our issue tracker. Make sure you search existing issues before creating new ones.

Open bug tickets | Open feature requests

Requirements

The Spotify iOS framework requires a deployment target of iOS 9 or higher. The following architectures are supported: armv7, armv7s and arm64 for devices, i386 and x86_64 for the iOS Simulator. Bitcode is also supported.

Components

Models

  • SPTAppRemoteAlbum
  • SPTAppRemoteArtist
  • SPTAppRemoteLibraryState
  • SPTAppRemotePlaybackRestrictions
  • SPTAppRemotePlaybackOptions
  • SPTAppRemotePlayerState
  • SPTAppRemoteTrack
  • SPTAppRemoteContentItem
  • SPTAppRemoteUserCapabilities
  • SPTAppRemoteImageRepresentable
  • SPTConfiguration

SPTAppRemote

The main entry point to connect to the Spotify app and retrieve API components. Use this to establish, monitor, and terminate the connection.

SPTAppRemotePlayerAPI

Send playback related commands such as:

  • Play track by URI
  • Resume/pause playback
  • Skip forwards and backwards
  • Seek to position
  • Set shuffle on/off
  • Request player state
  • Request player context
  • Subscribe to player state

SPTAppRemoteImagesAPI

Fetch an image for a SPTAppRemoteImageRepresentable

SPTAppRemoteUserAPI

Fetch/subscribe/set user-related data such as:

  • Fetch and/or subscribe to SPTAppRemoteUserCapabilities
  • Determine if a user can play songs on demand (Premium vs Free)
  • Add/remove/check if a song is in a user's library

SPTAppRemoteContentAPI

Fetch recommended content for the user.

How App Remote calls work

When you interact with any of the App Remote APIs you pass in a SPTAppRemoteCallback block that gets invoked with either the expected result item or an NSError if the operation failed. The block is triggered after the command was received by the Spotify app (or if the connection could not be made).

Here is an example using the SPTRemotePlayerAPI to skip a song:

[appRemote.playerAPI skipToNext:^(id  _Nullable result, NSError * _Nullable error) {
    if (error) {
        // Operation failed
    } else {
        // Operation succeeded
    }
}];

Tutorial and Examples

We provide a few sample projects to help you get started with the iOS Framework in the DemoProjects folder. See the Readme in the DemoProjects folder for more information on what each sample does.

Authentication and Authorization

To communicate with the Spotify app your application will need to get a user's permission to control playback first by using built-in authorization for App Remote. To do that you will need to request authorization view when connecting to Spotify. The framework will automatically request the app-remote-control scope and show the auth view if user hasn't agreed to it yet.

Terms of Use

Note that by using Spotify developer tools, you accept our Developer Terms of Use.

Included Open Source Libraries

Tutorial

This tutorial leads you step-by-step through the creation of a simple app that uses the Spotify iOS SDK to play an audio track and subscribe to player state. It will walk through the authorization flow.

Prepare Your Environment

Follow these steps to make sure you are prepared to start coding.

  • Download the Spotify iOS framework from the "Clone or download" button at the top of this page, and unzip it.
  • Install the latest version of Spotify from the App Store onto the device you will be using for development. Run the Spotify app and login or sign up. Note: A Spotify Premium account will be required to play a track on-demand for a uri.
  • Register Your Application. You will need to register your application at My Applications and obtain a client ID. When you register your app you will also need to whitelist a redirect URI that the Spotify app will use to callback to your app after authorization.

Add Dependencies

  1. Add the SpotifyiOS package to your project. You can either do this through Swift Package Manager (SPM), or by adding SpotifyiOS.framework or SpotifyiOS.xcframework to your Xcode project directly.

    Import SpotifyiOS.framework

  2. In your info.plist add your redirect URI you registered at My Applications. You will need to add your redirect URI under "URL types" and "URL Schemes". Be sure to set a unique "URL identifier" as well. More info on URL Schemes

    Info.plist

  3. Add #import <SpotifyiOS/SpotifyiOS.h> to your source files to import necessary headers.

Check if Spotify is Active

If a user is already using Spotify, but has not authorized your application, you can use the following check to prompt them to start the authorization process.

[SPTAppRemote checkIfSpotifyAppIsActive:^(BOOL active) {
    if (active) {
        // Prompt the user to connect Spotify here
    }
}];

Authorize Your Application

To be able to use the playback control part of the SDK the user needs to authorize your application. If they haven't, the connection will fail with a No token provided error. To allow the user to authorize your app, you can use the built-in authorization flow.

  1. Initialize SPTConfiguration with your client ID and redirect URI.

    SPTConfiguration *configuration =
        [[SPTConfiguration alloc] initWithClientID:@"your_client_id" redirectURL:[NSURL urlWithString:@"your_redirect_uri"]];
  2. Initialize SPTAppRemote with your SPTConfiguration

    self.appRemote = [[SPTAppRemote alloc] initWithConfiguration:configuration logLevel:SPTAppRemoteLogLevelDebug];
  3. Initiate the authentication flow (for other ways to detect if Spotify is installed, as well as attributing installs, please see our Content Linking Guide).

    // Note: A blank string will play the user's last song or pick a random one.
    BOOL spotifyInstalled = [self.appRemote authorizeAndPlayURI:@"spotify:track:69bp2EbF7Q2rqc5N3ylezZ"];
    if (!spotifyInstalled) {
        /*
        * The Spotify app is not installed.
        * Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier] to present the user
        * with a way to install the Spotify app.
        */
    }
  4. Configure your AppDelegate to parse out the accessToken in application:openURL:options: and set it on the SPTAppRemote connectionParameters.

    - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
    {
        NSDictionary *params = [self.appRemote authorizationParametersFromURL:url];
        NSString *token = params[SPTAppRemoteAccessTokenKey];
        if (token) {
            self.appRemote.connectionParameters.accessToken = token;
        } else if (params[SPTAppRemoteErrorDescriptionKey]) {
            NSLog(@"%@", params[SPTAppRemoteErrorDescriptionKey]);
        }
        return YES;
    }

    If you are using UIScene then you need to use appropriate method in your scene delegate.

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else {
            return
        }
    
        let parameters = appRemote.authorizationParameters(from: url);
    
        if let access_token = parameters?[SPTAppRemoteAccessTokenKey] {
            appRemote.connectionParameters.accessToken = access_token
            self.accessToken = access_token
        } else if let error_description = parameters?[SPTAppRemoteErrorDescriptionKey] {
            // Show the error
        }
    }

Connect and Subscribe to Player State

  1. Set your connection delegate and attempt to connect.

    self.appRemote.delegate = self;
    [self.appRemote connect];
    - (void)appRemoteDidEstablishConnection:(SPTAppRemote *)appRemote
    {
        // Connection was successful, you can begin issuing commands
    }
    
    - (void)appRemote:(SPTAppRemote *)appRemote didFailConnectionAttemptWithError:(NSError *)error
    {
        // Connection failed
    }
    
    - (void)appRemote:(SPTAppRemote *)appRemote didDisconnectWithError:(nullable NSError *)error
    {
        // Connection disconnected
    }
  2. Set a delegate and subscribe to player state:

    appRemote.playerAPI.delegate = self;
    
    [appRemote.playerAPI subscribeToPlayerState:^(id  _Nullable result, NSError * _Nullable error) {
        // Handle Errors
    }];
    - (void)playerStateDidChange:(id<SPTAppRemotePlayerState>)playerState
    {
        NSLog(@"Track name: %@", playerState.track.name);
    }

Connection handling

As a courtesy you should always disconnect App Remote when your app enters a background state. This tells Spotify that it's safe to disable the active stream. If your app does not properly call disconnect Spotify has no way of knowing that it should not maintain the connection, and this may result in future connection issues.

If you want your app to automatically reconnect after disruption events like incoming calls or Siri interactions you may use the willResignActive and didBecomeActive callbacks to safely disconnect and reconnect. If you don't wish to reconnect directly, it's typically enough to close the connection in didEnterBackground callbacks.

- (void)applicationWillResignActive:(UIApplication *)application
{
    [self.appRemote disconnect];
}
- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [self.appRemote connect];
}
// If you're using UIWindowSceneDelegate
- (void)sceneDidBecomeActive:(UIScene *)scene
{
    [self.appRemote connect];
}
- (void)sceneWillResignActive:(UIScene *)scene
{
    [self.appRemote disconnect];
}

Frequently Asked Questions

Why does music need to be playing to connect with SPTAppRemote?

Music must be playing when you connect with SPTAppRemote to ensure the Spotify app is not suspended in the background. iOS applications can only stay active in the background for a few seconds unless they are actively doing something like navigation or playing music.

Is SpotifyiOS.framework thread safe?

No, the framework currently expects to be called from the main thread. It will offload most of its work to a background thread internally but callbacks to your code will also occur on the main thread.

What if I need to authorize without starting playback?

There is an alternative authorization method. You can find more information about that here.

More Repositories

1

luigi

Luigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.
Python
17,089
star
2

annoy

Approximate Nearest Neighbors in C++/Python optimized for memory usage and loading/saving to disk
C++
12,458
star
3

docker-gc

INACTIVE: Docker garbage collection of containers and images
Shell
5,068
star
4

pedalboard

๐ŸŽ› ๐Ÿ”Š A Python library for audio.
C++
4,811
star
5

chartify

Python library that makes it easy for data scientists to create charts.
Python
3,447
star
6

basic-pitch

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection
Python
2,818
star
7

dockerfile-maven

MATURE: A set of Maven tools for dealing with Dockerfiles
Java
2,730
star
8

docker-maven-plugin

INACTIVE: A maven plugin for Docker
Java
2,652
star
9

scio

A Scala API for Apache Beam and Google Cloud Dataflow.
Scala
2,485
star
10

helios

Docker container orchestration platform
Java
2,097
star
11

web-api-examples

Basic examples to authenticate and fetch data using the Spotify Web API
HTML
1,889
star
12

HubFramework

DEPRECATED โ€“ Spotifyโ€™s component-driven UI framework for iOS
Objective-C
1,864
star
13

apollo

Java libraries for writing composable microservices
Java
1,648
star
14

dh-virtualenv

Python virtualenvs in Debian packages
Python
1,590
star
15

docker-client

INACTIVE: A simple docker client for the JVM
Java
1,425
star
16

docker-kafka

Kafka (and Zookeeper) in Docker
Shell
1,400
star
17

SPTPersistentCache

Everyone tries to implement a cache at some point in their iOS appโ€™s lifecycle, and this is ours.
Objective-C
1,244
star
18

mobius

A functional reactive framework for managing state evolution and side-effects.
Java
1,205
star
19

sparkey

Simple constant key/value storage library, for read-heavy systems with infrequent large bulk inserts.
C
1,143
star
20

ruler

Gradle plugin which helps you analyze the size of your Android apps.
Kotlin
1,100
star
21

voyager

๐Ÿ›ฐ๏ธ Voyager is an approximate nearest-neighbor search library for Python and Java with a focus on ease of use, simplicity, and deployability.
C++
1,090
star
22

XCMetrics

XCMetrics is the easiest way to collect Xcode build metrics and improve developer productivity.
Swift
1,074
star
23

web-api

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web API โžก๏ธ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
RAML
981
star
24

echoprint-codegen

Codegen for Echoprint
C++
948
star
25

snakebite

A pure python HDFS client
Python
859
star
26

heroic

The Heroic Time Series Database
Java
843
star
27

klio

Smarter data pipelines for audio.
Python
827
star
28

XCRemoteCache

Swift
815
star
29

apps-tutorial

A Spotify App that contains working examples of the use of Spotify Apps API
627
star
30

SPTDataLoader

The HTTP library used by the Spotify iOS client
Objective-C
624
star
31

postgresql-metrics

Tool that extracts and provides metrics on your PostgreSQL database
Python
584
star
32

JniHelpers

Tools for writing great JNI code
C++
584
star
33

reactochart

๐Ÿ“ˆ React chart component library ๐Ÿ“‰
JavaScript
548
star
34

Mobius.swift

A functional reactive framework for managing state evolution and side-effects [Swift implementation]
Swift
540
star
35

dockerfile-mode

An emacs mode for handling Dockerfiles
Emacs Lisp
520
star
36

threaddump-analyzer

A JVM threaddump analyzer
JavaScript
482
star
37

featran

A Scala feature transformation library for data science and machine learning
Scala
467
star
38

android-sdk

Spotify SDK for Android
HTML
440
star
39

echoprint-server

Server for the Echoprint audio fingerprint system
Java
398
star
40

web-scripts

DEPRECATED: A collection of base configs and CLI wrappers used to speed up development @ Spotify.
TypeScript
382
star
41

completable-futures

Utilities for working with futures in Java 8
Java
378
star
42

SpotifyLogin

Swift framework for authenticating with the Spotify API
Swift
344
star
43

ratatool

A tool for data sampling, data generation, and data diffing
Scala
334
star
44

fmt-maven-plugin

Opinionated Maven Plugin that formats your Java code.
Java
299
star
45

big-data-rosetta-code

Code snippets for solving common big data problems in various platforms. Inspired by Rosetta Code
Scala
286
star
46

trickle

A small library for composing asynchronous code
Java
284
star
47

coordinator

A visual interface for turning an SVG into XY coรถrdinates.
HTML
282
star
48

pythonflow

๐Ÿ Dataflow programming for python.
Python
279
star
49

styx

"The path to execution", Styx is a service that schedules batch data processing jobs in Docker containers on Kubernetes.
Java
267
star
50

cstar

Apache Cassandra cluster orchestration tool for the command line
Python
254
star
51

netty-zmtp

A Netty implementation of ZMTP, the ZeroMQ Message Transport Protocol.
Java
242
star
52

ios-style

Guidelines for iOS development in use at Spotify
240
star
53

cassandra-reaper

Software to run automated repairs of cassandra
235
star
54

confidence

Python
232
star
55

spotify-web-api-ts-sdk

A Typescript SDK for the Spotify Web API with types for returned data.
TypeScript
231
star
56

docker-cassandra

Cassandra in Docker with fast startup
Shell
219
star
57

terraform-gke-kubeflow-cluster

Terraform module for creating GKE clusters to run Kubeflow
HCL
209
star
58

dns-java

DNS wrapper library that provides SRV lookup functionality
Java
203
star
59

linux

Spotify's Linux kernel for Debian-based systems
C
203
star
60

git-test

test your commits
Shell
202
star
61

SPStackedNav

[DEPRECATED] Navigation controller which represents its content in stacks of panes, rather than one at a time
Objective-C
195
star
62

basic-pitch-ts

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection.
TypeScript
194
star
63

quickstart

A CommonJS module resolver, loader and compiler for node.js and browsers.
JavaScript
193
star
64

spotify-json

Fast and nice to use C++ JSON library.
C++
190
star
65

dbeam

DBeam exports SQL tables into Avro files using JDBC and Apache Beam
Java
181
star
66

flink-on-k8s-operator

Kubernetes operator for managing the lifecycle of Apache Flink and Beam applications.
Go
178
star
67

bazel-tools

Tools for dealing with very large Bazel-managed repositories
Java
165
star
68

lingon

A user friendly tool for building single-page JavaScript applications
JavaScript
162
star
69

dataenum

Algebraic data types in Java.
Java
159
star
70

magnolify

A collection of Magnolia add-on modules
Scala
157
star
71

async-google-pubsub-client

[SUNSET] Async Google Pubsub Client
Java
156
star
72

gcp-audit

A tool for auditing security properties of GCP projects.
Python
156
star
73

spark-bigquery

Google BigQuery support for Spark, SQL, and DataFrames
Scala
154
star
74

flo

A lightweight workflow definition library
Java
146
star
75

folsom

An asynchronous memcache client for Java
Java
143
star
76

should-up

Remove most of the "should" noise from your tests
JavaScript
143
star
77

missinglink

Build time tool for detecting link problems in java projects
Java
142
star
78

zoltar

Common library for serving TensorFlow, XGBoost and scikit-learn models in production.
Java
141
star
79

android-auth

Spotify authentication and authorization for Android. Part of the Spotify Android SDK.
HTML
139
star
80

proto-registry

An implementation of the Protobuf Registry API
TypeScript
139
star
81

futures-extra

Java library for working with Guava futures
Java
136
star
82

annoy-java

Approximate nearest neighbors in Java
Java
134
star
83

spydra

Ephemeral Hadoop clusters using Google Compute Platform
Java
132
star
84

spotify-tensorflow

Provides Spotify-specific TensorFlow helpers
Python
124
star
85

docker-stress

Simple docker stress test and monitoring tools
Python
124
star
86

spotify-web-playback-sdk-example

React based example app that creates a new player in Spotify Connect to play music from in the browse using Spotify Web Playback SDK.
JavaScript
120
star
87

crtauth

a public key backed client/server authentication system
Python
118
star
88

redux-location-state

Utilities for reading & writing Redux store state to & from the URL
JavaScript
118
star
89

sparkey-java

Java implementation of the Sparkey key value store
Java
117
star
90

rspec-dns

Easily test your DNS with RSpec
Ruby
108
star
91

web-playback-sdk

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web Playback SDK โžก๏ธ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
108
star
92

ffwd-ruby

An event and metrics fast-forwarding agent.
Ruby
106
star
93

realbook

Easier audio-based machine learning with TensorFlow.
Python
106
star
94

github-java-client

A Java client to Github API
Java
105
star
95

gimme

Creating time bound IAM Conditions with ease and flair
Python
103
star
96

super-smash-brogp

Sends and withdraws BGP prefixes for fun.
Python
98
star
97

lighthouse-audit-service

TypeScript
93
star
98

noether

Scala Aggregators used for ML Model metrics monitoring
Scala
91
star
99

python-graphwalker

Python re-implementation of the graphwalker testing tool
Python
90
star
100

spotify-js-challenge

JavaScript
87
star