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

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-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.

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.
