Skip to main content
`Ctrl`+`K`

# 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.

## Installation

To use the `titlecase` plugin, first enable it in your configuration (see Using Plugins). Then, install `beets` with `titlecase` extra:

    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{$album}/$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

    titlecase:
        auto: yes
        fields: []
        preserve: []
        replace: []
        separators: []
        force_lowercase: no
        small_first_last: yes
        the_artist: yes
        all_lowercase: no
        all_caps: no
        after_choice: no

auto (default: `yes`)

  Whether to automatically apply titlecase to new imports.

fields (default: `[]`)

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

  > A good starting point is below, which will titlecase album titles, track titles, and all artist fields.

    titlecase:
      fields:
        - album
        - title
        - albumartist
        - albumartist_credit
        - albumartist_sort
        - albumartists
        - albumartists_credit
        - albumartists_sort
        - artist
        - artist_credit
        - artist_sort
        - artists
        - artists_credit
        - artists_sort

preserve (default: `[]`)

  > 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`.

replace (default: `[]`)

  > The replace function takes place before any titlecasing occurs, and is intended to help normalize differences in puncuation styles. It accepts a list of tuples, with the first being the target, and the second being the replacement.

  > An example configuration that enforces one style of quotation mark is below.

    titlecase:
      replace:
        - "’": "'"
        - "‘": "'"
        - "“": '"'
        - "”": '"'

separators (default: `[]`)

  > A list of characters to treat as markers of new sentences. Helpful for split titles that might otherwise have a lowercase letter at the start of the second string.

force_lowercase (default: `no`)

  Force all strings to lowercase before applying titlecase, but can cause problems with all caps acronyms titlecase would otherwise recognize.

small_first_last (default: `yes`)

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

the_artist (default: `yes`)

  > If a field name contains `artist`, then any lowercase `the` will be capitalized. Useful for bands with `The` as part of the proper name, like `Amyl and The Sniffers`.

all_caps (default: `no`)

  If the letters a-Z in a string are all caps, do not modify the string. Useful if you encounter a lot of acronyms.

all_lowercase (default: `no`)

  If the letters a-Z in a string are all lowercase, do not modify the string. Useful if you encounter a lot of stylized lowercase spellings, but otherwise want titlecase applied.

after_choice (default: `no`)

  > By default, titlecase runs on the candidates that are received, adjusting them before you make your selection and creating different weight calculations. If you’d rather see the data as received from the database, set this to true to run after you make your tag choice.

### Dangerous Fields

`titlecase` only ever modifies string fields, however, this doesn’t prevent you from selecting a case sensitive field that another plugin or feature may rely on.

In particular, including any of the following in your configuration could lead to unintended behavior:

    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.