1Chromaprint and Acoustid for Python
2===================================
3
4`Chromaprint`_ and its associated `Acoustid`_ Web service make up a
5high-quality, open-source acoustic fingerprinting system. This package provides
6Python bindings for both the fingerprinting algorithm library, which is written
7in C but portable, and the Web service, which provides fingerprint lookups.
8
9.. _Chromaprint: http://acoustid.org/chromaprint
10.. _Acoustid: http://acoustid.org/
11
12
13Installation
14------------
15
16This library works with Python 2 (2.7+, possibly also 2.6) and Python 3
17(3.3+).
18
19First, install the `Chromaprint`_ fingerprinting library by `Lukáš Lalinský`__.
20(The library itself depends on an FFT library, but it's smart enough to use an
21algorithm from software you probably already have installed; see the Chromaprint
22page for details.) This module can use either the Chromaprint dynamic library or
23the ``fpcalc`` command-line tool, which itself depends on `libavcodec`_. If you
24use ``fpcalc``, either ensure that it is on your ``$PATH`` or set the ``FPCALC``
25environment variable to its location.
26
27__ lukas_
28.. _lukas: http://oxygene.sk/lukas/
29.. _libavcodec: http://ffmpeg.org/
30
31Then you can install this library from `PyPI`_ using `pip`_::
32
33 $ pip install pyacoustid
34
35This library uses `audioread`_ to do audio decoding when not using ``fpcalc``
36and `requests`_ to talk to the HTTP API (pip should automatically install
37these dependencies).
38
39.. _pip: http://www.pip-installer.org/
40.. _PyPI: http://pypi.python.org/
41.. _audioread: https://github.com/sampsyo/audioread
42.. _requests: http://python-requests.org
43
44
45Running
46-------
47
48You can run the included demonstration script, ``aidmatch.py``, to test your
49installation::
50
51 $ python aidmatch.py mysterious_music.mp3
52
53This will show the top metadata match from Acoustid's database. The script uses
54`audioread`_ to decode music, so it should transparently use a media library
55available on your system (GStreamer, FFmpeg, MAD, or Core Audio).
56
57
58Using in Your Code
59------------------
60
61The simplest way to use pyacoustid to identify audio files is to call the
62``match`` function::
63
64 >>> import acoustid
65 >>> for score, recording_id, title, artist in acoustid.match(apikey, path):
66 >>> ...
67
68This convenience function uses `audioread`_ to decode audio and parses the
69response for you, pulling out the most important track metadata. It returns in
70iterable over tuples of relevant information. Everything happens in one fell
71swoop. There are also a number of "smaller" functions you can use to perform
72parts of the process:
73
74- ``fingerprint(samplerate, channels, pcmiter)``: Generate a fingerprint for raw
75 audio data. Specify the audio parameters and give an iterable containing
76 blocks of PCM data.
77- ``fingerprint_file(path)``: Using either the Chromaprint dynamic library or
78 the ``fpcalc`` command-line tool, fingerprint an audio file. (You can use
79 ``force_fpcalc`` to use only the latter.) Returns a pair consisting of the
80 file's duration and its fingerprint.
81- ``lookup(apikey, fingerprint, duration)``: Make a request to the `Acoustid`_
82 API to look up the fingerprint returned by the previous function. An API key
83 is required, as is the length, in seconds, of the source audio. Returns a
84 parsed JSON response.
85- ``parse_lookup_result(data)``: Given a parsed JSON response, return an
86 iterator over tuples containing the match score (a float between 0 and 1), the
87 MusicBrainz recording ID, title, and artist name for each match.
88
89The module internally performs thread-safe API rate limiting to 3 queries per
90second whenever the Web API is called, in accordance with the `Web service
91documentation`_.
92
93If you're running your own Acoustid database server, you can set the base URL
94for all API calls with the ``set_base_url`` function.
95
96Calls to the library can raise ``AcoustidError`` exceptions of two subtypes:
97``FingerprintGenerationError`` and ``WebServiceError``. Catch these exceptions
98if you want to proceed when audio can't be decoded or no match is found on the
99server. ``NoBackendError``, a subclass of ``FingerprintGenerationError``, is
100used when the Chromaprint library or fpcalc command-line tool cannot be found.
101
102.. _Web service documentation: http://acoustid.org/webservice
103
104
105Version History
106---------------
107
1081.2.2
109 Fix a regression in the previous version that caused a `KeyError` crash when
110 calling `submit`.
111
1121.2.1
113 The `meta` parameter to some API functions can now be a list (instead of
114 just a single string).
115
1161.2.0
117 Add a `force_fpcalc` option to `fingerprint_file` and `match`.
118 Avoid leaving a dangling socket after communicating with the server.
119 Fix a crash when passing a `memoryview` object to the fingerprinter.
120 API requests can now optionally time out.
121 More reliably find the library on Windows on Python 3.8.
122 Add a `hash_fingerprint` function to the low-level library.
123
1241.1.7
125 Include a LICENSE file.
126
1271.1.6
128 In submission, avoid an error on non-integer durations.
129 A new function, `get_submission_status`, abstracts the API endpoint for
130 monitoring submissions using the (new) result from the `submit` function.
131
1321.1.5
133 Fix compatibility with Python 3 in the `submit` function.
134 Errors in `submit` are now also handled correctly (i.e., they raise an
135 informative `WebServiceError` instead of a `TypeError`).
136
1371.1.4
138 Fix an error on versions of the `fpcalc` tool that report the duration as a
139 fractional number.
140
1411.1.3
142 Accept `bytearray` objects in addition to other bytes-like types.
143
1441.1.2
145 Fix a possible crash on Unicode text in Python 2 in a non-Unicode locale.
146 Look for version "1" of the Chromaprint shared library file.
147
1481.1.1
149 Fix a possible setup error on Python 3 (thanks to Simon Chopin).
150
1511.1.0
152 Include ``fpcalc.py`` script in source distributions.
153 Add Python 3 support (thanks to Igor Tsarev).
154
1551.0.0
156 Include ``fpcalc.py``, a script mimicking the ``fpcalc`` program from the
157 Chromaprint package.
158 Handle a ``UnicodeDecodeError`` raised when using the ``fpcalc`` backend on
159 Windows with Unicode filenames.
160 Standard error output from ``fpcalc`` is suppressed.
161
1620.7
163 Properly encode Unicode parameters (resolves a ``UnicodeEncodeError``
164 in fingerprint submission).
165 Parse all recordings for each Acoustid lookup result.
166
1670.6
168 Add a new function, ``fingerprint_file``, that automatically selects a
169 backend for fingerprinting a single file.
170
1710.5
172 Fix response parsing when recording has no artists or title.
173 Fix compatibility with Python < 2.7.
174 Add specific ``NoBackendError`` exception.
175
1760.4
177 Fingerprinting can now fall back to using the ``fpcalc`` command-line tool
178 instead of the Chromaprint dynamic library so the library can be used with
179 the binary distributions (thanks to Lukáš Lalinský).
180 Fingerprint submission (thanks to Alastair Porter).
181 Data chunks can now be buffers as well as bytestrings (fixes compatibility
182 with pymad).
183
1840.3
185 Configurable API base URL.
186 Result parser now generates all results instead of returning just one.
187 Find the chromaprint library on Cygwin.
188 New module names: ``chromaprint`` and ``acoustid`` (no package).
189
1900.2
191 Compress HTTP requests and responses.
192 Limit audio decoding to 120 seconds.
193 Return score from convenience function.
194
1950.1
196 Initial release.
197
198
199Credits
200-------
201
202This library is by Adrian Sampson. Chromaprint and Acoustid are by `Lukáš
203Lalinský`__. This package includes the original `ctypes`_-based bindings
204written by Lukáš. The entire library is made available under the `MIT license`_.
205pyacoustid was written to be used with `beets`_, which you should probably check
206out.
207
208__ lukas_
209.. _ctypes: http://docs.python.org/library/ctypes.html
210.. _beets: http://beets.radbox.org/
211.. _MIT license: http://www.opensource.org/licenses/mit-license.php
212