Simplified Playlist Properties

isCollaborative
true if the owner allows other users to modify the playlist.
Declaration
Swift

public let isCollaborative: Bool
externalURLs
Known external URLs for this playlist.
Declaration
Swift

public let externalURLs: [String : URL]
url
A link to the Web API endpoint providing full details of the playlist.
Declaration
Swift

public let url: URL
id
The Spotify ID for the playlist.
Declaration
Swift

public let id: String
images
Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See Working with Playlists.

Note
If returned, the source URL for the image (url) is temporary and will expire in less than a day.
Declaration
Swift

public let images: [SKImage]
name
The name of the playlist.
Declaration
Swift

public let name: String
owner
The user who owns the playlist.
Declaration
Swift

public let owner: SKUser
isPublic
The playlist’s public/private status: true the playlist is public, false the playlist is private, nil the playlist status is not relevant. For more about public/private status, see Working with Playlists.
Declaration
Swift

public let isPublic: Bool?
snapshotID
The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version.
Declaration
Swift

public let snapshotID: String
tracksURL
A link to the Web API endpoint where full details of the playlist’s tracks can be retrieved.
Declaration
Swift

public let tracksURL: URL
totalTracks
The total number of tracks in the playlist.
Declaration
Swift

public let totalTracks: Int
uri
The Spotify URI for the playlist.
Declaration
Swift

public let uri: String

Full Playlist Properties

tracks
A collection containing information about the tracks of the playlist.
Declaration
Swift

public let tracks: Page<SKPlaylistTrack>?
userDescription
The playlist description. Only returned for modified, verified playlists, otherwise nil.
Declaration
Swift

public let userDescription: String?
followers
Information about the followers of the playlist.
Declaration
Swift

public let followers: SKFollowers?

Create a Playlist


                    
                    
                    makeNewPlaylistRequest(userID:name:description:isPublic:isCollaborative:)

Creates and returns the request used to create a new playlist.

Declaration

Swift

public static func makeNewPlaylistRequest(userID: String, name: String, description: String?, isPublic: Bool, isCollaborative: Bool) -> SKRequest

Parameters

`userID`	The Spotify ID for the current authenticated user.
`name`	The name for the new playlist. This name does not need to be unique; a user may have several playlists with the same name.
`description`	An optional description of the playlist.
`isPublic`	`true` if the playlist will be public, `false` if private.
`isCollaborative`	`true` if the playlist will be collaborative, `false` otherwise.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    createPlaylist(named:description:isPublic:isCollaborative:completion:)

Creates a new, empty playlist for the current authenticated user.

Note

This method uses the SPTAuth default instance session to provide the user ID for, and the access token to authenticate, the underlying request. If this session does not contain a valid access token, the request will result in an error; if this session does not contain a valid username, then this method will do nothing.

The access token must have been issued on behalf of the current user, who must have authorized either the playlist-modify-public or playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public static func createPlaylist(named name: String, description: String? = nil, isPublic: Bool = true, isCollaborative: Bool = false, completion handler: @escaping (SKPlaylist?, Error?) -> Void)

Parameters

`name`	The name for the new playlist. This name does not need to be unique; a user may have several playlists with the same name.
`description`	An optional description of the playlist. The default value is `nil`.
`isPublic`	`true` if the playlist should be public, `false` if private. The default value is `true`.
`isCollaborative`	`true` if the playlist should be collaborative, `false` otherwise. The default value is `false`.
`handler`	The callback handler for the request. The parameters for this handler are: `playlist`: The newly-created playlist, if the request was successful. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Update a Playlist's Details


                    
                    
                    makeUpdateDetailsRequest(name:description:isPublic:isCollaborative:)

Creates and returns the request used to update a playlist’s details.

Note

If all parameters have been set to nil, the returned request will not contain a request body.

Declaration

Swift

public func makeUpdateDetailsRequest(name: String?, description: String?, isPublic: Bool?, isCollaborative: Bool?) -> SKRequest

Parameters

`name`	The new name for the playlist.
`description`	A new description of the playlist.
`isPublic`	If `true`, the playlist will be made public; if `false`, private.
`isCollaborative`	If `true`, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    update(name:description:isPublic:isCollaborative:completion:)

Changes a playlist’s details, including its name, description, and access levels.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Changing the details for a public playlist requires authorization of the playlist-modify-public scope; likewise, changing the details for a private playlist requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

If all parameters have been set to nil, then this method will do nothing.

Declaration

Swift

public func update(name: String? = nil, description: String? = nil, isPublic: Bool? = nil, isCollaborative: Bool? = nil, completion handler: @escaping SKErrorHandler)

Parameters

`name`	The new name for the playlist. The default value is `nil`.
`description`	A new description of the playlist. The default value is `nil`.
`isPublic`	If `true`, the playlist will be made public; if `false`, private. The default value is `nil`.
`isCollaborative`	If `true`, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. The default value is `nil`.
`handler`	The callback handler for the request, providing an error identifying if and why the request failed, or `nil` if the request was successful.

Upload a Custom Playlist Cover Image


                    
                    
                    makeUpdateImageRequest(data:)

Creates and returns the request used to upload a custom playlist cover image.

Declaration

Swift

public func makeUpdateImageRequest(data: Data) -> SKRequest

Parameters


                                data

The image data to upload. The payload must contain Base-64 encoded JPEG image data. The maximum encoded payload size is 256 KB.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    updateImage(with:completion:)

Uploads a custom playlist cover image, replacing the current image used to represent the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

The access token must have been issued on behalf of the user who owns the playlist, and must have the ugc-image-upload scope authorized. In addition, the token must also contain the playlist-modify-public and/or playlist-modify-private scopes, depending the access level of playlist. See Authorization Scopes for more details.

Declaration

Swift

public func updateImage(with data: Data, completion handler: @escaping SKErrorHandler)

Parameters

`data`	The image data to upload. The payload must contain Base-64 encoded JPEG image data. The maximum encoded payload size is 256 KB.
`handler`	The callback handler for the request, providing an error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    updateImage(with:quality:completion:)

Uploads a custom playlist cover image, replacing the current image used to represent the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

The access token must have been issued on behalf of the user who owns the playlist, and must have the ugc-image-upload scope authorized. In addition, the token must also contain the playlist-modify-public and/or playlist-modify-private scopes, depending the access level of playlist. See Authorization Scopes for more details.

Declaration

Swift

public func updateImage(with image: UIImage, quality: Float = 0.8, completion handler: @escaping SKErrorHandler)

Parameters

`image`	The image data to upload. The maximum encoded payload size is 256 KB.
`quality`	The compression quality of the resulting JPEG image, expressed as a value from 0.0 to 1.0. The value 0.0 represents the maximum compression (or lowest quality) while the value 1.0 represents the least compression (or best quality). The default value is 0.8.
`handler`	The callback handler for the request, providing an error identifying if and why the request failed, or `nil` if the request was successful.

Get a Playlist's Tracks


                    
                    
                    makeTracksRequest(locale:page:)

Creates and returns the request used to get a playlist’s tracks.

Declaration

Swift

public func makeTracksRequest(locale: Locale?, page: Pagination?) -> SKRequest

Parameters

`locale`	The locale-specific storefront/market from which to request.
`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getTracks(for:page:completion:)

Gets the full details for the tracks of a playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

Both public and private playlists belonging to any user are retrievable on provision of a valid access token.

Declaration

Swift

public func getTracks(for locale: Locale? = SKCatalog.local.locale, page: Pagination? = nil, completion handler: @escaping (Page<SKPlaylistTrack>?, Error?) -> Void)

Parameters

`locale`	The locale-specific storefront/market from which to request. The default value is the locale for the shared `SKCatalog` instance, which by default represents the user’s region settings at the time the method is called.
`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `tracks`: A paginated collection of full playlist tracks, if available. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Add Tracks to a Playlist


                    
                    
                    makeAddTracksRequest(tracks:position:)

Creates and returns the request used to add tracks to the playlist.

Declaration

Swift

public func makeAddTracksRequest<T>(tracks: T, position: Int?) -> SKRequest where T : Collection, T.Element : Track

Parameters

`tracks`	A list of tracks to add.
`position`	The index at which to insert the tracks. If omitted or set to `nil`, the tracks will be appended to the playlist.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    add(_:at:completion:)

Adds the given tracks to the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Adding tracks to a public playlist requires authorization of the playlist-modify-public scope; likewise, adding tracks to a private playlist (including collaborative playlists) requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func add<T: Collection>(_ tracks: T, at position: Int? = nil, completion handler: @escaping (String?, Error?) -> Void) where T.Element: Track

Parameters

`tracks`	A list of tracks to add.
`position`	The index at which to insert the tracks. If omitted or set to `nil`, the tracks will be appended to the playlist. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    add(_:at:completion:)

Adds the given track to the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Adding tracks to a public playlist requires authorization of the playlist-modify-public scope; likewise, adding tracks to a private playlist (including collaborative playlists) requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func add<T: Track>(_ track: T, at position: Int? = nil, completion handler: @escaping (String?, Error?) -> Void)

Parameters

`track`	The track to add.
`position`	The index at which to insert the track. If omitted or set to `nil`, the track will be appended to the playlist. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Remove Tracks from a Playlist


                    
                    
                    makeRemoveTracksRequest(tracks:snapshotID:)

Creates and returns the request used to remove tracks from the playlist.

Declaration

Swift

public func makeRemoveTracksRequest<T>(tracks: T, snapshotID: String?) -> SKRequest where T : Collection, T.Element : Track

Parameters

`tracks`	The list of tracks to remove. The tracks’ URIs must match those already in the playlist, otherwise the request will result in an error. Call the method with this parameter when attempting to remove all occurrences of a given track or set of tracks within the playlist.
`snapshotID`	A specific playlist snapshot against which to perform the changes. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    makeRemoveTracksRequest(positions:snapshotID:)

Creates and returns the request used to remove tracks from the playlist.

Declaration

Swift

public func makeRemoveTracksRequest(positions: [Int], snapshotID: String?) -> SKRequest

Parameters

`positions`	An array of integers representing the indices of the tracks to remove. The values provided must be valid indices within the list of tracks. Call the method with this parameter when attempting to remove tracks at a specific position or positions within the playlist.
`snapshotID`	A specific playlist snapshot against which to perform the changes. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    remove(at:inSnapshot:completion:)

Removes one or more tracks from the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Removing tracks from a public playlist requires authorization of the playlist-modify-public scope; likewise, removing tracks from a private playlist requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func remove(at positions: [Int], inSnapshot snapshotID: String = "", completion handler: @escaping (String?, Error?) -> Void)

Parameters

`positions`	An array of integers representing the indices of the tracks to remove. The values provided must be valid indices within the list of tracks. A maximum of 100 values can be sent at once.
`snapshotID`	The specific playlist snapshot against which to perform the changes. This parameter is required to guard against concurrent edits to the playlist. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts. The default value is the playlist’s current `snapshotID`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    remove(at:inSnapshot:completion:)

Removes one or more tracks from the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Removing tracks from a public playlist requires authorization of the playlist-modify-public scope; likewise, removing tracks from a private playlist requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func remove(at position: Int, inSnapshot snapshotID: String = "", completion handler: @escaping (String?, Error?) -> Void)

Parameters

`position`	An integer representing the index of the track to remove. The value provided must be a valid index within the list of tracks.
`snapshotID`	The specific playlist snapshot against which to perform the changes. This parameter is required to guard against concurrent edits to the playlist. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts. The default value is the playlist’s current `snapshotID`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    removeOccurrences(of:inSnapshot:completion:)

Removes all occurrences of the specified tracks from the playlist.

Declaration

Swift

public func removeOccurrences<T: Collection>(of tracks: T, inSnapshot snapshotID: String? = nil, completion handler: @escaping (String?, Error?) -> Void) where T.Element: Track

Parameters

`tracks`	The list of tracks to remove. The tracks’ URIs must match those already in the playlist, otherwise the request will result in an error.
`snapshotID`	A specific playlist snapshot against which to perform the changes. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts. The API will validate that the specified tracks exist and make the changes, even if more recent changes have been made to the playlist. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    removeOccurrences(of:inSnapshot:completion:)

Removes all occurrences of the specified track from the playlist.

Declaration

Swift

public func removeOccurrences<T: Track>(of track: T, inSnapshot snapshotID: String? = nil, completion handler: @escaping (String?, Error?) -> Void)

Parameters

`track`	The track to remove. The track’s URI must match one already in the playlist, otherwise the request will result in an error.
`snapshotID`	A specific playlist snapshot against which to perform the changes. When making subsequent playlist requests, use this parameter to supply the most recent snapshot identifier to avoid editing conflicts. The API will validate that the specified track exists and make the changes, even if more recent changes have been made to the playlist. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Reorder a Playlist's Tracks


                    
                    
                    makeMoveTracksRequest(startIndex:rangeLength:position:snapshotID:)

Creates and returns the request used to reorder tracks in a playlist.

Declaration

Swift

public func makeMoveTracksRequest(startIndex: Int, rangeLength: Int?, position: Int, snapshotID: String?) -> SKRequest

Parameters

`startIndex`	The index of the first track to be reordered.
`rangeLength`	The number of tracks to be reordered, beginning with the start index. If reordering a single track, set this parameter to `nil`.
`position`	The index of the track before which the reordered track(s) should be inserted.
`snapshotID`	A specific playlist snapshot against which to perform the changes.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    move(at:before:inSnapshot:completion:)

Reorders a track or a group of tracks in a playlist.

When reordering tracks, the timestamp indicating when they were added and the user who added them will be kept untouched. In addition, users following the playlists will not be notified about changes in the playlists when the tracks are reordered.

Discussion

When selecting which tracks to reorder, you can use a half-open range to select tracks up to a given index. For example:

Listing 1

let endIndex = playlist.totalTracks
playlist.move(at: 7..<endIndex, before: 0) {
    (snapshotID, error) in
    // Moves tracks at index seven onwards
    // to the beginning of the playlist.
}

Alternatively, you can use a closed range to encompass all tracks at the given indices. For example:

Listing 2

let endIndex = playlist.totalTracks
playlist.move(at: 0...2, before: endIndex) {
    (snapshotID, error) in
    // Moves the first three tracks
    // to the end of the playlist.
}

If you simply want to move a single track instead of a range of tracks, you can also provide a single index value. For example:

Listing 3

playlist.move(at: 5, before: 0) {
    (snapshotID, error) in
    // Moves the track at index five
    // to the beginning of the playlist.
}

For a better visualization on how reordering Spotify tracks works, see the API Endpoint Reference.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Declaration

Swift

public func move(at indices: Range<Int>, before position: Int, inSnapshot snapshotID: String? = nil, completion handler: @escaping (String?, Error?) -> Void)

Parameters

`indices`	A contiguous range of integers representing the indices of the tracks to reorder, with the lower bound representing the index of the first track to be reordered. When using a closed range, the bounds of the range must be valid indices within the list of tracks; with a half-open range, all values up to (but not including) the upper bound must be valid indices within the list of tracks.
`position`	The index of the track before which the reordered track(s) should be inserted. To move tracks to the end of the playlist, set this parameter to the track list’s past the end position—that is, the position one greater than the last valid index. With the exception of this value, this parameter must be a valid index within the list of tracks.
`snapshotID`	A specific playlist snapshot against which to perform the changes. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    move(at:before:inSnapshot:completion:)

Reorders a track or a group of tracks in a playlist.

When reordering tracks, the timestamp indicating when they were added and the user who added them will be kept untouched. In addition, users following the playlists will not be notified about changes in the playlists when the tracks are reordered.

Discussion

When selecting which tracks to reorder, you can use a half-open range to select tracks up to a given index. For example:

Listing 1

let endIndex = playlist.totalTracks
playlist.move(at: 7..<endIndex, before: 0) {
    (snapshotID, error) in
    // Moves tracks at index seven onwards
    // to the beginning of the playlist.
}

Alternatively, you can use a closed range to encompass all tracks at the given indices. For example:

Listing 2

let endIndex = playlist.totalTracks
playlist.move(at: 0...2, before: endIndex) {
    (snapshotID, error) in
    // Moves the first three tracks
    // to the end of the playlist.
}

If you simply want to move a single track instead of a range of tracks, you can also provide a single index value. For example:

Listing 3

playlist.move(at: 5, before: 0) {
    (snapshotID, error) in
    // Moves the track at index five
    // to the beginning of the playlist.
}

For a better visualization on how reordering Spotify tracks works, see the API Endpoint Reference.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Declaration

Swift

public func move(at indices: ClosedRange<Int>, before position: Int, inSnapshot snapshotID: String? = nil, completion handler: @escaping (String?, Error?) -> Void)

Parameters

`indices`	A contiguous range of integers representing the indices of the tracks to reorder, with the lower bound representing the index of the first track to be reordered. When using a closed range, the bounds of the range must be valid indices within the list of tracks; with a half-open range, all values up to (but not including) the upper bound must be valid indices within the list of tracks.
`position`	The index of the track before which the reordered track(s) should be inserted. To move tracks to the end of the playlist, set this parameter to the track list’s past the end position—that is, the position one greater than the last valid index. With the exception of this value, this parameter must be a valid index within the list of tracks.
`snapshotID`	A specific playlist snapshot against which to perform the changes. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.


                    
                    
                    move(at:before:inSnapshot:completion:)

Reorders a track or a group of tracks in a playlist.

When reordering tracks, the timestamp indicating when they were added and the user who added them will be kept untouched. In addition, users following the playlists will not be notified about changes in the playlists when the tracks are reordered.

Discussion

When selecting which tracks to reorder, you can use a half-open range to select tracks up to a given index. For example:

Listing 1

let endIndex = playlist.totalTracks
playlist.move(at: 7..<endIndex, before: 0) {
    (snapshotID, error) in
    // Moves tracks at index seven onwards
    // to the beginning of the playlist.
}

Alternatively, you can use a closed range to encompass all tracks at the given indices. For example:

Listing 2

let endIndex = playlist.totalTracks
playlist.move(at: 0...2, before: endIndex) {
    (snapshotID, error) in
    // Moves the first three tracks
    // to the end of the playlist.
}

If you simply want to move a single track instead of a range of tracks, you can also provide a single index value. For example:

Listing 3

playlist.move(at: 5, before: 0) {
    (snapshotID, error) in
    // Moves the track at index five
    // to the beginning of the playlist.
}

For a better visualization on how reordering Spotify tracks works, see the API Endpoint Reference.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Declaration

Swift

public func move(at index: Int, before position: Int, inSnapshot snapshotID: String? = nil, completion handler: @escaping (String?, Error?) -> Void)

Parameters

`index`	The index of the track to reorder. This parameter must be valid index within the list of tracks.
`position`	The index of the track before which the reordered track(s) should be inserted. To move tracks to the end of the playlist, set this parameter to the track list’s past the end position—that is, the position one greater than the last valid index. With the exception of this value, this parameter must be a valid index within the list of tracks.
`snapshotID`	A specific playlist snapshot against which to perform the changes. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Replace a Playlist's Tracks


                    
                    
                    makeReplaceTracksRequest(tracks:)

Creates and returns the request used to replace tracks in the playlist.

Declaration

Swift

public func makeReplaceTracksRequest<T>(tracks: T) -> SKRequest where T : Collection, T.Element : Track

Parameters


                                tracks

The list of tracks with which to replace the contents of the playlist. To clear all tracks from the playlist, set this parameter to an empty array.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    replace(with:completion:)

Replaces all the tracks in the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Replacing tracks in a public playlist requires authorization of the playlist-modify-public scope; likewise, replacing tracks in a private playlist requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func replace<T: Collection>(with tracks: T, completion handler: @escaping (String?, Error?) -> Void) where T.Element: Track

Parameters

`tracks`	The list of tracks with which to replace the contents of the playlist. To clear all tracks from the playlist, set this parameter to an empty array.
`handler`	The callback handler for the request. The parameters for this handler are: `snapshotID`: On success, the snapshot ID string identifying the version of this playlist that reflects the given changes. This value can be used to identify this specific version in subsequent requests. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Follow a Playlist


                    
                    
                    makeFollowRequest(public:)

Creates and returns the request used to add the current authenticated user as a follower of the playlist.

Declaration

Swift

public func makeFollowRequest(public: Bool) -> SKRequest

Parameters


                                public

A Boolean value indicating whether the playlist should be included in the user’s public playlists.

Note: to follow playlists privately, the user must authorize the playlist-modify-private scope. See Using Scopes for more details.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    follow(makingPublic:completion:)

Adds the current authenticated user as a follower of the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Following a playlist publicly requires authorization of the playlist-modify-public scope; likewise, following a playlist privately requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func follow(makingPublic public: Bool = true, completion handler: @escaping SKErrorHandler)

Parameters

`public`	A Boolean value indicating whether the playlist should be included in the user’s public playlists. The default value is `true`.
`handler`	The callback handler for the request, providing an error identifying if and why the request failed, or `nil` if the request was successful.

Unfollow a Playlist

makeUnfollowRequest()
Creates and returns the request used to remove the current authenticated user as a follower of the playlist.
Declaration
Swift

public func makeUnfollowRequest() -> SKRequest
Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    unfollow(completion:)

Removes the current authenticated user as a follower of the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error. The access token must have been issued on behalf of the current user.

Unfollowing a publicly-followed playlist requires authorization of the playlist-modify-public scope; likewise, unfollowing a privately-followed playlist requires authorization of the playlist-modify-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func unfollow(completion handler: @escaping SKErrorHandler)

Parameters


                                handler

The callback handler for the request, providing an error identifying if and why the request failed, or nil if the request was successful.

Check if Users Follow a Playlist


                    
                    
                    makeFollowStatusRequest(users:)

Creates and returns the request used to check whether the given users are following the playlist.

Declaration

Swift

public func makeFollowStatusRequest<T>(users: T) -> SKRequest where T : Collection, T.Element : User

Parameters


                                users

The users against which to perform the check. Maximum: 5 users.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    checkIfFollowed(by:completion:)

Check to see if one or more Spotify users are following the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

Following a playlist can be done publicly or privately. Checking if a user publicly follows a playlist doesn’t require any scopes; if the user is publicly following the playlist, the resulting Boolean value will be true.

However, checking if the user is privately following a playlist is only possible for the current authenticated user when that user has granted access to the playlist-read-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func checkIfFollowed<T: Collection>(by users: T, completion handler: @escaping ([Bool]?, Error?) -> Void) where T.Element: User

Parameters


                                users

The users against which to perform the check. Maximum: 5 users.


                                handler

The callback handler for the request. The parameters for this handler are:

isFollowing: An array of Boolean values indicating whether the given users are following the playlist. For each user that is following, the resulting array will contain true at the corresponding index; false otherwise.
error: An error identifying if and why the request failed, or nil if the request was successful.


                    
                    
                    checkIfFollowed(by:completion:)

Check to see if one or more Spotify users are following the playlist.

Note

This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

Following a playlist can be done publicly or privately. Checking if a user publicly follows a playlist doesn’t require any scopes; if the user is publicly following the playlist, the resulting Boolean value will be true.

However, checking if the user is privately following a playlist is only possible for the current authenticated user when that user has granted access to the playlist-read-private scope. See Authorization Scopes for more details.

Declaration

Swift

public func checkIfFollowed<T: User>(by user: T, completion handler: @escaping (Bool?, Error?) -> Void)

Parameters

`user`	The user against which to perform the check.
`handler`	The callback handler for the request. The parameters for this handler are: `isFollowing`: A Boolean value indicating whether the given user is following the playlist: `true` if following, `false` otherwise. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Playable & Queueable Protocols


                    
                    
                    play(completion:)

Declaration

Swift

public func play(completion handler: @escaping SKErrorHandler/* = { _ in }*/)

Custom Decoding


                    
                    
                    init(from:)

Declaration

Swift

public init(from decoder: Decoder) throws

Expandable Conformance

isSimplified
Declaration
Swift

public var isSimplified: Bool { get }