Skip to main content
`Ctrl`+`K`

# Chromaprint/Acoustid Plugin

Acoustic fingerprinting is a technique for identifying songs from the way they “sound” rather from their existing metadata. That means that beets’ autotagger can theoretically use fingerprinting to tag files that don’t have any ID3 information at all (or have completely incorrect data). This plugin uses an open-source fingerprinting technology called Chromaprint and its associated Web service, called Acoustid.

Turning on fingerprinting can increase the accuracy of the autotagger—especially on files with very poor metadata—but it comes at a cost. First, it can be trickier to set up than beets itself (you need to set up the native fingerprinting library, whereas all of the beets core is written in pure Python). Also, fingerprinting takes significantly more CPU and memory than ordinary tagging—which means that imports will go substantially slower.

If you’re willing to pay the performance cost for fingerprinting, read on!

## Installing Dependencies

To get fingerprinting working, you’ll need to install three things:

1. pyacoustid Python library (version 0.6 or later). You can install it by installing `beets` with `chroma` extra

    pip install "beets[chroma]"

2. the Chromaprint library or command line tool

3. an audio decoder

### Installing the Binary Command-Line Tool

The simplest way to get up and running, especially on Windows, is to download the appropriate Chromaprint binary package and place the `fpcalc` (or `fpcalc.exe`) on your shell search path. On Windows, this means something like `C:\\Program Files`. On OS X or Linux, put the executable somewhere like `/usr/local/bin`.

### Installing the Library

On OS X and Linux, you can also use a library installed by your package manager, which has some advantages (automatic upgrades, etc.). The Chromaprint site has links to packages for major Linux distributions. If you use Homebrew on Mac OS X, you can install the library with `brew install chromaprint`.

### Audio Decoder

You will also need a mechanism for decoding audio files supported by the audioread library:

- OS X has a number of decoders already built into Core Audio, so there’s no need to install anything.

- On Linux, you can install GStreamer with PyGObject, FFmpeg, or MAD with pymad. How you install these will depend on your distribution. For example, on Ubuntu, run `apt-get install gstreamer1.0 python-gi`. On Arch Linux, you want `pacman -S gstreamer python2-gobject`. If you use GStreamer, be sure to install its codec plugins also (`gst-plugins-good`, etc.).

  Note that if you install beets in a virtualenv, you’ll need it to have `--system-site-packages` enabled for Python to see the GStreamer bindings.

- On Windows, builds are provided by GStreamer

To decode audio formats (MP3, FLAC, etc.) with GStreamer, you’ll need the standard set of Gstreamer plugins. For example, on Ubuntu, install the packages `gstreamer1.0-plugins-good`, `gstreamer1.0-plugins-bad`, and `gstreamer1.0-plugins-ugly`.

## Usage

Once you have all the dependencies sorted out, enable the `chroma` plugin in your configuration (see Using Plugins) to benefit from fingerprinting the next time you run `beet import`. (The plugin doesn’t produce any obvious output by default. If you want to confirm that it’s enabled, you can try running in verbose mode once with `beet -v import`.)

You can also use the `beet fingerprint` command to generate fingerprints for items already in your library. (Provide a query to fingerprint a subset of your library.) The generated fingerprints will be stored in the library database. If you have the `import.write` config option enabled, they will also be written to files’ metadata.

Note

The `chroma` plugin turns Acoustid fingerprint matches into autotagger candidates by resolving them through the MusicBrainz Plugin plugin, so you need to enable `musicbrainz` alongside `chroma` to get album and track candidates from acoustid lookups. If `musicbrainz` is not enabled, the `chroma` plugin will still fingerprint your files and store the `acoustid_id` and `acoustid_fingerprint` fields, but it will not contribute candidates during autotagging.

## Configuration

There is one configuration option in the `chroma:` section, `auto`, which controls whether to fingerprint files during the import process. To disable fingerprint-based autotagging, set it to `no`, like so:

    chroma:
        auto: no

## Submitting Fingerprints

You can help expand the Acoustid database by submitting fingerprints for the music in your collection. To do this, first get an API key from the Acoustid service. Just use an OpenID or MusicBrainz account to log in and you’ll get a short token string. Then, add the key to your `config.yaml` as the value `apikey` in a section called `acoustid` like so:

    acoustid:
        apikey: AbCd1234

Then, run `beet submit`. (You can also provide a query to submit a subset of your library.) The command will use stored fingerprints if they’re available; otherwise it will fingerprint each file before submitting it.

## Fingerprint Search

The `chromasearch` command lets you search your local beets library for tracks with similar audio fingerprints. This is useful for identifying duplicate files, finding alternate encodings of the same recording, or locating tracks when metadata is missing or incorrect.

To perform a search, run:

    beet chromasearch -s FINGERPRINT

The fingerprint must be provided using the `-s` (`--search`) option. You can generate a fingerprint using the external `fpcalc` tool from the Chromaprint project. For example:

    fpcalc -plain somefile.mp3

By default the whole library is searched, use a query to restrict the search:

    beet chromasearch -s FINGERPRINT artist:"rolling stones"

By default, the command returns the top 5 closest matches in your library. You can change the number of results using the `-c` (`--count`) option.

When an exact match is found, the search normally stops early. To continue searching for additional similar items even after an exact match, use the `--full` flag.

The `-w` (`--write`) option causes the plugin to store fingerprints for files that do not already have them. This can improve search results over time by ensuring more items in your library are indexed.