Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

bindings for Chromaprint acoustic fingerprinting and the Acoustid API

Project description

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 portable and written in C, and the Web service that provides fingerprint lookups.

Installation

First, install the Chromaprint fingerprinting library by Lukas Lalinsky. (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.)

Then you can install this library from PyPI using pip:

$ pip install pyacoustid

This library depends on audioread to do audio decoding (pip should automatically install this dependency), but it’s not really necessary if you already have decoded audio.

Running

You can run the included demonstration script, aidmatch.py, to test your installation:

$ 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 on Mac OS X).

Using in Your Code

The simplest way to use pyacoustid to identify audio files is to call the match function:

>>> import acoustid
>>> recording_id, title, artist = 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. 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): Returns 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 a tuple containing the MusicBrainz recording ID, title, and artist name of the top match.

The module internally performs thread-safe API limiting to 3 queries per second whenever the Web API is called, in accordance with the Web service documentation.

Calls to the library can raise AcoustidError exceptions of two subtypes: FingerprintGenerationError and WebServiceError. Catch these exceptions if you want to proceed when audio can’t be decoded or no match is found on the server.

Credits

This library is by Adrian Sampson. Chromaprint and Acoustid are by Lukas Lalinsky. These bindings include the original ctypes-based bindings written by Lukas. The library is made available under the MIT license. pyacoustid was written to be used with beets, which you should probably check out.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pyacoustid-0.1.tar.gz (6.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page