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
-
firstTrackPageproperty -
snapshotIdproperty -
followerCountproperty -
descriptionTextproperty
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 *descriptionTextDeclared In
SPTPlaylistSnapshot.hfirstTrackPage
The tracks of the playlist, as a page of SPTPartialTrack objects.
@property (nonatomic, readonly) SPTListPage *firstTrackPageDeclared In
SPTPlaylistSnapshot.hClass 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 **)errorParameters
- tracks
The tracks to add, as
SPTTrack,SPTPartialTrackorNSURLobjects.
- 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-publicorplaylist-modify-privatescope as necessary.
- error
An optional pointer to a
NSErrorobject 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.hcreateRequestForAddingTracks:toPlaylist:withAccessToken:error:
Create a request for appending tracks to a playlist.
+ (NSURLRequest *)createRequestForAddingTracks:(NSArray *)tracks toPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)errorParameters
- tracks
The tracks to add, as
SPTTrack,SPTPartialTrackorNSURLobjects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-publicorplaylist-modify-privatescope as necessary.
- error
An optional pointer to a
NSErrorobject 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.hcreateRequestForChangingDetails:inPlaylist:withAccessToken:error:
Change playlist details
+ (NSURLRequest *)createRequestForChangingDetails:(NSDictionary *)data inPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken error:(NSError **)errorParameters
- 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-publicorplaylist-modify-privatescope as necessary.
- error
An optional pointer to a
NSErrorobject 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.hcreateRequestForPlaylistWithURI:accessToken:error:
Create a request to fetch a single playlist
+ (NSURLRequest *)createRequestForPlaylistWithURI:(NSURL *)uri accessToken:(NSString *)accessToken error:(NSError **)errorParameters
- 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
NSErrorobject 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.hcreateRequestForRemovingTracks:fromPlaylist:withAccessToken:snapshot:error:
Remove tracks from playlist.
+ (NSURLRequest *)createRequestForRemovingTracks:(NSArray *)tracks fromPlaylist:(NSURL *)playlist withAccessToken:(NSString *)accessToken snapshot:(NSString *)snapshotId error:(NSError **)errorParameters
- tracks
An array of
SPTTrack,SPTPartialTrackorNSURLobjects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-publicorplaylist-modify-privatescope as necessary.
- snapshotId
The playlist snapshotId to manipulate.
- error
An optional pointer to a
NSErrorobject 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.hcreateRequestForRemovingTracksWithPositions: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 **)errorParameters
- tracks
An array of dictionaries with 2 keys:
trackwith the track to remove, asSPTTrack,SPTPartialTrackorNSURLobjects, andpositionsthat 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-publicorplaylist-modify-privatescope as necessary.
- snapshotId
The playlist snapshotId to manipulate.
- error
An optional pointer to a
NSErrorobject 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.hcreateRequestForSettingTracks: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 **)errorParameters
- tracks
The new tracks, as
SPTTrack,SPTPartialTrackorNSURLobjects.
- playlist
The playlist to manipulate.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-publicorplaylist-modify-privatescope as necessary.
- error
An optional pointer to a
NSErrorobject 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.hisPlaylistURI:
Check if a NSURL is a valid playlist uri.
+ (BOOL)isPlaylistURI:(NSURL *)uriParameters
- uri
The Spotify URI of the playlist.
Declared In
SPTPlaylistSnapshot.hisStarredURI:
Check if a NSURL is a starred uri.
+ (BOOL)isStarredURI:(NSURL *)uriParameters
- uri
The Spotify URI of the playlist.
Declared In
SPTPlaylistSnapshot.hplaylistSnapshotFromData:withResponse:error:
Parse the response from an API call into an SPTPlaylistSnapshot object
+ (instancetype)playlistSnapshotFromData:(NSData *)data withResponse:(NSURLResponse *)response error:(NSError **)errorParameters
- data
The API response data
- response
The API response object
- error
An optional pointer to an
NSErrorthat will receive the error code if operation failed.
Return Value
The SPTPlaylistSnapshot object
Declared In
SPTPlaylistSnapshot.hplaylistSnapshotFromDecodedJSON:error:
Parse the response from an API call into an SPTPlaylistSnapshot object
+ (instancetype)playlistSnapshotFromDecodedJSON:(id)decodedObject error:(NSError **)errorParameters
- decodedObject
The decoded JSON object structure
- error
An optional pointer to an
NSErrorthat will receive the error code if operation failed.
Return Value
The SPTPlaylistSnapshot object
Declared In
SPTPlaylistSnapshot.hplaylistWithURI:accessToken:callback:
Request the playlist at the given Spotify URI.
+ (void)playlistWithURI:(NSURL *)uri accessToken:(NSString *)accessToken callback:(SPTRequestCallback)blockParameters
- 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-privatescope 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.hplaylistsWithURIs:accessToken:callback:
Request multiple playlists given an array of Spotify URIs.
+ (void)playlistsWithURIs:(NSArray *)uris accessToken:(NSString *)accessToken callback:(SPTRequestCallback)blockParameters
- uris
An array of Spotify URIs.
- accessToken
An authenticated access token. Must be valid and authorized with the unspecified or
playlist-read-privatescope 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.hrequestStarredListForUser:withAccessToken:callback:
Request the starred playlist for a user
+ (void)requestStarredListForUser:(NSString *)username withAccessToken:(NSString *)accessToken callback:(SPTRequestCallback)blockParameters
- 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
SPTPlaylistSnapshotobject on success, otherwise an error.
Declared In
SPTPlaylistSnapshot.hInstance Methods
addTracksToPlaylist:withAccessToken:callback:
Append tracks to the playlist.
- (void)addTracksToPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)blockParameters
- tracks
The tracks to add, as
SPTTrackorSPTPartialTrackobjects.
- 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.haddTracksWithPositionToPlaylist:withPosition:accessToken:callback:
Add tracks to the playlist at a certain position.
- (void)addTracksWithPositionToPlaylist:(NSArray *)tracks withPosition:(int)position accessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)blockParameters
- tracks
The tracks to add, as
SPTTrackorSPTPartialTrackobjects.
- 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-publicorplaylist-modify-privatescope 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.hchangePlaylistDetails:withAccessToken:callback:
Change playlist details
- (void)changePlaylistDetails:(NSDictionary *)data withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)blockParameters
- 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-publicorplaylist-modify-privatescope 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.hremoveTracksFromPlaylist: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)blockParameters
- tracks
The tracks to remove, as
SPTTrackorSPTPartialTrackobjects.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-publicorplaylist-modify-privatescope 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.hremoveTracksWithPositionsFromPlaylist:withAccessToken:callback:
Remove tracks that are in specific positions from playlist.
- (void)removeTracksWithPositionsFromPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)blockParameters
- tracks
An array of dictionaries with 2 keys:
trackwith the track to remove, asSPTTrackorSPTPartialTrackobjects, andpositionsthat 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-publicorplaylist-modify-privatescope 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.hreplaceTracksInPlaylist:withAccessToken:callback:
Replace the tracks in a playlist, overwriting any tracks already in it
- (void)replaceTracksInPlaylist:(NSArray *)tracks withAccessToken:(NSString *)accessToken callback:(SPTMetadataErrorableOperationCallback)blockParameters
- tracks
The tracks to set, as
SPTTrackorSPTPartialTrackobjects.
- accessToken
An authenticated access token. Must be valid and authorized with the
playlist-modify-publicorplaylist-modify-privatescope 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