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

chroma
Use acoustic fingerprinting to identify audio files with missing or incorrect metadata.
discogs
Search for releases in the Discogs database.
spotify
Search for releases in the Spotify database.
deezer
Search for releases in the Deezer database.
fromfilename
Guess metadata for untagged tracks from their filenames.

Metadata

absubmit
Analyse audio with the streaming_extractor_music program and submit the metadata to an AcousticBrainz server
acousticbrainz
Fetch various AcousticBrainz metadata
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.
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-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
Is server implementation of the SubSonic API specification, 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-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-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.
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.
beets-youtube
Adds YouTube Music as a tagger data source.