mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
document new Confit-based configuration
This commit is contained in:
Adrian Sampson
parent
3c511b9e27
commit
11e1fd1bd8
25 changed files with 423 additions and 436 deletions
|
|
@ -96,12 +96,12 @@ Configuring
|
|||
-----------
|
||||
|
||||
You'll want to set a few basic options before you start using beets. The
|
||||
configuration is stored in a text file: on Unix-like OSes, the config file is at
|
||||
``~/.beetsconfig``; on Windows, it's at ``%APPDATA%\beetsconfig.ini``. Create
|
||||
and edit the appropriate file with your favorite text editor. This file will
|
||||
start out empty, but here's good place to start::
|
||||
configuration is stored in a text file: on Unix-like OSes, the config file is
|
||||
at ``~/.config/beets/config.yaml``; on Windows, it's at
|
||||
``%APPDATA%\beets\config.yaml``. Create and edit the appropriate file with your
|
||||
favorite text editor. This file will start out empty, but here's good place to
|
||||
start::
|
||||
|
||||
[beets]
|
||||
directory: ~/music
|
||||
library: ~/data/musiclibrary.blb
|
||||
|
||||
|
|
@ -115,16 +115,27 @@ empty folder using beets' ``import`` command (see below). But you can configure
|
|||
beets to behave many other ways:
|
||||
|
||||
* Start with a new empty directory, but *move* new music in instead of copying
|
||||
it (saving disk space). Put ``import_move: yes`` in your config file.
|
||||
it (saving disk space). Put this in your config file::
|
||||
|
||||
import:
|
||||
move: yes
|
||||
|
||||
* Keep your current directory structure; importing should never move or copy
|
||||
files but instead just correct the tags on music. Put the line ``import_copy:
|
||||
no`` in your config file to disable any copying or renaming. Make sure to
|
||||
point ``directory`` at the place where your music is currently stored.
|
||||
files but instead just correct the tags on music. Put the line ``copy: no``
|
||||
under the ``import:`` heading in your config file to disable any copying or
|
||||
renaming. Make sure to point ``directory`` at the place where your music is
|
||||
currently stored.
|
||||
|
||||
* Keep your current directory structure and *do not* correct files' tags: leave
|
||||
files completely unmodified on your disk. (Corrected tags will still be stored
|
||||
in beets' database, and you can use them to do renaming or tag changes later.)
|
||||
Add both ``import_copy: no`` and ``import_write: no`` to your config file to
|
||||
disable renaming and tag-writing.
|
||||
Put this in your config file::
|
||||
|
||||
import:
|
||||
copy: no
|
||||
write: no
|
||||
|
||||
to disable renaming and tag-writing.
|
||||
|
||||
There are approximately six million other configuration options you can set
|
||||
here, including the directory and file naming scheme. See
|
||||
|
|
@ -151,7 +162,7 @@ this::
|
|||
|
||||
(Note that by default, this command will *copy music into the directory you
|
||||
specified above*. If you want to use your current directory structure, set the
|
||||
``import_copy`` config option.) To take the fast,
|
||||
``import.copy`` config option.) To take the fast,
|
||||
un-autotagged path, just say::
|
||||
|
||||
$ beet import -A /my/huge/mp3/library
|
||||
|
|
|
|||
|
|
@ -35,12 +35,9 @@ with its Python bindings) on your system.
|
|||
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 ``.beetsconfig`` file and add the line
|
||||
``plugins: bpd``. Like so::
|
||||
|
||||
[beets]
|
||||
plugins: bpd
|
||||
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.
|
||||
|
||||
Then, you can run BPD by invoking::
|
||||
|
||||
|
|
@ -66,14 +63,14 @@ 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 ``.beetsconfig``
|
||||
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``, and ``password``. Here's an example::
|
||||
|
||||
[bpd]
|
||||
host: 127.0.0.1
|
||||
port: 6600
|
||||
password: seekrit
|
||||
bpd:
|
||||
host: 127.0.0.1
|
||||
port: 6600
|
||||
password: seekrit
|
||||
|
||||
Implementation Notes
|
||||
--------------------
|
||||
|
|
|
|||
|
|
@ -74,14 +74,9 @@ Using
|
|||
-----
|
||||
|
||||
Once you have all the dependencies sorted out, you can enable fingerprinting by
|
||||
editing your :doc:`/reference/config`. Put ``chroma`` on your ``plugins:``
|
||||
line. Your config file should contain something like this::
|
||||
|
||||
[beets]
|
||||
plugins: chroma
|
||||
|
||||
With that, beets will use fingerprinting the next time you run ``beet import``.
|
||||
|
||||
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``.
|
||||
|
||||
.. _submitfp:
|
||||
|
||||
|
|
@ -91,11 +86,11 @@ 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
|
||||
service. Just use an OpenID or MusicBrainz account to log in and you'll get a
|
||||
short token string. Then, add the key to your :doc:`/reference/config` as the
|
||||
short token string. Then, add the key to your ``config.yaml`` as the
|
||||
value ``apikey`` in a section called ``acoustid`` like so::
|
||||
|
||||
[acoustid]
|
||||
apikey=AbCd1234
|
||||
acoustid:
|
||||
apikey: AbCd1234
|
||||
|
||||
Then, run ``beet submit``. (You can also provide a query to submit a subset of
|
||||
your library.) The command will use stored fingerprints if they're available;
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ To transcode music, this plugin requires the ``ffmpeg`` command-line
|
|||
tool. If its executable is in your path, it will be found automatically
|
||||
by the plugin. Otherwise, configure the plugin to locate the executable::
|
||||
|
||||
[convert]
|
||||
ffmpeg: /usr/bin/ffmpeg
|
||||
convert:
|
||||
ffmpeg: /usr/bin/ffmpeg
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
|
@ -35,7 +35,7 @@ Configuration
|
|||
-------------
|
||||
|
||||
The plugin offers several configuration options, all of which live under the
|
||||
``[convert]`` section:
|
||||
``convert:`` section:
|
||||
|
||||
* ``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
|
||||
|
|
@ -57,9 +57,9 @@ The plugin offers several configuration options, all of which live under the
|
|||
|
||||
Here's an example configuration::
|
||||
|
||||
[convert]
|
||||
embed: false
|
||||
max_bitrate: 200
|
||||
opts: -aq 4
|
||||
dest: /home/user/MusicForPhone
|
||||
threads: 4
|
||||
convert:
|
||||
embed: false
|
||||
max_bitrate: 200
|
||||
opts: -aq 4
|
||||
dest: /home/user/MusicForPhone
|
||||
threads: 4
|
||||
|
|
|
|||
|
|
@ -25,30 +25,29 @@ 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:`/reference/config` as the value ``apikey`` in a section called
|
||||
``echonest_tempo`` like so::
|
||||
:doc:`configuration file </reference/config>` as the value for ``apikey`` under
|
||||
the key ``echonest_tempo`` like so::
|
||||
|
||||
[echonest_tempo]
|
||||
apikey=YOUR_API_KEY
|
||||
echonest_temo:
|
||||
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 ``~/.beetsconfig``::
|
||||
fetching during import. To do so, add this to your ``config.yaml``::
|
||||
|
||||
[echonest_tempo]
|
||||
autofetch: no
|
||||
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
|
||||
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`), along with adding your EchoNest API key to your
|
||||
``~/.beetsconfig``. 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.
|
||||
: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).
|
||||
|
||||
|
|
@ -61,7 +60,7 @@ items that match a query (see :doc:`/reference/query`). For example,
|
|||
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.
|
||||
``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.
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ 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.
|
||||
|
||||
This behavior can be disabled with the ``autoembed`` config option (see below).
|
||||
This behavior can be disabled with the ``auto`` config option (see below).
|
||||
|
||||
Manually Embedding and Extracting Art
|
||||
-------------------------------------
|
||||
|
|
@ -40,11 +40,11 @@ embedded album art:
|
|||
Configuring
|
||||
-----------
|
||||
|
||||
``autoembed`` option lets you disable automatic album art embedding.
|
||||
To do so, add this to your ``~/.beetsconfig``::
|
||||
The ``auto`` option lets you disable automatic album art embedding.
|
||||
To do so, add this to your ``config.yaml``::
|
||||
|
||||
[embedart]
|
||||
autoembed: no
|
||||
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
|
||||
|
|
|
|||
|
|
@ -19,8 +19,8 @@ the :ref:`art-filename` config option.
|
|||
To disable automatic art downloading, just put this in your configuration
|
||||
file::
|
||||
|
||||
[fetchart]
|
||||
autofetch: no
|
||||
fetchart:
|
||||
auto: no
|
||||
|
||||
Manually Fetching Album Art
|
||||
---------------------------
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ The ``-t NUMBER`` option lets you specify how precise the fuzzy match has to be
|
|||
(default is 0.7). To make a fuzzier search, try ``beet fuzzy -t 0.5 Varoeldur``.
|
||||
A value of ``1`` will show only perfect matches and a value of ``0`` will match everything.
|
||||
|
||||
The default threshold can also be set from the config file.::
|
||||
The default threshold can also be set in the config file::
|
||||
|
||||
[fuzzy]
|
||||
threshold: 0.8
|
||||
fuzzy:
|
||||
threshold: 0.8
|
||||
|
|
|
|||
|
|
@ -8,28 +8,21 @@ groups: warn and skip. The skip group is checked first. Whitelist overrides any
|
|||
other patterns.
|
||||
|
||||
To use the plugin, enable it by including ``ihate`` in the ``plugins`` line of
|
||||
your beets config::
|
||||
your beets config. Then, add an ``ihate:`` section to your configuration file::
|
||||
|
||||
[beets]
|
||||
plugins = ihate
|
||||
|
||||
You need to configure the plugin before use, so add the following section into
|
||||
your config file and adjust it to your needs::
|
||||
|
||||
[ihate]
|
||||
# you will be warned about these suspicious genres/artists (regexps):
|
||||
warn_genre=rnb soul power\smetal
|
||||
warn_artist=bad\band another\sbad\sband
|
||||
warn_album=tribute\sto
|
||||
# if you don't like a genre in general, but accept some band playing it,
|
||||
# add exceptions here:
|
||||
warn_whitelist=hate\sexception
|
||||
# never import any of this:
|
||||
skip_genre=russian\srock polka
|
||||
skip_artist=manowar
|
||||
skip_album=christmas
|
||||
# but import this:
|
||||
skip_whitelist=
|
||||
ihate:
|
||||
# you will be warned about these suspicious genres/artists (regexps):
|
||||
warn_genre=rnb soul power\smetal
|
||||
warn_artist=bad\band another\sbad\sband
|
||||
warn_album=tribute\sto
|
||||
# if you don't like a genre in general, but accept some band playing it,
|
||||
# add exceptions here:
|
||||
warn_whitelist=hate\sexception
|
||||
# never import any of this:
|
||||
skip_genre=russian\srock polka
|
||||
skip_artist=manowar
|
||||
skip_album=christmas
|
||||
# but import this:
|
||||
skip_whitelist=
|
||||
|
||||
Note: The plugin will trust your decision in 'as-is' mode.
|
||||
|
||||
|
|
@ -4,21 +4,20 @@ ImportFeeds Plugin
|
|||
The ``importfeeds`` 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:`/reference/config`::
|
||||
:doc:`configuration file </reference/config>`. Then set a few options under the
|
||||
``importfeeds:`` section in the config file.
|
||||
|
||||
[beets]
|
||||
plugins: importfeeds
|
||||
|
||||
The ``feeds_dir`` parameter can be set to specify another folder than the default library directory.
|
||||
Three different types of outputs coexist, specify the ones you want to use by setting the ``feeds_formats`` parameter:
|
||||
The ``feeds_dir`` configuration option can be set to specify another folder
|
||||
than the default library directory. Three different types of outputs coexist,
|
||||
specify the ones you want to use by setting the ``feeds_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 ``feeds_dir`` folder on the iTunes dock icon.
|
||||
|
||||
An example of ``importfeeds`` configuration::
|
||||
Here's an example configuration for this plugin::
|
||||
|
||||
[importfeeds]
|
||||
feeds_formats: m3u link
|
||||
feeds_dir: ~/imports/
|
||||
m3u_name: newfiles.m3u
|
||||
importfeeds:
|
||||
feeds_formats: m3u link
|
||||
feeds_dir: ~/imports/
|
||||
m3u_name: newfiles.m3u
|
||||
|
|
|
|||
|
|
@ -14,15 +14,17 @@ To use a plugin, you have two options:
|
|||
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 `pythonpath` config variable to point to the directory containing the
|
||||
* Set the `pluginpath` config variable to point to the directory containing the
|
||||
plugin. (See :doc:`/reference/cli`.)
|
||||
|
||||
Then, set the `plugins` option in your `~/.beetsconfig` file, like so::
|
||||
Then, set the `plugins` option in your `config.yaml` file, like so::
|
||||
|
||||
[beets]
|
||||
plugins = mygreatplugin someotherplugin
|
||||
plugins: mygreatplugin someotherplugin
|
||||
|
||||
The value for `plugins` should be a space-separated list of plugin module names.
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,26 +7,22 @@ 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, like so::
|
||||
|
||||
[beets]
|
||||
plugins: inline
|
||||
|
||||
Then, make a ``[pathfields]`` section in your config file. In this section,
|
||||
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. The expression has all of a track's fields in scope, so you
|
||||
can refer to any normal attributes (such as ``artist`` or ``title``) as Python
|
||||
on your ``plugins`` line in your configuration file. Then, make a
|
||||
``pathfields:`` 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. The expression has all of a track's fields in scope, so you can
|
||||
refer to any normal attributes (such as ``artist`` or ``title``) as Python
|
||||
variables. Here are a couple of examples::
|
||||
|
||||
[pathfields]
|
||||
initial: albumartist[0].upper() + u'.'
|
||||
disc_and_track: u'%02i.%02i' % (disc, track) if
|
||||
disctotal > 1 else u'%02i' % (track)
|
||||
pathfields:
|
||||
initial: albumartist[0].upper() + u'.'
|
||||
disc_and_track: u'%02i.%02i' % (disc, track) if
|
||||
disctotal > 1 else u'%02i' % (track)
|
||||
|
||||
(Note that the config file's syntax allows newlines in values if the subsequent
|
||||
lines are indented.) These examples define ``$initial`` and
|
||||
Note that YAML syntax allows newlines in values if the subsequent
|
||||
lines are indented. These examples define ``$initial`` and
|
||||
``$disc_and_track`` fields that can be referenced in path templates like so::
|
||||
|
||||
[paths]
|
||||
default: $initial/$artist/$album%aunique{}/$disc_and_track $title
|
||||
paths:
|
||||
default: $initial/$artist/$album%aunique{}/$disc_and_track $title
|
||||
|
|
|
|||
|
|
@ -16,19 +16,16 @@ 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:`/reference/config`, like so::
|
||||
your ``plugins`` line in :doc:`config file </reference/config>`.
|
||||
|
||||
[beets]
|
||||
plugins: lastgenre
|
||||
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::
|
||||
|
||||
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
|
||||
lastgenre:
|
||||
whitelist: /path/to/genres.txt
|
||||
|
||||
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,11 +35,12 @@ Wikipedia`_.
|
|||
.. _pylast: http://code.google.com/p/pylast/
|
||||
.. _script that scrapes Wikipedia: https://gist.github.com/1241307
|
||||
|
||||
If no genre is found, you have the opportunity to specify a fixed string instead
|
||||
(declare *fallback_str* with no value to blank the genre field)::
|
||||
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_str:
|
||||
lastgenre:
|
||||
fallback: ''
|
||||
|
||||
|
||||
Canonicalization
|
||||
|
|
@ -56,12 +54,12 @@ leaves of the tree represent the most specific genres.
|
|||
To enable canonicalization, first install the `pyyaml`_ module (``pip install
|
||||
pyyaml``). Then set the ``canonical`` configuration value::
|
||||
|
||||
[lastgenre]
|
||||
canonical:
|
||||
lastgenre:
|
||||
canonical: ''
|
||||
|
||||
Leaving this value blank 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.
|
||||
Setting this value to the empty string 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/
|
||||
.. _pyyaml: http://pyyaml.org/
|
||||
|
|
|
|||
|
|
@ -14,10 +14,10 @@ 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
|
||||
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 ``autofetch`` config option (see below).
|
||||
This behavior can be disabled with the ``auto`` config option (see below).
|
||||
|
||||
Fetching Lyrics Manually
|
||||
------------------------
|
||||
|
|
@ -27,7 +27,7 @@ match a query (see :doc:`/reference/query`). For example, ``beet lyrics magnetic
|
|||
fields absolutely cuckoo`` will get the lyrics for the appropriate Magnetic
|
||||
Fields song, ``beet lyrics magnetic fields`` will get lyrics for all my tracks
|
||||
by that band, and ``beet lyrics`` will get lyrics for my entire library. The
|
||||
lyrics will be added to the beets database and, if ``import_write`` is on,
|
||||
lyrics will be added to the beets database and, if ``import.write`` is on,
|
||||
embedded into files' metadata.
|
||||
|
||||
The ``-p`` option to the ``lyrics`` command makes it print lyrics out to the
|
||||
|
|
@ -36,9 +36,9 @@ console so you can view the fetched (or previously-stored) lyrics.
|
|||
Configuring
|
||||
-----------
|
||||
|
||||
The plugin has one configuration option, ``autofetch``, which lets you disable
|
||||
The plugin has one configuration option, ``auto``, which lets you disable
|
||||
automatic lyrics fetching during import. To do so, add this to your
|
||||
``~/.beetsconfig``::
|
||||
``config.yaml``::
|
||||
|
||||
[lyrics]
|
||||
autofetch: no
|
||||
lyrics:
|
||||
auto: no
|
||||
|
|
|
|||
|
|
@ -8,11 +8,11 @@ maintain your `music collection`_ list there.
|
|||
|
||||
To begin, just enable the ``mbcollection`` plugin (see :doc:`/plugins/index`).
|
||||
Then, add your MusicBrainz username and password to your
|
||||
:doc:`/reference/config` in a ``musicbrainz`` section::
|
||||
:doc:`configuration file </reference/config>` under a ``musicbrainz`` section::
|
||||
|
||||
[musicbrainz]
|
||||
user: USERNAME
|
||||
pass: PASSWORD
|
||||
musicbrainz:
|
||||
user: you
|
||||
pass: seekrit
|
||||
|
||||
Then, use the ``beet mbupdate`` command to send your albums to MusicBrainz. The
|
||||
command automatically adds all of your albums to the first collection it finds.
|
||||
|
|
|
|||
|
|
@ -6,18 +6,14 @@ update `MPD`_'s index whenever you change your beets library.
|
|||
|
||||
.. _MPD: http://mpd.wikia.com/wiki/Music_Player_Daemon_Wiki
|
||||
|
||||
To use it, enable it in your ``.beetsconfig`` by putting ``mpdupdate`` on your ``plugins`` line. Your ``.beetsconfig`` should look like this::
|
||||
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 ``mpdupdate:`` section in your
|
||||
``config.yaml``, which looks like this::
|
||||
|
||||
[beets]
|
||||
plugins: mpdupdate
|
||||
|
||||
Then, you'll probably want to configure the specifics of your MPD server. You
|
||||
can do that using an ``[mpdupdate]`` section in your ``.beetsconfig``, which
|
||||
looks like this::
|
||||
|
||||
[mpdupdate]
|
||||
host = localhost
|
||||
port = 6600
|
||||
password = seekrit
|
||||
mpdupdate:
|
||||
host: localhost
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -25,8 +25,8 @@ Then enable the ``replaygain`` plugin (see :doc:`/reference/config`). If beets
|
|||
doesn't automatically find the ``mp3gain`` or ``aacgain`` executable, you can
|
||||
configure the path explicitly like so::
|
||||
|
||||
[replaygain]
|
||||
command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain
|
||||
replaygain:
|
||||
command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain
|
||||
|
||||
Usage & Configuration
|
||||
---------------------
|
||||
|
|
@ -37,10 +37,10 @@ if your player supports these tags, it can use them to do level adjustment.
|
|||
|
||||
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:`/reference/config`, like so::
|
||||
for the plugin in your :doc:`configuration file </reference/config>`, like so::
|
||||
|
||||
[replaygain]
|
||||
overwrite: yes
|
||||
replaygain:
|
||||
overwrite: yes
|
||||
|
||||
The target level can be modified to any target dB with the ``targetlevel``
|
||||
option (default: 89 dB).
|
||||
|
|
@ -75,7 +75,7 @@ query (see :doc:`/reference/query`) to indicate which items or albums to
|
|||
analyze.
|
||||
|
||||
ReplayGain analysis is not fast, so you may want to disable it during import.
|
||||
Use the ``automatic`` config option to control this::
|
||||
Use the ``auto`` config option to control this::
|
||||
|
||||
[replaygain]
|
||||
automatic: no
|
||||
replaygain:
|
||||
auto: no
|
||||
|
|
|
|||
|
|
@ -6,19 +6,15 @@ 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::
|
||||
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::
|
||||
|
||||
[beets]
|
||||
plugins: rewrite
|
||||
|
||||
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
|
||||
rewrite:
|
||||
artist The Jimi Hendrix Experience: Jimi Hendrix
|
||||
|
||||
This will make ``$artist`` in your path formats expand to "Jimi Henrix" where it
|
||||
would otherwise be "The Jimi Hendrix Experience".
|
||||
|
|
@ -27,8 +23,8 @@ The pattern is a case-insensitive regular expression. This means you can use
|
|||
ordinary regular expression syntax to match multiple artists. For example, you
|
||||
might use::
|
||||
|
||||
[rewrite]
|
||||
artist .*jimi hendrix.*: Jimi Hendrix
|
||||
rewrite:
|
||||
artist .*jimi hendrix.*: Jimi Hendrix
|
||||
|
||||
As a convenience, the plugin applies patterns for the ``artist`` field to the
|
||||
``albumartist`` field as well. (Otherwise, you would probably want to duplicate
|
||||
|
|
|
|||
|
|
@ -12,11 +12,11 @@ Automatic Scrubbing
|
|||
|
||||
To automatically remove files' tags before writing new ones, just
|
||||
enable the plugin (see :doc:`/plugins/index`). When importing new files (with
|
||||
``import_write`` turned on) or modifying files' tags with the ``beet modify``
|
||||
``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.
|
||||
|
||||
This behavior can be disabled with the ``autoscrub`` config option (see below).
|
||||
This behavior can be disabled with the ``auto`` config option (see below).
|
||||
|
||||
Manual Scrubbing
|
||||
----------------
|
||||
|
|
@ -35,7 +35,7 @@ Configuring
|
|||
-----------
|
||||
|
||||
The plugin has one configuration option, ``autoscrub``, which lets you disable
|
||||
automatic metadata stripping. To do so, add this to your ``~/.beetsconfig``::
|
||||
automatic metadata stripping. To do so, add this to your ``config.yaml``::
|
||||
|
||||
[scrub]
|
||||
autoscrub: no
|
||||
scrub:
|
||||
auto: no
|
||||
|
|
|
|||
|
|
@ -11,35 +11,30 @@ regexp patterns can be added by user. How it works::
|
|||
A Band -> Band, A
|
||||
An Orchestra -> Orchestra, An
|
||||
|
||||
To use plugin, enable it by including ``the`` into ``plugins`` line of
|
||||
your beets config::
|
||||
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::
|
||||
|
||||
[beets]
|
||||
plugins = the
|
||||
paths:
|
||||
default: %the{$albumartist}/($year) $album/$track $title
|
||||
|
||||
Plugin provides template function %the, so you can use it on $albumartist or $artist::
|
||||
The default configuration moves all English articles to the end of the string,
|
||||
but you can override these defaults to make more complex changes::
|
||||
|
||||
[paths]
|
||||
default: %the{$albumartist}/($year) $album/$track $title
|
||||
the:
|
||||
# handle The, default is on
|
||||
the=yes
|
||||
# handle A/An, default is on
|
||||
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, separated by space
|
||||
patterns=
|
||||
|
||||
Default options are acceptable (moves all English articles to the end), but you
|
||||
can add plugin section into config file::
|
||||
|
||||
[the]
|
||||
# handle The, default is on
|
||||
the=yes
|
||||
# handle A/An, default is on
|
||||
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, separated by space
|
||||
patterns=
|
||||
|
||||
Custom patterns are usual regular expressions. Ignore case is turned on, but ^ is not added
|
||||
automatically, so be careful. Actually, you can swap arguments in format option and write
|
||||
regexp to match end of the string, so things will be moved from the end of the string to
|
||||
start.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,8 @@ flask``.
|
|||
|
||||
.. _Flask: http://flask.pocoo.org/
|
||||
|
||||
Put ``plugins=web`` in your ``.beetsconfig`` to enable the plugin.
|
||||
Put ``web`` on your ``plugins`` line in your configuration file to enable the
|
||||
plugin.
|
||||
|
||||
Run the Server
|
||||
--------------
|
||||
|
|
@ -32,14 +33,14 @@ http://localhost:8337/. This is what it looks like:
|
|||
|
||||
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:`/reference/config`.
|
||||
: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
|
||||
web:
|
||||
host: 127.0.0.1
|
||||
port: 8888
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
|
|
|||
|
|
@ -38,8 +38,8 @@ plugin can do. (Read on!)
|
|||
|
||||
To use your new plugin, make sure your ``beetsplug`` directory is in the Python
|
||||
path (using ``PYTHONPATH`` or by installing in a `virtualenv`_, for example).
|
||||
Then, as described above, edit your ``.beetsconfig`` to include
|
||||
``plugins=myawesomeplugin`` (substituting the name of the Python module
|
||||
Then, as described above, edit your ``config.yaml`` to include
|
||||
``plugins: myawesomeplugin`` (substituting the name of the Python module
|
||||
containing your plugin).
|
||||
|
||||
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
|
||||
|
|
@ -75,8 +75,7 @@ your command name.
|
|||
|
||||
You'll need to add a function to your command by saying ``mycommand.func =
|
||||
myfunction``. This function should take the following parameters: ``lib`` (a
|
||||
beets ``Library`` object), ``config`` (a `ConfigParser object`_ containing the
|
||||
configuration values), and ``opts`` and ``args`` (command-line options and
|
||||
beets ``Library`` object) and ``opts`` and ``args`` (command-line options and
|
||||
arguments as returned by `OptionParser.parse_args`_).
|
||||
|
||||
.. _ConfigParser object: http://docs.python.org/library/configparser.html
|
||||
|
|
@ -191,17 +190,28 @@ which have somewhat helpful docstrings.
|
|||
Read Configuration Options
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Plugins can configure themselves using the ``.beetsconfig`` file. Define a
|
||||
``configure`` method on your plugin that takes an ``OptionParser`` object as an
|
||||
argument. Then use the ``beets.ui.config_val`` convenience function to access
|
||||
values from the config file. Like so::
|
||||
Plugins can configure themselves using the ``config.yaml`` file. You can read
|
||||
configuration values in two ways. The first is to use `self.config` within
|
||||
your plugin class. This gives you a view onto the configuration values in a
|
||||
section with the same name as your plugin's module. For example, if your plugin
|
||||
is in ``greatplugin.py``, then `self.config` will refer to options under the
|
||||
``greatplugin:`` section of the config file.
|
||||
|
||||
class MyPlugin(BeetsPlugin):
|
||||
def configure(self, config):
|
||||
number_of_goats = beets.ui.config_val(config, 'myplug', 'goats', '42')
|
||||
For example, if you have a configuration value called "foo", then users can put
|
||||
this in their ``config.yaml``::
|
||||
|
||||
Try looking at the ``mpdupdate`` plugin (included with beets) for an example of
|
||||
real-world use of this API.
|
||||
greatplugin:
|
||||
foo: bar
|
||||
|
||||
To access this value, say ``self.config['foo'].get()`` at any point in your
|
||||
plugin's code. The `self.config` object is a *view* as defined by the `Confit`_
|
||||
library.
|
||||
|
||||
.. _Confit: http://confit.readthedocs.org/
|
||||
|
||||
If you want to access configuration values *outside* of your plugin's section,
|
||||
import the `config` object from the `beets` module. That is, just put ``from
|
||||
beets import config`` at the top of your plugin and access values from there.
|
||||
|
||||
Add Path Format Functions and Fields
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -1,29 +1,26 @@
|
|||
Zero Plugin
|
||||
===========
|
||||
|
||||
The ``zero`` plugin allows you to null fields before writing tags to files.
|
||||
Fields can be nulled unconditionally or by pattern match. For example, it can
|
||||
be used to strip useless comments like "ripped by" etc or any other stuff you
|
||||
hate. Library is not modified.
|
||||
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.
|
||||
|
||||
To use plugin, enable it by including ``zero`` into ``plugins`` line of
|
||||
your beets config::
|
||||
|
||||
[beets]
|
||||
plugins = zero
|
||||
|
||||
To configure the plugin, use a ``[zero]`` section in your configuration file.
|
||||
Set ``fields`` to the (whitespace-separated) list of fields to null. 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 plugin, enable it by including ``zero`` into ``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.
|
||||
|
||||
For example::
|
||||
|
||||
[zero]
|
||||
fields=month day genre comments
|
||||
# Custom regexp patterns for each field, separated by spaces:
|
||||
comments=EAC LAME from.+collection ripped\sby
|
||||
genre=rnb power\smetal
|
||||
zero:
|
||||
fields: month day genre comments
|
||||
comments: [EAC, LAME, from.+collection, 'ripped by']
|
||||
genre: [rnb, 'power metal']
|
||||
|
||||
If custom pattern is not defined, field will be nulled unconditionally. Note
|
||||
that the plugin currently does not zero fields when importing "as-is".
|
||||
If custom pattern is not defined for a given field, the field will be nulled
|
||||
unconditionally.
|
||||
|
||||
Note that the plugin currently does not zero fields when importing "as-is".
|
||||
|
|
|
|||
|
|
@ -24,6 +24,8 @@ Command-Line Interface
|
|||
Commands
|
||||
--------
|
||||
|
||||
.. _import-cmd:
|
||||
|
||||
import
|
||||
``````
|
||||
::
|
||||
|
|
@ -81,7 +83,7 @@ right now; this is something we need to work on. Read the
|
|||
To get this to work correctly, you'll need to use an incremental import *every
|
||||
time* you run an import on the directory in question---including the first
|
||||
time, when no subdirectories will be skipped. So consider enabling the
|
||||
``import_incremental`` configuration option.
|
||||
``incremental`` configuration option.
|
||||
|
||||
* By default, beets will proceed without asking if it finds a very close
|
||||
metadata match. To disable this and have the importer as you every time,
|
||||
|
|
@ -105,10 +107,10 @@ right now; this is something we need to work on. Read the
|
|||
Just point the ``beet import`` command at a directory of files that are
|
||||
already catalogged in your library. Beets will automatically detect this
|
||||
situation and avoid duplicating any items. In this situation, the "copy
|
||||
files" option (``-c``/``-C`` on the command line or ``import_copy`` in the
|
||||
files" option (``-c``/``-C`` on the command line or ``copy`` in the
|
||||
config file) has slightly different behavior: it causes files to be *moved*,
|
||||
rather than duplicated, if they're already in your library. (The same is
|
||||
true, of course, if ``import_move`` is enabled.) That is, your directory
|
||||
true, of course, if ``move`` is enabled.) That is, your directory
|
||||
structure will be updated to reflect the new tags if copying is enabled; you
|
||||
never end up with two copies of the file.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,100 +1,62 @@
|
|||
.beetsconfig
|
||||
============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
The ``beet`` command reads configuration information from ``~/.beetsconfig`` on
|
||||
Unix-like OSes (inluding Mac OS X) and ``%APPDATA%\beetsconfig.ini`` on Windows.
|
||||
The file is in INI format.
|
||||
Beets has an extensive configuration system that lets you customize nearly
|
||||
every aspect of its operation. To configure beets, you'll edit a file called
|
||||
``config.yaml``. The location of this file depends on your OS:
|
||||
|
||||
Options
|
||||
-------
|
||||
* On Unix-like OSes (including OS X), you want ``~/.config/beets/config.yaml``.
|
||||
* On Windows, use ``%APPDATA%\beets\config.yaml``. This is usually in a
|
||||
directory like ``C:\Users\You\AppData\Roaming``.
|
||||
* On OS X, you can also use ``~/Library/Application Support/beets/config.yaml``
|
||||
if you prefer that over the Unix-like ``~/.config``.
|
||||
* If you prefer a different location, set the ``BEETSDIR`` environment variable
|
||||
to a path; beets will then look for a ``config.yaml`` in that directory.
|
||||
|
||||
These options are available, all of which must appear under the ``[beets]``
|
||||
section header:
|
||||
The config file uses `YAML`_ syntax. You can use the full power of YAML, but
|
||||
most configuration options are simple key/value pairs. This means your config
|
||||
file will look like this::
|
||||
|
||||
option: value
|
||||
another_option: foo
|
||||
bigger_option:
|
||||
key: value
|
||||
foo: bar
|
||||
|
||||
If you have questions about more sophisticated syntax, take a look at the
|
||||
`YAML`_ documentation.
|
||||
|
||||
.. _YAML: http://yaml.org/
|
||||
|
||||
Global Options
|
||||
--------------
|
||||
|
||||
These options control beets' global operation.
|
||||
|
||||
library
|
||||
~~~~~~~
|
||||
|
||||
Path to the beets library file. Defaults to ``~/.beetsmusic.blb`` on Unix
|
||||
and ``%APPDATA\beetsmusic.blb`` on Windows.
|
||||
Path to the beets library file. By default, beets will use a file called
|
||||
``beetsmusic.blb`` alongside your configuration file.
|
||||
|
||||
directory
|
||||
~~~~~~~~~
|
||||
|
||||
The directory to which files will be copied/moved when adding them to the
|
||||
library. Defaults to ``~/Music``.
|
||||
library. Defaults to a folder called ``Music`` in your home directory.
|
||||
|
||||
import_write
|
||||
~~~~~~~~~~~~
|
||||
plugins
|
||||
~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether metadata (e.g., ID3) tags are
|
||||
written to files when using ``beet import``. Defaults to ``yes``. The ``-w``
|
||||
and ``-W`` command-line options override this setting.
|
||||
A space-separated list of plugin module names to load. For instance, beets
|
||||
includes the BPD plugin for playing music.
|
||||
|
||||
import_copy
|
||||
~~~~~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, indicating whether to **copy** files into the
|
||||
library directory when using ``beet import``. Defaults to ``yes``. Can be
|
||||
overridden with the ``-c`` and ``-C`` command-line options.
|
||||
|
||||
The option is ignored if ``import_move`` is enabled (i.e., beets can move or
|
||||
copy files but it doesn't make sense to do both).
|
||||
|
||||
import_move
|
||||
~~~~~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, indicating whether to **move** files into the
|
||||
library directory when using ``beet import``.
|
||||
Defaults to ``no``.
|
||||
|
||||
The effect is similar to the ``import_copy`` option but you end up with only
|
||||
one copy of the imported file. ("Moving" works even across filesystems; if
|
||||
necessary, beets will copy and then delete when a simple rename is
|
||||
impossible.) Moving files can be risky—it's a good idea to keep a backup in
|
||||
case beets doesn't do what you expect with your files.
|
||||
|
||||
This option *overrides* ``import_copy``, so enabling it will always move
|
||||
(and not copy) files. The ``-c`` switch to the ``beet import`` command,
|
||||
however, still takes precedence.
|
||||
|
||||
import_resume
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Either ``yes``, ``no``, or ``ask``. Controls whether interrupted imports
|
||||
should be resumed. "Yes" means that imports are always resumed when
|
||||
possible; "no" means resuming is disabled entirely; "ask" (the default)
|
||||
means that the user should be prompted when resuming is possible. The ``-p``
|
||||
and ``-P`` flags correspond to the "yes" and "no" settings and override this
|
||||
option.
|
||||
|
||||
import_incremental
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether imported directories are
|
||||
recorded and whether these recorded directories are skipped. This
|
||||
corresponds to the ``-i`` flag to ``beet import``.
|
||||
|
||||
import_quiet_fallback
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Either ``skip`` (default) or ``asis``, specifying what should happen in
|
||||
quiet mode (see the ``-q`` flag to ``import``, above) when there is no
|
||||
strong recommendation.
|
||||
|
||||
import_timid
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether the importer runs in *timid*
|
||||
mode, in which it asks for confirmation on every autotagging match, even the
|
||||
ones that seem very close. Defaults to ``no``. The ``-t`` command-line flag
|
||||
controls the same setting.
|
||||
|
||||
import_log
|
||||
pluginpath
|
||||
~~~~~~~~~~
|
||||
|
||||
Specifies a filename where the importer's log should be kept. By default,
|
||||
no log is written. This can be overridden with the ``-l`` flag to
|
||||
``import``.
|
||||
A colon-separated list of directories to search for plugins. These paths
|
||||
are just added to ``sys.path`` before the plugins are loaded. The plugins
|
||||
still have to be contained in a ``beetsplug`` namespace package.
|
||||
|
||||
ignore
|
||||
~~~~~~
|
||||
|
|
@ -110,25 +72,24 @@ replace
|
|||
|
||||
A set of regular expression/replacement pairs to be applied to all filenames
|
||||
created by beets. Typically, these replacements are used to avoid confusing
|
||||
problems or errors with the filesystem (for example, leading ``.``
|
||||
characters are replaced on Unix and trailing whitespace is removed on
|
||||
Windows). To override these substitutions, specify a sequence of
|
||||
whitespace-separated terms; the first term is a regular expression and the
|
||||
second is a string that should replace anything matching that regex. For
|
||||
example, ``replace = [xy] z`` will make beets replace all instances of the
|
||||
characters ``x`` or ``y`` with the character ``z``.
|
||||
problems or errors with the filesystem (for example, leading dots, which hide
|
||||
files on Unix, and trailing whitespace, which is illegal on Windows). To
|
||||
override these substitutions, specify a mapping from regular expression to
|
||||
replacement strings. For example, ``[xy]: z`` will make beets replace all
|
||||
instances of the characters ``x`` or ``y`` with the character ``z``.
|
||||
|
||||
If you do change this value, be certain that you include at least enough
|
||||
substitutions to avoid causing errors on your operating system. Here are
|
||||
the default substitutions used by beets, which are sufficient to avoid
|
||||
unexpected behavior on all popular platforms::
|
||||
|
||||
replace = [\\/] _
|
||||
^\. _
|
||||
[\x00-\x1f] _
|
||||
[<>:"\?\*\|] _
|
||||
\.$ _
|
||||
\s+$ <strip>
|
||||
replace:
|
||||
'[\\/]': _
|
||||
'^\.': _
|
||||
'[\x00-\x1f]': _
|
||||
'[<>:"\?\*\|]': _
|
||||
'\.$': _
|
||||
'\s+$': ''
|
||||
|
||||
These substitutions remove forward and back slashes, leading dots, and
|
||||
control characters—all of which is a good idea on any OS. The fourth line
|
||||
|
|
@ -137,20 +98,6 @@ compatibility with Windows-influenced network filesystems like Samba).
|
|||
Trailing dots and trailing whitespace, which can cause problems on Windows
|
||||
clients, are also removed.
|
||||
|
||||
To replace space characters, use the ``\s`` (whitespace) entity::
|
||||
|
||||
replace = \s _
|
||||
...
|
||||
|
||||
This will avoid using a literal space and thus confusing beets. (``\s`` also
|
||||
matches tabs and newlines, but that is probably fine.)
|
||||
|
||||
To remove characters entirely, use ``<strip>`` as the replacement. For
|
||||
example, to remove all vowels from your filenames::
|
||||
|
||||
replace = [aeiou] <strip>
|
||||
...
|
||||
|
||||
.. _art-filename:
|
||||
|
||||
art_filename
|
||||
|
|
@ -162,19 +109,6 @@ of the syntax available to :doc:`/reference/pathformat`. Defaults to ``cover``
|
|||
(i.e., images will be named ``cover.jpg`` or ``cover.png`` and placed in the
|
||||
album's directory).
|
||||
|
||||
plugins
|
||||
~~~~~~~
|
||||
|
||||
A space-separated list of plugin module names to load. For instance, beets
|
||||
includes the BPD plugin for playing music.
|
||||
|
||||
pluginpath
|
||||
~~~~~~~~~~
|
||||
|
||||
A colon-separated list of directories to search for plugins. These paths
|
||||
are just added to ``sys.path`` before the plugins are loaded. The plugins
|
||||
still have to be contained in a ``beetsplug`` namespace package.
|
||||
|
||||
threaded
|
||||
~~~~~~~~
|
||||
|
||||
|
|
@ -231,38 +165,113 @@ If you enable ``per_disc_numbering``, you will likely want to change your
|
|||
filenames sort correctly in album directories. For example, you might want to
|
||||
use a path format like this::
|
||||
|
||||
[paths]
|
||||
default: $albumartist/$album%aunique{}/$disc-$track $title
|
||||
paths:
|
||||
default: $albumartist/$album%aunique{}/$disc-$track $title
|
||||
|
||||
import_delete
|
||||
~~~~~~~~~~~~~
|
||||
Importer Options
|
||||
----------------
|
||||
|
||||
Either ``yes`` or ``no``. When enabled in conjunction with ``import_copy``,
|
||||
deletes original files after they are copied into your library. Has no
|
||||
effect if the importer is in ``import_move`` mode or "leave files in place"
|
||||
mode. Defaults to ``no``.
|
||||
The options that control the :ref:`import-cmd` command are indented under the
|
||||
``import:`` key. For example, you might have a section in your configuration
|
||||
file that looks like this::
|
||||
|
||||
This option is historical and deprecated: it's almost always more
|
||||
appropriate to use ``import_move`` instead.
|
||||
import:
|
||||
write: yes
|
||||
copy: yes
|
||||
resume: no
|
||||
|
||||
These options are available in this section:
|
||||
|
||||
write
|
||||
~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether metadata (e.g., ID3) tags are
|
||||
written to files when using ``beet import``. Defaults to ``yes``. The ``-w``
|
||||
and ``-W`` command-line options override this setting.
|
||||
|
||||
copy
|
||||
~~~~
|
||||
|
||||
Either ``yes`` or ``no``, indicating whether to **copy** files into the
|
||||
library directory when using ``beet import``. Defaults to ``yes``. Can be
|
||||
overridden with the ``-c`` and ``-C`` command-line options.
|
||||
|
||||
The option is ignored if ``move`` is enabled (i.e., beets can move or
|
||||
copy files but it doesn't make sense to do both).
|
||||
|
||||
move
|
||||
~~~~
|
||||
|
||||
Either ``yes`` or ``no``, indicating whether to **move** files into the
|
||||
library directory when using ``beet import``.
|
||||
Defaults to ``no``.
|
||||
|
||||
The effect is similar to the ``copy`` option but you end up with only
|
||||
one copy of the imported file. ("Moving" works even across filesystems; if
|
||||
necessary, beets will copy and then delete when a simple rename is
|
||||
impossible.) Moving files can be risky—it's a good idea to keep a backup in
|
||||
case beets doesn't do what you expect with your files.
|
||||
|
||||
This option *overrides* ``copy``, so enabling it will always move
|
||||
(and not copy) files. The ``-c`` switch to the ``beet import`` command,
|
||||
however, still takes precedence.
|
||||
|
||||
resume
|
||||
~~~~~~
|
||||
|
||||
Either ``yes``, ``no``, or ``ask``. Controls whether interrupted imports
|
||||
should be resumed. "Yes" means that imports are always resumed when
|
||||
possible; "no" means resuming is disabled entirely; "ask" (the default)
|
||||
means that the user should be prompted when resuming is possible. The ``-p``
|
||||
and ``-P`` flags correspond to the "yes" and "no" settings and override this
|
||||
option.
|
||||
|
||||
incremental
|
||||
~~~~~~~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether imported directories are
|
||||
recorded and whether these recorded directories are skipped. This
|
||||
corresponds to the ``-i`` flag to ``beet import``.
|
||||
|
||||
quiet_fallback
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Either ``skip`` (default) or ``asis``, specifying what should happen in
|
||||
quiet mode (see the ``-q`` flag to ``import``, above) when there is no
|
||||
strong recommendation.
|
||||
|
||||
timid
|
||||
~~~~~
|
||||
|
||||
Either ``yes`` or ``no``, controlling whether the importer runs in *timid*
|
||||
mode, in which it asks for confirmation on every autotagging match, even the
|
||||
ones that seem very close. Defaults to ``no``. The ``-t`` command-line flag
|
||||
controls the same setting.
|
||||
|
||||
log
|
||||
~~~
|
||||
|
||||
Specifies a filename where the importer's log should be kept. By default,
|
||||
no log is written. This can be overridden with the ``-l`` flag to
|
||||
``import``.
|
||||
|
||||
.. _path-format-config:
|
||||
|
||||
Path Format Configuration
|
||||
-------------------------
|
||||
|
||||
You can also configure the directory hierarchy beets uses to store music. These
|
||||
settings appear under the ``[paths]`` section (rather than the main ``[beets]``
|
||||
section we used above). Each string is a template string that can refer to
|
||||
metadata fields like ``$artist`` or ``$title``. The filename extension is added
|
||||
automatically. At the moment, you can specify three special paths: ``default``
|
||||
for most releases, ``comp`` for "various artist" releases with no dominant
|
||||
artist, and ``singleton`` for non-album tracks. The defaults look like this::
|
||||
You can also configure the directory hierarchy beets uses to store music.
|
||||
These settings appear under the ``paths:`` key. Each string is a template
|
||||
string that can refer to metadata fields like ``$artist`` or ``$title``. The
|
||||
filename extension is added automatically. At the moment, you can specify three
|
||||
special paths: ``default`` for most releases, ``comp`` for "various artist"
|
||||
releases with no dominant artist, and ``singleton`` for non-album tracks. The
|
||||
defaults look like this::
|
||||
|
||||
[paths]
|
||||
default: $albumartist/$album%aunique{}/$track $title
|
||||
singleton: Non-Album/$artist/$title
|
||||
comp: Compilations/$album%aunique{}/$track $title
|
||||
paths:
|
||||
default: $albumartist/$album%aunique{}/$track $title
|
||||
singleton: Non-Album/$artist/$title
|
||||
comp: Compilations/$album%aunique{}/$track $title
|
||||
|
||||
Note the use of ``$albumartist`` instead of ``$artist``; this ensure that albums
|
||||
will be well-organized. For more about these format strings, see
|
||||
|
|
@ -270,21 +279,19 @@ will be well-organized. For more about these format strings, see
|
|||
albums are placed in different directories; see :ref:`aunique` for details.
|
||||
|
||||
In addition to ``default``, ``comp``, and ``singleton``, you can condition path
|
||||
queries based on beets queries (see :doc:`/reference/query`). There's one catch:
|
||||
because the ``:`` character is reserved for separating the query from the
|
||||
template string, the ``_`` character is substituted for ``:`` in these queries.
|
||||
This means that a config file like this::
|
||||
queries based on beets queries (see :doc:`/reference/query`). This means that a
|
||||
config file like this::
|
||||
|
||||
[paths]
|
||||
albumtype_soundtrack: Soundtracks/$album/$track $title
|
||||
paths:
|
||||
albumtype:soundtrack: Soundtracks/$album/$track $title
|
||||
|
||||
will place soundtrack albums in a separate directory. The queries are tested in
|
||||
the order they appear in the configuration file, meaning that if an item matches
|
||||
multiple queries, beets will use the path format for the *first* matching query.
|
||||
|
||||
Note that the special ``singleton`` and ``comp`` path format conditions are, in
|
||||
fact, just shorthand for the explicit queries ``singleton_true`` and
|
||||
``comp_true``. In contrast, ``default`` is special and has no query equivalent:
|
||||
fact, just shorthand for the explicit queries ``singleton:true`` and
|
||||
``comp:true``. In contrast, ``default`` is special and has no query equivalent:
|
||||
the ``default`` format is only used if no queries match.
|
||||
|
||||
Example
|
||||
|
|
@ -292,17 +299,17 @@ Example
|
|||
|
||||
Here's an example file::
|
||||
|
||||
[beets]
|
||||
library: /var/music.blb
|
||||
directory: /var/mp3
|
||||
path_format: $genre/$artist/$album/$track $title
|
||||
import_copy: yes
|
||||
import_write: yes
|
||||
import_resume: ask
|
||||
import_art: yes
|
||||
import_quiet_fallback: skip
|
||||
import_timid: no
|
||||
import_log: beetslog.txt
|
||||
import:
|
||||
copy: yes
|
||||
write: yes
|
||||
resume: ask
|
||||
art: yes
|
||||
quiet_fallback: skip
|
||||
timid: no
|
||||
log: beetslog.txt
|
||||
ignore: .AppleDouble ._* *~ .DS_Store
|
||||
art_filename: albumart
|
||||
plugins: bpd
|
||||
|
|
@ -310,27 +317,20 @@ Here's an example file::
|
|||
threaded: yes
|
||||
color: yes
|
||||
|
||||
[paths]
|
||||
default: $genre/$albumartist/$album/$track $title
|
||||
singleton: Singletons/$artist - $title
|
||||
comp: $genre/$album/$track $title
|
||||
albumtype_soundtrack: Soundtracks/$album/$track $title
|
||||
paths:
|
||||
default: $genre/$albumartist/$album/$track $title
|
||||
singleton: Singletons/$artist - $title
|
||||
comp: $genre/$album/$track $title
|
||||
albumtype:soundtrack: Soundtracks/$album/$track $title
|
||||
|
||||
[bpd]
|
||||
host: 127.0.0.1
|
||||
port: 6600
|
||||
password: seekrit
|
||||
bpd:
|
||||
host: 127.0.0.1
|
||||
port: 6600
|
||||
password: seekrit
|
||||
|
||||
(That ``[bpd]`` section configures the optional :doc:`BPD </plugins/bpd>`
|
||||
plugin.)
|
||||
|
||||
Location
|
||||
--------
|
||||
|
||||
The configuration file is typically located at ``$HOME/.beetsconfig``. If you
|
||||
want to store your ``.beetsconfig`` file somewhere else for whatever reason, you
|
||||
can specify its path by setting the ``BEETSCONFIG`` environment variable.
|
||||
|
||||
.. only:: man
|
||||
|
||||
See Also
|
||||
|
|
|
|||
Loading…
Reference in a new issue