Filetote plugin for beets

A plugin that moves non-music extra files, attachments, and artifacts during imports and CLI file manipulation actions (move, modify, reimport, etc.) for beets, a music library manager (and much more!).

This plugin is supported/runs in beets v2 and above.

Installing

Stable

The stable version of the plugin is available from PyPI and can be installed using pip3:

pip3 install beets-filetote

Configuration

You will need to enable the plugin in beets' config.yaml:

plugins: filetote

It can copy files by file extension:

filetote:
  extensions: .cue .log

Or copy all non-music files:

filetote:
  extensions: .*

Or copy files by filename:

filetote:
  filenames: song.log

Or match based on a "pattern" (via glob pattern):

filetote:
  patterns:
    artworkdir:
      - "[aA]rtwork/"

It can look for and target "pairs" (files having the same name as a matching or "paired" media item/track):

filetote:
  pairing:
    enabled: true

You can specify pairing to happen to certain extensions, and even target/include only paired files:

filetote:
  pairing:
    enabled: true
    pairing_only: true
    extensions: ".lrc"

It can also exclude files that are otherwise matched:

filetote:
  exclude:
    filenames: song_lyrics.nfo

And print what got left:

filetote:
  print_ignored: true

File Ha 8000 ndling & Renaming

In order to collect extra files and artifacts, Filetote needs to be told which types of files it should care about. This can be done using the following:

Extensions (extensions:): Specify individual extensions like .cue or .log, or use a catch-all for all non-music files with .*.
Filenames (filenames:): Match specific filenames like cover.jpg or organize artwork with [aA]rtwork/*.
Patterns (patterns:): Use flexible glob patterns for more control, like matching all logs in a subfolder: CD1/*.log.
Pairing: Move files with the same name as imported music items, like .lrc lyrics or album logs.

Filetote Renaming Basics

Unless otherwise specified, the default name for artifacts and extra files is: $albumpath/$old_filename. This means that by default, the file is essentially moved/copied into destination directory of the music item it gets grabbed with. This also means that the album folder is flattened and any subdirectory is removed by default. To preserve subdirectories, see $subpath usage.

Note

To update the default renaming from $albumpath/$old_filename, use the filetote:default path specification.

Configuration for renaming works in much the same way as beets Path Formats, including the standard metadata values provided by beets along with replace settings. Filetote provides the below new path queries, which each takes a single corresponding value. These can be defined in either the top-level paths section of Beet's config or in the paths section of Filetote's config. Both of the following are equivalent:

paths:
  ext:.log: $albumpath/$artist - $album

filetote:
  paths:
    ext:.log: $albumpath/$artist - $album

Important

If you have the same path specified in both the top-level paths section of Beet's config and in the paths section of Filetote's config, the Filetote's specification will take precedence. There should not be a normal scenario where this is intentionally utilized with Filetote's new path queries, but it may be needed if there's a conflict/overlap with another plugin; this allows you to specify renaming rules that will only impact Filetote and not other plugins.

New path queries

These are the new path queries added by Filetote, from most to least specific:

filename:
paired_ext:
pattern:
ext:

This means that the filename: path query will take precedence over paired_ext:, pattern:, and ext: if a given file qualifies for them. This also means that the value in paired_ext: will take precedence over pattern: and ext:, and pattern: is higher priority than ext:.

Warning

ext:.* is not a valid query. If you need to update the default renaming, please use filetote:default.

Renaming considerations

Renaming has the following considerations:

The fields available include the standard metadata values of the imported item ($albumartist, $album, $title, etc.), along with Filetote-specific values of:

$albumpath: the entire path of the new destination of the item/track (a useful shorthand for when the extra/artifact file will be moved allongside the item/track).
- Note: Beets doesn't have a strict "album" path concept. All references are relative to Items (the actual media files). This is especially relevant for multi-disc files/albums, but usually isn't a problem. Check the section on multi-discs for more details.
$subpath: Represents any subdirectories under the base album path where an extra/artifact file resides. For use when it is desirable to preserve the directory hierarchy in the albums. This respects the original capitalization of directory names. Defaults to an empty string when no subdirectories exist.
- Example: If an extra file is located in a subdirectory named Extras under the album path, $subpath would be set to Extras/ (with the same casing).
$old_filename: the filename of the extra/artifact file before its renamed.
$medianame_old: the filename of the item/track triggering it, before it's renamed.
$medianame_new: the filename of the item/track triggering it, after it's renamed.

Warning

The fields mentioned above are not usable within other plugins such as inline. That said, inline and other plugins should work without issue unless otherwise specified here.

The full set of built in functions are also supported, with the exception of %aunique - which will return an empty string.

Important

If there are rename rules set that result with multiple files that will have the exact same filename, only the first file will be added to the library; other files that subsequently match will not be saved/renamed. To work around this, $old_filename can be used in conjunction with other fields to help with adding uniqueness to each name.

Subpath Renaming Example

The following configuration or template string will be applied to .log files by using the $subpath and will rename log file to: ~/Music/Artist/2014 - Album/Extras/Artist - Album.log

This assumes that the original file is in the subdirectory (subpath) of Extras/. Any other .log files in other subdirectories or in the root of the album will be moved accordingly. If a more targeted approach is needed, this can be combined with the pattern: query.

Note

$subpath automatically adds in path separators, including the end one if there are subdirectories.

paths:
  ext:.log: $albumpath/$subpath$artist - $album

Extension (`extensions:`)

Filename can match on the extension of the file, in a space-delimited list (i.e., a string sequence). Use .* to match all file extensions.

Extension Example Configuration

This example will match any file which has an extension of either .lrc or .log, across all subfolders.

filetote:
  extensions: .lrc .log

Extension Renaming Example

The following configuration or template string will be applied to .log files by using the ext: query and will rename log file to: ~/Music/Artist/2014 - Album/Artist - Album.log

paths:
  ext:.log: $albumpath/$artist - $album

Filename (`filenames:`)

Filetote can match on the actual name (including extension) of the file, in a space-delimited list (string sequence). filenames: will match across any subdirectories, meaning targeting a filename in a specific subdirectory will not work (this functionality can be achieved using a pattern, however).

Filename Example Configuration

This example will match if the filename of the given artifact or extra file matches the name exactly as specified, either cover.jpg or artifact.nfo.

filetote:
  filenames: cover.jpg artifact.nfo

Filename Renaming Example

The following configuration will rename the specific artifact.nfo file to: ~/Music/Artist/2014 - Album/Artist - Album.nfo

filetote:
  paths:
    filename:artifact.nfo: $albumpath/$artist - $album
  filenames: cover.jpg artifact.nfo

Pattern (`patterns:`)

Filetote can match on a given pattern as specified using glob patterns. This allows for more specific matching, like grabbing only PNG artwork files. Paths in the pattern are relative to the root of the importing album. Hence, if there are subdirectories in the album's folder (for multidisc setups, for instance, e.g., albumpath/CD1), the album's path would be the base/root for the pattern (ex: CD1/*.jpg). Patterns will work with or without the proceeding slash (/) (Windows users will need to use the appropriate slash \).

Patterns specifying folders with a trailing slash will (ex: albumpath/) will match every file in that subdirectory irrespective of name or extension (it is equivalent to albumpath/*.*).

Patterns are defined by a name so that any customization for renaming can apply to the pattern when specifying the path (ex: pattern:artworkdir; see the section on renaming below).

Important

Patterns process in order from top to bottom, and once matched will determine which path to apply during renaming. This is important in cases where theoretically a file could match to multiple patterns. For example, if you have a file here: albumpath/artwork/cover.jpg, the pattern it'll match to is the first (artworkdir) in the following config:

filetote:
 patterns:
   artworkdir:
     - "[aA]rtwork/"
   images:
     - "*.jpg"
     - "*.jpeg"
     - "*.png"

Thus, it will only match the pattern path of pattern:artworkdir and not pattern:images. Please note that irrespective if it matches a pattern, if there is a more specific path per the renaming rules it'll use that instead.

Pattern Example Configuration

This example will match if the filename of the given artifact or extra file matches the name exactly as specified, either cover.jpg or artifact.nfo.

This example will match all files within the given subdirectory of either artwork/ or Artwork/. Since it's not otherwise specified, [aA]rtwork/ will grab all non-media files in that subdirectory irrespective of name or extension.

filetote:
  patterns:
    artworkdir:
      - "[aA]rtwork/"

Pattern Renaming Example

The following pattern configuration will rename the file artwork/cover.jpeg to: ~/Music/Artist/2014 - Album/artwork/cover.jpeg

filetote:
  paths:
    pattern:artworkdir: $albumpath/artwork/$old_filename
  patterns:
    artworkdir:
      - "[aA]rtwork/"

Pairing (`pairing:`)

Filetote can specially target related files like lyrics or logs with the same name as music files ("paired" files). This keeps related files together, making your library even more organized. When enabled, it will match and move those files having the same name as a matching music file. Pairing can be configured to target only certain extensions, such as .lrc.

Note

Pairing takes precedence over other Filetote rules like filename or patterns.

Pairing Example Configuration

This example configuration will grab paired .lrc files, along with any artwork files:

filetote:
  pairing:
    enabled: true
    extensions: ".lrc"
  patterns:
    artworkdir:
          - "[aA]rtwork/"

Filetote can also be configured to only target paired files, which will ignore other Filetote configurations such as filename or patterns as described above. The following configuration would only target .lrc files:

filetote:
  pairing:
    enabled: true
    pairing_only: true
    extensions: ".lrc"

Pairing Renaming

To mainting the concept of "pairs" after importing, it is strongly encouraged to set the path for the paired files to use the media files new name. This will ensure that the file remains paired even after moving. E.g.:

paths:
  paired_ext:.lrc: $albumpath/$medianame_new

Excluding Files (`exclude:`)

Certain artifact files can be excluded/ignored by specifying settings under the exclude via filenames, extensions, and/or patterns. For example, to always exclude files named either song_lyrics.nfo or album_description.nfo, you can specify:

filetote:
  exclude:
    filenames: song_lyrics.nfo album_description.nfo

Likewise, to more broadly exclude extensions .nfo and .lrc, specify:

filetote:
  exclude:
    extensions: .nfo .lrc

Likewise, patterns can be used to perform more specialized exclusons, such as excluding all files in a subdirectory. For example, to exclude all artifact files in the subdirectories artwork and/or Artwork:

filetote:
  exclude:
    patterns:
      artworkdir:
        - "[aA]rtwork/"

exclude patterns follow the same glob rules specified the higher-level patterns config.

These can be combined to exclude any combination. For example, you can exclude by filename and pattern:

filetote:
  exclude:
    filenames: song_lyrics.nfo
    patterns:
      artworkdir:
        - "[aA]rtwork/"

Important

exclude-d files take precedence over other matching, meaning exclude will override other matches by either extensions or filenames.

Import Operations

This plugin supports the same operations as beets:

copy
move
link (symlink)
harklink
reflink

These options are mutually exclusive, and there are nuances to how beets (and thus this plugin) behave when there multiple set. See the beets import documentation and #36 for more details.

Reimporting has an additional nuance when copying of linking files that are already in the library, in which files will be moved rather than duplicated. This behavior in Filetote is identical to that of beets. See the beets reimport documentation for more details.

Other CLI Operations

Additional commands such such as move, modify, update, etc. will also trigger Filetote to handle files. These commands typically work with queries, targeting specific files that match the supplied query. Please note that the operation executed by beets for these commands do not use the value set in the config file under import, they instead are specified as part of the CLI command.

Examples of `config.yaml`

plugins: filetote

paths:
  default: $albumartist/$year - $album/$track - $title
  singleton: Singletons/$artist - $title
  ext:.log: $albumpath/$artist - $album
  ext:.cue: $albumpath/$artist - $album
  paired_ext:.lrc: $albumpath/$medianame_new
  filename:cover.jpg: $albumpath/cover

filetote:
  extensions: .cue .log .png
  filenames: cover.jpg
  pairing:
    enabled: true
    extensions: ".lrc"
  print_ignored: true

Or:

plugins: filetote

paths:
  default: $albumartist/$year - $album/$track - $title
  singleton: Singletons/$artist - $title

filetote:
  extensions: .txt .cue
  patterns:
    artworkdir:
      - "[sS]cans/"
      - "[aA]rtwork/"
  exclude:
    filenames: "copyright.txt"
  pairing:
    enabled: true
    extensions: .lrc
  paths:
    pattern:artworkdir: $albumpath/artwork
    paired_ext:.lrc: $albumpath/$medianame_old
    filename:cover.jpg: $albumpath/cover

Multi-Disc and Nested Import Directories

beets imports multi-disc albums as a single unit (see beets documentation). By default, this results in the media importing to a single directory in the library. Artifacts and extra files in the initial subdirectories will brought by Filetote to the destination of the file's they're near, resulting in them landing where one would expect. Because of this, the files will also be moved by Filetote to any specified subdirectory in the library if the path definition creates "Disc N" subfolders as described in the beets documentation.

In short, artifacts and extra files in these scenarios should simply just move/copy as expected.

Advanced renaming for multi-disc albums

The value for $albumpath is actually based on the path for the Item (music file) the lead to the artifact to be moved. Since it's common to store multi-disc albums with subfolders, this means that by default the artifact or extra file in question will also be in a subfolder.

For macOS and Linux, to achieve a different location (say the media is in Artist/Disc 01 but artifacts are intended to be in Artist/Extras), .. can be used to navigate to the parent directory of the $albumpath so that the entirety of the media's path does not have to be recreated. For Windows, the entire media path would need to be recreated as Windows sees .. as an attempt to create a directory with the name .. within path instead of it being a path component representing the parent.

macOS & Linux

The following example will have the following results on macOS & Linux:

Music: ~/Music/Artist/2014 - Album/Disc 1/media.mp3
Artifact: ~/Music/Artist/2014 - Album/Extras/example.log

plugins: filetote

paths:
  default: $albumartist/$year - $album/$track - $title
  comp: $albumartist/$year - $album/Disc $disc/$track - $title

filetote:
  extensions: .log
  paths:
    ext:log: $albumpath/../Extras/$old_filename

Windows

The following example will have the following results on Windows:

Music: ~/Music/Artist/2014 - Album/Disc 1/media.mp3
Artifact: ~/Music/Artist/2014 - Album/Extras/example.log

plugins: filetote

paths:
  default: $albumartist/$year - $album/$track - $title
  comp: $albumartist/$year - $album/Disc $disc/$track - $title

filetote:
  extensions: .log
  paths:
    ext:log: $albumartist/$year - $album/Extras/$old_filename

Filetote Compatibility with Other Plugins

Other plugins, including inline and convert, should be fully compatible with Filetote. That said, sometimes there are small considerations. For example, the new fields mentioned in Renaming C 9E81 onsiderations are not usable by other plugins (such as inline). If you experience any issues with any other plugins, please report them.

Important

convert is only compatible with Filetote v1.0.3+. convert performs conversion very early in the import process, before other plugins. In prior versions of Filetote this would cause Filetote to look into the wrong location (the temporary file location on the newly converted media file), instead of the original source the media file came from. A special workaround was needed which was introduced in v1.0.3.

Why Filetote and Not Other Similar Plugins?

Filetote serves the same core purpose as the copyfilertifacts plugin and the extrafiles plugin, however both have lacked in maintenance over the last few years. There are outstanding bugs in each (though copyfilertifacts has seen some recent activity resolving some). In addition, each are lacking in certain features and abilities, such as hardlink/reflink support, "paired" file handling, and extending renaming options. What's more, significant focus has been provided to Filetote around Python3 conventions, linting, and typing in order to promote healthier code and easier maintenance.

Filetote strives to encompass all functionality that both copyfilertifacts and extrafiles provide, and then some!

Migrating from `copyfilertifacts`

Filetote can be configured using nearly identical configuration as copyfilertifacts, simply replacing the name of the plugin in its configuration settings. There is one change that's needed if all extensions are desired, as Filetote does not grab all extensions by default (as copyfilertifacts does). To accommodate, simply explicitly state all extension using .*:

filetote:
  extensions: .*

Otherwise, simply replacing the name in the config section will work. For example:

copyartifacts:
  extensions: .cue .log

Would become:

filetote:
  extensions: .cue .log

Path definitions can also be specified in the way that copyfileartifacts does, alongside other path definitions for beets. E.g.:

paths:
  ext:log: $albumpath/$artist - $album

Migrating from `extrafiles`

Filetote can be configured using nearly identical configuration as extrafiles, simply replacing the name of the plugin in its configuration settings. For example:

extrafiles:
  patterns:
    all: "*.*"

Would become:

filetote:
  patterns:
    all: "*.*"

Path definitions can also be specified in the way that extrafiles does, e.g.:

filetote:
  patterns:
    artworkdir:
      - "[sS]cans/"
      - "[aA]rtwork/"
  paths:
    artworkdir: $albumpath/artwork

Version Upgrade Instructions

Certain versions require changes to configurations as upgrades occur. Please see below for specific steps for each version.

`1.0.2`

Config format for `exclude` now expects explicit `filenames`, `extensions`, and/or `patterns`

As of version 1.0.2, Filetote now emits a deprecation warning for configurations setting exclude to a simple list of filenames. Instead, Filetote now expects explicit filenames, extensions, and/or patterns, e.g.:

filetote:
  exclude:
    filenames: song_lyrics.nfo album_description.nfo

Contrast to the previous configuration (now deprecated):

filetote:
  exclude: song_lyrics.nfo album_description.nfo

For now, the old configuration style is still supported but logged as depreacated. In a future version this setting will no longer be backwards compatible.

`0.4.0`

Default for `extensions` is now `None`

As of version 0.4.0, Filetote no longer set the default for extensions to .*. Instead, setting Filetote to collect all extensions needs to be explicitly defined, e.g.:

filetote:
  extensions: .*

Pairing Config Changes

pairing has been converted from a boolean to an object with other like-config. Take the following config:

filetote:
  pairing: true
  pairing_only: false

These will both now be represented as individual settings within pairing:

filetote:
  pairing:
    enabled: true
    pairing_only: false
    extensions: ".lrc"

Both remain optional and both default to false.

Development & Contributing

Thank you for considering contributing to Filetote! Information on how you can contribute, develop, or help can be found in CONTRIBUTING.md.

Thanks

This plugin originated as a hard fork from beets-copyartifacts (copyartifacts3).

Thank you to the original work done by Sami Barakat and Adrian Sampson, along with the larger beets community.

Please report any issues you may have and feel free to contribute.

License

Licensed under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 242 Commits
.act		.act
.github		.github
beetsplug		beetsplug
tests		tests
typehints		typehints
.actrc		.actrc
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.yaml		.markdownlint.yaml
.pre-commit-config.yaml		.pre-commit-config.yaml
.tool-versions		.tool-versions
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
_typos.toml		_typos.toml
compose.yaml		compose.yaml
example.config.yaml		example.config.yaml
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
setup.py		setup.py

License

gtronset/beets-filetote

Folders and files

Latest commit

History

Repository files navigation

Filetote plugin for beets

Installing

Stable

Configuration

File Ha 8000 ndling & Renaming

Filetote Renaming Basics

New path queries

Renaming considerations

Subpath Renaming Example

Extension (extensions:)

Extension Example Configuration

Extension Renaming Example

Filename (filenames:)

Filename Example Configuration

Filename Renaming Example

Pattern (patterns:)

Pattern Example Configuration

Pattern Renaming Example

Pairing (pairing:)

Pairing Example Configuration

Pairing Renaming

Excluding Files (exclude:)

Import Operations

Other CLI Operations

Examples of config.yaml

Multi-Disc and Nested Import Directories

Advanced renaming for multi-disc albums

macOS & Linux

Windows

Filetote Compatibility with Other Plugins

Why Filetote and Not Other Similar Plugins?

Migrating from copyfilertifacts

Migrating from extrafiles

Version Upgrade Instructions

1.0.2

Config format for exclude now expects explicit filenames, extensions, and/or patterns

0.4.0

Default for extensions is now None

Pairing Config Changes

Development & Contributing

Thanks

License

About

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 21

Uh oh!

Contributors 3

Uh oh!

Languages

Extension (`extensions:`)

Filename (`filenames:`)

Pattern (`patterns:`)

Pairing (`pairing:`)

Excluding Files (`exclude:`)

Examples of `config.yaml`

Migrating from `copyfilertifacts`

Migrating from `extrafiles`

`1.0.2`

Config format for `exclude` now expects explicit `filenames`, `extensions`, and/or `patterns`

`0.4.0`

Default for `extensions` is now `None`