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'
Whether the playlist’s data is loaded.
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.
The playlist’s tracks.
Will always return an empty list if the playlist isn’t loaded.
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.
The playlist’s name.
Assigning to name will rename the playlist.
Will always return None if the playlist isn’t loaded.
Rename the playlist.
Whether the playlist can be modified by all users or not.
Set to True or False to change.
If a playlist is autolinked, unplayable tracks will be made playable by linking them to other Spotify tracks, where possible.
The playlist’s description.
Will return None if the description is unset.
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.
Check if the playlist has local changes that has not been acknowledged by the server yet.
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 the tracks at the given indexes from the playlist.
indexes can be a single index or a list of indexes to remove.
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.
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.
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.
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.
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.
Control whether or not to keep the playlist in RAM.
See is_in_ram for further details.
Mark the playlist to be synchronized for offline playback.
The playlist must be in the current user’s playlist container.
The playlist’s PlaylistOfflineStatus.
The download progress for an offline playlist.
A number in the range 0-100. Always None if offline_status isn’t PlaylistOfflineStatus.DOWNLOADING.
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.
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()
Return the number of listeners for event.
Return the total number of listeners for all events on this object if event is None.
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.
Called when one or more tracks have been added to the playlist.
Parameters: |
---|
Called when one or more tracks have been removed from the playlist.
Parameters: |
|
---|
Called when one or more tracks have been moved within a playlist.
Parameters: |
|
---|
Called when the playlist has been renamed.
Parameters: | playlist (Playlist) – the playlist |
---|
Called when the state changed for a playlist.
There are three states that trigger this callback:
Parameters: | playlist (Playlist) – the playlist |
---|
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: |
|
---|
Called when metadata for one or more tracks in the playlist have been updated.
Parameters: | playlist (Playlist) – the playlist |
---|
Called when the create time and/or creator for a playlist entry changes.
Parameters: |
---|
Called when the seen attribute of a playlist entry changes.
Parameters: |
|
---|
Called when the playlist description has changed.
Parameters: |
|
---|
Called when the playlist image has changed.
Parameters: |
---|
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
Whether the playlist container’s data is loaded.
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 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 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 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 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 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.
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.
Clears unseen tracks from the given playlist.
S.append(object) – append object to the end of the sequence
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.
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()
S.extend(iterable) – extend sequence by appending elements from the iterable
Raises ValueError if the value is not present.
Return the number of listeners for event.
Return the total number of listeners for all events on this object if event is None.
Raise IndexError if list is empty or index is out of range.
S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.
S.reverse() – reverse IN PLACE
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.
Called when a playlist is added to the container.
Parameters: |
|
---|
Called when a playlist is removed from the container.
Parameters: |
|
---|
Called when a playlist is moved in the container.
Parameters: |
|
---|
Called when the playlist container is loaded.
Parameters: | playlist_container (PlaylistContainer) – the playlist container |
---|
An object marking the start or end of a playlist folder.
An opaque ID that matches the ID of the PlaylistFolder object at the other end of the folder.
Name of the playlist folder. This is an empty string for the END_FOLDER.
The PlaylistType of the folder. Either START_FOLDER or END_FOLDER.
An object marking an unknown entry in the playlist container.
A playlist track with metadata specific to the playlist.
Use tracks_with_metadata to get a list of PlaylistTrack.
When the track was added to the playlist, as seconds since Unix epoch.
Whether the track is marked as seen or not.
A message attached to the track. Typically used in the inbox.
A list of unseen tracks in a playlist.
The list may contain items that are None.
Returned by PlaylistContainer.get_unseen_tracks().
Raises ValueError if the value is not present.