pyacoustid

library1.3.1pypypi✓ verified 86d ago

Python bindings for Chromaprint acoustic fingerprinting and the Acoustid API. Version 1.3.1 requires Python >=3.10. Maintained by the beetbox project. Release cadence is sporadic, with last release in 2024.

pip install pyacoustid

github ↗homepage ↗

INSTALL

IMPORT

SIG · PYACOUSTID

pyacoustid

searchpythonv1.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

match

✓ from acoustid import match

✗ import pyacoustid

The package is named 'pyacoustid' but the importable module is 'acoustid'. Using 'pyacoustid' as import name will fail.

fingerprint_file

✓ from acoustid import fingerprint_file

Fingerprint an audio file and identify it via the Acoustid API.

import os from acoustid import match api_key = os.environ.get('ACOUSTID_API_KEY', 'YOUR_API_KEY') # Fingerprint an audio file and match against Acoustid database results = match(api_key, 'path/to/audio.mp3', parse=False) for score, recording_id, title, artist in results: print(f"{title} by {artist} (score: {score})")

Debug

Known issues

breakingVersion 1.3.0 dropped support for Python <3.10. If you are using Python 3.8 or 3.9, you must use pyacoustid <1.3.0.

fix

Upgrade Python to 3.10+ or pin pyacoustid to 1.2.x.

affects: >=1.3.0

gotchaThe 'chromaprint' binary/library must be installed separately. On Windows, the library is often not included and requires manual download or conda installation. Without it, fingerprinting fails silently or with obscure errors.

fix

Install chromaprint via system package manager (e.g., apt install libchromaprint-dev, brew install chromaprint) or download from https://acoustid.org/chromaprint.

affects: all

deprecatedThe 'fingerprint' function (not fingerprint_file) is deprecated as of 1.3.0. Use fingerprint_file or the new API instead.

fix

Replace calls to acoustid.fingerprint(...) with acoustid.fingerprint_file(...).

affects: >=1.3.0

gotchaAudio decoding depends on 'audioread' library, which may fail on certain formats (e.g., MP3 without ffmpeg). This leads to cryptic errors like 'Could not decode audio'.

fix

Install audioread with a backend like ffmpeg: pip install audioread[ffmpeg] or ensure ffmpeg is in PATH.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'acoustid'

Trying to import 'pyacoustid' instead of 'acoustid'.

fix

Use 'from acoustid import ...' not 'import pyacoustid'.

OSError: libchromaprint.so.1: cannot open shared object file

The chromaprint library is not installed on the system.

fix

Install it: on Debian/Ubuntu run 'apt install libchromaprint-dev', on macOS use 'brew install chromaprint', on Windows download the DLL.

Could not decode audio

The audio file cannot be read by audioread. Possibly missing ffmpeg or the file is corrupted.

fix

Install ffmpeg (e.g., 'apt install ffmpeg') and ensure it's in PATH. Alternatively, convert the file to WAV first.

acoustid.WebServiceError: Invalid API key

The API key provided to match() is invalid or not set.

fix

Register at https://acoustid.org/ to get a valid API key and set the ACOUSTID_API_KEY environment variable or pass it explicitly.

Upgrade

Version history

1.3.1latest on PyPI · released Apr 9, 2026

Audit

Dependencies

chromaprintrequiredRequired for fingerprinting; must be installed externally (e.g., via system package manager or downloaded binary).

audioreadoptionalRequired for decoding audio files into raw audio samples if not using file reading functions that accept file paths.

Agent activity

47 hits · last 30 days

node

Resources

githubhttps://github.com/beetbox/pyacoustid ↗

homepagehttps://github.com/beetbox/pyacoustid ↗