The playlist subsystem handles playlists and playlist containers (list of playlists).
The playlist container functions are always valid, but your playlists are not guaranteed to be loaded until the sp_session_callbacks::logged_in callback has been issued.
| typedef struct sp_playlist_callbacks sp_playlist_callbacks |
Playlist callbacks
Used to get notifications when playlists are updated. If some callbacks should not be of interest, set them to NULL.
| typedef struct sp_playlistcontainer_callbacks sp_playlistcontainer_callbacks |
Playlist container callbacks. If some callbacks should not be of interest, set them to NULL.
| sp_error sp_playlist_add_callbacks | ( | sp_playlist * | playlist, | |
| sp_playlist_callbacks * | callbacks, | |||
| void * | userdata | |||
| ) |
Register interest in the given playlist
Here is a snippet from jukebox.c:
sp_playlist_add_callbacks(pl, &pl_callbacks, NULL);
| [in] | playlist | Playlist object |
| [in] | callbacks | Callbacks, see sp_playlist_callbacks |
| [in] | userdata | Userdata to be passed to callbacks |
| sp_error sp_playlist_add_ref | ( | sp_playlist * | playlist | ) |
Increase the reference count of a playlist
| [in] | playlist | The playlist object |
| sp_error sp_playlist_add_tracks | ( | sp_playlist * | playlist, | |
| sp_track *const * | tracks, | |||
| int | num_tracks, | |||
| int | position, | |||
| sp_session * | session | |||
| ) |
Add tracks to a playlist
| [in] | playlist | Playlist object |
| [in] | tracks | Array of pointer to tracks. |
| [in] | num_tracks | Length of tracks array |
| [in] | position | Start position in playlist where to insert the tracks |
| [in] | session | Your session object |
| sp_playlist* sp_playlist_create | ( | sp_session * | session, | |
| sp_link * | link | |||
| ) |
Load an already existing playlist without adding it to a playlistcontainer.
| [in] | session | Session object |
| [in] | link | Link object referring to a playlist |
| const char* sp_playlist_get_description | ( | sp_playlist * | playlist | ) |
Get description for a playlist
| [in] | playlist | Playlist object |
| bool sp_playlist_get_image | ( | sp_playlist * | playlist, | |
| byte | image[20] | |||
| ) |
Get description for a playlist
| [in] | playlist | Playlist object |
| [out] | image | 20 byte image id |
| int sp_playlist_get_offline_download_completed | ( | sp_session * | session, | |
| sp_playlist * | playlist | |||
| ) |
Get download progress for an offline playlist
| [in] | session | Session object |
| [in] | playlist | Playlist object |
| sp_playlist_offline_status sp_playlist_get_offline_status | ( | sp_session * | session, | |
| sp_playlist * | playlist | |||
| ) |
Get offline status for a playlist
| [in] | session | Session object |
| [in] | playlist | Playlist object |
| bool sp_playlist_has_pending_changes | ( | sp_playlist * | playlist | ) |
Check if a playlist has pending changes
Pending changes are local changes that have not yet been acknowledged by the server.
| [in] | playlist | Playlist object |
| bool sp_playlist_is_collaborative | ( | sp_playlist * | playlist | ) |
Return collaborative status for a playlist.
A playlist in collaborative state can be modifed by all users, not only the user owning the list
| [in] | playlist | Playlist object |
| bool sp_playlist_is_in_ram | ( | sp_session * | session, | |
| sp_playlist * | playlist | |||
| ) |
Return whether a playlist is loaded in RAM (as opposed to only stored on disk)
| [in] | session | Session object |
| [in] | playlist | Playlist object |
The easiest way to detect this case is when sp_playlist_is_in_ram() returns false and sp_link_create_from_playlist() returns NULL
| bool sp_playlist_is_loaded | ( | sp_playlist * | playlist | ) |
Get load status for the specified playlist. If it's false, you have to wait until playlist_state_changed happens, and check again if is_loaded has changed
| [in] | playlist | Playlist object |
| const char* sp_playlist_name | ( | sp_playlist * | playlist | ) |
| unsigned int sp_playlist_num_subscribers | ( | sp_playlist * | playlist | ) |
Return number of subscribers for a given playlist
| [in] | playlist | Playlist object |
| int sp_playlist_num_tracks | ( | sp_playlist * | playlist | ) |
| sp_user* sp_playlist_owner | ( | sp_playlist * | playlist | ) |
Return a pointer to the user for the given playlist
| [in] | playlist | Playlist object |
| sp_error sp_playlist_release | ( | sp_playlist * | playlist | ) |
| sp_error sp_playlist_remove_callbacks | ( | sp_playlist * | playlist, | |
| sp_playlist_callbacks * | callbacks, | |||
| void * | userdata | |||
| ) |
Unregister interest in the given playlist
The combination of (callbacks, userdata) is used to find the entry to be removed
Here is a snippet from jukebox.c:
sp_playlist_remove_callbacks(pl, &pl_callbacks, NULL);
| [in] | playlist | Playlist object |
| [in] | callbacks | Callbacks, see sp_playlist_callbacks |
| [in] | userdata | Userdata to be passed to callbacks |
| sp_error sp_playlist_remove_tracks | ( | sp_playlist * | playlist, | |
| const int * | tracks, | |||
| int | num_tracks | |||
| ) |
Remove tracks from a playlist
| [in] | playlist | Playlist object |
| [in] | tracks | Array of pointer to track indices. A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata, whereas [0, 1, 1] is invalid. |
| [in] | num_tracks | Length of tracks array |
| sp_error sp_playlist_rename | ( | sp_playlist * | playlist, | |
| const char * | new_name | |||
| ) |
Rename the given playlist The name must not consist of only spaces and it must be shorter than 256 characters.
| [in] | playlist | Playlist object |
| [in] | new_name | New name for playlist |
| sp_error sp_playlist_reorder_tracks | ( | sp_playlist * | playlist, | |
| const int * | tracks, | |||
| int | num_tracks, | |||
| int | new_position | |||
| ) |
Move tracks in playlist
| [in] | playlist | Playlist object |
| [in] | tracks | Array of pointer to track indices to be moved. A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata, whereas [0, 1, 1] is invalid. |
| [in] | num_tracks | Length of tracks array |
| [in] | new_position | New position for tracks |
| sp_error sp_playlist_set_autolink_tracks | ( | sp_playlist * | playlist, | |
| bool | link | |||
| ) |
Set autolinking state for a playlist.
If a playlist is autolinked, unplayable tracks will be made playable by linking them to other Spotify tracks, where possible.
| [in] | playlist | Playlist object |
| [in] | link | True or false |
| sp_error sp_playlist_set_collaborative | ( | sp_playlist * | playlist, | |
| bool | collaborative | |||
| ) |
Set collaborative status for a playlist.
A playlist in collaborative state can be modified by all users, not only the user owning the list
| [in] | playlist | Playlist object |
| [in] | collaborative | True or false |
| sp_error sp_playlist_set_in_ram | ( | sp_session * | session, | |
| sp_playlist * | playlist, | |||
| bool | in_ram | |||
| ) |
Return whether a playlist is loaded in RAM (as opposed to only stored on disk)
| [in] | session | Session object |
| [in] | playlist | Playlist object |
| [in] | in_ram | Controls whether or not to keep the list in RAM |
| sp_error sp_playlist_set_offline_mode | ( | sp_session * | session, | |
| sp_playlist * | playlist, | |||
| bool | offline | |||
| ) |
Mark a playlist to be synchronized for offline playback. The playlist must be in the users playlistcontainer
| [in] | session | Session object |
| [in] | playlist | Playlist object |
| [in] | offline | True iff playlist should be offline, false otherwise |
| sp_subscribers* sp_playlist_subscribers | ( | sp_playlist * | playlist | ) |
Return subscribers for a playlist
| [in] | playlist | Playlist object |
| sp_error sp_playlist_subscribers_free | ( | sp_subscribers * | subscribers | ) |
Free object returned from sp_playlist_subscribers()
| [in] | subscribers | Subscribers object |
| sp_track* sp_playlist_track | ( | sp_playlist * | playlist, | |
| int | index | |||
| ) |
Return the track at the given index in a playlist
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| int sp_playlist_track_create_time | ( | sp_playlist * | playlist, | |
| int | index | |||
| ) |
Return when the given index was added to the playlist
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| sp_user* sp_playlist_track_creator | ( | sp_playlist * | playlist, | |
| int | index | |||
| ) |
Return user that added the given index in the playlist
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| const char* sp_playlist_track_message | ( | sp_playlist * | playlist, | |
| int | index | |||
| ) |
Return a message attached to a playlist item. Typically used on inbox.
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| bool sp_playlist_track_seen | ( | sp_playlist * | playlist, | |
| int | index | |||
| ) |
Return if a playlist entry is marked as seen or not
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| sp_error sp_playlist_track_set_seen | ( | sp_playlist * | playlist, | |
| int | index, | |||
| bool | seen | |||
| ) |
Set seen status of a playlist entry
| [in] | playlist | Playlist object |
| [in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
| [in] | seen | Seen status to be set |
| sp_error sp_playlist_update_subscribers | ( | sp_session * | session, | |
| sp_playlist * | playlist | |||
| ) |
Ask library to update the subscription count for a playlist
When the subscription info has been fetched from the Spotify backend the playlist subscribers_changed() callback will be invoked. In that callback use sp_playlist_num_subscribers() and/or sp_playlist_subscribers() to get information about the subscribers. You can call those two functions anytime you want but the information might not be up to date in such cases
| [in] | session | Session object |
| [in] | playlist | Playlist object |
| sp_error sp_playlistcontainer_add_callbacks | ( | sp_playlistcontainer * | pc, | |
| sp_playlistcontainer_callbacks * | callbacks, | |||
| void * | userdata | |||
| ) |
Register interest in changes to a playlist container
| [in] | pc | Playlist container |
| [in] | callbacks | Callbacks, see sp_playlistcontainer_callbacks |
| [in] | userdata | Opaque value passed to callbacks. |
| sp_error sp_playlistcontainer_add_folder | ( | sp_playlistcontainer * | pc, | |
| int | index, | |||
| const char * | name | |||
| ) |
Add a playlist folder
| [in] | pc | Playlist container |
| [in] | index | Position of SP_PLAYLIST_TYPE_START_FOLDER entry |
| [in] | name | Name of group |
To remove a playlist folder both of these must be deleted or the list will be left in an inconsistant state.
There is no way to rename a playlist folder. Instead you need to remove the folder and recreate it again.
| sp_playlist* sp_playlistcontainer_add_new_playlist | ( | sp_playlistcontainer * | pc, | |
| const char * | name | |||
| ) |
Add an empty playlist at the end of the playlist container. The name must not consist of only spaces and it must be shorter than 256 characters.
| [in] | pc | Playlist container |
| [in] | name | Name of new playlist |
| sp_playlist* sp_playlistcontainer_add_playlist | ( | sp_playlistcontainer * | pc, | |
| sp_link * | link | |||
| ) |
Add an existing playlist at the end of the given playlist container
| [in] | pc | Playlist container |
| [in] | link | Link object pointing to a playlist |
| sp_error sp_playlistcontainer_add_ref | ( | sp_playlistcontainer * | pc | ) |
Increase reference count on playlistconatiner object
| [in] | pc | Playlist container. |
| int sp_playlistcontainer_clear_unseen_tracks | ( | sp_playlistcontainer * | pc, | |
| sp_playlist * | playlist | |||
| ) |
Clears a playlist from unseen tracks, so that next call to sp_playlistcontainer_get_unseen_tracks() will return 0 until a new track is added to the playslist.
| [in] | pc | Playlist container. |
| [in] | playlist | Playlist object. |
| int sp_playlistcontainer_get_unseen_tracks | ( | sp_playlistcontainer * | pc, | |
| sp_playlist * | playlist, | |||
| sp_track ** | tracks, | |||
| int | num_tracks | |||
| ) |
Get the number of new tracks in a playlist since the corresponding function sp_playlistcontainer_clear_unseen_tracks() was called. The function always returns the number of new tracks, and fills the tracks array with the new tracks, but not more than specified in num_tracks. The function will return a negative value on failure.
| [in] | pc | Playlist container. |
| [in] | playlist | Playlist object. |
| [out] | tracks | Array of pointer to new tracks (maybe NULL) |
| [in] | num_tracks | Size of tracks array |
| bool sp_playlistcontainer_is_loaded | ( | sp_playlistcontainer * | pc | ) |
Return true if the playlistcontainer is fully loaded
| [in] | pc | Playlist container |
| sp_error sp_playlistcontainer_move_playlist | ( | sp_playlistcontainer * | pc, | |
| int | index, | |||
| int | new_position, | |||
| bool | dry_run | |||
| ) |
Move a playlist in the playlist container
| [in] | pc | Playlist container |
| [in] | index | Index of playlist to be moved |
| [in] | new_position | New position for the playlist |
| [in] | dry_run | Do not execute the move, only check if it possible |
| int sp_playlistcontainer_num_playlists | ( | sp_playlistcontainer * | pc | ) |
Return the number of playlists in the given playlist container
| [in] | pc | Playlist container |
| sp_user* sp_playlistcontainer_owner | ( | sp_playlistcontainer * | pc | ) |
Return a pointer to the user object of the owner.
| [in] | pc | Playlist container. |
| sp_playlist* sp_playlistcontainer_playlist | ( | sp_playlistcontainer * | pc, | |
| int | index | |||
| ) |
Return a pointer to the playlist at a specific index
| [in] | pc | Playlist container |
| [in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
| sp_uint64 sp_playlistcontainer_playlist_folder_id | ( | sp_playlistcontainer * | pc, | |
| int | index | |||
| ) |
Return the folder id at index
| [in] | pc | Playlist container |
| [in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
| sp_error sp_playlistcontainer_playlist_folder_name | ( | sp_playlistcontainer * | pc, | |
| int | index, | |||
| char * | buffer, | |||
| int | buffer_size | |||
| ) |
Return the folder name at index
| [in] | pc | Playlist container |
| [in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]. Index should point at a start-folder entry, otherwise the empty string is written to buffer. |
| [in] | buffer | Pointer to char[] where to store folder name |
| [in] | buffer_size | Size of array |
| sp_playlist_type sp_playlistcontainer_playlist_type | ( | sp_playlistcontainer * | pc, | |
| int | index | |||
| ) |
Return the type of the playlist at a index
| [in] | pc | Playlist container |
| [in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
| sp_error sp_playlistcontainer_release | ( | sp_playlistcontainer * | pc | ) |
Release reference count on playlistconatiner object
| [in] | pc | Playlist container. |
| sp_error sp_playlistcontainer_remove_callbacks | ( | sp_playlistcontainer * | pc, | |
| sp_playlistcontainer_callbacks * | callbacks, | |||
| void * | userdata | |||
| ) |
Unregister interest in changes to a playlist container
| [in] | pc | Playlist container |
| [in] | callbacks | Callbacks, see sp_playlistcontainer_callbacks |
| [in] | userdata | Opaque value passed to callbacks. |
| sp_error sp_playlistcontainer_remove_playlist | ( | sp_playlistcontainer * | pc, | |
| int | index | |||
| ) |
Remove playlist at index from the given playlist container
| [in] | pc | Playlist container |
| [in] | index | Index of playlist to be removed |