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, like so:

plugins: 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: 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, like this:

pip install beets[fetchart,lyrics,lastgenre]

Using Metadata Source Plugins

Some plugins provide sources for metadata in addition to MusicBrainz. These plugins share the following configuration option:

  • source_weight: Penalty applied to matches during import. Set to 0.0 to disable. Default: 0.5.

For example, to equally consider matches from Discogs and MusicBrainz add the following to your configuration:

plugins: discogs

discogs:
   source_weight: 0.0

Autotagger Extensions

Metadata

Path Formats

  • AlbumTypes Plugin: Format album type in path formats.
  • Bucket Plugin: Group your files into bucket directories that cover different field values ranges.
  • Inline Plugin: Use Python snippets to customize path format strings.
  • Rewrite Plugin: Substitute values in path formats.
  • The Plugin: Move patterns in path formats (i.e., move “a” and “the” to the end).

Interoperability

Miscellaneous

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-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.
  • 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-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-importreplace lets you perform regex replacements on incoming metadata.
  • beets-mosaic generates a montage of a mosaic from cover art.
  • 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-popularity fetches popularity values from Spotify.
  • 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.
  • 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-yearfixer attempts to fix all missing original_year and year fields.