Backup_Repos/beets
1
0
Fork 0
mirror of https://github.com/beetbox/beets.git synced 2025-12-25 01:53:31 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1047 from sampsyo/docs_overhaul

Browse source 
Docs overhaul
This commit is contained in:
Adrian Sampson 2014-10-31 14:27:43 -07:00
commit 0773d47180
43 changed files with 754 additions and 776 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/Makefile
View file

@ -17,7 +17,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest auto
help:
@echo "Please use \`make <target>' where <target> is one of"
@ -38,6 +38,10 @@ help:
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
# My magical rebuilding, Safari-reloading auto target.
auto:
watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='if [ "$${watch_event_type}" == "created" -o "$${watch_event_type}" == "modified" ]; then make html ; osascript -l JavaScript refresh_safari.js; fi' --wait
clean:
-rm -rf $(BUILDDIR)/*

14
docs/changelog.rst
View file

@ -593,7 +593,7 @@ As usual, there are also innumerable little fixes and improvements:
* :doc:`/plugins/missing`: Avoid a possible error when an album's
``tracktotal`` field is missing.
* :doc:`/plugins/ftintitle`: Fix an error when the sort artist is missing.
* :doc:`/plugins/echonest_tempo`: The plugin should now match songs more
* ``echonest_tempo``: The plugin should now match songs more
reliably (i.e., fewer "no tempo found" messages). Thanks to Peter Schnebel.
* :doc:`/plugins/convert`: Fix an "Item has no library" error when using the
``auto`` config option.
@ -659,7 +659,7 @@ And some fixes:
(instead of failing with an API error).
* :doc:`/plugins/info`: Fail gracefully when used erroneously with a
directory.
* :doc:`/plugins/echonest_tempo`: Fix an issue where the plugin could use the
* ``echonest_tempo``: Fix an issue where the plugin could use the
tempo from the wrong song when the API did not contain the requested song.
* Fix a crash when a file's metadata included a very large number (one wider
than 64 bits). These huge numbers are now replaced with zeroes in the
@ -1015,7 +1015,7 @@ Other stuff:
* :doc:`/plugins/chroma`: A new ``fingerprint`` command lets you generate and
store fingerprints for items that don't yet have them. One more round of
applause for Lucas Duailibe.
* :doc:`/plugins/echonest_tempo`: API errors now issue a warning instead of
* ``echonest_tempo``: API errors now issue a warning instead of
exiting with an exception. We also avoid an error when track metadata
contains newlines.
* When the importer encounters an error (insufficient permissions, for
@ -1039,7 +1039,7 @@ Other stuff:
import command. Thanks to Lucas Duailibe.
* :doc:`/plugins/mbcollection`: Show friendly, human-readable errors when
MusicBrainz exceptions occur.
* :doc:`/plugins/echonest_tempo`: Catch socket errors that are not handled by
* ``echonest_tempo``: Catch socket errors that are not handled by
the Echo Nest library.
* :doc:`/plugins/chroma`: Catch Acoustid Web service errors when submitting
fingerprints.
@ -1138,7 +1138,7 @@ Other new stuff:
Dang Mai Hai.
* :doc:`/plugins/bpd`: Browse by album artist and album artist sort name.
Thanks to Steinþór Pálsson.
* :doc:`/plugins/echonest_tempo`: Don't attempt a lookup when the artist or
* ``echonest_tempo``: Don't attempt a lookup when the artist or
track title is missing.
* Fix an error when migrating the ``.beetsstate`` file on Windows.
* A nicer error message is now given when the configuration file contains tabs.
@ -1204,7 +1204,7 @@ This second release candidate follows quickly after rc1 and fixes a few small
bugs found since that release. There were a couple of regressions and some bugs
in a newly added plugin.
* :doc:`/plugins/echonest_tempo`: If the Echo Nest API limit is exceeded or a
* ``echonest_tempo``: If the Echo Nest API limit is exceeded or a
communication error occurs, the plugin now waits and tries again instead of
crashing. Thanks to Zach Denton.
* :doc:`/plugins/fetchart`: Fix a regression that caused crashes when art was
@ -1234,7 +1234,7 @@ begins today on features for version 1.1.
* New plugin: :doc:`/plugins/fuzzy` lets you find albums and tracks
using **fuzzy string matching** so you don't have to type (or even remember)
their exact names. Thanks to Philippe Mongeau.
* New plugin: :doc:`/plugins/echonest_tempo` fetches **tempo** (BPM) information
* New plugin: ``echonest_tempo`` fetches **tempo** (BPM) information
from `The Echo Nest`_. Thanks to David Brenner.
* New plugin: :doc:`/plugins/the` adds a template function that helps format
text for nicely-sorted directory listings. Thanks to Blemjhoo Tezoulbr.

4
docs/plugins/beatport.rst
View file

@ -18,8 +18,8 @@ both MusicBrainz and (to a lesser degree) Discogs show no matches.
Installation
------------
To see matches from the ``beatport`` plugin, you first have to enable it in
your configuration (see :doc:`/plugins/index`). Then, install the `requests`_
To use the ``beatport`` plugin, first enable it in your configuration (see
:ref:`using-plugins`). Then, install the `requests`_
library (which we need for querying the Beatport API) by typing::
pip install requests

42
docs/plugins/bpd.rst
View file

@ -38,13 +38,11 @@ installing GStreamer plugins.
.. _GStreamer WinBuilds: http://www.gstreamer-winbuild.ylatuya.es/
.. _Homebrew: http://mxcl.github.com/homebrew/
Using and Configuring
---------------------
BPD is a plugin for beets. It comes with beets, but it's disabled by default.
To enable it, you'll need to edit your :doc:`configuration file
</reference/config>` and add ``bpd`` to your ``plugins:`` line.
Usage
-----
To use the ``bpd`` plugin, first enable it in your configuration (see
:ref:`using-plugins`).
Then, you can run BPD by invoking::
$ beet bpd
@ -69,10 +67,22 @@ the client can just as easily on a different computer from the server as it can
be run locally. Control your music from your laptop (or phone!) while it plays
on your headless server box. Rad!
To configure the BPD server, add a ``bpd:`` section to your ``config.yaml``
file. The configuration values, which are pretty self-explanatory, are ``host``,
``port``, ``password`` and ``volume``. The volume option sets the initial
volume (in percent, default: 100). Here's an example::
Configuration
-------------
To configure the plugin, make a ``bpd:`` section in your configuration file.
The available options are:
- ``host``:
Default: Bind to all interfaces.
- ``port``:
Default: 6600
- ``password``:
Default: No password.
- ``volume``: Initial volume, as a percentage.
Default: 100
Here's an example::
bpd:
host: 127.0.0.1
@ -83,13 +93,13 @@ volume (in percent, default: 100). Here's an example::
Implementation Notes
--------------------
In the real MPD, the user can browse a music directory as it appears on disk. In
beets, we like to abstract away from the directory structure. Therefore, BPD
In the real MPD, the user can browse a music directory as it appears on disk.
In beets, we like to abstract away from the directory structure. Therefore, BPD
creates a "virtual" directory structure (artist/album/track) to present to
clients. This is static for now and cannot be reconfigured like the real on-disk
directory structure can. (Note that an obvious solution to this is just string
matching on items' destination, but this requires examining the entire library
Python-side for every query.)
clients. This is static for now and cannot be reconfigured like the real
on-disk directory structure can. (Note that an obvious solution to this is just
string matching on items' destination, but this requires examining the entire
library Python-side for every query.)
We don't currently support versioned playlists. Many clients, however, use
plchanges instead of playlistinfo to get the current playlist, so plchanges

19
docs/plugins/bpm.rst
View file

@ -1,22 +1,29 @@
BPM Plugin
==========
This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by tapping out the beat on your keyboard.
This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by
tapping out the beat on your keyboard.
Usage
-----
First, enable the plugin ``bpm`` as described in :doc:`/plugins/index`. Then, play a song you want to measure in your favorite media player and type::
To use the ``bpm`` plugin, first enable it in your configuration (see
:ref:`using-plugins`).
beet bpm <song>
Then, play a song you want to measure in your favorite media player and type::
You'll be prompted to press Enter three times to the rhythm. This typically allows to determine the BPM within 5% accuracy.
beet bpm <song>
The plugin works best if you wrap it in a script that gets the playing song. for instance, with ``mpc`` you can do something like::
You'll be prompted to press Enter three times to the rhythm. This typically
allows to determine the BPM within 5% accuracy.
The plugin works best if you wrap it in a script that gets the playing song.
for instance, with ``mpc`` you can do something like::
beet bpm $(mpc |head -1|tr -d "-")
Credit
------
This plugin is inspired by a similar feature present in the Banshee media player.
This plugin is inspired by a similar feature present in the Banshee media
player.

51
docs/plugins/bucket.rst
View file

@ -1,5 +1,5 @@
Bucket Plugin
==============
=============
The ``bucket`` plugin groups your files into buckets folders representing
*ranges*. This kind of organization can classify your music by periods of time
@ -7,8 +7,9 @@ The ``bucket`` plugin groups your files into buckets folders representing
smaller subfolders by grouping albums or artists alphabetically (e.g. *A-F*,
*G-M*, *N-Z*).
To use the plugin, enable ``bucket`` in your configuration file (see
:ref:`using-plugins`). The plugin provides a :ref:`template function
To use the ``bucket`` plugin, first enable it in your configuration (see
:ref:`using-plugins`).
The plugin provides a :ref:`template function
<template-functions>` called ``%bucket`` for use in path format expressions::
paths:
@ -25,25 +26,45 @@ The ``bucket_year`` parameter is used for all substitutions occuring on the
The definition of a range is somewhat loose, and multiple formats are allowed:
- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise) alphanumeric characters in the string you provide. For example, *ABCD*, *A-D*, *A->D*, and *[AD]* are all equivalent.
- For year ranges: digits characters are extracted and the two extreme years define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are equivalent. If no upper bound is given, the range is extended to current year (unless a later range is defined). For example, *1975* encompasses all years from 1975 until now.
- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise)
alphanumeric characters in the string you provide. For example, *ABCD*,
*A-D*, *A->D*, and *[AD]* are all equivalent.
- For year ranges: digits characters are extracted and the two extreme years
define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are
equivalent. If no upper bound is given, the range is extended to current year
(unless a later range is defined). For example, *1975* encompasses all years
from 1975 until now.
If you want to group your files into multiple year ranges, you don't have to
enumerate them all in `bucket_year` parameter but can activate the ``extrapolate``
option instead. This option will generate year bucket names by reproducing characteristics
of declared buckets::
Configuration
-------------
bucket:
bucket_year: ['2000-05']
extrapolate: true
To configure the plugin, make a ``bucket:`` section in your configuration file.
The available options are:
The above configuration creates five-year ranges for any input year.
- ``bucket_alpha``: Ranges to use for all substitutions occurring on textual
fields.
Default: none.
- ``bucket_alpha_regex``: A ``range: regex`` mapping (one per line) where
``range`` is one of the `bucket_alpha` range and ``value`` is a regex that
override original range definition.
Default: none.
- ``bucket_year``: Ranges to use for all substitutions occurring on the
`$year` field.
Default: none.
- ``extrapolate``: Enable this if you want to group your files into multiple
year ranges without enumerating them all. This option will generate year
bucket names by reproducing characteristics of declared buckets.
Default: ``no``
If the automatic range of an alpha bucket is not sufficient an overriding regular expression can be used::
Here's an example::
bucket:
bucket_year: ['2000-05']
extrapolate: true
bucket_alpha: ['A - D', 'E - L', 'M - R', 'S - Z']
bucket_alpha_regex:
'A - D': ^[0-9a-dA-D…äÄ]
The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 and … (three dots). The other buckets work as ranges (see above).
This configuration creates five-year ranges for any input year.
The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9
and … (ellipsis). The other alpha buckets work as ranges.

31
docs/plugins/chroma.rst
View file

@ -65,10 +65,10 @@ You will also need a mechanism for decoding audio files supported by the
need to install anything.
* On Linux, you can install `GStreamer for Python`_, `FFmpeg`_, or `MAD`_ and
`pymad`_. How you install these will depend on your distribution. For example,
on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch Linux, you want
``pacman -S gstreamer0.10-python``. If you use GStreamer, be sure to install
its codec plugins also.
`pymad`_. How you install these will depend on your distribution.
For example, on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch
Linux, you want ``pacman -S gstreamer0.10-python``. If you use GStreamer, be
sure to install its codec plugins also.
* On Windows, try the Gstreamer "WinBuilds" from the `OSSBuild`_ project.
@ -87,13 +87,12 @@ standard set of Gstreamer plugins. For example, on Ubuntu, install the packages
``gstreamer0.10-plugins-good``, ``gstreamer0.10-plugins-bad``, and
``gstreamer0.10-plugins-ugly``.
Using
Usage
-----
Once you have all the dependencies sorted out, you can enable fingerprinting by
editing your :doc:`configuration file </reference/config>`. Put ``chroma`` on
your ``plugins:`` line. With that, beets will use fingerprinting the next time
you run ``beet import``.
Once you have all the dependencies sorted out, enable the ``chroma`` plugin in
your configuration (see :ref:`using-plugins`) to benefit from fingerprinting
the next time you run ``beet import``.
You can also use the ``beet fingerprint`` command to generate fingerprints for
items already in your library. (Provide a query to fingerprint a subset of your
@ -101,16 +100,20 @@ library.) The generated fingerprints will be stored in the library database.
If you have the ``import.write`` config option enabled, they will also be
written to files' metadata.
You can disable fingerprinting on import by setting the ``auto`` option to
false, like so::
.. _submitfp:
Configuration
-------------
There is one configuration option in the ``chroma:`` section, ``auto``, which
controls whether to fingerprint files during the import process. To disable
fingerprint-based autotagging, set it to ``no``, like so::
chroma:
auto: no
.. _submitfp:
Submitting Fingerprints
'''''''''''''''''''''''
-----------------------
You can help expand the `Acoustid`_ database by submitting fingerprints for the
music in your collection. To do this, first `get an API key`_ from the Acoustid

68
docs/plugins/convert.rst
View file

@ -10,8 +10,8 @@ line.
Installation
------------
Enable the ``convert`` plugin in your configuration (see
:doc:`/plugins/index`). By default, the plugin depends on `FFmpeg`_ to
To use the ``chroma`` plugin, first enable it in your configuration (see
:ref:`using-plugins`). By default, the plugin depends on `FFmpeg`_ to
transcode the audio, so you might want to install it.
.. _FFmpeg: http://ffmpeg.org
@ -50,35 +50,37 @@ them.
Configuration
-------------
The plugin offers several configuration options, all of which live under the
``convert:`` section:
To configure the plugin, make a ``convert:`` section in your configuration
file. The available options are:
* ``dest`` sets the directory the files will be converted (or copied) to.
A destination is required---you either have to provide it in the config file
or on the command-line using the ``-d`` flag.
* ``embed`` indicates whether or not to embed album art in converted items.
Default: true.
* If you set ``max_bitrate``, all lossy files with a higher bitrate will be
- ``auto``: Import transcoded versions of your files automatically during
imports. With this option enabled, the importer will transcode all (in the
default configuration) non-MP3 files over the maximum bitrate before adding
them to your library.
Default: ``no``.
- ``dest``: The directory where the files will be converted (or copied) to.
Default: none.
- ``embed``: Embed album art in converted items. Default: ``yes``.
- ``max_bitrate``: All lossy files with a higher bitrate will be
transcoded and those with a lower bitrate will simply be copied. Note that
this does not guarantee that all converted files will have a lower
bitrate---that depends on the encoder and its configuration.
* ``auto`` gives you the option to import transcoded versions of your files
automatically during the ``import`` command. With this option enabled, the
importer will transcode all non-MP3 files over the maximum bitrate before
adding them to your library.
* ``quiet`` mode prevents the plugin from announcing every file it processes.
Default: false.
* ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg vorbis,
etc, are never converted, as converting lossy files to other lossy codecs will
decrease quality further. If set to true, lossy files are always copied.
Default: false
* ``paths`` lets you specify the directory structure and naming scheme for the
converted files. Use the same format as the top-level ``paths`` section (see
:ref:`path-format-config`). By default, the plugin reuses your top-level
path format settings.
* Finally, ``threads`` determines the number of threads to use for parallel
encoding. By default, the plugin will detect the number of processors
available and use them all.
Default: none.
- ``never_convert_lossy_files``: Cross-conversions between lossy codecs---such
as mp3, ogg vorbis, etc.---makes little sense as they will decrease quality
even further. If set to ``yes``, lossy files are always copied.
Default: ``no``.
- ``paths``: The directory structure and naming scheme for the converted
files. Uses the same format as the top-level ``paths`` section (see
:ref:`path-format-config`).
Default: Reuse your top-level path format settings.
- ``quiet``: Prevent the plugin from announcing every file it processes.
Default: ``false``.
- ``threads``: The number of threads to use for parallel encoding.
By default, the plugin will detect the number of processors available and use
them all.
You can also configure the format to use for transcoding.
.. _convert-format-config:
@ -87,7 +89,9 @@ Configuring the transcoding command
You can customize the transcoding command through the ``formats`` map
and select a command with the ``--format`` command-line option or the
``format`` configuration.::
``format`` configuration.
::
convert:
format: speex
@ -105,7 +109,7 @@ Each entry in the ``formats`` map consists of a key (the name of the
format) as well as the command and the possibly the file extension.
``extension`` is the filename extension to be used for newly transcoded
files. If only the command is given as a string, the file extension
defaults to the format’s name. ``command`` is the command-line to use
defaults to the format's name. ``command`` is the command-line to use
to transcode audio. The tokens ``$source`` and ``$dest`` in the command
are replaced with the paths to the existing and new file.
@ -114,8 +118,10 @@ formats: `mp3`, `alac`, `flac`, `aac`, `opus`, `ogg`, `wmv`. For
details have a look at the output of ``beet config -d``.
For a one-command-fits-all solution use the ``convert.command`` and
``convert.extension`` options. If these are set the formats are ignored
and the given command is used for all conversions.::
``convert.extension`` options. If these are set, the formats are ignored
and the given command is used for all conversions.
::
convert:
command: ffmpeg -i $source -y -vn -aq 2 $dest

4
docs/plugins/discogs.rst
View file

@ -9,8 +9,8 @@ include matches from the `Discogs`_ database.
Installation
------------
First, enable the ``discogs`` plugin (see :doc:`/plugins/index`). Then,
install the `discogs-client`_ library by typing::
To use the ``discogs`` plugin, first enable it in your configuration (see
:ref:`using-plugins`). Then, install the `discogs-client`_ library by typing::
pip install discogs-client

165
docs/plugins/duplicates.rst
View file

@ -4,43 +4,20 @@ Duplicates Plugin
This plugin adds a new command, ``duplicates`` or ``dup``, which finds
and lists duplicate tracks or albums in your collection.
Installation
------------
Usage
-----
Enable the plugin by putting ``duplicates`` on your ``plugins`` line in
your :doc:`config file </reference/config>`::
plugins: duplicates
Configuration
-------------
To use the ``duplicates`` plugin, first enable it in your configuration (see
:ref:`using-plugins`).
By default, the ``beet duplicates`` command lists the names of tracks
in your library that are duplicates. It assumes that Musicbrainz track
and album ids are unique to each track or album. That is, it lists
every track or album with an ID that has been seen before in the
library.
You can customize the output format, count the number of duplicate
tracks or albums, and list all tracks that have duplicates or just the
duplicates themselves. These options can either be specified in the
config file::
duplicates:
checksum: no
copy: no
keys: mb_trackid album
album: no
count: no
delete: no
format: "$albumartist - $album - $title"
full: no
move: no
path: no
tag: no
or on the command-line::
duplicates themselves via command-line switches ::
-h, --help show this help message and exit
-f FMT, --format=FMT print with custom format
@ -56,83 +33,52 @@ or on the command-line::
-p, --path print paths for matched items or albums
-t TAG, --tag=TAG tag matched items with 'k=v' attribute
Configuration
-------------
format
~~~~~~
To configure the plugin, make a ``duplicates:`` section in your configuration
file. The available options mirror the command-line options:
The ``format`` option (default: :ref:`list_format_item`) lets you
specify a specific format with which to print every track or
album. This uses the same template syntax as beets’ :doc:`path formats
</reference/pathformat>`. The usage is inspired by, and therefore
similar to, the :ref:`list <list-cmd>` command.
path
~~~~
Convenience wrapper for ``-f \$path``.
count
~~~~~
The ``count`` option (default: false) prints a count of duplicate
tracks or albums, with ``format`` hard-coded to ``$albumartist -
$album - $title: $count`` or ``$albumartist - $album: $count`` (for
the ``-a`` option).
album
~~~~~
The ``album`` option (default: false) lists duplicate albums instead
of tracks.
full
~~~~
The ``full`` option (default: false) lists every track or album that
has duplicates, not just the duplicates themselves.
keys
~~~~
The ``keys`` option (default: ``[mb_trackid, mb_albumid]``) defines in which track
or album fields duplicates are to be searched. By default, the plugin
uses the musicbrainz track and album IDs for this purpose. Using the
``keys`` option (as a YAML list in the configuration file, or as
space-delimited strings in the command-line), you can extend this behavior
to consider other attributes.
checksum
~~~~~~~~
The ``checksum`` option (default: ``ffmpeg -i {file} -f crc -``) enables the use of
any arbitrary command to compute a checksum of items. It overrides the ``keys``
option the first time it is run; however, because it caches the resulting checksums
as ``flexattrs`` in the database, you can use
``--keys=name_of_the_checksumming_program any_other_keys`` the second time around.
copy
~~~~
The ``copy`` option (default: ``no``) takes a destination base directory into which
it will copy matched items.
move
~~~~
The ``move`` option (default: ``no``) takes a destination base directory into which
it will move matched items.
delete
~~~~~~
The ``delete`` option (default: ``no``) removes matched items from the library
and from the disk.
tag
~~~
The ``tag`` option (default: ``no``) takes a ``key=value`` string, and adds a new
``key`` attribute with ``value`` value as a flexattr to the database.
- ``album``: List duplicate albums instead of tracks.
Default: ``no``.
- ``checksum``: Use an arbitrary command to compute a checksum
of items. This overrides the ``keys`` option the first time it is run;
however, because it caches the resulting checksum as ``flexattrs`` in the
database, you can use ``--keys=name_of_the_checksumming_program
any_other_keys`` (or set configuration ``keys`` option) the second time
around.
Default: ``ffmpeg -i {file} -f crc -``.
- ``copy``: A destination base directory into which to copy matched
items.
Default: none (disabled).
- ``count``: Print a count of duplicate tracks or albums in the format
``$albumartist - $album - $title: $count`` (for tracks) or ``$albumartist -
$album: $count`` (for albums).
Default: ``no``.
- ``delete``: Removes matched items from the library and from the disk.
Default: ``no``
- ``format``: A specific format with which to print every track
or album. This uses the same template syntax as beets'
:doc:`path formats</reference/pathformat>`. The usage is inspired by, and
therefore similar to, the :ref:`list <list-cmd>` command.
Default: :ref:`list_format_item`
- ``full``: List every track or album that has duplicates, not just the
duplicates themselves.
Default: ``no``.
- ``keys``: Define in which track or album fields duplicates are to be
searched. By default, the plugin uses the musicbrainz track and album IDs for
this purpose. Using the ``keys`` option (as a YAML list in the configuration
file, or as space-delimited strings in the command-line), you can extend this
behavior to consider other attributes.
Default: ``[mb_trackid, mb_albumid]``
- ``move``: A destination base directory into which it will move matched
items.
Default: none (disabled).
- ``path``: Output the path instead of metadata when listing duplicates.
Default: ``no``.
- ``tag``: A ``key=value`` pair. The plugin will add a new ``key`` attribute
with ``value`` value as a flexattr to the database for duplicate items.
Default: ``no``.
Examples
--------
@ -150,7 +96,8 @@ Print out a unicode histogram of duplicate track years using `spark`_::
beet duplicates -f '$year' | spark
▆▁▆█▄▇▇▄▇▇▁█▇▆▇▂▄█▁██▂█▁▁██▁█▂▇▆▂▇█▇▇█▆▆▇█▇█▇▆██▂▇
Print out a listing of all albums with duplicate tracks, and respective counts::
Print out a listing of all albums with duplicate tracks, and respective
counts::
beet duplicates -ac
@ -162,8 +109,8 @@ Get tracks with the same title, artist, and album::
beet duplicates -k title albumartist album
Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report back
duplicates based on those values::
Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report
back duplicates based on those values::
beet dup -C 'ffmpeg -i {file} -f crc -'
beet dup -C 'md5sum {file}'
@ -181,12 +128,8 @@ Delete items (careful!), if they're Nickelback::
beet duplicates --delete --keys albumartist albumartist:nickelback
Tag duplicate items with some flag::
beet duplicates --tag dup=1
TODO
----
- better duplicate disambiaguation strategies (eg, based on bitrate, etc)
.. _spark: https://github.com/holman/spark

74
docs/plugins/echonest.rst
View file

@ -41,63 +41,45 @@ algorithms supported by the Echo Nest. Please note that fingerprinting is not
required if ``upload`` and ``convert`` is enabled, which is the default (but
it can be faster than uploading).
Finally, enable the ``echonest`` plugin in your configuration (see
:ref:`using-plugins`).
.. _pip: http://pip.openplans.org/
.. _FFmpeg: http://ffmpeg.org
.. _ENMFP: http://static.echonest.com/ENMFP_codegen.zip
.. _Echoprint: http://echoprint.me
Configuring
-----------
Configuration
-------------
Beets includes its own Echo Nest API key, but you can `apply for your own`_ for
free from the Echo Nest. To specify your own API key, add the key to your
:doc:`configuration file </reference/config>` as the value for ``apikey`` under
the key ``echonest`` like so::
To configure the plugin, make an ``echonest:`` section in your configuration
file. The available options are:
echonest:
apikey: YOUR_API_KEY
In addition, the ``auto`` config option lets you disable automatic metadata
fetching during import. To do so, add this to your ``config.yaml``::
echonest:
auto: no
The ``echonest`` plugin tries to upload files to the Echo Nest server if it
can not be identified by other means. If you don't want that, disable the
``upload`` config option like so::
echonest:
upload: no
The Echo Nest server only supports a limited range of file formats. The plugin
automatically converts unsupported files to ``ogg``. If you don't want that,
disable the ``convert`` config option like so::
echonest:
convert: no
The Echo Nest server does not allow uploading of files with sizes greater than
50MB. The plugin automatically truncates large files to their first 5
minutes. If you don't want that, disable the ``truncate`` config option like
so::
echonest:
truncate: no
To enable fingerprinting, you'll need to tell the plugin where to find the
Echoprint or ENMFP codegen binary. Use the ``codegen`` key under the
``echonest`` section like so::
echonest:
codegen: /usr/bin/echoprint-codegen
- ``apikey``: A custom EchoNest API key. You can `apply for your own`_ for
free from the EchoNest.
Default: beets' own Echo Nest API key.
- ``auto``: Enable automatic metadata fetching during import.
Default: ``yes``.
- ``codegen``: Echoprint or ENMFP codegen binary path.
Default: look for the executable in your ``$PATH``.
- ``upload``: Send files to the Echo Nest server if they can not be identified
by other means.
Default: ``yes``.
- ``convert``: Because the Echo Nest server only supports a limited range of
file formats, the plugin automatically converts unsupported files to ``ogg``.
Default: ``yes``.
- ``truncate``: Automatically truncate large files to their first 5 minutes
before uploading them to The Echo Nest server (as files with sizes greater
than 50MB are rejected).
Default: ``yes``.
.. _apply for your own: http://developer.echonest.com/account/register
Running Manually
----------------
In addition to running automatically on import, the plugin can also be run manually
from the command line. Use the command ``beet echonest [QUERY]`` to fetch
acoustic attributes for albums matching a certain query.
In addition to running automatically on import, the plugin can also be run
manually from the command line. Use the command ``beet echonest [QUERY]`` to
fetch acoustic attributes for albums matching a certain query.

73
docs/plugins/echonest_tempo.rst
View file

@ -1,73 +0,0 @@
EchoNest Tempo Plugin
=====================
.. note::
A newer :doc:`echonest` is available that supersedes this plugin. In
addition to the tempo, the new plugin can fetch the Echo Nest's full
complement of acoustic attributes. This older tempo-specific plugin is
**deprecated**.
The ``echonest_tempo`` plugin fetches and stores a track's tempo (the "bpm"
field) from the `Echo Nest API`_.
.. _Echo Nest API: http://developer.echonest.com/
Installing Dependencies
-----------------------
This plugin requires the pyechonest library in order to talk to the EchoNest
API.
There are packages for most major linux distributions, you can download the
library from the Echo Nest, or you can install the library from `pip`_,
like so::
$ pip install pyechonest
.. _pip: http://pip.openplans.org/
Configuring
-----------
Beets includes its own Echo Nest API key, but you can `apply for your own`_ for
free from the EchoNest. To specify your own API key, add the key to your
:doc:`configuration file </reference/config>` as the value for ``apikey`` under
the key ``echonest_tempo`` like so::
echonest_tempo:
apikey: YOUR_API_KEY
In addition, the ``autofetch`` config option lets you disable automatic tempo
fetching during import. To do so, add this to your ``config.yaml``::
echonest_tempo:
auto: no
.. _apply for your own: http://developer.echonest.com/account/register
Fetch Tempo During Import
-------------------------
To automatically fetch the tempo for songs you import, just enable the plugin
by putting ``echonest_tempo`` on your config file's ``plugins`` line (see
:doc:`/plugins/index`). When importing new files, beets will now fetch the
tempo for files that don't already have them. The bpm field will be stored in
the beets database. If the ``import.write`` config option is on, then the tempo
will also be written to the files' tags.
This behavior can be disabled with the ``autofetch`` config option (see below).
Fetching Tempo Manually
-----------------------
The ``tempo`` command provided by this plugin fetches tempos for
items that match a query (see :doc:`/reference/query`). For example,
``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the
appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get
tempos for all my tracks by that band, and ``beet tempo`` will get tempos for
my entire library. The tempos will be added to the beets database and, if
``import.write`` is on, embedded into files' metadata.
The ``-p`` option to the ``tempo`` command makes it print tempos out to the
console so you can view the fetched (or previously-stored) tempos.

62
docs/plugins/embedart.rst
View file

@ -7,13 +7,11 @@ You might want to embed the album art directly into each file's metadata. While
this will take more space than the external-file approach, it is necessary for
displaying album art in some media players (iPods, for example).
This plugin was added in beets 1.0b8.
Embedding Art Automatically
---------------------------
To automatically embed discovered album art into imported files, just enable the
plugin (see :doc:`/plugins/index`). You'll also want to enable the
To automatically embed discovered album art into imported files, just enable
the ``embedart`` plugin (see :doc:`/plugins/index`). You'll also want to enable the
:doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be
embedded after each album is added to the library.
@ -40,6 +38,34 @@ number, the more similar the images must be.
This feature requires `ImageMagick`_.
Configuration
-------------
To configure the plugin, make an ``embedart:`` section in your configuration
file. The available options are:
- ``auto``: Enable automatic album art embedding.
Default: ``yes``.
- ``compare_threshold``: How similar candidate art must be to
existing art to be written to the file (see :ref:`image-similarity-check`).
Default: 0 (disabled).
- ``ifempty``: Avoid embedding album art for files that already have art
embedded.
Default: ``no``.
- ``maxwidth``: A maximum width to downscale images before embedding
them (the original image file is not altered). The resize operation reduces
image width to at most ``maxwidth`` pixels. The height is recomputed so that
the aspect ratio is preserved. See also :ref:`image-resizing` for further
caveats about image resizing.
Default: 0 (disabled).
Note: ``compare_threshold`` option requires `ImageMagick`_, and ``maxwidth``
requires either `ImageMagick`_ or `PIL`_.
.. _PIL: http://www.pythonware.com/products/pil/
.. _ImageMagick: http://www.imagemagick.org/
.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/
Manually Embedding and Extracting Art
-------------------------------------
@ -59,31 +85,3 @@ embedded album art:
* ``beet clearart QUERY``: removes all embedded images from all items matching
the query. (Use with caution!)
Configuring
-----------
The ``auto`` option lets you disable automatic album art embedding.
To do so, add this to your ``config.yaml``::
embedart:
auto: no
A maximum image width can be configured as ``maxwidth`` to downscale images
before embedding them (the original image file is not altered). The resize
operation reduces image width to ``maxwidth`` pixels. The height is recomputed
so that the aspect ratio is preserved. `PIL`_ or `ImageMagick`_ is required to
use the ``maxwidth`` config option. See also :ref:`image-resizing` for further
so that the aspect ratio is preserved.
The ``compare_threshold`` option defines how similar must candidate art be
regarding to embedded art to be written to the file (see
:ref:`image-similarity-check`). The default is 0 (no similarity check).
Requires `ImageMagick`_.
To avoid embedding album art for files that already have album art, set the
``ifempty`` config option to ``yes``.
.. _PIL: http://www.pythonware.com/products/pil/
.. _ImageMagick: http://www.imagemagick.org/
.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/

56
docs/plugins/fetchart.rst
View file

@ -4,7 +4,7 @@ FetchArt Plugin
The ``fetchart`` plugin retrieves album art images from various sources on the
Web and stores them as image files.
To use the plugin, first enable it in your configuration (see
To use the ``fetchart`` plugin, first enable it in your configuration (see
:ref:`using-plugins`). Then, install the `requests`_ library by typing::
pip install requests
@ -23,11 +23,36 @@ By default, beets stores album art image files alongside the music files for an
album in a file called ``cover.jpg``. To customize the name of this file, use
the :ref:`art-filename` config option.
To disable automatic art downloading, just put this in your configuration
file::
Configuration
-------------
To configure the plugin, make a ``fetchart:`` section in your configuration
file. The available options are:
- ``auto``: Enable automatic album art fetching during import.
Default: ``yes``.
- ``cautious``: Pick only trusted album art by ignoring filenames that do not
contain one of the keywords in ``cover_names``.
Default: ``no``.
- ``cover_names``: Prioritize images containing words in this list.
Default: ``['cover', 'front', 'art', 'album', 'folder']``.
- ``google_search``: Gather images from Google Image Search.
Default: ``no``.
- ``maxwidth``: A maximum image width to downscale fetched images if they are
too big. The resize operation reduces image width to at most ``maxwidth``
pixels. The height is recomputed so that the aspect ratio is preserved.
- ``remote_priority``: Query remote sources every time and use local image only
as fallback.
Default: ``no``; remote (Web) art sources are only queried if no local art is
found in the filesystem.
Here's an example that makes plugin select only images that contain *front* or
*back* keywords in their filenames::
fetchart:
auto: no
cautious: true
cover_names: front back
Manually Fetching Album Art
---------------------------
@ -47,11 +72,6 @@ be processed; otherwise, the command processes every album in your library.
Image Resizing
--------------
A maximum image width can be configured as ``maxwidth`` to downscale fetched
images if they are too big. The resize operation reduces image width to
``maxwidth`` pixels. The height is recomputed so that the aspect ratio is
preserved.
Beets can resize images using `PIL`_, `ImageMagick`_, or a server-side resizing
proxy. If either PIL or ImageMagick is installed, beets will use those;
otherwise, it falls back to the resizing proxy. If the resizing proxy is used,
@ -79,19 +99,6 @@ file whose name contains "cover", "front", "art", "album" or "folder", but in
the absence of well-known names, it will use any image file in the same folder
as your music files.
You can change the list of filename keywords using the ``cover_names`` config
option. Or, to use *only* filenames containing the keywords and not fall back
to any image, set ``cautious`` to true. For example::
fetchart:
cautious: true
cover_names: front back
By default, remote (Web) art sources are only queried if no local art is found
in the filesystem. To query remote sources every time, set the
``remote_priority`` configuration option to true, which will cause beets to
prefer remote cover art over any local image files.
When you choose to apply changes during an import, beets will search for art as
described above. For "as-is" imports (and non-autotagged imports using the
``-A`` flag), beets only looks for art on the local filesystem.
@ -106,11 +113,6 @@ unlikely).
.. _Google Images: http://images.google.com/
To enable gathering art from Google, enable the ``google_search`` option in
your config file::
fetchart:
google_search: true
Embedding Album Art
-------------------

5
docs/plugins/fromfilename.rst
View file

@ -9,6 +9,5 @@ When you attempt to import a track that's missing a title, this plugin will
look at the track's filename and guess its track number, title, and artist.
These will be used to search in MusicBrainz and match track ordering.
To use the plugin, just enable it by putting ``fromfilename`` on the
``plugins:`` line in your config file. There are currently no configuration
options.
To use the ``fromfilename`` plugin, enable it in your configuration
(see :ref:`using-plugins`).

29
docs/plugins/ftintitle.rst
View file

@ -1,7 +1,7 @@
FtInTitle Plugin
================
The ``ftintitle`` plugin automatically moved "featured" artists from the
The ``ftintitle`` plugin automatically moves "featured" artists from the
``artist`` field to the ``title`` field.
According to `MusicBrainz style`_, featured artists are part of the artist
@ -10,17 +10,32 @@ tracks in your library like "Tellin' Me Things" by the artist "Blakroc feat.
RZA". If you prefer to tag this as "Tellin' Me Things feat. RZA" by "Blakroc",
then this plugin is for you.
To use the plugin, just enable it and run the command::
To use the ``ftintitle`` plugin, enable it in your configuration
(see :ref:`using-plugins`).
Configuration
-------------
To configure the plugin, make a ``ftintitle:`` section in your configuration
file. The available options are:
- ``auto``: Enable metadata rewriting during import.
Default: ``yes``.
- ``drop``: Remove featured artists entirely instead of adding them to the
title field.
Default: ``no``.
Running Manually
----------------
From the command line, type::
$ beet ftintitle [QUERY]
The query is optional; if it's left off, the transformation will be applied to
your entire collection.
If you prefer to remove featured artists entirely instead of adding them to
the title field, either use the ``-d`` flag to the command or set the
``ftintitle.drop`` config option.
To disable this plugin on import, set the ``auto`` config option to false.
Use the ``-d`` flag to remove featured artists (equivalent of the ``drop``
config option).
.. _MusicBrainz style: http://musicbrainz.org/doc/Style

23
docs/plugins/fuzzy.rst
View file

@ -1,25 +1,24 @@
Fuzzy Search Plugin
===================
The ``fuzzy`` plugin provides a prefixed query that search you library using
The ``fuzzy`` plugin provides a prefixed query that searches your library using
fuzzy pattern matching. This can be useful if you want to find a track with
complicated characters in the title.
First, enable the plugin named ``fuzzy`` (see :doc:`/plugins/index`).
First, enable the plugin named ``fuzzy`` (see :ref:`using-plugins`).
You'll then be able to use the ``~`` prefix to use fuzzy matching::
$ beet ls '~Vareoldur'
Sigur Rós - Valtari - Varðeldur
The plugin provides config options that let you choose the prefix and the
threshold.::
Configuration
-------------
fuzzy:
threshold: 0.8
prefix: '@'
To configure the plugin, make a ``fuzzy:`` section in your configuration
file. The available options are:
A threshold value of 1.0 will show only perfect matches and a value of 0.0
will match everything.
The default prefix ``~`` needs to be escaped or quoted in most shells. If this
bothers you, you can change the prefix in your config file.
- ``threshold``: The "sensitivity" of the fuzzy match. A value of 1.0 will
show only perfect matches and a value of 0.0 will match everything.
Default: 0.7.
- ``prefix``: The character used to designate fuzzy queries.
Default: ``~``, which may need to be escaped in some shells.

20
docs/plugins/ihate.rst
View file

@ -6,18 +6,28 @@ import or warn you about them. You specify queries (see
:doc:`/reference/query`) and the plugin skips (or warns about) albums or items
that match any query.
To use the plugin, first enable it in your configuration (see
:ref:`using-plugins`). Then, add an ``ihate:`` section to your configuration
file::
To use the ``ihate`` plugin, enable it in your configuration (see
:ref:`using-plugins`).
Configuration
-------------
To configure the plugin, make an ``ihate:`` section in your configuration
file. The available options are:
- ``skip``: Never import items and albums that match a query in this list.
Default: ``[]`` (empty list).
- ``warn``: Print a warning message for matches in this list of queries.
Default: ``[]``.
Here's an example::
ihate:
# Print a warning message for these.
warn:
- artist:rnb
- genre: soul
# Only warn about tribute albums in rock genre.
- genre:rock album:tribute
# Never import any of this.
skip:
- genre::russian\srock
- genre:polka

25
docs/plugins/importadded.rst
View file

@ -4,6 +4,12 @@ ImportAdded Plugin
The ``importadded`` plugin is useful when an existing collection is imported
and the time when albums and items were added should be preserved.
To use the ``importadded`` plugin, enable it in your configuration (see
:ref:`using-plugins`).
Usage
-----
The :abbr:`mtime (modification time)` of files that are imported into the
library are assumed to represent the time when the items were originally
added.
@ -16,10 +22,8 @@ The ``item.added`` field is populated as follows:
set to the oldest mtime of the files in the album before they were imported.
The mtime of album directories is ignored.
This plugin can optionally be configured to also preserve mtimes::
importadded:
preserve_mtimes: yes # default: no
This plugin can optionally be configured to also preserve mtimes using the
``preserve_mtimes`` option.
File modification times are preserved as follows:
@ -32,7 +36,18 @@ File modification times are preserved as follows:
Note that there is no ``album.mtime`` field in the database and that the mtime
of album directories on disk aren't preserved.
Configuration
-------------
To configure the plugin, make an ``importadded:`` section in your
configuration file. There is one option available:
- ``preserve_mtimes``: After writing files, re-set their mtimes to their
original value.
Default: ``no``.
Reimport
--------
This plugin will skip reimported singleton items and reimported albums and all of their items.
This plugin will skip reimported singleton items and reimported albums and all
of their items.

48
docs/plugins/importfeeds.rst
View file

@ -1,30 +1,40 @@
ImportFeeds Plugin
==================
The ``importfeeds`` plugin helps you keep track of newly imported music in your library.
This plugin helps you keep track of newly imported music in your library.
To use the plugin, just put ``importfeeds`` on the ``plugins`` line in your
:doc:`configuration file </reference/config>`. Then set a few options under the
``importfeeds:`` section in the config file.
To use the ``importfeeds`` plugin, enable it in your configuration
(see :ref:`using-plugins`).
The ``dir`` configuration option can be set to specify another folder
than the default library directory. This is where your playlist will be created.
Configuration
-------------
The ``relative_to`` configuration option can be set to make the m3u paths
relative to another folder than where the playlist is being written. If you're
using importfeeds to generate a playlist for MPD, you should set this to the
root of your music library.
To configure the plugin, make an ``importfeeds:`` section in your
configuration file. The available options are:
The ``absolute_path`` configuration option can be set to use absolute paths
instead of relative paths. Some applications may need this to work properly.
- ``absolute_path``: Use absolute paths instead of relative paths. Some
applications may need this to work properly.
Default: ``no``.
- ``dir``: The output directory.
Default: Your beets library directory.
- ``formats``: Select the kind of output. Use one or more of:
- ``m3u``: Catalog the imports in a centralized playlist.
- ``m3u_multi``: Create a new playlist for each import (uniquely named by
appending the date and track/album name).
- ``link``: Create a symlink for each imported item. This is the
recommended setting to propagate beets imports to your iTunes library:
just drag and drop the ``dir`` folder on the iTunes dock icon.
- ``echo``: Do not write a playlist file at all, but echo a list of new
file paths to the terminal.
Four different types of outputs are available. Specify the ones you want to
use by setting the ``formats`` parameter:
- ``m3u``: catalog the imports in a centralized playlist. By default, the playlist is named ``imported.m3u``. To use a different file, just set the ``m3u_name`` parameter inside the ``importfeeds`` config section.
- ``m3u_multi``: create a new playlist for each import (uniquely named by appending the date and track/album name).
- ``link``: create a symlink for each imported item. This is the recommended setting to propagate beets imports to your iTunes library: just drag and drop the ``dir`` folder on the iTunes dock icon.
- ``echo``: do not write a playlist file at all, but echo a list of new file paths to the terminal.
Default: None.
- ``m3u_name``: Playlist name used by the ``m3u`` format.
Default: ``imported.m3u``.
- ``relative_to``: Make the m3u paths relative to another
folder than where the playlist is being written. If you're using importfeeds
to generate a playlist for MPD, you should set this to the root of your music
library.
Default: None.
Here's an example configuration for this plugin::

10
docs/plugins/index.rst
View file

@ -15,18 +15,24 @@ 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 :doc:`config.yaml </reference/config>`: file, like so::
plugins: inline discogs web
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
.. toctree::
:hidden:
chroma
lyrics
echonest_tempo
echonest
bpd
mpdupdate

3
docs/plugins/info.rst
View file

@ -5,7 +5,8 @@ The ``info`` plugin provides a command that dumps the current tag values for
any file format supported by beets. It works like a supercharged version of
`mp3info`_ or `id3v2`_.
Enable the plugin and then type::
Enable the ``info`` plugin in your configuration (see :ref:`using-plugins`) and
then type::
$ beet info /path/to/music.flac

8
docs/plugins/inline.rst
View file

@ -6,9 +6,9 @@ it, you can define template fields in your beets configuration file and refer
to them from your template strings in the ``paths:`` section (see
:doc:`/reference/config/`).
To use inline field definitions, first enable the plugin by putting ``inline``
on your ``plugins`` line in your configuration file. Then, make a
``item_fields:`` block in your config file. Under this key, every line defines a
To use the `ìnline`` plugin, enable it in your configuration
(see :ref:`using-plugins`).
Then, make a `item_fields:`` block in your config file. Under this key, every line defines a
new template field; the key is the name of the field (you'll use the name to
refer to the field in your templates) and the value is a Python expression or
function body. The Python code has all of a track's fields in scope, so you can
@ -42,7 +42,7 @@ a result for the value of the path field, like so::
item_fields:
filename: |
import os
from beets.util import bytestring_path
from beets.util import bytestring_path
return bytestring_path(os.path.basename(path))
You might want to use the YAML syntax for "block literals," in which a leading

28
docs/plugins/keyfinder.rst
View file

@ -3,26 +3,30 @@ Key Finder Plugin
The `keyfinder` plugin uses the `KeyFinder`_ program to detect the
musical key of track from its audio data and store it in the
`initial_key` field of you database. If enabled, it does so
`initial_key` field of your database. It does so
automatically when importing music or through the ``beet keyfinder
[QUERY]`` command.
There are a couple of configuration options to customize the behavior of
the plugin. By default they are::
To use the ``keyfinder`` plugin, enable it in your configuration (see
:ref:`using-plugins`).
keyfinder:
bin: KeyFinder
auto: yes
overwrite: no
Configuration
-------------
* ``bin``: The name of the `KeyFinder` program on your system or
a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for
To configure the plugin, make a ``keyfinder:`` section in your
configuration file. The available options are:
- ``bin``: The name of the `KeyFinder`_ program on your system or
a path to the binary. If you installed the KeyFinder GUI on a Mac, for
example, you want something like
``/Applications/KeyFinder.app/Contents/MacOS/KeyFinder``.
* ``auto``: If set to `yes`, the plugin will analyze every file on
Default: ``KeyFinder`` (i.e., search for the program in your ``$PATH``).
- ``auto``: Analyze every file on
import. Otherwise, you need to use the ``beet keyfinder`` command
explicitly.
* ``overwrite``: If set to `no`, the import hook and the command will skip
any file that already has an `initial_key` in the database.
Default: ``yes``.
- ``overwrite``: Calculate a key even for files that already have an
`initial_key` value.
Default: ``no``.
.. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/

101
docs/plugins/lastgenre.rst
View file

@ -4,30 +4,31 @@ LastGenre Plugin
The MusicBrainz database `does not contain genre information`_. Therefore, when
importing and autotagging music, beets does not assign a genre. The
``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres
to your albums and items. The plugin is included with beets as of version
1.0b11.
to your albums and items.
.. _does not contain genre information:
http://musicbrainz.org/doc/General_FAQ#Why_does_MusicBrainz_not_support_genre_information.3F
.. _Last.fm: http://last.fm/
Installation
------------
The plugin requires `pylast`_, which you can install using `pip`_ by typing::
pip install pylast
After you have pylast installed, enable the plugin by putting ``lastgenre`` on
your ``plugins`` line in :doc:`config file </reference/config>`.
After you have pylast installed, enable the ``lastgenre`` plugin in your
configuration (see :ref:`using-plugins`).
Usage
-----
The plugin chooses genres based on a *whitelist*, meaning that only certain
tags can be considered genres. This way, tags like "my favorite music" or "seen
live" won't be considered genres. The plugin ships with a fairly extensive
`internal whitelist`_, but you can set your own in the config file using the
``whitelist`` configuration value::
lastgenre:
whitelist: /path/to/genres.txt
…or go for no whitelist altogether by setting the option to `false`.
`internal whitelist`_, but you can set your own in the config file using the
``whitelist`` configuration value or forgo a whitelist altogether by setting
the option to `false`.
The genre list file should contain one genre per line. Blank lines are ignored.
For the curious, the default genre list is generated by a `script that scrapes
@ -38,79 +39,75 @@ Wikipedia`_.
.. _script that scrapes Wikipedia: https://gist.github.com/1241307
.. _internal whitelist: https://raw.githubusercontent.com/sampsyo/beets/master/beetsplug/lastgenre/genres.txt
By default, beets will always fetch new genres, even if the files already have
once. To instead leave genres in place in when they pass the whitelist, set
the ``force`` option to `no`.
If no genre is found, the file will be left unchanged. To instead specify a
fallback genre, use the ``fallback`` configuration option. You can, of
course, use the empty string as a fallback, like so::
lastgenre:
fallback: ''
Canonicalization
----------------
^^^^^^^^^^^^^^^^
The plugin can also *canonicalize* genres, meaning that more obscure genres can
be turned into coarser-grained ones that are present in the whitelist. This
works using a tree of nested genre names, represented using `YAML`_, where the
leaves of the tree represent the most specific genres.
To enable canonicalization, set the ``canonical`` configuration value::
lastgenre:
canonical: true
Setting this value to `true` will use a built-in canonicalization
tree. You can also set it to a path, just like the ``whitelist`` config value,
to use your own tree.
.. _YAML: http://www.yaml.org/
Genre Source
------------
^^^^^^^^^^^^
When looking up genres for albums or individual tracks, you can choose whether
to use Last.fm tags on the album, the artist, or the track. For example, you
might want all the albums for a certain artist to carry the same genre. Set the
``source`` configuration value to "album", "track", or "artist", like so::
lastgenre:
source: artist
might want all the albums for a certain artist to carry the same genre.
The default is "album". When set to "track", the plugin will fetch *both*
album-level and track-level genres for your music when importing albums.
Multiple Genres
---------------
^^^^^^^^^^^^^^^
By default, the plugin chooses the most popular tag on Last.fm as a genre. If
you prefer to use a *list* of popular genre tags, you can increase the number
of the ``count`` config option::
lastgenre:
count: 3
of the ``count`` config option.
Lists of up to *count* genres will then be used instead of single genres. The
genres are separated by commas by default, but you can change this with the
``separator`` config option::
lastgenre:
separator: ' / '
``separator`` config option.
`Last.fm`_ provides a popularity factor, a.k.a. *weight*, for each tag ranging
from 100 for the most popular tag down to 0 for the least popular.
The plugin uses this weight to discard unpopular tags. The default is to
ignore tags with a weight less then 10. You can change this by setting
the ``min_weight`` config option::
the ``min_weight`` config option.
lastgenre:
min_weight: 15
Configuration
-------------
To configure the plugin, make a ``lastgenre:`` section in your
configuration file. The available options are:
- ``auto``: Fetch genres automatically during import.
Default: ``yes``.
- ``canonical``: Use a canonicalization tree. Setting this to ``yes`` will use
a built-in tree. You can also set it to a path, like the ``whitelist``
config value, to use your own tree.
Default: ``no`` (disabled).
- ``count``: Number of genres to fetch.
Default: 1
- ``fallback``: A string if to use a fallback genre when no genre is found.
You can use the empty string ``''`` to reset the genre.
Default: None.
- ``force``: By default, beets will always fetch new genres, even if the files
already have one. To instead leave genres in place in when they pass the
whitelist, set the ``force`` option to ``no``.
Default: ``yes``.
- ``min_weight``: Minimum popularity factor below which genres are discarded.
Default: 10.
- ``source``: Which entity to look up in Last.fm. Can be
either ``artist``, ``album`` or ``track``.
Default: ``album``.
- ``separator``: A separator for multiple genres.
Default: ``', '``.
- ``whitelist``: The filename of a custom genre list, ``yes`` to use
the internal whitelist, or ``no`` to consider all genres valid.
Default: ``yes``.
Running Manually
----------------

62
docs/plugins/lyrics.rst
View file

@ -12,14 +12,38 @@ and, optionally, the Google custom search API.
Fetch Lyrics During Import
--------------------------
To automatically fetch lyrics for songs you import, just enable the plugin by
putting ``lyrics`` on your config file's ``plugins`` line (see
:doc:`/plugins/index`). When importing new files, beets will now fetch lyrics
for files that don't already have them. The lyrics will be stored in the beets
database. If the ``import.write`` config option is on, then the lyrics will also
be written to the files' tags.
To automatically fetch lyrics for songs you import, enable the ``lyrics``
plugin in your configuration (see :ref:`using-plugins`).
When importing new files, beets will now fetch lyrics for files that don't
already have them. The lyrics will be stored in the beets database. If the
``import.write`` config option is on, then the lyrics will also be written to
the files' tags.
This behavior can be disabled with the ``auto`` config option (see below).
Configuration
-------------
To configure the plugin, make a ``lyrics:`` section in your
configuration file. The available options are:
- ``auto``: Fetch lyrics automatically during import.
Default: ``yes``.
- ``fallback``: By default, the file will be left unchanged when no lyrics are
found. Use the empty string ``''`` to reset the lyrics in such a case.
Default: None.
- ``google_API_key``: Your Google API key (to enable the Google Custom Search
backend).
Default: None.
- ``google_engine_ID``: The custom search engine to use.
Default: The beets custom search engine, which gathers a list of sources
known to be scrapeable.
Here's an example of ``config.yaml``::
lyrics:
fallback: ''
google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
google_engine_ID: 009217259823014548361:lndtuqkycfu
Fetching Lyrics Manually
@ -39,26 +63,8 @@ console so you can view the fetched (or previously-stored) lyrics.
The ``-f`` option forces the command to fetch lyrics, even for tracks that
already have lyrics.
Configuring
-----------
To disable automatic lyric fetching during import, set the ``auto`` option to
false, like so::
lyrics:
auto: no
By default, if no lyrics are found, the file will be left unchanged. To
specify a placeholder for the lyrics tag when none are found, use the
``fallback`` configuration option::
lyrics:
fallback: 'No lyrics found'
.. _activate-google-custom-search:
Activate Google custom search
------------------------------
@ -78,12 +84,6 @@ default, beets use a list of sources known to be scrapeable.
.. _define a custom search engine: http://www.google.com/cse/all
Here's an example of ``config.yaml``::
lyrics:
google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
google_engine_ID: 009217259823014548361:lndtuqkycfu
Note that the Google custom search API is limited to 100 queries per day.
After that, the lyrics plugin will fall back on its other data sources.

21
docs/plugins/mbcollection.rst
View file

@ -6,7 +6,8 @@ maintain your `music collection`_ list there.
.. _music collection: http://musicbrainz.org/doc/Collections
To begin, just enable the ``mbcollection`` plugin (see :doc:`/plugins/index`).
To begin, just enable the ``mbcollection`` plugin in your
configuration (see :ref:`using-plugins`).
Then, add your MusicBrainz username and password to your
:doc:`configuration file </reference/config>` under a ``musicbrainz`` section::
@ -19,16 +20,12 @@ command automatically adds all of your albums to the first collection it finds.
If you don't have a MusicBrainz collection yet, you may need to add one to your
profile first.
Automatically Update on Import
------------------------------
Configuration
-------------
You can also configure the plugin to automatically amend your MusicBrainz
collection whenever you import a new album. To do this, first enable the
plugin and add your MusicBrainz account as above. Then, add ``mbcollection``
section and enable the enable ``auto`` flag therein::
To configure the plugin, make a ``mbcollection:`` section in your
configuration file. There is one option available:
mbcollection:
auto: yes
During future imports, your default collection will be updated with each
imported album.
- ``auto``: Automatically amend your MusicBrainz collection whenever you
import a new album.
Default: ``no``.

6
docs/plugins/mbsync.rst
View file

@ -15,9 +15,9 @@ configuration.
Usage
-----
Enable the plugin and then run ``beet mbsync QUERY`` to fetch updated metadata
for a part of your collection (or omit the query to run over your whole
library).
Enable the ``mbsync`` plugin in your configuration (see :ref:`using-plugins`)
and then run ``beet mbsync QUERY`` to fetch updated metadata for a part of your
collection (or omit the query to run over your whole library).
This plugin treats albums and singletons (non-album tracks) separately. It
first processes all matching singletons and then proceeds on to full albums.

70
docs/plugins/missing.rst
View file

@ -6,59 +6,46 @@ and lists, for every album in your collection, which or how many
tracks are missing. Listing missing files requires one network call to
MusicBrainz. Merely counting missing files avoids any network calls.
Usage
-----
Installation
------------
Enable the plugin by putting ``missing`` on your ``plugins`` line in
:doc:`config file </reference/config>`::
plugins:
missing
...
Configuration
-------------
Add the ``missing`` plugin to your configuration (see :ref:`using-plugins`).
By default, the ``beet missing`` command lists the names of tracks that your
library is missing from each album. You can customize the output format, count
library is missing from each album.
You can customize the output format, count
the number of missing tracks per album, or total up the number of missing
tracks over your whole library. These options can either be specified in the
config file::
missing:
format: $albumartist - $album - $title
count: no
total: no
or on the command-line::
tracks over your whole library, using command-line switches::
-f FORMAT, --format=FORMAT
print with custom FORMAT
-c, --count count missing tracks per album
-t, --total count total of missing tracks
…or by editing corresponding options.
format
~~~~~~
Configuration
-------------
The ``format`` option (default: :ref:`list_format_item`) lets you specify a
specific format with which to print every track. This uses the same template
syntax as beets’ :doc:`path formats </reference/pathformat>`. The usage is
inspired by, and therefore similar to, the :ref:`list <list-cmd>` command.
To configure the plugin, make a ``missing:`` section in your
configuration file. The available options are:
count
~~~~~
- ``count``: Print a count of missing tracks per album, with ``format``
defaulting to ``$albumartist - $album: $missing``.
Default: ``no``.
- ``format``: A specific format with which to print every
track. This uses the same template syntax as beets'
:doc:`path formats </reference/pathformat>`. The usage is inspired by, and
therefore similar to, the :ref:`list <list-cmd>` command.
Default: :ref:`list_format_item`.
- ``total``: Print a single count of missing tracks in all albums.
Default: ``no``.
The ``count`` option (default: false) prints a count of missing tracks
per album, with ``format`` defaulting to ``$albumartist - $album:
$missing``.
Here's an example ::
total
~~~~~
The ``total`` option (default: false) prints a single
count of missing tracks in all albums
missing:
format: $albumartist - $album - $title
count: no
total: no
Template Fields
---------------
@ -94,9 +81,4 @@ Call this plugin from other beet commands::
beet ls -a -f '$albumartist - $album: $missing'
TODO
----
- Add caching.
.. _spark: https://github.com/holman/spark

58
docs/plugins/mpdstats.rst
View file

@ -21,49 +21,37 @@ Install the library from `pip`_, like so::
$ pip install python-mpd
Add the ``mpdstats`` plugin to your configuration (see :ref:`using-plugins`).
.. _pip: http://www.pip-installer.org/
Configuring
-----------
To use it, enable it in your ``config.yaml`` by putting ``mpdstats`` on your
``plugins`` line. Then, you'll probably want to configure the specifics of
your MPD server. You can do that using an ``mpd:`` section in your
``config.yaml``, which looks like this::
mpd:
host: localhost
port: 6600
password: seekrit
If your MPD library is at another location then the beets library (e.g.,
because one is mounted on a NFS share), you can specify the
``music_directory`` in the config like this::
mpdstats:
music_directory: /PATH/TO/YOUR/FILES
If you don't want the plugin to update the rating, you can disable it with::
mpdstats:
rating: False
If you want to change the way the rating is calculated, you can set the
``rating_mix`` option like this::
mpdstats:
rating_mix: 1.0
For details, see below.
Usage
-----
Now use the ``mpdstats`` command to fire it up::
Use the ``mpdstats`` command to fire it up::
$ beet mpdstats
Configuration
-------------
To configure the plugin, make an ``mpd:`` section in your
configuration file. The available options are:
- ``host``: The MPD server hostname.
Default: ``localhost``.
- ``port``: The MPD server port.
Default: 6600.
- ``password``: The MPD server password.
Default: None.
- ``music_directory``: If your MPD library is at a different location from the
beets library (e.g., because one is mounted on a NFS share), specify the path
here.
Default: The beets library directory.
- ``rating``: Enable rating updates.
Default: ``yes``.
- ``rating_mix``: Tune the way rating is calculated (see below).
Default: 0.75.
A Word on Ratings
-----------------

22
docs/plugins/mpdupdate.rst
View file

@ -6,9 +6,10 @@ update `MPD`_'s index whenever you change your beets library.
.. _MPD: http://www.musicpd.org/
To use it, enable it in your ``config.yaml`` by putting ``mpdupdate`` on your
``plugins`` line. Then, you'll probably want to configure the specifics of your
MPD server. You can do that using an ``mpd:`` section in your ``config.yaml``,
To use ``mpdupdate`` plugin, enable it in your configuration
(see :ref:`using-plugins`).
Then, you'll probably want to configure the specifics of your MPD server.
You can do that using an ``mpd:`` section in your ``config.yaml``,
which looks like this::
mpd:
@ -16,9 +17,22 @@ which looks like this::
port: 6600
password: seekrit
With that all in place, you'll see beets send the "update" command to your MPD server every time you change your beets library.
With that all in place, you'll see beets send the "update" command to your MPD
server every time you change your beets library.
If you want to communicate with MPD over a Unix domain socket instead over
TCP, just give the path to the socket in the filesystem for the ``host``
setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain
socket.)
Configuration
-------------
The available options under the ``mpd:`` section are:
- ``host``: The MPD server name.
Default: ``localhost``.
- ``password``: The MPD server password.
Default: None.
- ``port``: The MPD server port.
Default: 6600.

31
docs/plugins/play.rst
View file

@ -4,7 +4,10 @@ Play Plugin
The ``play`` plugin allows you to pass the results of a query to a music
player in the form of an m3u playlist.
To use the plugin, enable it in your configuration (see
Usage
-----
To use the ``play`` plugin, enable it in your configuration (see
:ref:`using-plugins`). Then use it by invoking the ``beet play`` command with
a query. The command will create a temporary m3u file and open it using an
appropriate application. You can query albums instead of tracks using the
@ -23,15 +26,21 @@ would on the command-line)::
play:
command: /usr/bin/command --option1 --option2 some_other_option
You can configure the plugin to emit relative paths. Use the ``relative_to``
configuration option::
play:
relative_to: /my/music/folder
When using the ``-a`` option, the m3u will have the paths to each track on
the matched albums. If you wish to have folders instead, you can change that
by setting ``use_files: False`` in your configuration file.
Enable beets' verbose logging to see the command's output if you need to
debug.
Configuration
-------------
To configure the plugin, make a ``play:`` section in your
configuration file. The available options are:
- ``command``: The command used to open the playlist.
Default: ``open`` on OS X, ``xdg-open`` on other Unixes and ``start`` on
Windows.
- ``relative_to``: Emit paths relative to base directory.
Default: None.
- ``use_folders``: When using the ``-a`` option, the m3u will contain the
paths to each track on the matched albums. Enable this option to
store paths to folders instead.
Default: ``no``.

4
docs/plugins/random.rst
View file

@ -5,8 +5,8 @@ The ``random`` plugin provides a command that randomly selects tracks or albums
from your library. This can be helpful if you need some help deciding what to
listen to.
First, enable the plugin named ``random`` (see :doc:`/plugins/index`). You'll then
be able to use the ``beet random`` command::
First, enable the plugin named ``random`` (see :ref:`using-plugins`). You'll
then be able to use the ``beet random`` command::
$ beet random
Aesop Rock - None Shall Pass - The Harbor Is Yours

41
docs/plugins/replaygain.rst
View file

@ -28,8 +28,8 @@ You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. python-gi).
.. _PyGObject 3.x: https://wiki.gnome.org/action/show/Projects/PyGObject
.. _GStreamer: http://gstreamer.freedesktop.org/
Then, enable the plugin (see :ref:`using-plugins`) and specify the GStreamer
backend by adding this to your configuration file::
Then, enable the ``replaygain`` plugin (see :ref:`using-plugins`) and specify
the GStreamer backend by adding this to your configuration file::
replaygain:
backend: gstreamer
@ -65,31 +65,32 @@ you can configure the path explicitly like so::
Configuration
-------------
Available configuration options for the ``replaygain`` section in your
configuration file include:
To configure the plugin, make a ``replaygain:`` section in your
configuration file. The available options are:
* **overwrite**: By default, files that already have ReplayGain tags will not
be re-analyzed. If you want to analyze *every* file on import, you can set
the ``overwrite`` option for the plugin in your :doc:`configuration file
</reference/config>`, like so::
replaygain:
overwrite: yes
* **targetlevel**: The target loudness level can be modified to any number of
decibels with the ``targetlevel`` option (default: 89 dB).
- ``auto``: Enable ReplayGain analysis during import.
Default: ``yes``.
- ``backend``: The analysis backend; either ``gstreamer`` or ``command``.
Default: ``command``.
- ``overwrite``: Re-analyze files that already have ReplayGain tags.
Default: ``no``.
- ``targetlevel``: A number of decibels for the target loudness level.
Default: 89.
These options only work with the "command" backend:
* **apply**: If you use a player that does not support ReplayGain
- ``apply``: If you use a player that does not support ReplayGain
specifications, you can force the volume normalization by applying the gain
to the file via the ``apply`` option. This is a lossless and reversible
operation with no transcoding involved.
* **noclip**: The use of ReplayGain can cause clipping if the average volume
of a song is below the target level. By default, a "prevent clipping" option
named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment to
whatever amount would keep clipping from occurring.
Default: ``no``.
- ``command``: The path to the ``mp3gain`` or ``aacgain`` executable (if beets
cannot find it by itself).
For example: ``/Applications/MacMP3Gain.app/Contents/Resources/aacgain``.
Default: Search in your ``$PATH``.
- ``noclip``: Reduce the amount of ReplayGain adjustment to whatever amount
would keep clipping from occurring.
Default: ``yes``.
Manual Analysis
---------------

12
docs/plugins/rewrite.rst
View file

@ -6,12 +6,12 @@ path formats. Specifically, it is intended to let you *canonicalize* names
such as artists: for example, perhaps you want albums from The Jimi Hendrix
Experience to be sorted into the same folder as solo Hendrix albums.
To use field rewriting, first enable the plugin by putting ``rewrite`` on your
``plugins`` line. Then, make a ``rewrite:`` section in your config file to
contain your rewrite rules. Each rule consists of a field name, a regular
expression pattern, and a replacement value. Rules are written ``fieldname
regex: replacement``. For example, this line implements the Jimi Hendrix
example above::
To use field rewriting, first enable the ``rewrite`` plugin
(see :ref:`using-plugins`).
Then, make a ``rewrite:`` section in your config file to contain your rewrite
rules. Each rule consists of a field name, a regular expression pattern, and a
replacement value. Rules are written ``fieldname regex: replacement``.
For example, this line implements the Jimi Hendrix example above::
rewrite:
artist The Jimi Hendrix Experience: Jimi Hendrix

14
docs/plugins/scrub.rst
View file

@ -11,7 +11,7 @@ Automatic Scrubbing
-------------------
To automatically remove files' tags before writing new ones, just
enable the plugin (see :doc:`/plugins/index`). When importing new files (with
enable the ``scrub`` plugin (see :ref:`using-plugins`). When importing new files (with
``import.write`` turned on) or modifying files' tags with the ``beet modify``
command, beets will first strip all types of tags entirely and then write the
database-tracked metadata to the file.
@ -31,11 +31,11 @@ The ``-W`` (or ``--nowrite``) option causes the command to just remove tags but
not restore any information. This will leave the files with no metadata
whatsoever.
Configuring
-----------
Configuration
-------------
The plugin has one configuration option, ``auto``, which lets you disable
automatic metadata stripping. To do so, add this to your ``config.yaml``::
To configure the plugin, make a ``scrub:`` section in your
configuration file. There is one option:
scrub:
auto: no
- ``auto``: Enable metadata stripping during import.
Default: ``yes``.

31
docs/plugins/smartplaylist.rst
View file

@ -7,9 +7,9 @@ created to work well with `MPD's`_ playlist functionality.
.. _MPD's: http://www.musicpd.org/
To use it, enable the plugin by putting ``smartplaylist`` in the ``plugins``
section in your ``config.yaml``. Then configure your smart playlists like the
following example::
To use it, enable the ``smartplaylist`` plugin in your configuration
(see :ref:`using-plugins`).
Then configure your smart playlists like the following example::
smartplaylist:
relative_to: ~/Music
@ -21,12 +21,6 @@ following example::
- name: beatles.m3u
query: 'artist:Beatles'
If you intend to use this plugin to generate playlists for MPD, you should set
``relative_to`` to your MPD music directory (by default, ``relative_to`` is
``None``, and the absolute paths to your music files will be generated).
``playlist_dir`` is where the generated playlist files will be put.
You can generate as many playlists as you want by adding them to the
``playlists`` section, using beets query syntax (see
:doc:`/reference/query`) for ``query`` and the file name to be generated for
@ -60,8 +54,7 @@ to albums that have a ``for_travel`` extensible field set to 1::
query: 'for_travel:1'
By default, all playlists are automatically regenerated after every beets
command that changes the library database. This can be disabled by specifying
``auto: no``. To force regeneration, you can invoke it manually from the
command that changes the library database. To force regeneration, you can invoke it manually from the
command line::
$ beet splupdate
@ -72,3 +65,19 @@ You can also use this plugin together with the :doc:`mpdupdate`, in order to
automatically notify MPD of the playlist change, by adding ``mpdupdate`` to
the ``plugins`` line in your config file *after* the ``smartplaylist``
plugin.
Configuration
-------------
To configure the plugin, make a ``smartplaylist:`` section in your
configuration file. In addition to the ``playlists`` described above, the
other configuration options are:
- ``auto``: Regenerate the playlist after every database change.
Default: ``yes``.
- ``playlist_dir``: Where to put the generated playlist files.
Default: The current working directory (i.e., ``'.'``).
- ``relative_to``: Generate paths in the playlist files relative to a base
directory. If you intend to use this plugin to generate playlists for MPD,
point this to your MPD music directory.
Default: Use absolute paths.

73
docs/plugins/spotify.rst
View file

@ -16,8 +16,8 @@ Why Use This Plugin?
Basic Usage
-----------
First, enable the plugin (see :ref:`using-plugins`). Then, use the ``spotify``
command with a beets query::
First, enable the ``spotify`` plugin (see :ref:`using-plugins`).
Then, use the ``spotify`` command with a beets query::
beet spotify [OPTIONS...] QUERY
@ -37,51 +37,43 @@ Command-line options include:
* ``--show-failures`` or ``-f``: List the tracks that did not match a Spotify
ID.
Configuring
-----------
Configuration
-------------
The default options should work as-is, but there are some options you can put in config.yaml:
The default options should work as-is, but there are some options you can put
in config.yaml under the ``spotify:`` section:
* ``mode``: See the section below on modes.
* ``region_filter``: Use the 2-character country abbreviation to limit results
* ``mode``: One of the following:
- ``list``: Print out the playlist as a list of links. This list can then
be pasted in to a new or existing Spotify playlist.
- ``open``: This mode actually sends a link to your default browser with
instructions to open Spotify with the playlist you created. Until this
has been tested on all platforms, it will remain optional.
Default: ``list``.
* ``region_filter``: A two-character country abbreviation, to limit results
to that market.
* ``show_failures``: Show the artist/album/track for each lookup that does not
return a Spotify ID (and therefore cannot be added to a playlist).
Default: None.
* ``show_failures``: List each lookup that does not return a Spotify ID (and
therefore cannot be added to a playlist).
Default: ``no``.
* ``tiebreak``: How to choose the track if there is more than one identical
result. For example, there might be multiple releases of the same album.
Currently, this defaults to "popularity", "first" simply chooses the first
in the list returned by Spotify.
result. For example, there might be multiple releases of the same album.
The options are ``popularity`` and ``first`` (to just choose the first match
returned).
Default: ``popularity``.
* ``regex``: An array of regex transformations to perform on the
track/album/artist fields before sending them to Spotify. Can be useful for
changing certain abbreviations, like ft. -> feat. See the examples below.
* ``artist_field`` / ``album_field`` / ``track_field``: These allow the user
to choose a different field to send to Spotify when looking up the track,
album and artist. Most users will not want to change this.
Default: None.
Example Configuration
---------------------
::
Here's an example::
spotify:
# Default is list, shows the plugin output. Open attempts to open
# directly in Spotify (only tested on Mac).
mode: "open"
# Filter tracks by only that market (2-letter code)
region_filter: "US"
# Display the tracks that did not match a Spotify ID.
mode: open
region_filter: US
show_faiulres: on
# Need to break ties when then are multiple tracks. Default is
popularity.
tiebreak: "first"
# Which beets fields to use for lookups.
artist_field: "albumartist"
album_field: "album"
track_field: "title"
tiebreak: first
regex: [
{
@ -96,12 +88,3 @@ Example Configuration
}
]
Spotify Plugin Modes
---------------------
* ``list``: The default mode is to print out the playlist as a list of links.
This list can then be pasted in to a new or existing Spotify playlist.
* ``open``: This mode actually sends a link to your default browser with
instructions to open Spotify with the playlist you created. Until this has
been tested on all platforms, it will remain optional.

49
docs/plugins/the.rst
View file

@ -2,39 +2,42 @@ The Plugin
==========
The ``the`` plugin allows you to move patterns in path formats. It's suitable,
for example, for moving articles from string start to the end. This is useful
for quick search on filesystems and generally looks good. Plugin DOES NOT
change tags. By default plugin supports English "the, a, an", but custom
for example, for moving articles from string start to the end. This is useful
for quick search on filesystems and generally looks good. Plugin does not
change tags. By default plugin supports English "the, a, an", but custom
regexp patterns can be added by user. How it works::
The Something -> Something, The
A Band -> Band, A
An Orchestra -> Orchestra, An
To use plugin, enable it by including ``the`` into ``plugins`` line of your
beets config. The plugin provides a template function called ``%the`` for use
in path format expressions::
To use the ``the`` plugin, enable it (see :doc:`/plugins/index`) and then use
a template function called ``%the`` in path format expressions::
paths:
default: %the{$albumartist}/($year) $album/$track $title
The default configuration moves all English articles to the end of the string,
but you can override these defaults to make more complex changes::
but you can override these defaults to make more complex changes.
the:
# handle "The" (on by default)
the: yes
# handle "A/An" (on by default)
a: yes
# format string, {0} - part w/o article, {1} - article
# spaces already trimmed from ends of both parts
# default is '{0}, {1}'
format: '{0}, {1}'
# strip instead of moving to the end, default is off
strip: no
# custom regexp patterns, space-separated
patterns: ...
Configuration
-------------
Custom patterns are case-insensitive regular expressions. Patterns can be
matched anywhere in the string (not just the beginning), so use ``^`` if you
intend to match leading words.
To configure the plugin, make a ``the:`` section in your
configuration file. The available options are:
- ``a``: Handle "A/An" moves.
Default: ``yes``.
- ``the``: handle "The" moves.
Default: ``yes``.
- ``patterns``: Custom regexp patterns, space-separated. Custom patterns are
case-insensitive regular expressions. Patterns can be matched anywhere in the
string (not just the beginning), so use ``^`` if you intend to match leading
words.
Default: ``[]``.
- ``strip``: Remove the article altogether instead of moving it to the end.
Default: ``no``.
- ``format``: A Python format string for the output. Use ``{0}`` to indicate
the part without the article and ``{1}`` for the article.
Spaces are already trimmed from ends of both parts.
Default: ``'{0}, {1}'``.

4
docs/plugins/types.rst
View file

@ -6,8 +6,8 @@ library. For example, you can declare that a ``rating`` field is numeric so
that you can query it with ranges---which isn't possible when the field is
considered a string (the default).
Enable the plugin as described in :doc:`/plugins/index` and then add a
``types`` section to your :doc:`configuration file </reference/config>`. The
Enable the ``types`` plugin as described in :doc:`/plugins/index` and then add
a ``types`` section to your :doc:`configuration file </reference/config>`. The
configuration section should map field name to one of ``int``, ``float``,
``bool``, or ``date``.

23
docs/plugins/web.rst
View file

@ -20,8 +20,8 @@ flask``.
.. _Flask: http://flask.pocoo.org/
Put ``web`` on your ``plugins`` line in your configuration file to enable the
plugin.
Finally, enable the ``web`` plugin in your configuration
(see :ref:`using-plugins`).
Run the Server
--------------
@ -35,12 +35,8 @@ You can also specify the hostname and port number used by the Web server. These
can be specified on the command line or in the ``[web]`` section of your
:doc:`configuration file </reference/config>`.
On the command line, use ``beet web [HOSTNAME] [PORT]``. In the config file, use
something like this::
web:
host: 127.0.0.1
port: 8888
On the command line, use ``beet web [HOSTNAME] [PORT]``. Or the configuration
options below.
Usage
-----
@ -50,6 +46,17 @@ Type queries into the little search box. Double-click a track to play it with
.. _HTML5 Audio: http://www.w3.org/TR/html-markup/audio.html
Configuration
-------------
To configure the plugin, make a ``web:`` section in your
configuration file. The available options are:
- ``host``: The server hostname.
Default: Bind to all interfaces.
- ``port``: The server port.
Default: 8337.
Implementation
--------------

21
docs/plugins/zero.rst
View file

@ -4,14 +4,21 @@ Zero Plugin
The ``zero`` plugin allows you to null fields in files' metadata tags. Fields
can be nulled unconditionally or conditioned on a pattern match. For example,
the plugin can strip useless comments like "ripped by MyGreatRipper." This
plugin only affects files' tags; the beets database is unchanged.
plugin only affects files' tags ; the beets database is left unchanged.
To use the plugin, enable it by including ``zero`` in the ``plugins`` line of
your configuration file. To configure the plugin, use a ``zero:`` section in
your configuration file. Set ``fields`` to the (whitespace-separated) list of
fields to change. You can get the list of available fields by running ``beet
fields``. To conditionally filter a field, use ``field: [regexp, regexp]`` to
specify regular expressions.
To use the ``zero`` plugin, enable the plugin in your configuration
(see :ref:`using-plugins`).
Configuration
-------------
Make a ``zero:`` section in your configuration file. You can specify the
fields to nullify and the conditions for nullifying them:
* Set ``fields`` to a whitespace-separated list of fields to change. You can
get the list of all available fields by running ``beet fields``.
* To conditionally filter a field, use ``field: [regexp, regexp]`` to specify
regular expressions.
For example::

19
docs/refresh_safari.js Normal file
View file

@ -0,0 +1,19 @@
var safari = Application('com.apple.Safari');
for (var i = 0; i < safari.windows.length; ++i) {
var win = safari.windows[i];
var tabs = win.tabs;
if (Object.keys(tabs).length) {
for (var j = 0; j < win.tabs.length; ++j) {
var tab = win.tabs[j];
var url = tab.url();
if (url.indexOf("file:") == 0) {
// A local file URL.
safari.doJavaScript("location.reload();", { in: tab });
console.log(url);
}
}
}
}
'done';