last.fm fingerprint

That's the official repository for the last.fm fingerprint library. The fingerprinting process works in two steps:

Get PCM data and pass it to fplib which will return byte string to be submitted to the last.fm HTTP fingerprint service. This will return a number (fingerprintID).
Query the last.fm API with the fingerprintID and obtain the metadata in xml format.

The lastfm-fpclient directory contains an example of application that uses fplib and queries both services.

Building

fplib requires the following libraries

fftw3-dev

lastfm-fpclient requires the following libraries:

libtag1c2a libtagc0-dev libcurl3 libcurl3-dev libmad0-dev libsamplerate0-dev

(see also doc/readme-unix.txt & doc/readme-osx.txt)

To compile both fplib and lastfm-fpclient just run (you'll need cmake): $ cmake . $ make

Packaging

To create debian packages just run 'dpkg-buildpackage'

API Documentation

To create API documentation just run 'doxygen' (NB. you'll also need dot)

Running

To use lastfm-fpclient just pass any mp3 as argument

$ lastfm-fpclient mysterious.mp3

Using fplib

You can freely use fplib in your application without any restriciton (see debian/copyright). Accessing the last.fm API services is restricted to our terms of services (see http://www.last.fm/api/tos). Basically you can do pretty much whatever you want as long as it's not for profit.

If you plan to use fplib in your application, there are a few VERY important things to keep in mind:

important things to keep in mind

a. fplib accepts standard PCM data, which means that if your track is encoded with some format (mp3, ogg, wma, etc..) you need to decode it first.

b. IMPORTANT: The library REQUIRES the data to be from the beginning of the file.

c. You don't have to decode the whole thing as the library can get as many bytes as you want to pass it. If it needs more it will return false. Basically the whole processing steps can be summarized by this loop:

  for (;;)
  {
     // read some data from the file
     size_t sz = read_some_source( pPCMBuffer );
     if ( sz == 0 )
     {
        cerr << "ERROR: Insufficient input data!" << endl;
        exit(1); // goodbye!
     }

     // Process to create the fingerprint. If process returns true
     // it means he's happy with what he has.
     if ( fextr.process( pPCMBuffer, sz
             /*, bool: set it to true if it's EOF */ ) )
        break;
  }

  // get the fingerprint data
  pair<const char*, size_t> fpData = fextr.getFingerprint();

d. fpData is what you'll need to send to the HTTP fingerprint service along with (also VERY important) the length of the track in seconds.

e. Other stuff to send is nice to have (artist and track names, genre, username, etc..) but not mandatory (but if you abuse us, we'll get you)

The protocol used to talk to the HTTP fingerprint service is just a POST with the fingerprint binary as object, and the other things (length, metadata, etc..) as parameters. See lastfm-fpclient for an example.

Using the metadata API

Once you have obtained the fingerprintID from the HTTP fingerprint service (see above) you have to talk to the metadata API to get the XML with the description of the track.

To do so, you have to obtain an API key (http://www.last.fm/api/account) then just query the service with the following parameters:

http://ws.audioscrobbler.com/2.0/?method=track.getfingerprintmetadata&fingerprintid=THE_FINGERPRINT_ID&api_key=YOUR_API_KEY

Fingerprinter

Install / Use

README