Playlists

class spotify.Playlist(session, uri=None, sp_playlist=None, add_ref=True)

A Spotify playlist.

You can get playlists from the playlist_container, inbox, get_starred(), search(), etc., or you can create a playlist yourself from a Spotify URI:

>>> session = spotify.Session()
# ...
>>> playlist = session.get_playlist(
...     'spotify:user:fiat500c:playlist:54k50VZdvtnIPt4d8RBCmZ')
>>> playlist.load().name
u'500C feelgood playlist'

property is_loaded

Whether the playlist’s data is loaded.

load(timeout=None)

Block until the playlist’s data is loaded.

After timeout seconds with no results Timeout is raised. If timeout is None the default timeout is used.

The method returns self to allow for chaining of calls.

property tracks

The playlist’s tracks.

Will always return an empty list if the playlist isn’t loaded.

property tracks_with_metadata

The playlist’s tracks, with metadata specific to the playlist as a a list of PlaylistTrack objects.

Will always return an empty list if the playlist isn’t loaded.

property name

The playlist’s name.

Assigning to name will rename the playlist.

Will always return None if the playlist isn’t loaded.

rename(new_name)

Rename the playlist.

property owner

The User object for the owner of the playlist.

property collaborative

Whether the playlist can be modified by all users or not.

Set to True or False to change.

set_autolink_tracks(link=True)

If a playlist is autolinked, unplayable tracks will be made playable by linking them to other Spotify tracks, where possible.

property description

The playlist’s description.

Will return None if the description is unset.

image(callback=None)

The playlist’s Image.

Due to limitations in libspotify’s API you can’t specify the ImageSize of these images.

If callback isn’t None, it is expected to be a callable that accepts a single argument, an Image instance, when the image is done loading.

Will always return None if the playlist isn’t loaded or the playlist has no image.

property has_pending_changes

Check if the playlist has local changes that has not been acknowledged by the server yet.

add_tracks(tracks, index=None)

Add the given tracks to playlist at the given index.

tracks can either be a single Track or a list of Track objects. If index isn’t specified, the tracks are added to the end of the playlist.

remove_tracks(indexes)

Remove the tracks at the given indexes from the playlist.

indexes can be a single index or a list of indexes to remove.

reorder_tracks(indexes, new_index)

Move the tracks at the given indexes to a new_index in the playlist.

indexes can be a single index or a list of indexes to move.

new_index must be equal to or lower than the current playlist length.

property num_subscribers

The number of subscribers to the playlist.

The number can be higher than the length of the subscribers collection, especially if the playlist got many subscribers.

May be zero until you call update_subscribers() and the SUBSCRIBERS_CHANGED event is emitted from the playlist.

property subscribers

The canonical usernames of up to 500 of the subscribers of the playlist.

May be empty until you call update_subscribers() and the SUBSCRIBERS_CHANGED event is emitted from the playlist.

update_subscribers()

Request an update of num_subscribers and the subscribers collection.

The SUBSCRIBERS_CHANGED event is emitted from the playlist when the subscriber data has been updated.

property is_in_ram

Whether the playlist is in RAM, and not only on disk.

A playlist must currently be in RAM for tracks to be available. A playlist must have been in RAM for other metadata to be available.

By default, playlists are kept in RAM unless initially_unload_playlists is set to True before creating the Session. If the playlists are initially unloaded, use set_in_ram() to have a playlist loaded into RAM.

set_in_ram(in_ram=True)

Control whether or not to keep the playlist in RAM.

See is_in_ram for further details.

set_offline_mode(offline=True)

Mark the playlist to be synchronized for offline playback.

The playlist must be in the current user’s playlist container.

property offline_status

The playlist’s PlaylistOfflineStatus.

property offline_download_completed

The download progress for an offline playlist.

A number in the range 0-100. Always None if offline_status isn’t PlaylistOfflineStatus.DOWNLOADING.

property link

A Link to the playlist.

on(event, listener, *user_args)

Register a listener to be called on event.

The listener will be called with any extra arguments passed to emit() first, and then the extra arguments passed to on() last.

If the listener function returns False, it is removed and will not be called the next time the event is emitted.

off(event=None, listener=None)

Remove a listener that was to be called on event.

If listener is None, all listeners for the given event will be removed.

If event is None, all listeners for all events on this object will be removed.

call(event, *event_args)

Call the single registered listener for event.

The listener will be called with any extra arguments passed to call() first, and then the extra arguments passed to on()

Raises AssertionError if there is none or multiple listeners for event. Returns the listener’s return value on success.

emit(event, *event_args)

Call the registered listeners for event.

The listeners will be called with any extra arguments passed to emit() first, and then the extra arguments passed to on()

num_listeners(event=None)

Return the number of listeners for event.

Return the total number of listeners for all events on this object if event is None.

class spotify.PlaylistEvent

Playlist events.

Using Playlist objects, you can register listener functions to be called when various events occurs in the playlist. This class enumerates the available events and the arguments your listener functions will be called with.

Example usage:

import spotify

def tracks_added(playlist, tracks, index):
    print('Tracks added to playlist')

session = spotify.Session()
# Login, etc...

playlist = session.playlist_container[0]
playlist.on(spotify.PlaylistEvent.TRACKS_ADDED, tracks_added)

All events will cause debug log statements to be emitted, even if no listeners are registered. Thus, there is no need to register listener functions just to log that they’re called.

TRACKS_ADDED = 'tracks_added'

Called when one or more tracks have been added to the playlist.

Parameters

• playlist (Playlist) – the playlist

• tracks (list of Track) – the added tracks

• index (int) – the index in the playlist the tracks were added at

TRACKS_REMOVED = 'tracks_removed'

Called when one or more tracks have been removed from the playlist.

Parameters

• playlist (Playlist) – the playlist

• indexes (list of ints) – indexes of the tracks that were removed

TRACKS_MOVED = 'tracks_moved'

Called when one or more tracks have been moved within a playlist.

Parameters

• playlist (Playlist) – the playlist

• old_indexes (list of ints) – old indexes of the tracks that were moved

• new_index (int) – the new index in the playlist the tracks were moved to

PLAYLIST_RENAMED = 'playlist_renamed'

Called when the playlist has been renamed.

Parameters

playlist (Playlist) – the playlist

PLAYLIST_STATE_CHANGED = 'playlist_state_changed'

Called when the state changed for a playlist.

There are three states that trigger this callback:

• Collaboration for this playlist has been turned on or off. See Playlist.is_collaborative().

• The playlist started having pending changes, or all pending changes have now been committed. See Playlist.has_pending_changes.

• The playlist started loading, or finished loading. See Playlist.is_loaded.

Parameters

playlist (Playlist) – the playlist

PLAYLIST_UPDATE_IN_PROGRESS = 'playlist_update_in_progress'

Called when a playlist is updating or is done updating.

This is called before and after a series of changes are applied to the playlist. It allows e.g. the user interface to defer updating until the entire operation is complete.

Parameters

• playlist (Playlist) – the playlist

• done (bool) – if the update is completed

PLAYLIST_METADATA_UPDATED = 'playlist_metadata_updated'

Called when metadata for one or more tracks in the playlist have been updated.

Parameters

playlist (Playlist) – the playlist

TRACK_CREATED_CHANGED = 'track_created_changed'

Called when the create time and/or creator for a playlist entry changes.

Parameters

• playlist (Playlist) – the playlist

• index (int) – the index of the entry in the playlist that was changed

• user (User) – the user that created the playlist entry

• time (int) – the time the entry was created, in seconds since Unix epoch

TRACK_SEEN_CHANGED = 'track_seen_changed'

Called when the seen attribute of a playlist entry changes.

Parameters

• playlist (Playlist) – the playlist

• index (int) – the index of the entry in the playlist that was changed

• seen (bool) – whether the entry is seen or not

DESCRIPTION_CHANGED = 'description_changed'

Called when the playlist description has changed.

Parameters

• playlist (Playlist) – the playlist

• description (string) – the new description

IMAGE_CHANGED = 'image_changed'

Called when the playlist image has changed.

Parameters

• playlist (Playlist) – the playlist

• image (Image) – the new image

TRACK_MESSAGE_CHANGED = 'track_message_changed'

Called when the message attribute of a playlist entry changes.

Parameters

• playlist (Playlist) – the playlist

• index (int) – the index of the entry in the playlist that was changed

• message (string) – the new message

SUBSCRIBERS_CHANGED = 'subscribers_changed'

Called when playlist subscribers changes, either the count or the subscriber names.

Parameters

playlist (Playlist) – the playlist

class spotify.PlaylistContainer(session, sp_playlistcontainer, add_ref=True)

A Spotify playlist container.

The playlist container can be accessed as a regular Python collection to work with the playlists:

>>> import spotify
>>> session = spotify.Session()
# Login, etc.
>>> container = session.playlist_container
>>> container.is_loaded
False
>>> container.load()
[Playlist(u'spotify:user:jodal:playlist:6xkJysqhkj9uwufFbUb8sP'),
 Playlist(u'spotify:user:jodal:playlist:0agJjPcOhHnstLIQunJHxo'),
 PlaylistFolder(id=8027491506140518932L, name=u'Shared playlists',
    type=<PlaylistType.START_FOLDER: 1>),
 Playlist(u'spotify:user:p3.no:playlist:7DkMndS2KNVQuf2fOpMt10'),
 PlaylistFolder(id=8027491506140518932L, name=u'',
    type=<PlaylistType.END_FOLDER: 2>)]
>>> container[0]
Playlist(u'spotify:user:jodal:playlist:6xkJysqhkj9uwufFbUb8sP')

As you can see, a playlist container can contain a mix of Playlist and PlaylistFolder objects.

The container supports operations that changes the container as well.

To add a playlist you can use append() or insert() with either the name of a new playlist or an existing playlist object. For example:

>>> playlist = session.get_playlist(
...     'spotify:user:fiat500c:playlist:54k50VZdvtnIPt4d8RBCmZ')
>>> container.insert(3, playlist)
>>> container.append('New empty playlist')

To remove a playlist or folder you can use remove_playlist(), or:

>>> del container[0]

To replace an existing playlist or folder with a new empty playlist with the given name you can use remove_playlist() and add_new_playlist(), or:

>>> container[0] = 'My other new empty playlist'

To replace an existing playlist or folder with an existing playlist you can :use remove_playlist() and add_playlist(), or:

>>> container[0] = playlist

property is_loaded

Whether the playlist container’s data is loaded.

load(timeout=None)

Block until the playlist container’s data is loaded.

After timeout seconds with no results Timeout is raised. If timeout is None the default timeout is used.

The method returns self to allow for chaining of calls.

add_new_playlist(name, index=None)

Add an empty playlist with name at the given index.

The playlist name must not be space-only or longer than 255 chars.

If the index isn’t specified, the new playlist is added at the end of the container.

Returns the new playlist.

add_playlist(playlist, index=None)

Add an existing playlist to the playlist container at the given index.

The playlist can either be a Playlist, or a Link linking to a playlist.

If the index isn’t specified, the playlist is added at the end of the container.

Returns the added playlist, or None if the playlist already existed in the container. If the playlist already exists, it will not be moved to the given index.

add_folder(name, index=None)

Add a playlist folder with name at the given index.

The playlist folder name must not be space-only or longer than 255 chars.

If the index isn’t specified, the folder is added at the end of the container.

remove_playlist(index, recursive=False)

Remove playlist at the given index from the container.

If the item at the given index is the start or the end of a playlist folder, and the other end of the folder is found, it is also removed. The folder content is kept, but is moved one level up the folder hierarchy. If recursive is True, the folder content is removed as well.

Using del playlist_container[3] is equivalent to playlist_container.remove_playlist(3). Similarly, del playlist_container[0:2] is equivalent to calling this method with indexes 1 and 0.

move_playlist(from_index, to_index, dry_run=False)

Move playlist at from_index to to_index.

If dry_run is True the move isn’t actually done. It is only checked if the move is possible.

property owner

The User object for the owner of the playlist container.

get_unseen_tracks(playlist)

Get a list of unseen tracks in the given playlist.

The list is a PlaylistUnseenTracks instance.

The tracks will remain “unseen” until clear_unseen_tracks() is called on the playlist.

clear_unseen_tracks(playlist)

Clears unseen tracks from the given playlist.

insert(index, value)

S.insert(index, value) – insert value before index

on(event, listener, *user_args)

Register a listener to be called on event.

The listener will be called with any extra arguments passed to emit() first, and then the extra arguments passed to on() last.

If the listener function returns False, it is removed and will not be called the next time the event is emitted.

off(event=None, listener=None)

Remove a listener that was to be called on event.

If listener is None, all listeners for the given event will be removed.

If event is None, all listeners for all events on this object will be removed.

append(value)

S.append(value) – append value to the end of the sequence

call(event, *event_args)

Call the single registered listener for event.

The listener will be called with any extra arguments passed to call() first, and then the extra arguments passed to on()

Raises AssertionError if there is none or multiple listeners for event. Returns the listener’s return value on success.

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

emit(event, *event_args)

Call the registered listeners for event.

The listeners will be called with any extra arguments passed to emit() first, and then the extra arguments passed to on()

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

num_listeners(event=None)

Return the number of listeners for event.

Return the total number of listeners for all events on this object if event is None.

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class spotify.PlaylistContainerEvent

Playlist container events.

Using PlaylistContainer objects, you can register listener functions to be called when various events occurs in the playlist container. This class enumerates the available events and the arguments your listener functions will be called with.

Example usage:

import spotify

def container_loaded(playlist_container):
    print('Playlist container loaded')

session = spotify.Session()
# Login, etc...

session.playlist_container.on(
    spotify.PlaylistContainerEvent.CONTAINER_LOADED, container_loaded)

All events will cause debug log statements to be emitted, even if no listeners are registered. Thus, there is no need to register listener functions just to log that they’re called.

PLAYLIST_ADDED = 'playlist_added'

Called when a playlist is added to the container.

Parameters

• playlist_container (PlaylistContainer) – the playlist container

• playlist (Playlist) – the added playlist

• index (int) – the index the playlist was added at

PLAYLIST_REMOVED = 'playlist_removed'

Called when a playlist is removed from the container.

Parameters

• playlist_container (PlaylistContainer) – the playlist container

• playlist (Playlist) – the removed playlist

• index (int) – the index the playlist was removed from

PLAYLIST_MOVED = 'playlist_moved'

Called when a playlist is moved in the container.

Parameters

• playlist_container (PlaylistContainer) – the playlist container

• playlist (Playlist) – the moved playlist

• old_index (int) – the index the playlist was moved from

• new_index (int) – the index the playlist was moved to

CONTAINER_LOADED = 'container_loaded'

Called when the playlist container is loaded.

Parameters

playlist_container (PlaylistContainer) – the playlist container

class spotify.PlaylistFolder

An object marking the start or end of a playlist folder.

id

An opaque ID that matches the ID of the PlaylistFolder object at the other end of the folder.

name

Name of the playlist folder. This is an empty string for the END_FOLDER.

type

The PlaylistType of the folder. Either START_FOLDER or END_FOLDER.

class spotify.PlaylistOfflineStatus

class spotify.PlaylistPlaceholder

An object marking an unknown entry in the playlist container.

class spotify.PlaylistTrack(session, sp_playlist, index)

A playlist track with metadata specific to the playlist.

Use tracks_with_metadata to get a list of PlaylistTrack.

property track

The Track.

property create_time

When the track was added to the playlist, as seconds since Unix epoch.

property creator

The User that added the track to the playlist.

is_seen()

set_seen(value)

property seen

Whether the track is marked as seen or not.

property message

A message attached to the track. Typically used in the inbox.

class spotify.PlaylistType

class spotify.PlaylistUnseenTracks(session, sp_playlistcontainer, sp_playlist)

A list of unseen tracks in a playlist.

The list may contain items that are None.

Returned by PlaylistContainer.get_unseen_tracks().

count(value) → integer -- return number of occurrences of value

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.