SPTPlaylistSnapshot Class Reference
Inherits from | SPTPartialPlaylist : SPTJSONObjectBase : NSObject |
Conforms to | SPTJSONObject |
Declared in | SPTPlaylistSnapshot.h |
Overview
Represents a user’s playlist on the Spotify service.
API Docs: https://developer.spotify.com/web-api/playlist-endpoints/
API Console: https://developer.spotify.com/web-api/console/playlists/
API Model: https://developer.spotify.com/web-api/object-model/#playlist-object-full
Playlist Guide: https://developer.spotify.com/web-api/working-with-playlists/
Example:
[SPTPlaylistSnapshot playlistWithURI:[NSURL URLWithString:@"spotify:user:spotify:playlist:2ujjMpFriZ2nayLmrD1Jgl"]
accessToken:accessToken
callback:^(NSError *error, SPTPlaylistSnapshot *object) {
NSLog(@"tracks on page 1 = %@", [object.firstTrackPage tracksForPlayback]);
[object.firstTrackPage requestNextPageWithAccessToken:accessToken
callback:^(NSError *error, id object) {
NSLog(@"tracks on page 2 = %@", [object tracksForPlayback]);
}];
}];
Tasks
Properties
-
firstTrackPage
property -
snapshotId
property -
followerCount
property -
descriptionText
property
Requesting Playlists
-
+ playlistWithURI:accessToken:callback:
-
+ playlistsWithURIs:accessToken:callback:
-
+ isPlaylistURI:
-
+ isStarredURI:
-
+ requestStarredListForUser:withAccessToken:callback:
Helper methods for playlist manipulation
-
– addTracksToPlaylist:withAccessToken:callback:
-
– addTracksWithPositionToPlaylist:withPosition:accessToken:callback:
-
– replaceTracksInPlaylist:withAccessToken:callback:
-
– changePlaylistDetails:withAccessToken:callback:
-
– removeTracksFromPlaylist:withAccessToken:callback:
-
– removeTracksWithPositionsFromPlaylist:withAccessToken:callback:
Playlist manipulation request creation methods
-
+ createRequestForAddingTracks:toPlaylist:withAccessToken:error:
-
+ createRequestForAddingTracks:atPosition:toPlaylist:withAccessToken:error:
-
+ createRequestForSettingTracks:inPlaylist:withAccessToken:error:
-
+ createRequestForChangingDetails:inPlaylist:withAccessToken:error:
-
+ createRequestForRemovingTracksWithPositions:fromPlaylist:withAccessToken:snapshot:error:
-
+ createRequestForRemovingTracks:fromPlaylist:withAccessToken:snapshot:error:
-
+ createRequestForPlaylistWithURI:accessToken:error:
Response parser methods
Properties
descriptionText
The description of the playlist
@property (nonatomic, readonly, copy) NSString *descriptionText
Declared In
SPTPlaylistSnapshot.h
firstTrackPage
The tracks of the playlist, as a page of SPTPartialTrack
objects.
@property (nonatomic, readonly) SPTListPage *firstTrackPage
Declared In
SPTPlaylistSnapshot.h
Class Methods
createRequestForAddingTracks:atPosition:toPlaylist:withAccessToken:error:
Create a request for adding tracks to the playlist at a certain position.
+ (NSURLRequest *)createRequestForAddingTracks:(NSArray *)tracks atPosition:(int)position toPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)error
Parameters
- tracks
The tracks to add, as
SPTTrack
,SPTPartialTrack
orNSURL
objects.
- position
The position in which the tracks will be added, being 0 the top position.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
createRequestForAddingTracks:toPlaylist:withAccessToken:error:
Create a request for appending tracks to a playlist.
+ (NSURLRequest *)createRequestForAddingTracks:(NSArray *)tracks toPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)error
Parameters
- tracks
The tracks to add, as
SPTTrack
,SPTPartialTrack
orNSURL
objects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
createRequestForChangingDetails:inPlaylist:withAccessToken:error:
Change playlist details
+ (NSURLRequest *)createRequestForChangingDetails:(NSDictionary *)data inPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)error
Parameters
- data
The data to be changed. Use the key constants to refer to the field to change (e.g.
SPTPlaylistSnapshotNameKey
,SPTPlaylistSnapshotPublicKey
). When passing boolean values, use @YES or @NO.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Example: NSURLRequest *req = [SPTPlaylistSnapshot createRequestForChangingDetails:@{ @“name”: @“New name!”, @“public”: @(false) } inPlaylist:[NSURL URLWithString:@“spotify:user:username234:playlist:playlistid123”] withAccessToken:@“xyz123” error:&err];
Declared In
SPTPlaylistSnapshot.h
createRequestForPlaylistWithURI:accessToken:error:
Create a request to fetch a single playlist
+ (NSURLRequest *)createRequestForPlaylistWithURI:(NSURL *)uri accessToken:(NSString *)accessToken error:(NSError **)error
Parameters
- uri
The playlist to get.
- accessToken
An authenticated access token. Must be valid and authorized with the appropriate scope as necessary.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
createRequestForRemovingTracks:fromPlaylist:withAccessToken:snapshot:error:
Remove tracks from playlist.
+ (NSURLRequest *)createRequestForRemovingTracks:(NSArray *)tracks fromPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken snapshot:(NSString *)snapshotId error:(NSError **)error
Parameters
- tracks
An array of
SPTTrack
,SPTPartialTrack
orNSURL
objects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- snapshotId
The playlist snapshotId to manipulate.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
createRequestForRemovingTracksWithPositions:fromPlaylist:withAccessToken:snapshot:error:
Remove tracks that are in specific positions from playlist.
+ (NSURLRequest *)createRequestForRemovingTracksWithPositions:(NSArray *)tracks fromPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken snapshot:(NSString *)snapshotId error:(NSError **)error
Parameters
- tracks
An array of dictionaries with 2 keys:
track
with the track to remove, asSPTTrack
,SPTPartialTrack
orNSURL
objects, andpositions
that is an array of integers with the positions the track will be removed from.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- snapshotId
The playlist snapshotId to manipulate.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Example: NSURLRequest *req = [SPTPlaylistSnapshot createRequestForRemovingTracksWithPositions:@[ @{ @“track”: [NSURL URLWithString:@“spotify:track:a”], @“positions”: @[ @(3) ] }, @{ @“track”: [NSURL URLWithString:@“spotify:track:b”], @“positions”: @[ @(5), @(6) ] } ] fromPlaylist:[NSURL URLWithString:@“spotify:user:username:playlist:playlistid”] withAccessToken:@“xyz123” snapshot:@“snapshot!” error:&err];
Declared In
SPTPlaylistSnapshot.h
createRequestForSettingTracks:inPlaylist:withAccessToken:error:
Replace all the tracks in a playlist, overwriting any tracks already in it
+ (NSURLRequest *)createRequestForSettingTracks:(NSArray *)tracks inPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)error
Parameters
- tracks
The new tracks, as
SPTTrack
,SPTPartialTrack
orNSURL
objects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- error
An optional pointer to a
NSError
object that will be set if an error occured.
Return Value
A NSURLRequest
object
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
isPlaylistURI:
Check if a NSURL
is a valid playlist uri.
+ (BOOL)isPlaylistURI:(NSURL *)uri
Parameters
- uri
The Spotify URI of the playlist.
Declared In
SPTPlaylistSnapshot.h
isStarredURI:
Check if a NSURL
is a starred uri.
+ (BOOL)isStarredURI:(NSURL *)uri
Parameters
- uri
The Spotify URI of the playlist.
Declared In
SPTPlaylistSnapshot.h
playlistSnapshotFromData:withResponse:error:
Parse the response from an API call into an SPTPlaylistSnapshot
object
+ (instancetype)playlistSnapshotFromData:(NSData *)data withResponse:(NSURLResponse *)response error:(NSError **)error
Parameters
- data
The API response data
- response
The API response object
- error
An optional pointer to an
NSError
that will receive the error code if operation failed.
Return Value
The SPTPlaylistSnapshot
object
Declared In
SPTPlaylistSnapshot.h
playlistSnapshotFromDecodedJSON:error:
Parse the response from an API call into an SPTPlaylistSnapshot
object
+ (instancetype)playlistSnapshotFromDecodedJSON:(id)decodedObject error:(NSError **)error
Parameters
- decodedObject
The decoded JSON object structure
- error
An optional pointer to an
NSError
that will receive the error code if operation failed.
Return Value
The SPTPlaylistSnapshot
object
Declared In
SPTPlaylistSnapshot.h
playlistWithURI:accessToken:callback:
Request the playlist at the given Spotify URI.
+ (void)playlistWithURI:(NSURL *)uri accessToken:(NSString *)accessToken callback:(SPTRequestCallback)block
Parameters
- uri
The Spotify URI of the playlist to request.
- accessToken
An authenticated access token. Must be valid and authorized with the unspecified or
playlist-read-private
scope as necessary.
- block
The block to be called when the operation is complete. The block will pass a Spotify SDK metadata object on success, otherwise an error.
Discussion
Note: This method takes Spotify URIs in the form spotify:*
, NOT HTTP URLs.
Declared In
SPTPlaylistSnapshot.h
playlistsWithURIs:accessToken:callback:
Request multiple playlists given an array of Spotify URIs.
+ (void)playlistsWithURIs:(NSArray *)uris accessToken:(NSString *)accessToken callback:(SPTRequestCallback)block
Parameters
- uris
An array of Spotify URIs.
- accessToken
An authenticated access token. Must be valid and authorized with the unspecified or
playlist-read-private
scope as necessary.
- block
The block to be called when the operation is complete. The block will pass an array of Spotify SDK metadata objects on success, otherwise an error.
Discussion
Note: This method takes an array of Spotify URIs in the form spotify:*
, NOT HTTP URLs.
Declared In
SPTPlaylistSnapshot.h
requestStarredListForUser:withAccessToken:callback:
Request the starred playlist for a user
+ (void)requestStarredListForUser:(NSString *)username withAccessToken:(NSString *)accessToken callback:(SPTRequestCallback)block
Parameters
- username
The user to get the starred playlist for
- accessToken
An authenticated access token. Must be valid and authorized.
- block
The block to be called when the operation is complete. The block will pass an
SPTPlaylistSnapshot
object on success, otherwise an error.
Declared In
SPTPlaylistSnapshot.h
Instance Methods
addTracksToPlaylist:withAccessToken:callback:
Append tracks to the playlist.
- (void)addTracksToPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- tracks
The tracks to add, as
SPTTrack
orSPTPartialTrack
objects.
- accessToken
An authenticated access token. Must be valid and authorized with the playlist-modify-public
or
playlist-modify-private` scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
addTracksWithPositionToPlaylist:withPosition:accessToken:callback:
Add tracks to the playlist at a certain position.
- (void)addTracksWithPositionToPlaylist:(NSArray *)tracks withPosition:(int)position accessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- tracks
The tracks to add, as
SPTTrack
orSPTPartialTrack
objects.
- position
The position in which the tracks will be added, being 0 the top position.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
changePlaylistDetails:withAccessToken:callback:
Change playlist details
- (void)changePlaylistDetails:(NSDictionary *)data withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- data
The data to be changed. Use the key constants to refer to the field to change (e.g.
SPTPlaylistSnapshotNameKey
,SPTPlaylistSnapshotPublicKey
). When passing boolean values, use @YES or @NO.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
removeTracksFromPlaylist:withAccessToken:callback:
Remove tracks from playlist. It removes all occurrences of the tracks in the playlist.
- (void)removeTracksFromPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- tracks
The tracks to remove, as
SPTTrack
orSPTPartialTrack
objects.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
removeTracksWithPositionsFromPlaylist:withAccessToken:callback:
Remove tracks that are in specific positions from playlist.
- (void)removeTracksWithPositionsFromPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- tracks
An array of dictionaries with 2 keys:
track
with the track to remove, asSPTTrack
orSPTPartialTrack
objects, andpositions
that is an array of integers with the positions the track will be removed from.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h
replaceTracksInPlaylist:withAccessToken:callback:
Replace the tracks in a playlist, overwriting any tracks already in it
- (void)replaceTracksInPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)block
Parameters
- tracks
The tracks to set, as
SPTTrack
orSPTPartialTrack
objects.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-public
orplaylist-modify-private
scope as necessary.
- block
The block to be called when the operation is started. This block will pass an error if the operation failed.
Discussion
Note: This operation is asynchronous on the server, it can take a couple of seconds for your changes to propagate everywhere after this operation has started.
Declared In
SPTPlaylistSnapshot.h