
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


Autotagger Extensions
=====================

* *Chromaprint/Acoustid Plugin*: Use acoustic fingerprinting to
  identify audio files with missing or incorrect metadata.

* *Discogs Plugin*: Search for releases in the Discogs database.

* *FromFilename Plugin*: Guess metadata for untagged tracks from
  their filenames.


Metadata
========

* *BPM Plugin*: Measure tempo using keystrokes.

* *Echo Nest Plugin*: Automatically fetch acoustic attributes from
  the Echo Nest (tempo, energy, danceability, ...).

* *EmbedArt Plugin*: Embed album art images into files' metadata.

* *FetchArt Plugin*: Fetch album cover art from various sources.

* *FtInTitle Plugin*: Move "featured" artists from the artist field
  to the title field.

* *Key Finder Plugin*: Use the KeyFinder program to detect the
  musical key from the audio.

* *ImportAdded Plugin*: Use file modification times for guessing the
  value for the *added* field in the database.

* *LastGenre Plugin*: Fetch genres based on Last.fm tags.

* *LastImport Plugin*: Collect play counts from Last.fm.

* *Lyrics Plugin*: Automatically fetch song lyrics.

* *MBSync Plugin*: Fetch updated metadata from MusicBrainz

* *MetaSync Plugin*: Fetch metadata from local or remote sources

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

* *ReplayGain Plugin*: Calculate volume normalization for players
  that support it.

* *Scrub Plugin*: Clean extraneous metadata from music files.

* *Zero Plugin*: Nullify fields by pattern or unconditionally.


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

* *ImportFeeds Plugin*: Keep track of imported files via ".m3u"
  playlist file(s) or symlinks.

* *MPDUpdate Plugin*: Automatically notifies MPD whenever the beets
  library changes.

* *Play Plugin*: Play beets queries in your music player.

* *PlexUpdate Plugin*: Automatically notifies Plex whenever the
  beets library changes.

* *Smart Playlist Plugin*: Generate smart playlists based on beets
  queries.

* *Thumbnails Plugin*: Get thumbnails with the cover art on your
  album folders.


Miscellaneous
=============

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

* *Convert Plugin*: Transcode music and embed album art while
  exporting to a different directory.

* *Duplicates Plugin*: List duplicate tracks or albums.

* *Fuzzy Search Plugin*: Search albums and tracks with fuzzy string
  matching.

* *IHate Plugin*: Automatically skip albums and tracks during the
  import process.

* *Info Plugin*: Print music files' tags to the console.

* *MusicBrainz Collection Plugin*: Maintain your MusicBrainz
  collection list.

* *Missing Plugin*: List missing tracks.

* *Random Plugin*: Randomly choose albums and tracks from your
  library.

* *FileFilter Plugin*: Automatically skip files during the import
  process based on regular expressions.

* *Spotify Plugin*: Create Spotify playlists from the Beets library.

* *Types Plugin*: Declare types for flexible attributes.

* *Web Plugin*: 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:

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

* A cmus plugin integrates with the cmus console music player.

* beets-artistcountry fetches the artist's country of origin from
  MusicBrainz.

* dsedivec has two plugins: "edit" and "moveall".

* beet-amazon adds Amazon.com as a tagger data source.

* copyartifacts helps bring non-music files along during import.

* beets-check automatically checksums your files to detect
  corruption.

* beets-alternatives manages external files.

* beets-follow lets you check for new albums from artists you like.

* beets-setlister generate playlists from the setlists of a given
  artist
