The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-EchoNest-v0.0.2
River stage zero No dependents
++
/ WWW::EchoNest::Song

NAME

WWW::EchoNest::Song.

SYNOPSIS

use WWW::EchoNest::Song;

METHODS

new

  Returns a new WWW::EchoNest::Song instance.

  NOTE:
    WWW::EchoNest also provides a song() convenience function that also returns a new WWW::EchoNest::Song instance.

  ARGUMENTS:
    id         => a song ID 
    buckets    => a list of strings specifying which buckets to retrieve
  
  RETURNS:
    A new WWW::EchoNest::Song instance.

get_id

  Returns the Echo Nest Song ID.

  ARGUMENTS:
    none
  
  RETURNS:
    The Echo Nest Song ID.

get_title

  Returns the song title.

  ARGUMENTS:
    none
  
  RETURNS:
    Song title.

get_artist_name

  Returns the artist name.

  ARGUMENTS:
    none
  
  RETURNS:
    Artist name.

get_artist_id

  Returns the artist ID.

  ARGUMENTS:
    none
  
  RETURNS:
    The Echo Nest Artist ID.

get_song_hotttnesss

  Returns The Echo Nest's numerical estimation of how hottt this song is.

  ARGUMENTS:
    cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
  
  RETURNS:
    Float representing this song's hotttnesss.

get_artist_hotttnesss

  Returns The Echo Nest's numerical estimation of how hottt the artist for this song is.

  ARGUMENTS:
    cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
  
  RETURNS:
    Float representing the artist's hotttnesss for this song.

get_artist_familiarity

  Returns The Echo Nest's numerical estimation of how familiar the artist for this song is to the rest of the world.

  ARGUMENTS:
    cache    => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
  
  RETURNS:
    Float representing the artist's familiarity for this song.

get_artist_location

  Returns info about where this song's artist is from.

  ARGUMENTS:
    cache   => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
  
  RETURNS:
    A reference to a hash describing location, latitude,
    and longitude for this Song's artist.

get_audio_summary

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

  ARGUMENTS:
    cache => A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
  
  RETURNS:
    A reference to a hash containing mode, tempo, key, duration, time signature, loudness, danceability, energy and analysis_url keys.

get_foreign_id

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

  ARGUMENTS:
    idspace     => A string indicating the idspace to fetch a foreign id for.
  
  RETURNS:
    A foreign ID string.

get_tracks

  Get the tracks for a song given a catalog.

  ARGUMENTS:
    catalog => A string representing the catalog whose track you want to retrieve.
  
  RETURNS:
    A reference to an array of hash refs describing tracks.

FUNCTIONS

identify

  Identify a song.

  ARGUMENTS:
    filename         => The path of the file you want to analyze (requires codegen binary!)
    query_obj        => A dict or list of dicts containing a 'code' element with an fp code
    code             => A fingerprinter code
    artist           => An artist name
    title            => A song title
    release          => A release name
    duration         => A song duration
    genre            => A string representing the genre
    buckets          => A list of strings specifying which buckets to retrieve
    codegen_start    => The point (in seconds) where the codegen should start
    codegen_duration => The duration (in seconds) the codegen should analyze
  
  RETURNS:
    A foreign ID string.

search_song

  Search for songs by name, description, or constraint.

  ARGUMENTS:
    title                  => the name of a song
    artist                 => the name of an artist
    artist_id              => the artist_id
    combined               => the artist name and song title
    description            => A string describing the artist and song
    style                  => A string describing the style/genre of the artist and song
    mood                   => A string describing the mood of the artist and song
    results                => An integer number of results to return
    max_tempo              => The max tempo of song results
    min_tempo              => The min tempo of song results
    max_duration           => The max duration of song results
    min_duration           => The min duration of song results
    max_loudness           => The max loudness of song results
    min_loudness           => The min loudness of song results
    artist_max_familiarity => A float specifying the max familiarity of artists to search for
    artist_min_familiarity => A float specifying the min familiarity of artists to search for
    artist_max_hotttnesss  => A float specifying the max hotttnesss of artists to search for
    artist_min_hotttnesss  => A float specifying the max hotttnesss of artists to search for
    song_max_hotttnesss    => A float specifying the max hotttnesss of songs to search for
    song_min_hotttnesss    => A float specifying the max hotttnesss of songs to search for
    max_energy             => The max energy of song results
    min_energy             => The min energy of song results
    max_dancibility        => The max dancibility of song results
    min_dancibility        => The min dancibility of song results
    mode                   => 0 or 1 (minor or major)
    key                    => 0-11 (c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b)
    max_latitude           => A float specifying the max latitude of artists to search for
    min_latitude           => A float specifying the min latitude of artists to search for
    max_longitude          => A float specifying the max longitude of artists to search for
    min_longitude          => A float specifying the min longitude of artists to search for                        
    sort                   => A string indicating an attribute and order for sorting the results
    buckets                => A list of strings specifying which buckets to retrieve
    limit                  => A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
    rank_type              => A string denoting the desired ranking for description searches, either 'relevance' or 'familiarity'
  
  RETURNS:
    A reference to an array of Song objects.

  EXAMPLE:
    # Insert helpful example here!

profile

  Get the profiles for multiple songs at once.

  ARGUMENTS:
    ids     => A song ID or list of song IDs
    buckets => A list of strings specifying which buckets to retrieve
    limit   => A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets

  RETURNS:
    A reference to an array of Song objects.

AUTHOR

Brian Sorahan, <bsorahan@gmail.com>

SUPPORT

Join the Google group: <http://groups.google.com/group/www-echonest>

ACKNOWLEDGEMENTS

Thanks to all the folks at The Echo Nest for providing access to their powerful API.

LICENSE

Copyright 2011 Brian Sorahan.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.