pyechonest.playlist
index
http://pyechonest.googlecode.com/svn/trunk/doc/playlist.py

Copyright (c) 2010 The Echo Nest. All rights reserved.
Created by Tyler Williams on 2010-04-25.
 
The Playlist module loosely covers http://developer.echonest.com/docs/v4/playlist.html
Refer to the official api documentation if you are unsure about something.

 
Modules
       
pyechonest.catalog
pyechonest.util

 
Classes
       
pyechonest.proxies.PlaylistProxy(pyechonest.proxies.GenericProxy)
Playlist

 
class Playlist(pyechonest.proxies.PlaylistProxy)
    A Dynamic Playlist object
 
Attributes:
    session_id: Playlist Session ID
    song: The current song
 
Example:
    >>> p = Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
    >>> p
    <Dynamic Playlist - 9c210205d4784144b4fa90770fa55d0b>
    >>> p.song
    <song - Later On>
    >>> p.get_next_song()
    <song - Overall>
    >>>
 
 
Method resolution order:
Playlist
pyechonest.proxies.PlaylistProxy
pyechonest.proxies.GenericProxy
__builtin__.object

Methods defined here:
__init__(self, session_id=None, type='artist', artist_pick='song_hotttnesss-desc', variety=0.5, artist_id=None, artist=None, song_id=None, description=None, max_tempo=None, min_tempo=None, max_duration=None, min_duration=None, max_loudness=None, min_loudness=None, max_danceability=None, min_danceability=None, max_energy=None, min_energy=None, artist_max_familiarity=None, artist_min_familiarity=None, artist_max_hotttnesss=None, artist_min_hotttnesss=None, song_max_hotttnesss=None, song_min_hotttnesss=None, min_longitude=None, max_longitude=None, min_latitude=None, max_latitude=None, mode=None, key=None, buckets=[], sort=None, limit=False, dmca=False, audio=False, chain_xspf=False, seed_catalog=None, steer=None, source_catalog=None, steer_description=None)
Args:
 
Kwargs:
    type (str): a string representing the playlist type ('artist', 'artist-radio', ...)
 
    artist_pick (str): How songs should be chosen for each artist
 
    variety (float): A number between 0 and 1 specifying the variety of the playlist
 
    artist_id (str): the artist_id
 
    artist (str): the name of an artist
 
    song_id (str): the song_id
 
    description (str): A string describing the artist and song
 
    results (int): An integer number of results to return
 
    max_tempo (float): The max tempo of song results
 
    min_tempo (float): The min tempo of song results
 
    max_duration (float): The max duration of song results
 
    min_duration (float): The min duration of song results
 
    max_loudness (float): The max loudness of song results
 
    min_loudness (float): The min loudness of song results
 
    artist_max_familiarity (float): A float specifying the max familiarity of artists to search for
 
    artist_min_familiarity (float): A float specifying the min familiarity of artists to search for
 
    artist_max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
 
    artist_min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
 
    song_max_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
 
    song_min_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
 
    max_energy (float): The max energy of song results
 
    min_energy (float): The min energy of song results
 
    max_dancibility (float): The max dancibility of song results
 
    min_dancibility (float): The min dancibility of song results
 
    mode (int): 0 or 1 (minor or major)
 
    key (int): 0-11 (c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b)
 
    max_latitude (float): A float specifying the max latitude of artists to search for
 
    min_latitude (float): A float specifying the min latitude of artists to search for
 
    max_longitude (float): A float specifying the max longitude of artists to search for
 
    min_longitude (float): A float specifying the min longitude of artists to search for                        
 
    sort (str): A string indicating an attribute and order for sorting the results
 
    buckets (list): A list of strings specifying which buckets to retrieve
 
    limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
 
    seed_catalog (str or Catalog): A Catalog object or catalog id to use as a seed
    
    source_catalog (str or Catalog): A Catalog object or catalog id
    
    steer (str): A steering value to determine the target song attributes
    
    steer_description (str): A steering value to determine the target song description term attributes
    
 
Returns:
    A dynamic playlist object
__repr__(self)
get_current_song(self)
Get the current song in the playlist
 
Args:
 
Kwargs:
 
Returns:
    A song object
 
Example:
 
>>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p.song
<song - Later On>
>>> p.get_current_song()
<song - Later On>
>>>
get_next_song(self, **kwargs)
Get the next song in the playlist
 
Args:
 
Kwargs:
 
Returns:
    A song object
 
Example:
 
>>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p.get_next_song()
<song - She Said>
>>>
session_info(self)
Get information about the playlist
 
Args:
 
Kwargs:
 
Returns:
    A dict with diagnostic information about the currently running playlist
 
Example:
 
>>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p.info
 
{
    u 'terms': [{
        u 'frequency': 1.0,
        u 'name': u 'rock'
    },
    {
        u 'frequency': 0.99646542152360207,
        u 'name': u 'pop'
    },
    {
        u 'frequency': 0.90801905502131963,
        u 'name': u 'indie'
    },
    {
        u 'frequency': 0.90586455490260576,
        u 'name': u 'indie rock'
    },
    {
        u 'frequency': 0.8968907243373172,
        u 'name': u 'alternative'
    },
    [...]
    {
        u 'frequency': 0.052197425644931635,
        u 'name': u 'easy listening'
    }],
    u 'description': [],
    u 'seed_songs': [],
    u 'banned_artists': [],
    u 'rules': [{
        u 'rule': u "Don't put two copies of the same song in a playlist."
    },
    {
        u 'rule': u 'Give preference to artists that are not already in the playlist'
    }],
    u 'session_id': u '9c1893e6ace04c8f9ce745f38b35ff95',
    u 'seeds': [u 'ARI4XHX1187B9A1216', u 'ARNCHOP121318C56B8'],
    u 'skipped_songs': [],
    u 'banned_songs': [],
    u 'playlist_type': u 'artist-radio',
    u 'seed_catalogs': [],
    u 'rated_songs': [],
    u 'history': [{
        u 'artist_id': u 'ARN6QMG1187FB56C8D',
        u 'artist_name': u 'Laura Marling',
        u 'id': u 'SOMSHNP12AB018513F',
        u 'served_time': 1291412277.204201,
        u 'title': u 'Hope In The Air'
    }]
}
 
>>> p.session_info()
(same result as above)
>>>

Data descriptors defined here:
info
Get information about the playlist
 
Args:
 
Kwargs:
 
Returns:
    A dict with diagnostic information about the currently running playlist
 
Example:
 
>>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p.info
 
{
    u 'terms': [{
        u 'frequency': 1.0,
        u 'name': u 'rock'
    },
    {
        u 'frequency': 0.99646542152360207,
        u 'name': u 'pop'
    },
    {
        u 'frequency': 0.90801905502131963,
        u 'name': u 'indie'
    },
    {
        u 'frequency': 0.90586455490260576,
        u 'name': u 'indie rock'
    },
    {
        u 'frequency': 0.8968907243373172,
        u 'name': u 'alternative'
    },
    [...]
    {
        u 'frequency': 0.052197425644931635,
        u 'name': u 'easy listening'
    }],
    u 'description': [],
    u 'seed_songs': [],
    u 'banned_artists': [],
    u 'rules': [{
        u 'rule': u "Don't put two copies of the same song in a playlist."
    },
    {
        u 'rule': u 'Give preference to artists that are not already in the playlist'
    }],
    u 'session_id': u '9c1893e6ace04c8f9ce745f38b35ff95',
    u 'seeds': [u 'ARI4XHX1187B9A1216', u 'ARNCHOP121318C56B8'],
    u 'skipped_songs': [],
    u 'banned_songs': [],
    u 'playlist_type': u 'artist-radio',
    u 'seed_catalogs': [],
    u 'rated_songs': [],
    u 'history': [{
        u 'artist_id': u 'ARN6QMG1187FB56C8D',
        u 'artist_name': u 'Laura Marling',
        u 'id': u 'SOMSHNP12AB018513F',
        u 'served_time': 1291412277.204201,
        u 'title': u 'Hope In The Air'
    }]
}
 
>>> p.session_info()
(same result as above)
>>>
song
Get the current song in the playlist
 
Args:
 
Kwargs:
 
Returns:
    A song object
 
Example:
 
>>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p.song
<song - Later On>
>>> p.get_current_song()
<song - Later On>
>>>

Methods inherited from pyechonest.proxies.PlaylistProxy:
get_attribute(self, *args, **kwargs)

Methods inherited from pyechonest.proxies.GenericProxy:
post_attribute(self, method_name, **kwargs)

Data descriptors inherited from pyechonest.proxies.GenericProxy:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
static(type='artist', artist_pick='song_hotttnesss-desc', variety=0.5, artist_id=None, artist=None, song_id=None, description=None, results=15, max_tempo=None, min_tempo=None, max_duration=None, min_duration=None, max_loudness=None, min_loudness=None, max_danceability=None, min_danceability=None, max_energy=None, min_energy=None, artist_max_familiarity=None, artist_min_familiarity=None, artist_max_hotttnesss=None, artist_min_hotttnesss=None, song_max_hotttnesss=None, song_min_hotttnesss=None, min_longitude=None, max_longitude=None, min_latitude=None, max_latitude=None, mode=None, key=None, buckets=[], sort=None, limit=False, seed_catalog=None, source_catalog=None)
Get a static playlist
 
Args:
 
Kwargs:
    type (str): a string representing the playlist type ('artist', 'artist-radio', ...)
    
    artist_pick (str): How songs should be chosen for each artist
    
    variety (float): A number between 0 and 1 specifying the variety of the playlist
    
    artist_id (str): the artist_id
    
    artist (str): the name of an artist
    
    song_id (str): the song_id
 
    description (str): A string describing the artist and song
 
    results (int): An integer number of results to return
 
    max_tempo (float): The max tempo of song results
 
    min_tempo (float): The min tempo of song results
 
    max_duration (float): The max duration of song results
 
    min_duration (float): The min duration of song results
 
    max_loudness (float): The max loudness of song results
 
    min_loudness (float): The min loudness of song results
 
    artist_max_familiarity (float): A float specifying the max familiarity of artists to search for
 
    artist_min_familiarity (float): A float specifying the min familiarity of artists to search for
 
    artist_max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
 
    artist_min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
 
    song_max_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
 
    song_min_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
 
    max_energy (float): The max energy of song results
 
    min_energy (float): The min energy of song results
 
    max_dancibility (float): The max dancibility of song results
 
    min_dancibility (float): The min dancibility of song results
 
    mode (int): 0 or 1 (minor or major)
 
    key (int): 0-11 (c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b)
 
    max_latitude (float): A float specifying the max latitude of artists to search for
 
    min_latitude (float): A float specifying the min latitude of artists to search for
 
    max_longitude (float): A float specifying the max longitude of artists to search for
 
    min_longitude (float): A float specifying the min longitude of artists to search for                        
 
    sort (str): A string indicating an attribute and order for sorting the results
 
    buckets (list): A list of strings specifying which buckets to retrieve
 
    limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
    
    seed_catalog (str or Catalog): An Artist Catalog object or Artist Catalog id to use as a seed
    
    source_catalog (str or Catalog): A Catalog object or catalog id
 
Returns:
    A list of Song objects
 
Example:
 
>>> p = playlist.static(type='artist-radio', artist=['ida maria', 'florence + the machine'])
>>> p
[<song - Pickpocket>,
 <song - Self-Taught Learner>,
 <song - Maps>,
 <song - Window Blues>,
 <song - That's Not My Name>,
 <song - My Lover Will Go>,
 <song - Home Sweet Home>,
 <song - Stella & God>,
 <song - Don't You Want To Share The Guilt?>,
 <song - Forget About It>,
 <song - Dull Life>,
 <song - This Trumpet In My Head>,
 <song - Keep Your Head>,
 <song - One More Time>,
 <song - Knights in Mountain Fox Jackets>]
>>>