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]);
        }];
    }];

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

followerCount

The number of followers of this playlist

@property (nonatomic, readonly) long followerCount

Declared In

SPTPlaylistSnapshot.h

snapshotId

The version identifier for the playlist.

@property (nonatomic, readonly, copy) NSString *snapshotId

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 or NSURL 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 or playlist-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 or NSURL objects.

playlist

The playlist to manipulate.

accessToken

An authenticated access token. Must be valid and authorized with the playlist-modify-public or playlist-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 or playlist-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 or NSURL objects.

playlist

The playlist to manipulate.

accessToken

An authenticated access token. Must be valid and authorized with the playlist-modify-public or playlist-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, as SPTTrack, SPTPartialTrack or NSURL objects, and positions 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 or playlist-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 or NSURL objects.

playlist

The playlist to manipulate.

accessToken

An authenticated access token. Must be valid and authorized with the playlist-modify-public or playlist-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 or SPTPartialTrack objects.

accessToken

An authenticated access token. Must be valid and authorized with the playlist-modify-publicorplaylist-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 or SPTPartialTrack 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 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

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 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

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 or SPTPartialTrack 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

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, as SPTTrack or SPTPartialTrack objects, and positions 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 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

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 or SPTPartialTrack 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