-
Notifications
You must be signed in to change notification settings - Fork 12
API
- spotify.Session
- Properties
- spotify.AudioPlayer
- Methods
- Events
- spotify.Playlist
- Methods
- Properties
- spotify.Album
- Properties
- spotify.Artist
- Properties
- spotify.Track
- Properties
- Properties
Authenticate the user with the Spotify API
spotify.authenticate(clientId, tokenExchangeURL, [scopes], callback)the clientId supplied by Spotify.
The URL for your token exchange service. See setting up a token exchange service
Custom scopes to request from the Spotify authentication service
The callback gets two arguments error and session. session is a spotify.Session object.
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)The query to search for.
this can be one of three strings:
-
artistto perform an artist search. -
albumto perform an album search. -
trackto perform a track search.
The starting index of the search results. If omitted the search will start from the first entry.
The spotify.Session object to use for authentication.
The callback gets two arguments error and result. result is an array of partial items. Each item has the following properties:
-
name. The name of the item. -
uri. The URI of the item.
Use the uri with the correct spotify object to promote a partial item to a full item.
For example (Get the largest image for an artist from the search results):
var session = ...a valid spotify.Session object...
var item = ...a single artist search item.....
spotify.Artist(item.uri, session, function(error, artist) {
var image = artist.largestImage; //returns the largest spotify.Image object belonging to the artist.
console.log('Image URL: %s', image.imageURL);
console.log('Image aspect ratio: %f', image.aspect);
console.log('Image size: %s', image.aspect);
});Get an array of playlists for user with username.
spotify.getPlaylistsForUser(username, session, callback);The username of the user to request the playlists from.
The spotify.Session object to use for authentication.
The callback gets two arguments error and result. result is an array of partial items, see spotify.search for an explanation of partial items.
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 = spotify.Session({username: 'someUsername', credentials: 'AFD42....GD43'});The username of the user.
An access token to verify the session.
The constructor for a new spotify.AudioPlayer object.
spotify.AudioPlayer(companyName, appName, session, callback)Your company name
Your application name
The user's spotify.Session object.
The callback gets two arguments error and an spotify.AudioPlayer object, ready to start playing tracks.
These examples show how to construct a spotify.AudioPlayer and play a track.
spotify.AudioPlayer('Your-Company-Name', 'Your-App-Name', session, function(error, audioPlayer) {
audioPlayer.playURI('spotify:track:6JEK0CvvjDjjMUBFoXShNZ');
});Add an event listener to the audio player.
audioPlayer.addEventListener(event, listener)The event linked to the event listener.
When an event is dispatched, the listener gets called with zero or more arguments depending on the event.
Play the audio track belonging to the supplied Spotify track URI.
audioPlayer.playURI(uri, callback)The URI belonging to the track to play.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Skip the track to the specified offset.
audioPlayer.seekToOffset(offset, callback)The new playback position (offset) in seconds.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Request the current playback status.
audioPlayer.getIsPlaying(callback)The callback gets two arguments error and status. The status value will be true if playing or false if paused / stopped.
Set the current playback status. This can be seen as a method for pausing / resuming playback.
audioPlayer.setIsPlaying(status, callback)The new playback status.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Request the playback volume.
audioPlayer.getVolume(callback)The callback gets two arguments error and volume. The volume value will be a numeric value between 0.0 and 1.0.
Set the playback volume.
audioPlayer.setVolume(volume, callback)The new playback volume between 0.0 and 1.0.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Request the current login status of the audio player.
audioPlayer.getLoggedIn(callback)The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Request information about the track that is currently playing.
audioPlayer.getCurrentTrack(callback)The callback gets two arguments error and track. The track value will be an object literal with the track's metadata.
Request the current playback position.
audioPlayer.getCurrentPlaybackPosition(callback)The callback gets two arguments error and offset. The offset value will be a numeric value in seconds between 0.0 and the duration of the track.
This event is dispatched when the player has logged in.
This event is dispatched when the player is logged out.
This event is dispatched when the playback permission is lost. This happens mostly when the user plays a track on another device.
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.
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.
This event is dispatched when the playback status has changed.
The listener method receives a single boolean argument status.
This event is dispatched if the playback offset has changed "unnaturally".
The listener method receives a single Number argument offset.
Change the playlist's name.
playlist.setName(name, session, callback)The name of the playlist
The user's spotify.Session object.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Change the playlist's description.
playlist.setDescription(description, session, callback)The playlist description
The user's spotify.Session object.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Change the collaborative flag.
playlist.setCollaborative(collaborative, session, callback)If the playlist should be collaborative.
The user's spotify.Session object.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Add tracks to the playlist.
playlist.addTracks(tracks, session, callback)An array of track Spotify URIs.
The user's spotify.Session object.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Permanently delete the playlist.
playlist.delete(session, callback)The user's spotify.Session object.
The callback gets one argument error. The error argument will be null if successful or an Error object if something went wrong.
Name of the playlist
A numeric value showing the version of the playlist. Higher value equals newer version.
The Playlist's Spotify URI.
Defines if the playlist is a collaborative playlist.
The username of the user that created the playlist.
An array of partial track objects holding the track's name and uri.
The date and time when the playlist was last modified.
The name of the album.
The Spotify URI belonging to the album.
The Spotify sharing URL (e.g., http://open.spotify.com/album/2bOPMrFFQ00pA4QzaBn16F)
External IDs belonging to the album, like the UPC code.
A list of ISO 3166 country codes.
A list of objects containing the name and Spotify uri of the artists belonging to the album.
A list of objects containing the name and Spotify uri of the tracks on the album.
Holds the properties year, month and day.
The type of album. Possible values:
albumsinglecompilationappearsOn
A list of genres belonging to the album.
A list of spotify.Image objects.
The largest cover image.
The smallest cover image.
A numeric value between 0.0 and 100.0, expressing the album's popularity.
The name of the artist.
The Spotify URI belonging to the artist.
The Spotify sharing URL (e.g., http://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt)
A list of genres belonging to the artist.
A list of spotify.Image objects.
The smallest artist image.
The largest artist image.
A numeric value between 0.0 and 100.0, expressing the artist's popularity.
The name of the track.
The Spotify URI belonging to the track.
The Spotify sharing URL (e.g., http://open.spotify.com/track/0bhCFkDynlihxlkI1nd4WZ)
The URL of the track's preview mp3.
The duration of the track in seconds.
A list of objects containing the name and Spotify uri of the artists belonging to the track.
A partial object with holding the name and Spotify uri of the album where the track belongs to.
The track's position on the disc.
The disc number of the track.
A numeric value between 0.0 and 100.0, expressing the track's popularity.
Value showing if the track has been flagged as explicit.
External IDs belonging to the album, like the UPC code.
A list of ISO 3166 country codes.
The URL of the image.
An object with the properties width and height.
A numeric value for the ratio between the width and height of the image.