Package: pyacoustid
Chromaprintand its associatedAcoustidWeb 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.InstallationThis library works with Python 2 (2.7+, possibly also 2.6) and Python 3
(3.3+).First, install theChromaprintfingerprinting library byLukas 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.) This module can use either the Chromaprint dynamic library or
thefpcalccommand-line tool, which itself depends onlibavcodec. If you
usefpcalc, either ensure that it is on your$PATHor set theFPCALCenvironment variable to its location.Then you can install this library fromPyPIusingpip:$ pip install pyacoustidThis library usesaudioreadto do audio decoding when not usingfpcalcandrequeststo talk to the HTTP API (pip should automatically install
these dependencies).RunningYou can run the included demonstration script,aidmatch.py, to test your
installation:$ python aidmatch.py mysterious_music.mp3This will show the top metadata match from Acoustid’s database. The script usesaudioreadto decode music, so it should transparently use a media library
available on your system (GStreamer, FFmpeg, MAD, or Core Audio).Using in Your CodeThe simplest way to use pyacoustid to identify audio files is to call thematchfunction:>>> import acoustid
>>> for score, recording_id, title, artist in acoustid.match(apikey, path):
>>>     ...This convenience function usesaudioreadto 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.fingerprint_file(path): Using either the Chromaprint dynamic library or
thefpcalccommand-line tool, fingerprint an audio file. (You can useforce_fpcalcto use only the latter.) Returns a pair consisting of the
file’s duration and its fingerprint.lookup(apikey, fingerprint, duration): Make a request to theAcoustidAPI 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.compare_fingerprints(a, b): Compare two fingerprints produced byfingerprint_file, returning a similarity score.The module internally performs thread-safe API rate limiting to 3 queries per
second whenever the Web API is called, in accordance with theWeb service
documentation.If you’re running your own Acoustid database server, you can set the base URL
for all API calls with theset_base_urlfunction.Calls to the library can raiseAcoustidErrorexceptions of two subtypes:FingerprintGenerationErrorandWebServiceError. Catch these exceptions
if you want to proceed when audio can’t be decoded or no match is found on the
server.NoBackendError, a subclass ofFingerprintGenerationError, is
used when the Chromaprint library or fpcalc command-line tool cannot be found.Version History1.3.0Multiple artists are joined by join phrases, as displayed on the web page.
A new (pure-Python) function compares two Chromaprint fingerprints for
similarity.
Search more shared-library locations for the Chromaprint library on Windows.1.2.3Fix the signedness of numbers returned fromchromaprint_decode_fingerprint.1.2.2Fix a regression in the previous version that caused aKeyErrorcrash when
callingsubmit.1.2.1Themetaparameter to some API functions can now be a list (instead of
just a single string).1.2.0Add aforce_fpcalcoption tofingerprint_fileandmatch.
Avoid leaving a dangling socket after communicating with the server.
Fix a crash when passing amemoryviewobject to the fingerprinter.
API requests can now optionally time out.
More reliably find the library on Windows on Python 3.8.
Add ahash_fingerprintfunction to the low-level library.1.1.7Include a LICENSE file.1.1.6In submission, avoid an error on non-integer durations.
A new function,get_submission_status, abstracts the API endpoint for
monitoring submissions using the (new) result from thesubmitfunction.1.1.5Fix compatibility with Python 3 in thesubmitfunction.
Errors insubmitare now also handled correctly (i.e., they raise an
informativeWebServiceErrorinstead of aTypeError).1.1.4Fix an error on versions of thefpcalctool that report the duration as a
fractional number.1.1.3Acceptbytearrayobjects in addition to other bytes-like types.1.1.2Fix a possible crash on Unicode text in Python 2 in a non-Unicode locale.
Look for version “1” of the Chromaprint shared library file.1.1.1Fix a possible setup error on Python 3 (thanks to Simon Chopin).1.1.0Includefpcalc.pyscript in source distributions.
Add Python 3 support (thanks to Igor Tsarev).1.0.0Includefpcalc.py, a script mimicking thefpcalcprogram from the
Chromaprint package.
Handle aUnicodeDecodeErrorraised when using thefpcalcbackend on
Windows with Unicode filenames.
Standard error output fromfpcalcis suppressed.0.7Properly encode Unicode parameters (resolves aUnicodeEncodeErrorin fingerprint submission).
Parse all recordings for each Acoustid lookup result.0.6Add a new function,fingerprint_file, that automatically selects a
backend for fingerprinting a single file.0.5Fix response parsing when recording has no artists or title.
Fix compatibility with Python < 2.7.
Add specificNoBackendErrorexception.0.4Fingerprinting can now fall back to using thefpcalccommand-line tool
instead of the Chromaprint dynamic library so the library can be used with
the binary distributions (thanks to Lukas Lalinsky).
Fingerprint submission (thanks to Alastair Porter).
Data chunks can now be buffers as well as bytestrings (fixes compatibility
with pymad).0.3Configurable API base URL.
Result parser now generates all results instead of returning just one.
Find the chromaprint library on Cygwin.
New module names:chromaprintandacoustid(no package).0.2Compress HTTP requests and responses.
Limit audio decoding to 120 seconds.
Return score from convenience function.0.1Initial release.CreditsThis library is by Adrian Sampson. Chromaprint and Acoustid are byLukas
Lalinsky. This package includes the originalctypes-based bindings
written by Lukas. The entire library is made available under theMIT license.
pyacoustid was written to be used withbeets, which you should probably check
out.