This is a Python interface to Last.fm's acoustic fingerprinting library (called fplib) and its related API services. It performs fingerprint extraction, fingerprint ID lookup, and track metadata lookup. It also comes with some helpers for decoding audio files.
Installation
To install, you will need a compiler and the dependencies required by fplib
itself: fftw (compiled for single-precision floats) and libsamplerate.
(On Debian/Ubuntu, the packages are libfftw3-dev
and
libsamplerate0-dev
.)
Once you have these, you can easily install from PyPI using pip:
$ pip install pylastfp
Or, if you don't have pip (or easy_install), head to the download page. The normal install command should work:
$ python setup.py install
To build from the version control source (i.e., not from a release
tarball), you will also need Cython. (The source distributions include
the generated C++ file, avoiding the need for Cython. This package's
setup.py
plays tricks to detect whether you have Cython installed.)
Running
You can run the included fingerprinter/lookup script, lastmatch.py
,
to test your installation:
$ lastmatch.py mysterious_music.mp3
This will show metadata matches from Last.fm's database. The script
uses Gstreamer's Python bindings to decode MP3s. You can also use pymad
instead of Gstreamer (for MPEG audio only) by supplying the -m
flag:
$ lastmatch.py -m mysterious_music.mp3
Using in Your Code
The script exhibits the usual way to use pylastfp, which is this:
>>> import lastfp >>> xml = lastfp.gst_match(apikey, path) >>> matches = lastfp.parse_metadata(xml) >>> print matches[0]['artist'], '-', matches[0]['title'] The National - Fake Emprire
This example uses the gst_match
convenience function, which uses Gstreamer
to decode audio data. The function imports the Gstreamer module when called,
so if you don't want to depend on Gstreamer, just don't call this function.
Another similar function called mad_match
instead imports the pymad
library and uses MAD to decode instead of Gstreamer.
If you have your own way of decoding audio, you can use the lower-level interface:
>>> xml = lastfp.match(apikey, pcmdata, samplerate, time_in_secs)
Of course, you'll need a PCM stream for the audio you want to
fingerprint. The pcmdata parameter must be an iterable of Python
str
or buffer
objects containing PCM data as arrays of C short
(16-bit integer) values.
All of these functions (match
, gst_match
, and mad_match
) accept
an additional optional parameter called metadata
. It should be a dict
containing your current guess at the file's metadata. Last.fm might use
this information to improve their database. The dict should use these keys
(all of which are optional): "artist"
, "album"
, and "track"
.
The module internally performs thread-safe API limiting to 5 queries per second, in accordance with Last.fm's API TOS.
To-Do
The fingerprinting library allows for an optimization that skips decoding
a few milliseconds at the beginning of every file. (See
FingerprintExtractor::getToSkipMs()
, as demonstrated by the
example client.) Taking advantage of this will complicate the module's
interface a bit because the decoding source will need to know the amount of
time to skip.
Version History
- 0.3
- Fix typo in handling of HTTP errors. Handle cases when HTTP status line is malformed.
- 0.2
- Fix a horrible memory leak. Fail safely when file is too short. Safely handle malformed XML returned from the API. Handle and expose HTTP failures.
- 0.1
- Initial release.
Credits
This library is by Adrian Sampson. It includes the fplib source code, which is by Last.fm. fplib is licensed under the LGPLv3, so pylastfp uses the same license. pylastfp was written to be used with beets, which you should probably check out.