Playlists¶
Warning
The playlists API was broken at 2018-05-24 by a server-side change made by Spotify. The functionality was never restored.
Please use the Spotify Web API to work with playlists.
-
class
spotify.
Playlist
(session, uri=None, sp_playlist=None, add_ref=True)[source]¶ 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'
-
is_loaded
¶ Whether the playlist’s data is loaded.
-
load
(timeout=None)[source]¶ Block until the playlist’s data is loaded.
After
timeout
seconds with no resultsTimeout
is raised. Iftimeout
isNone
the default timeout is used.The method returns
self
to allow for chaining of calls.
-
tracks
¶ The playlist’s tracks.
Will always return an empty list if the playlist isn’t loaded.
-
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.
-
name
¶ The playlist’s name.
Assigning to
name
will rename the playlist.Will always return
None
if the playlist isn’t loaded.
-
collaborative
¶ Whether the playlist can be modified by all users or not.
Set to
True
orFalse
to change.
-
set_autolink_tracks
(link=True)[source]¶ If a playlist is autolinked, unplayable tracks will be made playable by linking them to other Spotify tracks, where possible.
-
description
¶ The playlist’s description.
Will return
None
if the description is unset.
-
image
(callback=None)[source]¶ The playlist’s
Image
.Due to limitations in libspotify’s API you can’t specify the
ImageSize
of these images.If
callback
isn’tNone
, it is expected to be a callable that accepts a single argument, anImage
instance, when the image is done loading.Will always return
None
if the playlist isn’t loaded or the playlist has no image.
-
has_pending_changes
¶ Check if the playlist has local changes that has not been acknowledged by the server yet.
-
add_tracks
(tracks, index=None)[source]¶ Add the given
tracks
to playlist at the givenindex
.tracks
can either be a singleTrack
or a list ofTrack
objects. Ifindex
isn’t specified, the tracks are added to the end of the playlist.
-
remove_tracks
(indexes)[source]¶ 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)[source]¶ Move the tracks at the given
indexes
to anew_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.
-
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 theSUBSCRIBERS_CHANGED
event is emitted from the playlist.
-
subscribers
¶ The canonical usernames of up to 500 of the subscribers of the playlist.
May be empty until you call
update_subscribers()
and theSUBSCRIBERS_CHANGED
event is emitted from the playlist.
-
update_subscribers
()[source]¶ Request an update of
num_subscribers
and thesubscribers
collection.The
SUBSCRIBERS_CHANGED
event is emitted from the playlist when the subscriber data has been updated.
-
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 toTrue
before creating theSession
. If the playlists are initially unloaded, useset_in_ram()
to have a playlist loaded into RAM.
-
set_in_ram
(in_ram=True)[source]¶ Control whether or not to keep the playlist in RAM.
See
is_in_ram
for further details.
-
set_offline_mode
(offline=True)[source]¶ Mark the playlist to be synchronized for offline playback.
The playlist must be in the current user’s playlist container.
-
offline_status
¶ The playlist’s
PlaylistOfflineStatus
.
-
offline_download_completed
¶ The download progress for an offline playlist.
A number in the range 0-100. Always
None
ifoffline_status
isn’tPlaylistOfflineStatus.DOWNLOADING
.
-
on
(event, listener, *user_args)[source]¶ Register a
listener
to be called onevent
.The listener will be called with any extra arguments passed to
emit()
first, and then the extra arguments passed toon()
last.If the listener function returns
False
, it is removed and will not be called the next time theevent
is emitted.
-
off
(event=None, listener=None)[source]¶ Remove a
listener
that was to be called onevent
.If
listener
isNone
, all listeners for the givenevent
will be removed.If
event
isNone
, 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 toon()
Raises
AssertionError
if there is none or multiple listeners forevent
. 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 toon()
-
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
isNone
.
-
-
class
spotify.
PlaylistEvent
[source]¶ 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:
-
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
- playlist (
-
TRACKS_MOVED
= 'tracks_moved'¶ Called when one or more tracks have been moved within a playlist.
Parameters:
-
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- Collaboration for this playlist has been turned on or off. See
-
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_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:
-
TRACK_SEEN_CHANGED
= 'track_seen_changed'¶ Called when the seen attribute of a playlist entry changes.
Parameters:
-
DESCRIPTION_CHANGED
= 'description_changed'¶ Called when the playlist description has changed.
Parameters: - playlist (
Playlist
) – the playlist - description (string) – the new description
- playlist (
-
IMAGE_CHANGED
= 'image_changed'¶ Called when the playlist image has changed.
Parameters:
-
TRACK_MESSAGE_CHANGED
= 'track_message_changed'¶ Called when the message attribute of a playlist entry changes.
Parameters:
-
-
class
spotify.
PlaylistContainer
(session, sp_playlistcontainer, add_ref=True)[source]¶ 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
andPlaylistFolder
objects.The container supports operations that changes the container as well.
To add a playlist you can use
append()
orinsert()
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()
andadd_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()
andadd_playlist()
, or:>>> container[0] = playlist
-
is_loaded
¶ Whether the playlist container’s data is loaded.
-
load
(timeout=None)[source]¶ Block until the playlist container’s data is loaded.
After
timeout
seconds with no resultsTimeout
is raised. Iftimeout
isNone
the default timeout is used.The method returns
self
to allow for chaining of calls.
-
add_new_playlist
(name, index=None)[source]¶ Add an empty playlist with
name
at the givenindex
.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)[source]¶ Add an existing
playlist
to the playlist container at the givenindex
.The playlist can either be a
Playlist
, or aLink
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 givenindex
.
-
add_folder
(name, index=None)[source]¶ Add a playlist folder with
name
at the givenindex
.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)[source]¶ 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. Ifrecursive
isTrue
, the folder content is removed as well.Using
del playlist_container[3]
is equivalent toplaylist_container.remove_playlist(3)
. Similarly,del playlist_container[0:2]
is equivalent to calling this method with indexes1
and0
.
-
move_playlist
(from_index, to_index, dry_run=False)[source]¶ Move playlist at
from_index
toto_index
.If
dry_run
isTrue
the move isn’t actually done. It is only checked if the move is possible.
-
get_unseen_tracks
(playlist)[source]¶ 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.
-
on
(event, listener, *user_args)[source]¶ Register a
listener
to be called onevent
.The listener will be called with any extra arguments passed to
emit()
first, and then the extra arguments passed toon()
last.If the listener function returns
False
, it is removed and will not be called the next time theevent
is emitted.
-
off
(event=None, listener=None)[source]¶ Remove a
listener
that was to be called onevent
.If
listener
isNone
, all listeners for the givenevent
will be removed.If
event
isNone
, 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 toon()
Raises
AssertionError
if there is none or multiple listeners forevent
. 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 toon()
-
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
isNone
.
-
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
[source]¶ 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_container (
-
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_container (
-
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
- playlist_container (
-
CONTAINER_LOADED
= 'container_loaded'¶ Called when the playlist container is loaded.
Parameters: playlist_container ( PlaylistContainer
) – the playlist container
-
-
class
spotify.
PlaylistFolder
[source]¶ 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. EitherSTART_FOLDER
orEND_FOLDER
.
-
-
class
spotify.
PlaylistPlaceholder
[source]¶ An object marking an unknown entry in the playlist container.
-
class
spotify.
PlaylistTrack
(session, sp_playlist, index)[source]¶ A playlist track with metadata specific to the playlist.
Use
tracks_with_metadata
to get a list ofPlaylistTrack
.-
create_time
¶ When the track was added to the playlist, as seconds since Unix epoch.
-
seen
¶ Whether the track is marked as seen or not.
-
message
¶ A message attached to the track. Typically used in the inbox.
-
-
class
spotify.
PlaylistUnseenTracks
(session, sp_playlistcontainer, sp_playlist)[source]¶ 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.
-