Chromaprint and Acoustid for Python
Chromaprint and its associated Acoustid Web service make up a high-quality, open-source acoustic fingerprinting system. This package provides Python bindings for both the fingerprinting algorithm library, which is written in C but portable, and the Web service, which provides fingerprint lookups.
First, install the Chromaprint fingerprinting library by Lukáš Lalinský. (The library itself depends on an FFT library, but it's smart enough to use an algorithm from software you probably already have installed; see the Chromaprint page for details.)
$ pip install pyacoustid
This library uses audioread to do audio decoding (pip should automatically install this dependency), but it's not really necessary if you already have decoded audio.
You can run the included demonstration script,
aidmatch.py, to test your
$ python aidmatch.py mysterious_music.mp3
This will show the top metadata match from Acoustid's database. The script uses audioread to decode music, so it should transparently use a media library available on your system (GStreamer, FFmpeg, MAD, or Core Audio).
Using in Your Code
The simplest way to use pyacoustid to identify audio files is to call the
>>> import acoustid >>> for score, recording_id, title, artist in acoustid.match(apikey, path): >>> ...
This convenience function uses audioread to decode audio and parses the response for you, pulling out the most important track metadata. It returns in iterable over tuples of relevant information. Everything happens in one fell swoop. There are also a number of "smaller" functions you can use to perform parts of the process:
fingerprint(samplerate, channels, pcmiter): Generate a fingerprint for raw audio data. Specify the audio parameters and give an iterable containing blocks of PCM data.
lookup(apikey, fingerprint, duration): Make a request to the Acoustid API to look up the fingerprint returned by the previous function. An API key is required, as is the length, in seconds, of the source audio. Returns a parsed JSON response.
parse_lookup_result(data): Given a parsed JSON response, return an iterator over tuples containing the match score (a float between 0 and 1), the MusicBrainz recording ID, title, and artist name for each match.
The module internally performs thread-safe API rate limiting to 3 queries per second whenever the Web API is called, in accordance with the Web service documentation.
If you're running your own Acoustid database server, you can set the base URL
for all API calls with the
Calls to the library can raise
AcoustidError exceptions of two subtypes:
WebServiceError. Catch these exceptions
if you want to proceed when audio can't be decoded or no match is found on the
- Data chunks can now be buffers as well as bytestrings (fixes compatibility with pymad).
- Configurable API base URL.
Result parser now generates all results instead of returning just one.
Find the chromaprint library on Cygwin.
New module names:
- Compress HTTP requests and responses. Limit audio decoding to 120 seconds. Return score from convenience function.
- Initial release.
This library is by Adrian Sampson. Chromaprint and Acoustid are by Lukáš Lalinský. This package includes the original ctypes-based bindings written by Lukáš. The entire library is made available under the MIT license. pyacoustid was written to be used with beets, which you should probably check out.