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
General: How does the "mechanics" in AmpJuke+Echonest work ?
It should be obvious that having something like the Echonest API in AmpJuke is a powerful feature with a lot of configuration options.
This FAQ-entry will (at least: try to) explain how it all works. This explanation might help understand the very "low level" basics of how AmpJuke and the Echonest API interacts with eachother.
So - let's take it step by step. I might as well warn you: Geeky stuff below.
By the way: I'm also assuming you're familiar with configuration of the Echonest API in AmpJuke, as well as the effects of having different configuration scenarios.
Facts about an individual track's Echonest status in AmpJuke.
Provided you have configured the "similar/related tracks (Echonest API)" feature in AmpJuke, all tracks in your AmpJuke database will have one of three possible status-codes in relation to identification from the Echonest API:
"Not identified": An attempt to identify the track has not been made previously (or the feature "Mark tracks not identified" has been turned off in the configuration).
"Attempted identification - no match found": An attempt to identify the track was made previously using the "lazy" approach (see below). Based on the track's name and the configured setting "Maximum difference in duration", the Echonest API returned some results, but none of them enabled a positive identification of the track.
The track has been marked as a candidate for upload using the Echonest API and subsequent identification. This is a "manual" step (controlled by you or other admins).
"Identified OK": Based on the track's name and duration, the "lazy" call to the Echonest API returned at least one useful result.
Based on that result, the track is considered to be "identified", - that is: The track's "fingerprint"/details have been stored in the AmpJuke database with values for: BPM/tempo, danceability, energy, key and loudness.
When is an attempt made to identify a track using the Echonest API ?
Simple answer: Right after the track has been streamed/played....
...unless: the track has been identified earlier already (has a status of "Identified OK" - see above).
...or the track couldn't be identified using the "lazy" API-call (the status will then be "Attempted identification - no match found"). If that's the case, only an upload + analysis of the track to the Echonest API will convert into a successfull identification.
There's functionality in AmpJuke that allows batch-processing of tracks (so you don't have to listen to each and every track in order to attempt to identify a track).
Once a track has been identified with success, the data from the identification (BPM/tempo, energy etc.) is stored in the AmpJuke database and no other attempts to identify the same track using the API will ever be made again.
What's the difference between a "lazy" call vs. a "real" call to the Echonest API ?
The "lazy" call occurs in two situations: Right after a track has been streamed (provided that the track's status is "Not identified" - see above) or during batch processing.
A "real" call only occurs on request (by you/an admin) using the batch processing feature.
A "lazy" call doesn't involve an upload of a given track to the Echonest API for processing+identification.
A "real" call does.
Those are the basic differences between a "lazy" and a "real" call to the Echonest API from within AmpJuke.
Furthermore, a "lazy" call is much quicker to process (since no upload is required) and the "lazy" call only makes a query against the Echonest API in an attempt to identify a track based on:
Name of artist/performer, name of track and the duration of track.
These three parameters are used to make a quick (or "lazy") call to the Echonest API.
Based on the set of results (the "Maximum number of results returned by API-calls" in the configuration), each individual result is compared against the "Maximum difference in duration" (also found in the configuration) and - finally - the result with a duration as close as possible to the track's duration is considered to be the best match, - provided artist/performer name and name of track returned from the API are the same as the track being identified.
The values from the best match is then stored in the AmpJuke database. "Values" in this context are: BPM/tempo, danceability, energy, key and loudness.
Also, the track is marked as "identified OK" (see above). As mentioned above there will not be another attempt to identify the track again if the status is "Identified OK".
If the set of results from the quick call doesn't contain an individual result that satisfies the name of the track, the name of the artist/performer as well as a duration within "Maximum difference in duration", then the track is marked as "Attempted identification - no match found".
It is then possible to upload and identify that track later using the batch processing feature of tracks in AmpJuke.
Uploading and analysis of a track using the Echonest API is considered a "real" identification, since the "fingerprint" (BPM/tempo, energy, danceability etc.) is done on *the* track being uploaded, rather than making a good, qualified guess based on a "lazy" call.
Other documentation related to the Echonest API in AmpJuke:
What it is.
How to configure.
The "mechanics" (this doc.).
Improved listening experience.