Song – song methods

class pyechonest.song.Song(id, buckets=None, **kwargs)

A Song object

Attributes:

id (str): Echo Nest Song ID

title (str): Song Title

artist_name (str): Artist Name

artist_id (str): Artist ID

audio_summary (dict): An Audio Summary dict

song_hotttnesss (float): A float representing a song’s hotttnesss

artist_hotttnesss (float): A float representing a song’s parent artist’s hotttnesss

artist_familiarity (float): A float representing a song’s parent artist’s familiarity

artist_location (dict): A dictionary of strings specifying a song’s parent artist’s location, lattitude and longitude

Create a song object like so:

>>> s = song.Song('SOPEXHZ12873FD2AC7')

__init__(id, buckets=None, **kwargs)

Song class

Args:

id (str): a song ID

Kwargs:

buckets (list): A list of strings specifying which buckets to retrieve

Returns:

A Song object

Example:

>>> s = song.Song('SOPEXHZ12873FD2AC7', buckets=['song_hotttnesss', 'artist_hotttnesss'])
>>> s.song_hotttnesss
0.58602500000000002
>>> s.artist_hotttnesss
0.80329715999999995
>>> 

__repr__()

__str__()

get_artist_familiarity(cache=True)

Get our numerical estimation of how familiar a song’s artist currently is to the world

Args:

cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

A float representing familiarity.

Example:

>>> s = song.Song('SOQKVPH12A58A7AF4D')
>>> s.get_artist_familiarity()
0.639626025843539
>>> s.artist_familiarity
0.639626025843539
>>> 

get_artist_hotttnesss(cache=True)

Get our numerical description of how hottt a song’s artist currently is

Args:

Kwargs:

cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

A float representing hotttnesss.

Example:

>>> s = song.Song('SOOLGAZ127F3E1B87C')
>>> s.artist_hotttnesss
0.45645633000000002
>>> s.get_artist_hotttnesss()
0.45645633000000002
>>> 

get_artist_location(cache=True)

Get the location of a song’s artist.

Args:

cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

An artist location object.

Example:

>>> s = song.Song('SOQKVPH12A58A7AF4D')
>>> s.artist_location
{u'latitude': 34.053489999999996, u'location': u'Los Angeles, CA', u'longitude': -118.24532000000001}
>>> 

get_audio_summary(cache=True)

Get an audio summary of a song containing mode, tempo, key, duration, time signature, loudness, danceability, energy, and analysis_url.

Args:

Kwargs:

cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

A dictionary containing mode, tempo, key, duration, time signature, loudness, danceability, energy and analysis_url keys.

Example:

>>> s = song.Song('SOGNMKX12B0B806320')
>>> s.audio_summary
 {u'analysis_url': u'https://echonest-analysis.s3.amazonaws.com/TR/RnMKCg47J5LgQZr0SISyoPuRxKVQx3Z_YSuhVa/3/full.json?Signature=KBUbewLiP3sZ2X6rRZzXhrgh8fw%3D&Expires=1349809604&AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ',
  u'audio_md5': u'ca3fdfa72eed23d5ad89872c38cecc0e',
  u'danceability': 0.33712086491871546,
  u'duration': 470.70666999999997,
  u'energy': 0.58186979146361684,
  u'key': 0,
  u'liveness': 0.08676759933615498,
  u'loudness': -9.5960000000000001,
  u'mode': 1,
  u'speechiness': 0.036938896635994867,
  u'tempo': 126.949,
  u'time_signature': 4}
>>> 

get_foreign_id(idspace='', cache=True)

Get the foreign id for this song for a specific id space

Args:

Kwargs:

idspace (str): A string indicating the idspace to fetch a foreign id for.

Returns:

A foreign ID string

Example:

>>> s = song.Song('SOYRVMR12AF729F8DC')
>>> s.get_foreign_id('CAGPXKK12BB06F9DE9')

>>> 

get_song_hotttnesss(cache=True)

Get our numerical description of how hottt a song currently is

Args:

Kwargs:

cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

A float representing hotttnesss.

Example:

>>> s = song.Song('SOLUHKP129F0698D49')
>>> s.get_song_hotttnesss()
0.57344379999999995
>>> s.song_hotttnesss
0.57344379999999995
>>> 

get_song_type(cache=True)

Get the types of a song.

Args:

cache (boolean): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.

Returns:

A list of strings, each representing a song type: ‘christmas’, for example.

Example:

>>> s = song.Song('SOQKVPH12A58A7AF4D')
>>> s.song_type
[u'christmas']
>>> 

get_tracks(catalog, cache=True)

Get the tracks for a song given a catalog.

Args:

catalog (str): a string representing the catalog whose track you want to retrieve.

Returns:

A list of Track dicts.

Example:

>>> s = song.Song('SOWDASQ12A6310F24F')
>>> s.get_tracks('7digital')[0]
{u'catalog': u'7digital',
 u'foreign_id': u'7digital:track:8445818',
 u'id': u'TRJGNNY12903CC625C',
 u'preview_url': u'http://previews.7digital.com/clips/34/8445818.clip.mp3',
 u'release_image': u'http://cdn.7static.com/static/img/sleeveart/00/007/628/0000762838_200.jpg'}
>>> 

static song.identify(filename=None, query_obj=None, code=None, artist=None, title=None, release=None, duration=None, genre=None, buckets=None, version=None, codegen_start=0, codegen_duration=30)

Identify a song.

Args:

Kwargs:

filename (str): The path of the file you want to analyze (requires codegen binary!)

query_obj (dict or list): A dict or list of dicts containing a ‘code’ element with an fp code

code (str): A fingerprinter code

artist (str): An artist name

title (str): A song title

release (str): A release name

duration (int): A song duration

genre (str): A string representing the genre

buckets (list): A list of strings specifying which buckets to retrieve

version (str): The version of the code generator used to generate the code

codegen_start (int): The point (in seconds) where the codegen should start

codegen_duration (int): The duration (in seconds) the codegen should analyze

Example:

>>> qo
{'code': 'eJxlldehHSEMRFsChAjlAIL-S_CZvfaXXxAglEaBTen300Qu__lAyoJYhVQdXTvXrmvXdTsKZOqoU1q63QNydBGfOd1cGX3scpb1jEiWRLaPcJureC6RVkXE69jL8pGHjpP48pLI1m7r9oiEyBXvoVv45Q-5IhylYLkIRxGO4rp18ZpEOmpFPopwfJjL0u3WceO3HB1DIvJRnkQeO1PCLIsIjBWEzYaShq4pV9Z0KzDiQ8SbSNuSyBZPOOxIJKR7dauEmXwotxDCqllEAVZlrX6F8Y-IJ0e169i_HQaqslaVtTq1W-1vKeupImzrxWWVI5cPlw-XDxckN-3kyeXDm3jKmqv6PtB1gfH1Eey5qu8qvAuMC4zLfPv1l3aqviylJhytFhF0mzqs6aYpYU04mlqgKWtNjppwNKWubR2FowlHUws0gWmPi668dSHq6rOuPuhqgRcVKKM8s-fZS937nBe23iz3Uctx9607z-kLph1i8YZ8f_TfzLXseBh7nXy9nn1YBAg4Nwjp4AzTL23M_U3Rh0-sdDFtyspNOb1bYeZZqz2Y6TaHmXeuNmfFdTueLuvdsbOU9luvtIkl4vI5F_92PVprM1-sdJ_o9_Guc0b_WimpD_Rt1DFg0sY3wyw08e6jlqhjH3o76naYvzWqhX9rOv15Y7Ww_MIF8dXzw30s_uHO5PPDfUonnzq_NJ8J93mngAkIz5jA29SqxGwwvxQsih-sozX0zVk__RFaf_qyG9hb8dktZZXd4a8-1ljB-c5bllXOe1HqHplzeiN4E7q9ZRdmJuI73gBEJ_HcAxUm74PAVDNL47D6OAfzTHI0mHpXAmY60QNmlqjDfIPzwUDYhVnoXqtvZGrBdMi3ClQUQ8D8rX_1JE_In94CBXER4lrrw0H867ei8x-OVz8c-Osh5plzTOySpKIROmFkbn5xVuK784vTyPpS3OlcSjHpL16saZnm4Bk66hte9sd80Dcj02f7xDVrExjk32cssKXjmflU_SxXmn4Y9Ttued10YM552h5Wtt_WeVR4U6LPWfbIdW31J4JOXnpn4qhH7yE_pdBH9E_sMwbNFr0z0IW5NA8aOZhLmOh3zSVNRZwxiZc5pb8fikGzIf-ampJnCSb3r-ZPfjPuvLm7CY_Vfa_k7SCzdwHNg5mICTSHDxyBWmaOSyLQpPmCSXyF-eL7MHo7zNd668JMb_N-AJJRuMwrX0jNx7a8-Rj5oN6nyWoL-jRv4pu7Ue821TzU3MhvpD9Fo-XI',
 'code_count': 151,
 'low_rank': 0,
 'metadata': {'artist': 'Harmonic 313',
              'bitrate': 198,
              'codegen_time': 0.57198400000000005,
              'decode_time': 0.37954599999999999,
              'duration': 226,
              'filename': 'koln.mp3',
              'genre': 'Electronic',
              'given_duration': 30,
              'release': 'When Machines Exceed Human Intelligence',
              'sample_rate': 44100,
              'samples_decoded': 661816,
              'start_offset': 0,
              'title': 'kln',
              'version': 3.1499999999999999},
 'tag': 0}
>>> song.identify(query_obj=qo)
[<song - Köln>]
>>> 

static song.search(title=None, artist=None, artist_id=None, combined=None, description=None, style=None, mood=None, results=None, start=None, max_tempo=None, min_tempo=None, max_duration=None, min_duration=None, max_loudness=None, min_loudness=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, mode=None, min_energy=None, max_energy=None, min_danceability=None, max_danceability=None, key=None, max_latitude=None, min_latitude=None, max_longitude=None, min_longitude=None, sort=None, buckets=None, limit=False, test_new_things=None, rank_type=None, artist_start_year_after=None, artist_start_year_before=None, artist_end_year_after=None, artist_end_year_before=None, song_type=None)

Search for songs by name, description, or constraint.

Args:

Kwargs:

title (str): the name of a song

artist (str): the name of an artist

artist_id (str): the artist_id

combined (str): the artist name and song title

description (str): A string describing the artist and song

style (str): A string describing the style/genre of the artist and song

mood (str): A string describing the mood of 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

rank_type (str): A string denoting the desired ranking for description searches, either ‘relevance’ or ‘familiarity

artist_start_year_before (int): Returned songs’s artists will have started recording music before this year.

artist_start_year_after (int): Returned songs’s artists will have started recording music after this year.

artist_end_year_before (int): Returned songs’s artists will have stopped recording music before this year.

artist_end_year_after (int): Returned songs’s artists will have stopped recording music after this year.

song_type (string): A string or list of strings specifiying the type of song to search for.

Returns:

A list of Song objects

Example:

>>> results = song.search(artist='shakira', title='she wolf', buckets=['id:7digital', 'tracks'], limit=True, results=1)
>>> results
[<song - She Wolf>]
>>> results[0].get_tracks('7digital')[0]
{u'catalog': u'7digital',
 u'foreign_id': u'7digital:track:7854109',
 u'id': u'TRTOBSE12903CACEC4',
 u'preview_url': u'http://previews.7digital.com/clips/34/7854109.clip.mp3',
 u'release_image': u'http://cdn.7static.com/static/img/sleeveart/00/007/081/0000708184_200.jpg'}
>>> 

static song.profile(ids=None, track_ids=None, buckets=None, limit=False)

get the profiles for multiple songs at once

Args:

ids (str or list): a song ID or list of song IDs

Kwargs:

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

Returns:

A list of term document dicts

Example:

>>> song_ids = ['SOBSLVH12A8C131F38', 'SOXMSGY1338A5D5873', 'SOJPHZO1376210AFE5', 'SOBHNKR12AB0186218', 'SOSJAHD13770F4D40C']
>>> songs = song.profile(song_ids, buckets=['audio_summary'])
[<song - Say It Ain't So>,
 <song - Island In The Sun>,
 <song - My Name Is Jonas>,
 <song - Buddy Holly>]
>>> songs[0].audio_summary
{u'analysis_url': u'https://echonest-analysis.s3.amazonaws.com/TR/7VRBNguufpHAQQ4ZjJ0eWsIQWl2S2_lrK-7Bp2azHOvPN4VFV-YnU7uO0dXgYtOKT-MTEa/3/full.json?Signature=hmNghHwfEsA4JKWFXnRi7mVP6T8%3D&Expires=1349809918&AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ',
 u'audio_md5': u'b6079b2b88f8265be8bdd5fe9702e05c',
 u'danceability': 0.64540643050283253,
 u'duration': 255.92117999999999,
 u'energy': 0.30711665772260549,
 u'key': 8,
 u'liveness': 0.088994423525370583,
 u'loudness': -9.7799999999999994,
 u'mode': 1,
 u'speechiness': 0.031970700260699259,
 u'tempo': 76.049999999999997,
 u'time_signature': 4}
>>>