Skip to main content
`Ctrl`+`K`

# Plugins

Plugins extend beets’ core functionality. They add new commands, fetch additional data during import, provide new metadata sources, and much more. If beets by itself doesn’t do what you want it to, you may just need to enable a plugin—or, if you want to do something new, writing a plugin is easy if you know a little Python.

## Using Plugins

To use one of the plugins included with beets (see the rest of this page for a list), just use the `plugins` option in your config.yaml file:

    plugins: musicbrainz inline convert web

The value for `plugins` can be a space-separated list of plugin names or a YAML list like `[foo, bar]`. You can see which plugins are currently enabled by typing `beet version`.

Each plugin has its own set of options that can be defined in a section bearing its name:

    plugins: musicbrainz inline convert web

    convert:
        auto: true

Some plugins have special dependencies that you’ll need to install. The documentation page for each plugin will list them in the setup instructions. For some, you can use `pip`’s “extras” feature to install the dependencies:

    pip install "beets[fetchart,lyrics,lastgenre]"

## Using Metadata Source Plugins

We provide several Autotagger Extensions that fetch metadata from online databases. They share the following configuration options:

- data_source_mismatch_penalty: Penalty applied when the data source of a match candidate differs from the original source of your existing tracks. Any decimal number between 0.0 and 1.0. Default: `0.5`.

  This setting controls how much to penalize matches from different metadata sources during import. The penalty is applied when beets detects that a match candidate comes from a different data source than what appears to be the original source of your music collection.

  Example configurations:

      # Prefer MusicBrainz over Discogs when sources don't match
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.3  # Lower penalty = preferred
      discogs:
          data_source_mismatch_penalty: 0.8  # Higher penalty = less preferred

      # Do not penalise candidates from Discogs at all
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.5
      discogs:
          data_source_mismatch_penalty: 0.0

      # Disable cross-source penalties entirely
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.0
      discogs:
          data_source_mismatch_penalty: 0.0

  Tip

  The last configuration is equivalent to setting:

      match:
          distance_weights:
              data_source: 0.0  # Disable data source matching

- source_weight

  Deprecated since version 2.5: Use data_source_mismatch_penalty instead.

- search_limit: Maximum number of search results to consider. Default: `5`.

## Autotagger Extensions

chroma

  Use acoustic fingerprinting to identify audio files with missing or incorrect metadata.

deezer

  Search for releases in the Deezer database.

discogs

  Search for releases in the Discogs database.

fromfilename

  Guess metadata for untagged tracks from their filenames.

musicbrainz

  Search for releases in the MusicBrainz database.

spotify

  Search for releases in the Spotify database.

## Metadata

absubmit

  Analyse audio with the streaming_extractor_music program and submit the metadata to an AcousticBrainz server

acousticbrainz

  Fetch various AcousticBrainz metadata

autobpm

  Use Librosa to calculate the BPM from the audio.

bpm

  Measure tempo using keystrokes.

bpsync

  Fetch updated metadata from Beatport.

edit

  Edit metadata from a text editor.

embedart

  Embed album art images into files’ metadata.

fetchart

  Fetch album cover art from various sources.

ftintitle

  Move “featured” artists from the artist field to the title field.

keyfinder

  Use the KeyFinder program to detect the musical key from the audio.

importadded

  Use file modification times for guessing the value for the `added` field in the database.

lastgenre

  Fetch genres based on Last.fm tags.

lastimport

  Collect play counts from Last.fm.

lyrics

  Automatically fetch song lyrics.

mbsync

  Fetch updated metadata from MusicBrainz.

metasync

  Fetch metadata from local or remote sources

mpdstats

  Connect to MPD and update the beets library with play statistics (last_played, play_count, skip_count, rating).

parentwork

  Fetch work titles and works they are part of.

replaygain

  Calculate volume normalization for players that support it.

scrub

  Clean extraneous metadata from music files.

zero

  Nullify fields by pattern or unconditionally.

## Path Formats

albumtypes

  Format album type in path formats.

bucket

  Group your files into bucket directories that cover different field values ranges.

inline

  Use Python snippets to customize path format strings.

rewrite

  Substitute values in path formats.

advancedrewrite

  Substitute field values for items matching a query.

substitute

  As an alternative to rewrite, use this plugin. The main difference between them is that this plugin never modifies the files metadata.

the

  Move patterns in path formats (i.e., move “a” and “the” to the end).

## Interoperability

aura

  A server implementation of the AURA specification.

badfiles

  Check audio file integrity.

embyupdate

  Automatically notifies Emby whenever the beets library changes.

fish

  Adds Fish shell tab autocompletion to `beet` commands.

importfeeds

  Keep track of imported files via `.m3u` playlist file(s) or symlinks.

ipfs

  Import libraries from friends and get albums from them via ipfs.

kodiupdate

  Automatically notifies Kodi whenever the beets library changes.

mpdupdate

  Automatically notifies MPD whenever the beets library changes.

play

  Play beets queries in your music player.

playlist

  Use M3U playlists to query the beets library.

plexupdate

  Automatically notifies Plex whenever the beets library changes.

smartplaylist

  Generate smart playlists based on beets queries.

sonosupdate

  Automatically notifies Sonos whenever the beets library changes.

thumbnails

  Get thumbnails with the cover art on your album folders.

subsonicupdate

  Automatically notifies Subsonic whenever the beets library changes.

## Miscellaneous

bareasc

  Search albums and tracks with bare ASCII string matching.

bpd

  A music player for your beets library that emulates MPD and is compatible with MPD clients.

convert

  Transcode music and embed album art while exporting to a different directory.

duplicates

  List duplicate tracks or albums.

export

  Export data from queries to a format.

filefilter

  Automatically skip files during the import process based on regular expressions.

fuzzy

  Search albums and tracks with fuzzy string matching.

hook

  Run a command when an event is emitted by beets.

ihate

  Automatically skip albums and tracks during the import process.

info

  Print music files’ tags to the console.

loadext

  Load SQLite extensions.

mbcollection

  Maintain your MusicBrainz collection list.

mbsubmit

  Print an album’s tracks in a MusicBrainz-friendly format.

missing

  List missing tracks.

mstream

  A music streaming server + webapp that can be used alongside beets.

random

  Randomly choose albums and tracks from your library.

spotify

  Create Spotify playlists from the Beets library.

types

  Declare types for flexible attributes.

web

  An experimental Web-based GUI for beets.

## Other Plugins

In addition to the plugins that come with beets, there are several plugins that are maintained by the beets community. To use an external plugin, there are two options for installation:

- Make sure it’s in the Python path (known as `sys.path` to developers). This just means the plugin has to be installed on your system (e.g., with a `setup.py` script or a command like `pip` or `easy_install`).

- Set the `pluginpath` config variable to point to the directory containing the plugin. (See Configuration.)

Once the plugin is installed, enable it by placing its name on the `plugins` line in your config file.

Here are a few of the plugins written by the beets community:

beets-alternatives

  Manages external files.

beet-amazon

  Adds Amazon.com as a tagger data source.

beets-artistcountry

  Fetches the artist’s country of origin from MusicBrainz.

beets-autofix

  Automates repetitive tasks to keep your library in order.

beets-autogenre

  Assigns genres to your library items using the lastgenre and beets-xtractor plugins as well as additional rules.

beets-audible

  Adds Audible as a tagger data source and provides other features for managing audiobook collections.

beets-barcode

  Lets you scan or enter barcodes for physical media to search for their metadata.

beetcamp

  Enables bandcamp.com autotagger with a fairly extensive amount of metadata.

beetstream

  Server implementation of the Subsonic API specification, serving the beets library and (smartplaylist plugin generated) M3U playlists, allowing you to stream your music on a multitude of clients.

beets-bpmanalyser

  Analyses songs and calculates their tempo (BPM).

beets-check

  Automatically checksums your files to detect corruption.

A cmus plugin

  Integrates with the cmus console music player.

beets-copyartifacts

  Helps bring non-music files along during import.

beets-describe

  Gives you the full picture of a single attribute of your library items.

drop2beets

  Automatically imports singles as soon as they are dropped in a folder (using Linux’s `inotify`). You can also set a sub-folders hierarchy to set flexible attributes by the way.

dsedivec

  Has two plugins: `edit` and `moveall`.

beets-filetote

  Helps bring non-music extra files, attachments, and artifacts during imports and CLI file manipulation actions (`beet move`, etc.).

beets-follow

  Lets you check for new albums from artists you like.

beetFs

  Is a FUSE filesystem for browsing the music in your beets library. (Might be out of date.)

beets-goingrunning

  Generates playlists to go with your running sessions.

beets-ibroadcast

  Uploads tracks to the iBroadcast cloud service.

beets-id3extract

  Maps arbitrary ID3 tags to beets custom fields.

beets-importreplace

  Lets you perform regex replacements on incoming metadata.

beets-jiosaavn

  Adds JioSaavn.com as a tagger data source.

beets-more

  Finds versions of indexed releases with more tracks, like deluxe and anniversary editions.

beets-mosaic

  Generates a montage of a mosaic from cover art.

beets-mpd-utils

  Plugins to interface with MPD. Comes with `mpd_tracker` (track play/skip counts from MPD) and `mpd_dj` (auto-add songs to your queue.)

beets-noimport

  Adds and removes directories from the incremental import skip list.

beets-originquery

  Augments MusicBrainz queries with locally-sourced data to improve autotagger results.

beets-plexsync

  Allows you to sync your Plex library with your beets library, create smart playlists in Plex, and import online playlists (from services like Spotify) into Plex.

beets-setlister

  Generate playlists from the setlists of a given artist.

beet-summarize

  Can compute lots of counts and statistics about your music library.

beets-usertag

  Lets you use keywords to tag and organize your music.

beets-webm3u

  Serves the (smartplaylist plugin generated) M3U playlists via HTTP.

beets-webrouter

  Serves multiple beets webapps (e.g. web, beets-webm3u, beetstream, aura) using a single command/process/host/port, each under a different path.

whatlastgenre

  Fetches genres from various music sites.

beets-xtractor

  Extracts low- and high-level musical information from your songs.

beets-ydl

  Downloads audio from youtube-dl sources and import into beets.

beets-ytimport

  Download and import your liked songs from YouTube into beets.

beets-yearfixer

  Attempts to fix all missing `original_year` and `year` fields.

beets-youtube

  Adds YouTube Music as a tagger data source.