Module: Echowrap::API::Song

Includes:
Utils
Included in:
Client
Defined in:
lib/echowrap/api/song.rb

Constant Summary

Constants included from Utils

Utils::API_KEY_CANNOT_CALL_THIS_METHOD, Utils::INVALID_PARAMETER, Utils::MISSING_OR_INVALID_KEY, Utils::MISSING_PARAMETER, Utils::RATE_LIMIT_EXCEEDED, Utils::SUCCESS

Instance Method Summary collapse

Instance Method Details

#song_identify(options = {}) ⇒ Echowrap::Track

Identifies a song given an Echoprint or Echo Nest Musical Fingerprint hash codes.

Examples:

Identify via json query file

Echowrap.song_identify(:query => File.new('query.json'))

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :query (String) —

    The JSON query. Use only with POST. Example: See “Here is a sample query:” at developer.echonest.com/docs/v4/song.html#identify.

  • :code (String) —

    The FP hashcodes for the track. Use only with GET. Example: See “Identifying Songs with GET at developer.echonest.com/docs/v4/song.html#identify.”

  • :artist (String) —

    The name of the artist from the ID3 tag. Use only with GET, not required. Example: ‘Michael+Jackson’

  • :title (String) —

    The title of the track from the ID3 tag. Use only with GET, not required. Example: ‘Billie+Jean’

  • :release (String) —

    The title of the track from the ID3 tag. Use only with GET, not required. Example: ‘Thriller’

  • :duration (String) —

    The length of time of the track, in seconds. Use only with GET, not required. Example: ‘296.15’

  • :genre (String) —

    The genre from the ID3 tag. Use only with GET, not required. Example: ‘pop’

  • :version (String) —

    Version of codegen used to generate the code. Not required. Example: For ENMFP use 3.15, for Echoprint use 4.12, defaults to 3.15

  • :bucket (String) —

    The type of track data that should be returned. Must be one of [‘audio_summary’, ‘artist_familiarity’, ‘artist_hotttnesss’, ‘artist_location’, ‘song_hotttnesss’, ‘song_type’, ‘tracks’, ‘id:Rosetta-space’]. Example: audio_summary.

Returns:

Raises:

  • (Echowrap::Error::Unauthorized) —

    Error raised when supplied api key is not valid. # @raise [Echowrap::Error::Unauthorized] Error raised when supplied user credentials are not valid.

See Also:



26
27
28
29
30
31
32
 
# File 'lib/echowrap/api/song.rb', line 26

def song_identify(options={})
  if options.key?(:query)
    objects_from_response(Echowrap::Song, :post, '/api/v4/song/identify', :songs, options).first
  else
    objects_from_response(Echowrap::Song, :get, '/api/v4/song/identify', :songs, options).first
  end
end

#song_profile(options = {}) ⇒ Echowrap::Song

Get info about songs given a song id or track id.

Examples:

Profile via id

Echowrap.song_profile(:id => 'SOCZMFK12AC468668F')

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :id (String) —

    The ID of the song. Required if track_id is not provided. Example: ‘SOCZMFK12AC468668F’.

  • :track_id (String) —

    The ID of the track. Required if id is not provided. Example: ‘TRTLKZV12E5AC92E11’.

  • :bucket (String) —

    The type of track data that should be returned. Must be one of [‘audio_summary’, ‘artist_familiarity’, ‘artist_hotttnesss’, ‘artist_location’, ‘song_hotttnesss’, ‘song_type’, ‘tracks’, ‘id:Rosetta-space’]. Example: audio_summary.

Returns:

Raises:

  • (Echowrap::Error::Unauthorized) —

    Error raised when supplied api key is not valid. # @raise [Echowrap::Error::Unauthorized] Error raised when supplied user credentials are not valid.

See Also:



47
48
49
 
# File 'lib/echowrap/api/song.rb', line 47

def song_profile(options={})
  objects_from_response(Echowrap::Song, :get, '/api/v4/song/profile', :songs, options).first
end

#song_search(options = {}) ⇒ Array, Array<Echowrap::Song>

Search for songs given different query types

Examples:

Return an array of songs with artist ‘Daft Punk’

Echowrap.song_search(:artist => "Daft Punk")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :title (String) —

    The title of the song.

  • :artist (String) —

    The artist of the song.

  • :combined (String) —

    Query both artist and title fields.

  • :description (String) —

    A description of the artist, some examples are: ‘alt-rock’,‘-emo’, ‘harp^2’. Warning Description cannot be used in conjunction with title, artist, combined, or artist_id.

  • :style (String) —

    A musical style or genre like rock, jazz, or funky, some examples are: ‘jazz’, ‘metal^2’.

  • :mood (String) —

    A mood like happy or sad, some examples are: ‘happy’, ‘sad^.5’.

  • :rank_type (String) —

    For search by description, style or mood indicates whether results should be ranked by query relevance or by artist familiarity, must be one of [‘relevance’, ‘familiarity’], with ‘relevance’ as default

  • :artist_id (String) —

    The artist ID. An Echo Nest ID or a Rosetta ID.

  • :results (Integer) —

    The desired number of results to return, the valid range is 0 to 100, with 15 as the default

  • :start (Integer) —

    The desired index of the first result returned, must be on of [0, 15, 30] with 0 as the default

  • :song_type (String) —

    Controls the type of songs returned. Supported song_types are: ‘christmas’, ‘live’ and ‘studio’. A song type can optionally be followed by ‘:’ and a state, where the state can be one of ‘true’, ‘false’ or ‘any’. If no state is given, the desired state is assumed to be ‘true’.

  • :max_tempo (Float) —

    The maximum tempo for the song, the valid range for max_tempo is 0.0 to 500.0 (BPM), with 500.0 as default.

  • :min_tempo (Float) —

    The minimum tempo for the song, the valid range for min_tempo is 0.0 to 500.0 (BPM), with 0.0 as default.

  • :max_duration (Float) —

    The maximum duration of any song, the valid range for max_duration is 0.0 to 3600.0 (seconds), with 3600.0 as default.

  • :min_duration (Float) —

    The minimum duration of any song, the valid range for min_duration is 0.0 to 3600.0 (seconds), with 0.0 as default.

  • :max_loudness (Float) —

    The maximum loudness of any song, the valid range for max_loudness is -100.0 to 100.0 (decibels), with 100.0 as default.

  • :min_loudness (Float) —

    The minimum loudness of any song, the valid range for min_loudness is 0.0 to -100.0 (decibels), with -100.0 as default.

  • :artist_max_familiarity (Float) —

    The maximum familiarity of any song, the valid range for artist_max_familiarity is 0.0 to 1.0, with 1.0 as default.

  • :artist_min_familiarity (Float) —

    The minimum familiarity of any song, the valid range for artist_min_familiarity is 0.0 to 1.0, with 0.0 as default.

  • :artist_start_year_before (String) —

    Matches artists that have an earliest start year before the given value, some examples are ‘1970’, ‘2011’, ‘present’.

  • :artist_start_year_after (String) —

    Matches artists that have an earliest start year after the given value, some examples are ‘1970’, ‘2011’, ‘present’.

  • :artist_end_year_before (String) —

    Matches artists that have an latest start year before the given value, some examples are ‘1970’, ‘2011’, ‘present’.

  • :artist_end_year_after (String) —

    Matches artists that have an latest start year after the given value, some examples are ‘1970’, ‘2011’, ‘present’.

  • :song_max_hotttnesss (Float) —

    The maximum hotttnesss of any song, the valid range for song_max_hotttnesss is 0.0 to 1.0, with 1.0 as default.

  • :song_min_hotttnesss (Float) —

    The minimum hotttnesss of any song, the valid range for the song_min_hotttnesss is 0.0 to 1.0, with 0.0 as default.

  • :artist_max_hotttnesss (Float) —

    The maximum hotttnesss of any song’s artist, the valid range for artist_max_hotttnesss is 0.0 to 1.0, with 1.0 as default.

  • :artist_min_hotttnesss (Float) —

    The minimum hotttnesss of any song’s artist, the valid range for the artist_min_hotttnesss is 0.0 to 1.0, with 0.0 as default.

  • :max_longitude (Float) —

    The maximum longitude of the primary artist location, the valid range for max_longitude is -180.0 to 180.0, with 180.0 as default.

  • :min_longitude (Float) —

    The minimum longitude of the primary artist location, the valid range for min_longitude is -180.0 to 180.0, with -180.0 as default.

  • :max_latitude (Float) —

    The maximum latitude of the primary artist location, the valid range for max_latitude is -90.0 to 90.0, with 90.0 as default.

  • :min_latitude (Float) —

    The minimum longitude of the primary artist location, the valid range for max_latitude is -90.0 to 90.0, with -90.0 as default.

  • :max_danceability (Float) —

    The maximum danceability of any song, the valid range for max_danceability is 0.0 to 1.0, with 1.0 as default.

  • :min_danceability (Float) —

    The minimum danceability of any song, the valid range for min_danceability is 0.0 to 1.0, with 0.0 as default.

  • :max_energy (Float) —

    The maximum energy of any song, the valid range for max_energy is 0.0 to 1.0, with 1.0 as default.

  • :min_energy (Float) —

    The minimum energy of any song, the valid range for min_energy is 0.0 to 1.0, with 0.0 as default.

  • :max_liveness (Float) —

    The maximum liveness of any song, the valid range for max_liveness is 0.0 to 1.0, with 1.0 as default.

  • :min_liveness (Float) —

    The minimum liveness of any song, the valid range for min_liveness is 0.0 to 1.0, with 0.0 as default.

  • :max_speechiness (Float) —

    The maximum speechiness of any song, the valid range for max_speechiness is 0.0 to 1.0, with 1.0 as default.

  • :min_speechiness (Float) —

    The minimum speechiness of any song, the valid range for min_speechiness is 0.0 to 1.0, with 0.0 as default.

  • :key (Integer) —

    The key of songs in the playlist, the valid range for key is 0 to 11 (C, C-sharp, D, D-sharp, E… with 0 representing C and 11 representing B).

  • :mode (Integer) —

    The mode of songs, must be one of [0, 1] (minor, major), with 0 representing minor and 1 represeting major.

  • :bucket (String) —

    Indicates what data should be returned for each song. If specifying the “tracks” bucket, a bucket with an id space must also be specified. Must be one of [‘audio_summary’, ‘artist_familiarity’, ‘artist_hotttnesss’, ‘artist_location’, ‘song_hotttnesss’, ‘song_type’, ‘tracks’, ‘id:Rosetta-space’].

  • :sort (String) —

    Indicates how the songs results should be ordered. Must be one of [‘tempo-asc’, ‘duration-asc’, ‘loudness-asc’, ‘speechiness-asc’, ‘liveness-asc’, ‘artist_familiarity-asc’, ‘artist_hotttnesss-asc’, ‘artist_start_year-asc’, ‘artist_start_year-desc’, ‘artist_end_year-asc’, ‘artist_end_year-desc’, ‘song_hotttness-asc’, ‘latitude-asc’, ‘longitude-asc’, ‘mode-asc’, ‘key-asc’, ‘tempo-desc’, ‘duration-desc’, ‘loudness-desc’, ‘liveness-desc’, ‘speechiness-desc’, ‘artist_familiarity-desc’, ‘artist_hotttnesss-desc’, ‘song_hotttnesss-desc’, ‘latitude-desc’, ‘longitude-desc’, ‘mode-desc’, ‘key-desc’, ‘energy-asc’, ‘energy-desc’, ‘danceability-asc’, ‘danceability-desc’].

  • :limit (String) —

    If ‘true’, limit the results to any of the given idspaces or catalogs. Must be on of [‘true’, ‘false’] with ‘false’ as the default.

Returns:

Raises:

See Also:



105
106
107
 
# File 'lib/echowrap/api/song.rb', line 105

def song_search(options={})
  objects_from_response(Echowrap::Song, :get, '/api/v4/song/search', :songs, options)
end