mirror of
https://github.com/beetbox/beets.git
synced 2025-12-27 02:52:33 +01:00
3eb6f8e5eb
This is a refactor of the plugin developed by `imenem`. - Pass `artist`, `album` and `va_likely` to `candidates()` so that plugins don't have to work this out from `items` all over again. - Pass `artist` and `title` to `item_candidates()`. - Silence spurious `urllib3` info log lines. - Use a proper "beets" user agent with `discogs_client`. - Remove `abstract_search` plugin. It seems unnecessary. How many music databases are there? How many will beets support? How much common code might there be between them? We can add some abstraction if or when more databases are supported. - Derive more AlbumInfo and TrackInfo properties from discogs Release objects, especially album ID so that beets doesn't just use the first release and think all subsequent releases are duplicates. - Add basic documentation, doc strings and code comments. - Sanitise search query. Remove non-word characters and medium info that might filter out good search results. - Use artist `join` strings from discogs Release object when an album or track has multiple artists. - Don't rely on discogs track position, which is unreliable. But tracks are in order, so we can recalculate medium and medium_index as long as we can extract a consistent medium across tracks from the position. - Add "various" as a known signal to indicate various artists. - Prevent `chroma` plugin from returning a a huge track distance for any track that is missing an ID (e.g. all discog tracks). - `TrackInfo.index` should be the release index (calculated by beets), not the medium index (derived from discogs track position). - Add `AlbumInfo.data_source`. It's "Unknown" by default which is shown in red when displaying a suggested or selected match. The built in auto tagger sets it to "MusicBrainz" which is shown in green. Anything else (e.g. "Discogs") is shown in yellow. - Remove double spaces from album titles (bad data from Discogs).
153 lines
4.4 KiB
ReStructuredText
153 lines
4.4 KiB
ReStructuredText
Plugins
|
|
=======
|
|
|
|
Plugins can extend beets' core functionality. Plugins can add new commands to
|
|
the command-line interface, respond to events in beets, augment the autotagger,
|
|
or provide new path template functions.
|
|
|
|
Using Plugins
|
|
-------------
|
|
|
|
To use a plugin, you have two options:
|
|
|
|
* 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 :doc:`/reference/cli`.)
|
|
|
|
Then, set the `plugins` option in your `config.yaml` file, like so::
|
|
|
|
plugins: mygreatplugin someotherplugin
|
|
|
|
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``.
|
|
|
|
.. _included-plugins:
|
|
|
|
Plugins Included With Beets
|
|
---------------------------
|
|
|
|
There are a few plugins that are included with the beets distribution. They're
|
|
disabled by default, but you can turn them on as described above.
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
chroma
|
|
lyrics
|
|
echonest_tempo
|
|
bpd
|
|
mpdupdate
|
|
fetchart
|
|
embedart
|
|
web
|
|
lastgenre
|
|
replaygain
|
|
inline
|
|
scrub
|
|
rewrite
|
|
random
|
|
mbcollection
|
|
importfeeds
|
|
the
|
|
fuzzy
|
|
zero
|
|
ihate
|
|
convert
|
|
info
|
|
smartplaylist
|
|
mbsync
|
|
missing
|
|
discogs
|
|
|
|
Autotagger Extensions
|
|
''''''''''''''''''''''
|
|
|
|
* :doc:`chroma`: Use acoustic fingerprinting to identify audio files with
|
|
missing or incorrect metadata.
|
|
* :doc:`discogs`: Search for releases in the discogs database.
|
|
|
|
Metadata
|
|
''''''''
|
|
|
|
* :doc:`lyrics`: Automatically fetch song lyrics.
|
|
* :doc:`echonest_tempo`: Automatically fetch song tempos (bpm).
|
|
* :doc:`lastgenre`: Fetch genres based on Last.fm tags.
|
|
* :doc:`mbsync`: Fetch updated metadata from MusicBrainz
|
|
* :doc:`fetchart`: Fetch album cover art from various sources.
|
|
* :doc:`embedart`: Embed album art images into files' metadata.
|
|
* :doc:`replaygain`: Calculate volume normalization for players that support it.
|
|
* :doc:`scrub`: Clean extraneous metadata from music files.
|
|
* :doc:`zero`: Nullify fields by pattern or unconditionally.
|
|
|
|
Path Formats
|
|
''''''''''''
|
|
|
|
* :doc:`inline`: Use Python snippets to customize path format strings.
|
|
* :doc:`rewrite`: Substitute values in path formats.
|
|
* :doc:`the`: Move patterns in path formats (i.e., move "a" and "the" to the
|
|
end).
|
|
|
|
Interoperability
|
|
''''''''''''''''
|
|
|
|
* :doc:`mpdupdate`: Automatically notifies `MPD`_ whenever the beets library
|
|
changes.
|
|
* :doc:`importfeeds`: Keep track of imported files via ``.m3u`` playlist file(s) or symlinks.
|
|
* :doc:`smartplaylist`: Generate smart playlists based on beets queries.
|
|
|
|
Miscellaneous
|
|
'''''''''''''
|
|
|
|
* :doc:`web`: An experimental Web-based GUI for beets.
|
|
* :doc:`random`: Randomly choose albums and tracks from your library.
|
|
* :doc:`fuzzy`: Search albums and tracks with fuzzy string matching.
|
|
* :doc:`mbcollection`: Maintain your MusicBrainz collection list.
|
|
* :doc:`ihate`: Automatically skip albums and tracks during the import process.
|
|
* :doc:`bpd`: A music player for your beets library that emulates `MPD`_ and is
|
|
compatible with `MPD clients`_.
|
|
* :doc:`convert`: Transcode music and embed album art while exporting to
|
|
a different directory.
|
|
* :doc:`info`: Print music files' tags to the console.
|
|
* :doc:`missing`: List missing tracks.
|
|
|
|
.. _MPD: http://mpd.wikia.com/
|
|
.. _MPD clients: http://mpd.wikia.com/wiki/Clients
|
|
|
|
.. _other-plugins:
|
|
|
|
Other Plugins
|
|
-------------
|
|
|
|
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.
|
|
|
|
* `featInTitle`_ moves featured artists from the artist tag to the title tag.
|
|
|
|
.. _beetFs: http://code.google.com/p/beetfs/
|
|
.. _Beet-MusicBrainz-Collection:
|
|
https://github.com/jeffayle/Beet-MusicBrainz-Collection/
|
|
.. _A cmus plugin:
|
|
https://github.com/coolkehon/beets/blob/master/beetsplug/cmus.py
|
|
.. _cmus: http://cmus.sourceforge.net/
|
|
.. _featInTitle: https://github.com/Verrus/beets-plugin-featInTitle/
|
|
|
|
Writing Plugins
|
|
---------------
|
|
|
|
If you know a little Python, you can write your own plugin to do almost anything
|
|
you can imagine with your music collection. See the :doc:`guide to writing beets
|
|
plugins </plugins/writing>`.
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
writing
|