---
id: pyacoustid
version: "1.3.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# pyacoustid — Bindings for Chromaprint acoustic fingerprinting and the Acoustid API

License: permissive · Maintenance: active · Downloads: 119.6K/mo

## What it is and what it does

pyacoustid is a Python wrapper around Chromaprint, an open-source acoustic fingerprinting system, and the Acoustid Web service for music identification. It lets you generate a compact fingerprint from an audio file and look it up against Acoustid's database to retrieve metadata like title, artist, and MusicBrainz recording IDs. The package handles audio decoding via audioread and communicates with the Acoustid API via requests, abstracting away the complexity of working with raw fingerprints and HTTP calls.

You can use it at a high level with a single match call to identify a file, or drop down to lower-level functions to fingerprint raw PCM data, compare fingerprints, or submit new fingerprints to the database. The library enforces rate limiting (3 queries per second) when calling the Web API and raises specific exceptions for fingerprinting failures and lookup errors, making it straightforward to handle failures gracefully.

Use it for:

- Identify unknown music files by matching their acoustic fingerprint against the Acoustid database.
- Bulk-tag a music library with metadata (title, artist, recording ID) by fingerprinting each file.
- Compare two audio files for similarity without relying on file metadata or format.
- Submit new fingerprints to Acoustid to improve the database coverage for unrecognized tracks.
- Build a music recognition feature into an application using the Acoustid API.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides Python bindings for Chromaprint acoustic fingerprinting and the Acoustid Web service to identify music files by their audio content.

Yes. The package is actively maintained, has no known vulnerabilities, and low install friction. It fills a specific niche—acoustic music identification—with a clean API and permissive MIT license. Install it if you need to identify or match audio files; skip it if you only work with file metadata or don't need music recognition.

## Install

pip install pyacoustid
uv add pyacoustid
poetry add pyacoustid

## Installing pyacoustid

Before you install: Low friction install with a pure-wheel distribution. Actively maintained with recent commits and no known vulnerabilities. Requires Python 3.10+ and the external Chromaprint library or fpcalc command-line tool to be available on your system.

License in practice: MIT license permits commercial and private use with minimal restrictions, making it suitable for most projects.

Quickstart:

pip install pyacoustid

import pyacoustid
for score, recording_id, title, artist in pyacoustid.match(apikey, 'path/to/audio.mp3'):
    print(f"{title} by {artist} (score: {score})")

Requires Chromaprint library installed separately or fpcalc command-line tool on $PATH; set FPCALC environment variable if fpcalc is not in standard locations.

Verify before relying:

- Whether audioread's codec support (GStreamer, FFmpeg, MAD, Core Audio) covers your target audio formats.
- Performance characteristics when fingerprinting large audio files or batch processing.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 119.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

audio fingerprinting python, music identification acoustid, chromaprint bindings, identify songs from audio, acoustic fingerprint lookup, music metadata recognition, audio matching api, audio-fingerprinting, music-identification, metadata-lookup

[View on SkillFed](https://skillfed.io/packages/pyacoustid) · [View on PyPI](https://pypi.org/project/pyacoustid/)