Get the blues when trying to install something ? Don't! The step-by-step install-guide
from a real-life installation of AmpJuke might help. Read more
How do I configure Echonest in AmpJuke ?
In order to use the Echonest features in AmpJuke, you should - besides your AmpJuke installation - have obtained an API-key at the Echonest homepage.
You access and configure the feature (just like almost everything else) by logging in as a user with administrator access and then click on "Configuration..." on the "welcome" page.
On the configuration page, you'll see an entry labeled "Similar/related tracks (Echonest API)":
Click to enlarge
Taking advantage of (and enabling) the Echonest+AmpJuke combination really adds some value to your music-collection! The above configuration (apart from the API-key, of course) comes straight from my own box!
Let's take a look at these - at first glance - overwhelming number of options in this section.
Enable calls to the Echonest API: If checked (enabled), AmpJuke will use the Echonest API in order to "identify" the individual music tracks within your music collection.
If you leave this setting unchecked (disabled) the rest of the parameters will not have any effect.
Echonest API key: Punch in the API-key received from the Echonest (see link above).
Echonest API "base" URL: This is the "entry point" for calls made to the Echonest API.
The current, default value is "http://developer.echonest.com/api/v4/". You should leave it like that unless the Echonest later changes the way API-calls are made.
Maximum number of results returned by API-calls: This setting controls how many results are returned when making a call to the Echonest API. The way AmpJuke uses the Echonest API is actually based on a "lazy" call (no upload) vs. a "real" call (upload+identification).
However, to keep it simple right now, it is sufficient to know that this setting controls how many results are expected when asking the API for a track's "fingerprint" (BPM, loudness, danceability etc.).
In order to fully understand the impact of this parameter, you should read about the "mechanics" (see link below). The default value of 5 is great and can be left unchanged.
Maximum difference in duration: Like the previous setting, this has something to do with the "lazy" call vs. a "real" call to the Echonest API, - "lazy" and "real" is just something I named these two types of calls
Again: In order to fully understand the impact of this parameter, you should read about the "mechanics" (see link below). The default value of 3 (seconds) is great and can be left unchanged.
Mark tracks not identified: This setting is also related to the "lazy" vs. the "real" call to the API (mentioned above).
In almost any case you should leave this setting on (checked), if you later wants to "identify" tracks that could not be identified used the "lazy" call to the API.
Note that marking tracks not identified has the effect that an indivdual track that was marked earlier, might be uploaded (only on request by you/administrators) to the Echonest API for processing and identification of the track's "fingerprint" (BPM, danceability, key etc.).
If you choose to leave this setting off (unchecked), a track will not be marked for upload, if the "lazy" call to the Echonest API doesn't return any useful results.
Use echonest parameters in advanced search: If checked (on), it will be possible to make an advanced search using echonest parameters, when "Search" is clicked:
If unchecked (off), the normal advanced search method is used.
Again (again!): For further explanation, see the link about the "mechanics" at the bottom.
The next set of parameters are related.
A quick tour of each, follows - all values presented have been taken from my own installation and should only be used as guidelines/examples.
Limit factor: Each track can be identified by the Echonest API. The identification (or "fingerprint") is based on a number of values for each parameter, such as tempo, danceability, loudness, energy, key etc.
The Limit factor is the "filter" used to determine if track A is similar to track B.
A simple example: Let's say we want to find out if two individual tracks are similar based on a single parameter: danceability. If "Limit factor" is 0.05 (the default) and track A has a danceability value of 0.77 and track B has a danceability value of 0.79, then track A and B are similar/related, since the difference in danceability values for both tracks are less than 0.05.
If track B had a danceability value of 0.61, then the tracks will not be considered similar/related, because the difference in danceability is greater than 0.05.
In other words: The lower the limit factor is, the smaller the difference between to tracks can be (based on any parameter - see below), before the two tracks can be considered similar/related.
It's simple math!
BPM/tempo priority and BPM/tempo factor: Enter a value for the priority of BPM/tempo value when comparing two tracks for similarity.
The priority must be 0-9. A high value means a high priority of BPM/tempo as parameter when comparing two tracks for similarity. Setting the value to 0 ignores BPM/tempo when comparing tracks for similarity.
The BPM/tempo factor is a number that's multiplied with the "limit factor" (mentioned above) when comparing two tracks.
A simple example: Let's say we want to find out if two individual tracks are similar based on a single parameter: tempo/BPM. If "Limit factor" is 0.05 (the default) and track A has a tempo/BPM value of 120 and track B has a tempo/BPM value of 123, then track A and B are similar/related, since the tempo/BPM values for both tracks is less than "limit factor" multiplied with "tempo/BPM factor" : 0.05 * 100 = 5.
If track B has a tempo/BPM value of 114, then the tracks will not be considered similar/related, bacause the difference is grater than 5 (provided "limit factor" and "tempo/BPM factor" is 0.05 resp. 100).
In other words: The lower "limit factor" and "BPM/tempo factor", the smaller the difference in BPM/tempo can be, before the two tracks can be considered similar/related.
Danceability priority: Like BPM/tempo above, the priority must be 0-9. A high value means a high priority of the danceability parameter when comparing two tracks for similarity. Setting the value to 0 ignores danceability when comparing tracks for similarity.
Energy priority: Like BPM/tempo and danceability above, the priority must be 0-9. A value of 0 ignores energy when comparing tracks for similarity.
Key priority and key factor: Like seen above with BPM/tempo above, this parameter consists of two values.
The key priority can be set to something from 0-9. Setting it is 0 ignores the key when comparing tracks for similarity.
Key factor: The key is a numerical representation of the track's music key (c, c-sharp, d, e-flat, e, f, f-sharp and so on), where a value of f.ex. 1 corresponds to c-sharp.
In order to find out if two tracks are related, the key factor is the allowed maximum (+/-) when comparing tracks.
A simple example: Let's say we want to find out if two individual tracks are similar based on a single parameter: key. If "key factor" is 1 (the default) and track A has a key value of 2 (corresponds to "d") and track B has a key value of 1 (corresponds to "c-sharp") then track A and B a similar/related, since the difference in key is less than (or equal to) the "key factor" (1 in this example).
Loudness priority: Like all the other parameters mentioned above, the priority value must be 0-9. A value of 0 ignores loudness when comparing tracks for similarity.
Liveness priority: You know the drill by now: A value between 0-9. A value of 0 ignores leveness when comparing tracks fro similarity.
Speechiness, acousticness and valence priority: Same as above. Value between 0-9 where 0 ignores the setting.
The number of possibilities that can be used to configure "similarity parameters" may seem overwhelming at a first glance. On the other hand bear in mind that the high level of detail allows for a very "fine-tuned" configuration of how tracks are compared for similarity in AmpJuke.
It all comes down to the wanted listening experience when streaming tracks on a random basis using the "Related tracks" setting in the personal settings: Should it be towards same rhythm and genre ? Then high priority for BPM, danceability and energy should be taken into consideration.
Should it be the same "mood" ? Then high values for valence, leveness and speechiness should be considered.
The possibilites are endless!
Unfortunately, The Echonest is very "quiet" (for lack of a better word) in describing the above mentioned attributes and their meaning!
The onle (best?) I could find is located here: http://developer.echonest.com/raw_tutorials/faqs/faq_04.html
Other documentation related to the Echonest API in AmpJuke:
What it is.
How to configure (this doc.).
Improved listening experience.