mirror of
https://github.com/beetbox/beets.git
synced 2025-12-28 19:42:42 +01:00
131 lines
3.6 KiB
ReStructuredText
131 lines
3.6 KiB
ReStructuredText
Titlecase Plugin
|
|
================
|
|
|
|
The ``titlecase`` plugin lets you format tags and paths in accordance with the
|
|
titlecase guidelines in the `New York Times Manual of Style`_ and uses the
|
|
`python titlecase library`_.
|
|
|
|
Motivation for this plugin comes from a desire to resolve differences in style
|
|
between databases sources. For example, `MusicBrainz style`_ follows standard
|
|
title case rules, except in the case of terms that are deemed generic, like
|
|
"mix" and "remix". On the other hand, `Discogs guidelines`_ recommend
|
|
capitalizing the first letter of each word, even for small words like "of" and
|
|
"a". This plugin aims to achieve a middle ground between disparate approaches to
|
|
casing, and bring more consistency to titles in your library.
|
|
|
|
.. _discogs guidelines: https://support.discogs.com/hc/en-us/articles/360005006334-Database-Guidelines-1-General-Rules#Capitalization_And_Grammar
|
|
|
|
.. _musicbrainz style: https://musicbrainz.org/doc/Style
|
|
|
|
.. _new york times manual of style: https://search.worldcat.org/en/title/946964415
|
|
|
|
.. _python titlecase library: https://pypi.org/project/titlecase/
|
|
|
|
Installation
|
|
------------
|
|
|
|
To use the ``titlecase`` plugin, first enable it in your configuration (see
|
|
:ref:`using-plugins`). Then, install ``beets`` with ``titlecase`` extra:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install "beets[titlecase]"
|
|
|
|
If you'd like to just use the path format expression, call ``%titlecase`` in
|
|
your path formatter, and set ``auto`` to ``no`` in the configuration.
|
|
|
|
::
|
|
|
|
paths:
|
|
default: %titlecase($albumartist)/$titlecase($albumtitle)/$track $title
|
|
|
|
You can now configure ``titlecase`` to your preference.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
This plugin offers several configuration options to tune its function to your
|
|
preference.
|
|
|
|
Default
|
|
~~~~~~~
|
|
|
|
.. code-block:: yaml
|
|
|
|
titlecase:
|
|
auto: yes
|
|
fields:
|
|
preserve:
|
|
force_lowercase: no
|
|
small_first_last: yes
|
|
|
|
.. conf:: auto
|
|
:default: yes
|
|
|
|
Whether to automatically apply titlecase to new imports.
|
|
|
|
.. conf:: fields
|
|
|
|
A list of fields to apply the titlecase logic to. You must specify the fields
|
|
you want to have modified in order for titlecase to apply changes to metadata.
|
|
|
|
.. conf:: preserve
|
|
|
|
List of words and phrases to preserve the case of. Without specifying ``DJ`` on
|
|
the list, titlecase will format it as ``Dj``, or specify ``The Beatles`` to make sure
|
|
``With The Beatles`` is not capitalized as ``With the Beatles``
|
|
|
|
.. conf:: force_lowercase
|
|
:default: no
|
|
|
|
Force all strings to lowercase before applying titlecase, but can cause
|
|
problems with all caps acronyms titlecase would otherwise recognize.
|
|
|
|
.. conf:: small_first_last
|
|
|
|
An option from the base titlecase library. Controls capitalizing small words at the start
|
|
of a sentence. With this turned off ``a`` and similar words will not be capitalized
|
|
under any circumstance.
|
|
|
|
Excluded Fields
|
|
~~~~~~~~~~~~~~~
|
|
|
|
``titlecase`` only ever modifies string fields, and will never interact with
|
|
fields that it considers to be case sensitive.
|
|
|
|
For reference, the string fields ``titlecase`` ignores:
|
|
|
|
.. code-block:: bash
|
|
|
|
acoustid_fingerprint
|
|
acoustid_id
|
|
artists_ids
|
|
asin
|
|
deezer_track_id
|
|
format
|
|
id
|
|
isrc
|
|
mb_workid
|
|
mb_trackid
|
|
mb_albumid
|
|
mb_artistid
|
|
mb_artistids
|
|
mb_albumartistid
|
|
mb_albumartistids
|
|
mb_releasetrackid
|
|
mb_releasegroupid
|
|
bitrate_mode
|
|
encoder_info
|
|
encoder_settings
|
|
|
|
Running Manually
|
|
----------------
|
|
|
|
From the command line, type:
|
|
|
|
::
|
|
|
|
$ beet titlecase [QUERY]
|
|
|
|
Configuration is drawn from the config file. Without a query the operation will
|
|
be applied to the entire collection.
|