Configuration

Moe will automatically create a config file, config.toml, in $HOME/.config/moe or %USERPROFILE%\.config\moe if you’re on Windows. This directory is also where your library database file will reside.

Note

The configuration directory can be overwritten by setting the environment variable MOE_CONFIG_DIR.

Throughout this documentation, all configuration options will be displayed in the following format:

option = default_value

If there is any functionality you’d like to customize that doesn’t have a configuration option, please feel free to open a feature request asking for it!

Global Options

Most configuration options reside in their relevant plugin, however there are the following global options:

default_plugins = ["add", "cli", "duplicate", "edit", "import", "list", "move", "remove", "write"]

Overrides the list of default plugins.

disable_plugins = []

List of any plugins to explicitly disable. This takes priority over enable_plugins.

enable_plugins = []

List of any plugins to explicitly enable.

library_path = "~/Music"

Tells Moe where your music library resides.

For Windows users, ~ is your %USERPROFILE% directory. It’s recommended to use a forward slash / to delineate sub-directories for your library path for consistency with other configuration options, but you may also use a backslash \. If you choose to use backslashes, ensure you enclose your path in single quotes, e.g. '~\Music', to ensure the backslash \ isn’t interpreted as an escape character.

Note

If you change library_path, Moe will attempt to search for your music in the new location.

original_date = false

Whether or not to always set an album’s date to its original_date if present.

Note

This change will also propagate onto the respective year fields.

Plugin Options

Each plugin option should be specified under that plugin’s section in the config. For example, to customize the asciify_paths option under the move plugin, we’d write the following in our config file.

[move]
asciify_paths = true

Move

asciify_paths = false

Whether or not to convert all filesystem paths to ascii.

If true, non-ascii characters will be converted to their ascii equivalents, e.g. café.mp3 will become cafe.mp3.

Import

max_candidates = 5

Maximum number of candidate albums to display in the import prompt.

When running moe add, this setting controls how many potential matches are shown when importing albums. Increasing this value allows you to see more options when multiple matches are found from metadata providers like MusicBrainz and Discogs.

[import]
max_candidates = 10  # Show up to 10 candidate albums

Note

This setting only affects the number of candidates displayed in the interactive prompt. To increase the number of candidates fetched from metadata providers, you may also need to adjust the search limits for individual plugins like musicbrainz.search_limit.

Path Configuration Options

Note

Any items added to your library will be automatically copied to their respective path configurations.

album_path = "{album.artist}/{album.title} ({album.year})"

Album filesystem path format relative to the global configuration option, library_path.

track_path = "{f'Disc {track.disc:02}' if album.disc_total > 1 else ''}/{track.track_num:02} - {track.title}{track.path.suffix}"

Track filesystem path format relative to album_path.

Note

• The if statement inside the path simply means that if there is more than one disc in the album, the tracks will be put into separate directories for their respective disc.

• Include track.path.suffix at the end if you wish to retain the file extension of the track file.

extra_path = "{e_unique(extra)}"

Extra filesystem path format relative to album_path.

Paths are formatted using python f-strings which, as demonstrated by the default track path, allow all the advanced formatting and expression evaluation that come with them. You can access any of the respective item’s fields in these strings using {[album/track/extra].field} notation as shown.

Important

Windows users should use a forward slash / when delineating sub-directories in path formats as the back slash \ is used as an escape character.

Note

Forward slashes / cannot be used inside a nested f-string variable e.g. {f'Disc {track.disc}/{track.disc}} is not allowed. You may instead be able to achieve the behavior you’re after by implementing a custom path template function as described below.

Tip

• For any path formatting changes, run moe move -n for a dry-run to avoid any unexpected results.

• For a more detailed look at all the field options and types, take a look at the library api. album, track, and extra in the path formats are Album, Track, and Extra objects respectively and thus you can reference any of their available attributes.

Advanced Path Template Configuration

There are two options for even more customization of your path templates: functions, and programmatically overriding the template entirely. Both of these options require Extending Your Configuration With Plugins.

Custom Path Template Functions

Plugins can create custom path template functions to be called within the path templates. These functions are useful for altering the results of directory or file names, but cannot be used to specify custom sub-directories (for that, see Overriding Path Templates Programmatically).

The function called in the default extra_path template, e_unique, is an example of a custom path template function. The following custom template functions are included in the move plugin:

e_unique(extra: Extra) → str

Returns a unique filename for an extra within its album.

To create your own path template functions, implement the create_path_template_func() hook in your plugin.

Overriding Path Templates Programmatically

The path templates themselves can also be set programmatically via a plugin rather than from your configuration file. Using python to set your path templates allows you to specify different path templates entirely based on criteria such as storing all classical albums in a separate directory. Currently, both the album and extra path templates can be set by plugins using the override_album_path_config() and the override_extra_path_config() hooks.

Overriding Config Values

All configuration parameters can be overridden through environment variables. To override global configuration parameters use an environment variable named MOE_{PARAM}:

$ MOE_DISABLE_PLUGINS="['musicbrainz']" moe

For plugin specific configuration parameters, use MOE_{PLUGIN}__{PARAM}:

$ MOE_MOVE__ASCIIFY_PATHS=true moe

Extending Your Configuration With Plugins

If you aren’t afraid of writing a little bit of Python, the best way to extend your configuration and truly mold Moe to your exact liking is through local plugins. Writing plugins is extremely easy, and can allow you to customize Moe beyond the limitations of the configuration file.

Check out the writing plugins docs to get started on writing your own plugins.

If you have any questions, please don’t hesitate to ask on github!