Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

added readme.txt

  • Loading branch information...
commit a81ac3bc3ebac4a4b03f7736dccfa804d546eae0 1 parent 9ee83a5
Norman Casagrande nova77 authored

Showing 1 changed file with 79 additions and 0 deletions. Show diff stats Hide diff stats

  1. +79 0 readme.txt
79 readme.txt
... ... @@ -0,0 +1,79 @@
  1 +last.fm fingerprint
  2 +===================
  3 +
  4 +That's the official repository for the last.fm fingerprint library.
  5 +The fingerprinting process works in two steps:
  6 +
  7 +1. 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).
  8 +2. Query the last.fm API with the fingerprintID and obtain the metadata in xml format.
  9 +
  10 +The lastfmfpclient directory contains an example of application that uses fplib and queries both services.
  11 +
  12 +Building
  13 +--------
  14 +
  15 +fplib requires the following libraries
  16 + fftw3-dev
  17 +lastfmfpclient requires the following libraries:
  18 + libtag1c2a libtagc0-dev libcurl4-gnutls-dev libmad0-dev libsamplerate0-dev
  19 +
  20 +(see also readme-unix.txt)
  21 +
  22 +To compile both fplib and lastfmfpclient just run (you'll need cmake):
  23 + $ cmake .
  24 + $ make
  25 + $ make install
  26 +
  27 +Running
  28 +-------
  29 +
  30 +To use lastfmfpclient just pass any mp3 as argument
  31 +
  32 + $ lastfmfpclient mysterious.mp3
  33 +
  34 +Using fplib
  35 +===========
  36 +
  37 +You can freely use fplib in your application without any restriciton (see license.txt). 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.
  38 +
  39 +If you plan to use fplib in your application, there are a few VERY important things to keep in mind:
  40 +
  41 +important things to keep in mind
  42 +--------------------------------
  43 +
  44 +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.
  45 +b. IMPORTANT: The library *REQUIRES* the data to be from the beginning of the file.
  46 +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:
  47 +
  48 + for (;;)
  49 + {
  50 + // read some data from the mp3
  51 + size_t sz = read_some_source( pPCMBuffer );
  52 + if ( sz == 0 )
  53 + {
  54 + cerr << "ERROR: Insufficient input data!" << endl;
  55 + exit(1); // goodbye!
  56 + }
  57 +
  58 + // Process to create the fingerprint. If process returns true
  59 + // it means he's happy with what he has.
  60 + if ( fextr.process( pPCMBuffer, sz /*, bool: set it to true if it's EOF */ ) )
  61 + break;
  62 + }
  63 +
  64 + // get the fingerprint data
  65 + pair<const char*, size_t> fpData = fextr.getFingerprint();
  66 +
  67 +d. fpData is what you'll need to send to the HTTP fingerprint service along with (also VERY important) the lenght of the track in seconds.
  68 +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)
  69 +
  70 +The protocol used to talk to the HTTP fingerprint service is just a POST with the fingerprint binary as object, and the other things (lenght, metadata, etc..) as parameters. See lastfmfpclient for an example.
  71 +
  72 +Using the metadata API
  73 +======================
  74 +
  75 +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.
  76 +
  77 +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:
  78 +
  79 +http://ws.audioscrobbler.com/2.0/?method=track.getfingerprintmetadata&fingerprintid=THE_FINGERPRINT_ID&api_key=YOUR_API_KEY

0 comments on commit a81ac3b

Please sign in to comment.
Something went wrong with that request. Please try again.