Skip to content

API

Jump to bottom
Tim Flapper edited this page May 16, 2014 · 33 revisions

Cordova Spotify Plugin API

Table of Contents

spotify

Session

AudioPlayer

Playlist

Album

Artist

Track

Image

spotify

Methods

spotify.authenticate

Authenticate the user with the Spotify API

spotify.authenticate(clientId, tokenExchangeURL, [scopes], callback)

clientId string

the clientId supplied by Spotify.

tokenExchangeURL string

The URL for your token exchange service. See setting up a token exchange service

scopes [optional] Array

Custom scopes to request from the Spotify authentication service

callback function

The callback gets two arguments error and session. session is a spotify.Session object.

spotify.search

Search albums, artists or tracks. Return a maximum of 20 items. Use multiple requests with offset to receive more results.

spotify.search(query, searchType, [offset], session, callback)

query string

The query to search for.

searchType string

this can be one of three strings:

  • artists to perform an artist search.
  • albums to perform an album search.
  • tracks to perform a track search.

offset [optional] integer

The starting index of the search results. If omitted the search will start from the first entry.

session [optional] object

The spotify.Session object belong to the user.

callback function

The callback gets two arguments error and result. The result object can have any of the following properties: artists, albums or tracks. These properties hold an array of objects with partial information compared to the 'full' Spotify objects spotify.Artist, spotify.Album and spotify.Track.

spotify.requestItemAtURI

Request a Spotify object by their Spotify URI.

spotify.requestItemAtURI(uri, session, callback)

uri string

The Spotify URI of the object that is being requested.

session [optional] object

The spotify.Session object belong to the user. Only required for playlist URIs.

callback function

The callback gets two arguments error and object. object is the resulting data object belonging to the Spotify URI. See the description about Album, Artist, Track and Playlist for more information.

spotify.getPlaylistsForUser

Get an array of playlists for user with username.

spotify.getPlaylistsForUser(username, session, callback);

username string

The username of the user to request the playlists from.

session object

The spotify.Session object belong to the user.

callback function

The callback gets two arguments error and result. result is an array of partial items, see spotify.search for an explanation of partial items.

spotify.createPlaylist

Create a new playlist on the user's account.

spotify.createPlaylist(name, session, callback);

name string

The name of the new playlist

session object

The spotify.Session object belong to the user.

callback function

The callback gets two arguments error and playlist. playlist is a spotify.Playlist object that can be used for further modification of the playlist.

spotify.Session

Normally a spotify.Session object is returned from spotify.authenticate() but you can use the spotify.Session object to store the session for later use. A session is valid for 24 hours after which the user will need to login again.

var session = new spotify.Session({username: 'someUsername', credential: 'AFD42....GD43'});

Properties

session.username

type string

The username of the user.

session.credential

type string

An access token to verify the session.

spotify.AudioPlayer

Create a new spotify.AudioPlayer object.

new spotify.AudioPlayer(companyName, appName)

companyName string

Your company name

appName string

Your application name

Methods

audioPlayer.login

Registers the audio player with the Spotify service to allow playing tracks.

audioPlayer.login(session, [callback])

session object

The spotify.Session object belong to the user.

callback [optional] function

The callback gets a single argument error if an error occurred while logging in.

Example

This example shows how to construct a spotify.AudioPlayer, login and play a track using the callback method.

var audioPlayer = new spotify.AudioPlayer('Your-Company-Name', 'Your-App-Name');

audioPlayer.login(session, function(error) {
	audioPlayer.playURI('spotify:track:6JEK0CvvjDjjMUBFoXShNZ');
});

Alternatively, you can also listen for the login event to start playback.

var audioPlayer = new spotify.AudioPlayer('Your-Company-Name', 'Your-App-Name');

var loginListener = function() {
	audioPlayer.removeEventListener('login', loginListener);
	audioplayer.playURI('spotify:track:6JEK0CvvjDjjMUBFoXShNZ');
}

audioPlayer.addEventListener('login', loginListener);

audioPlayer.login(session);

audioPlayer.addEventListener

audioPlayer.on

Add an event listener to the audio player.

audioPlayer.addEventListener(event, listener)
audioPlayer.on(event, listener)

event string

The event linked to the event listener.

listener function

When an event is dispatched, the listener gets called with a zero or more arguments. See events for more information.

audioPlayer.removeEventListener

Remove an event listener to the audio player.

audioPlayer.removeEventListener(event, listener)

event string

The event linked to the event listener.

listener function

The listener that will be removed from the listener stack.

Example

Add an event and remove it.

var logoutListener = function() {
	console.log('AudioPlayer has logged out');
}

audioPlayer.on('logout', logoutListener);

// ....

audioPlayer.removeEventListener('logout', logoutListener);

audioPlayer.playURI

Play the audio track belonging to the supplied Spotify URI.

audioPlayer.playURI(uri, callback)

uri string

The URI belonging to the track to play.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

audioPlayer.seekToOffset

Skip the track to the specified offset.

audioPlayer.seekToOffset(offset, callback)

offset integer

The new playback position (offset) in milliseconds.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

audioPlayer.getIsPlaying

Request the current playback status.

audioPlayer.getIsPlaying(callback)

callback function

The callback gets two arguments error and playing. The playing value will be a boolean.

audioPlayer.setIsPlaying

Set the current playback status. This can be seen as a method for pausing / resuming playback.

audioPlayer.setIsPlaying(status, callback)

status boolean

The new playback status.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

audioPlayer.getVolume

Request the playback volume.

audioPlayer.getVolume(callback)

callback function

The callback gets two arguments error and volume. The volume value will be a numeric value between 0.0 and 1.0.

audioPlayer.setVolume

Set the playback volume.

audioPlayer.setVolume(volume, callback)

volume Number

The new playback volume between 0.0 and 1.0.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

audioPlayer.getLoggedIn

Request the current login status of the audio player.

audioPlayer.getLoggedIn(callback)

callback function

The callback gets one argument result. The result argument will be a boolean.

audioPlayer.getCurrentTrack

Request information about the track that is currently playing.

audioPlayer.getCurrentTrack(callback)

callback function

The callback gets two arguments error and track. The track value will be an object literal with the track's metadata.

audioPlayer.getCurrentPlaybackPosition

Request the current playback position.

audioPlayer.getCurrentPlaybackPosition(callback)

callback function

The callback gets two arguments error and offset. The offset value will be a numeric value in milliseconds between 0 and the duration of the track.

Events

login

This event is dispatched when the player has logged in.

logout

This event is dispatched when the player is logged out.

permissionLost

This event is dispatched when the playback permission is lost. This happens mostly when the user plays a track on another device.

error

This event is dispatched whenever an error occurs in the audio player.

The listener method receives a single string argument error.

If no error event listener is found, the AudioPlayer will throw a JavaScript Error.

message

This event is dispatched when a message is sent by Spotify to the user. This message has to be shown to the user see the iOS SDK reference.

The listener method receives a single string argument message.

If no message event listener is found, the AudioPlayer will fire a standard JavaScript alert.

playbackStatus

This event is dispatched when the playback status has changed.

The listener method receives a single boolean argument status.

seekToOffset

This event is dispatched if the playback offset has changed "unnaturally".

The listener method receives a single integer argument offset in milliseconds.

spotify.Playlist

A playlist on the spotify service.

Methods

playlist.setName

Change the playlist's name.

playlist.setName(name, session, callback)

name string

The name of the playlist

session object

The user's spotify.Session object.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

playlist.setDescription

Change the playlist's description.

playlist.setDescription(description, session, callback)

description string

The playlist description

session object

The user's spotify.Session object.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

playlist.setCollaborative

Change the collaborative flag.

playlist.setCollaborative(collaborative, session, callback)

collaborative boolean

If the playlist should be collaborative.

session object

The user's spotify.Session object.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

playlist.addTracks

Add tracks to the playlist.

playlist.addTracks(tracks, session, callback)

tracks Array

An array of track Spotify URIs.

session object

The user's spotify.Session object.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

playlist.delete

Permanently delete the playlist.

playlist.delete(session, callback)

session object

The spotify.Session object belong to the user.

callback function

The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.

Properties

playlist.name

Type string

Name of the playlist

playlist.version

Type integer

A numeric value showing the version of the playlist. Higher value equals newer version.

playlist.uri

Type string

The Playlist's Spotify URI.

playlist.collaborative

Type boolean

Defines if the playlist is a collaborative playlist.

playlist.creator

Type string

The username of the user that created the playlist.

playlist.tracks

Type Array

An array of partial track objects holding the track's name and uri.

playlist.dateModified

Type Date

The date and time when the playlist was last modified.

spotify.Album

An album on the Spotify service.

Properties

album.name

Type string

The name of the album.

album.uri

Type string

The Spotify URI belonging to the album.

album.sharingURL

Type string

The Spotify sharing URL (e.g., http://open.spotify.com/album/2bOPMrFFQ00pA4QzaBn16F)

album.externalIds

Type Array

External IDs belonging to the album, like the UPC code.

album.availableTerritories

Type Array

A list of ISO 3166 country codes.

album.artists

Type Array

A list of objects containing the name and uri (Spotify URI) of the artists belonging to the album.

album.tracks

Type Array

A list of objects containing the name and uri (Spotify URI) of the tracks on the album.

album.releaseDate

Type object

Holds the properties year, month and day.

album.albumType

Type string

The type of album. Possible values:

  • album
  • single
  • compilation
  • appearsOn

album.genres

Type Array

A list of genres belonging to the album.

album.images

Type Array

A list of spotify.Image objects.

album.largestImage

Type spotify.Image

The largest cover image.

album.smallestImage

Type spotify.Image

The smallest cover image.

album.popularity

Type Number

A numeric value between 0.0 and 100.0, expressing the album's popularity.

spotify.Artist

An artist on the Spotify service.

Properties

artist.name

Type string

The name of the artist.

artist.uri

Type string

The Spotify URI belonging to the artist.

artist.sharingURL

Type string

The Spotify sharing URL (e.g., http://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt)

artist.genres

Type Array

A list of genres belonging to the artist.

artist.images

A list of spotify.Image objects.

Type Array

artist.smallestImage

Type spotify.Image

The smallest artist image.

artist.largestImage

Type spotify.Image

The largest artist image.

artist.popularity

Type Number

A numeric value between 0.0 and 100.0, expressing the artist's popularity.

spotify.Track

A Spotify audio track.

Properties

track.name

Type string

The name of the track.

track.uri

Type string

The Spotify URI belonging to the track.

track.sharingURL

Type string

The Spotify sharing URL (e.g., http://open.spotify.com/track/0bhCFkDynlihxlkI1nd4WZ)

track.previewURL

Type string

The URL of the track's preview mp3.

track.duration

Type Number

The duration of the track in seconds.

track.artists

Type Array

A list of objects containing the name and uri (Spotify URI) of the artists belonging to the track.

track.album

Type object

A partial object with holding the name and uri (Spotify URI) of the album where the track belongs to.

track.trackNumber

Type integer

The track's position on the disc.

track.discNumber

Type integer

The disc number of the track.

track.popularity

Type Number

A numeric value between 0.0 and 100.0, expressing the track's popularity.

track.flaggedExplicit

Type boolean

Value showing if the track has been flagged as explicit.

track.externalIds

Type Array

External IDs belonging to the album, like the UPC code.

track.availableTerritories

Type Array

A list of ISO 3166 country codes.

spotify.Image

An image belonging to an artist or album.

Properties

image.url

Type string

The URL of the image.

image.width

Type integer

The image width (pixels)

image.height

Type integer

The image height (pixels)

Clone this wiki locally