beets-genrecanon: user-defined canonical genres without online lookups

[gbcox]

Making genre useful for playlists: beets-genrecanon

Genre metadata has become increasingly difficult to use for organizing a music
library. A large collection can contain hundreds of highly specific,
overlapping, and inconsistently applied genres. Those descriptions may be
interesting, but they are nearly useless for generating balanced playlists.

I created beets-genrecanon to solve that problem.

The plugin preserves the detailed source genre while mapping it into a broader,
user-defined canonical category:

GENRE=Symphonic Rock
GENRE_CANON=Rock

This provides two useful levels of information:

• GENRE retains the original descriptive genre.
• GENRE_CANON provides a stable personal category suitable for library
  organization, beets queries, and playlist generation.

The canonical taxonomy is defined entirely by the user in genres.yaml:

Rock:
  - Classic Rock
  - Progressive Rock
  - Symphonic Rock

Jazz:
  - Bebop
  - Cool Jazz
  - Hard Bop

The categories do not have to follow anyone else’s definition of genre. They
can be organized according to how the user actually wants to group and listen
to the library.

Why use a separate canonical genre?

Many genre plugins attempt to clean up, normalize, or replace the existing
genre field. The problem is that genre metadata is open-ended, subjective,
and increasingly granular. New labels and combinations appear continuously,
and different sources frequently describe the same music differently.

Trying to reduce that entire universe to one authoritative set of genre values
is not realistically achievable.

beets-genrecanon takes a different approach. It leaves the original GENRE
untouched and creates a separate, deliberately limited classification chosen by
the user.

The detailed genre can remain:

GENRE=Symphonic Rock

while the canonical category becomes:

GENRE_CANON=Rock

The canonical taxonomy does not need to settle what the “correct” genre is. It
only needs to reflect how the user wants the library organized. This makes the
categories stable and practical for beets queries, playlist generation, and
other library-management tasks.

Import behavior

During beet import, the plugin:

• scans and validates the complete import before writing tags;
• leaves files unchanged when GENRE_CANON already matches;
• detects missing, stale, or duplicate canonical tags;
• prompts when it encounters a genre missing from genres.yaml;
• allows the genre to be assigned to an existing or new category;
• updates genres.yaml only after confirmation;
• writes the canonical value to the FLAC GENRE_CANON tag;
• synchronizes it into the beets genre_canon flexible field;
• supports beet import --pretend without changing the mapping, files, or
  database.

It does not require an online service. The initial release supports FLAC files
only.

Installation

python -m pip install beets-genrecanon

Enable it in config.yaml:

plugins:
  - genrecanon

Create the initial mapping file:

beet genrecanon --init

The included taxonomy is only a starting point and can be reorganized however
the user prefers.

Project: https://codeberg.org/gbcox/beets-genrecanon
PyPI: https://pypi.org/project/beets-genrecanon/

Licensed under GPL-2.0-or-later.

[arsaboo]

Beets natively supports such canonicalization - https://beets.readthedocs.io/en/stable/plugins/lastgenre.html

[gbcox]

Yes, I reviewed LastGenre while developing this plugin. Although LastGenre uses the term “canonicalization,” it addresses a different problem; essentially apples and oranges.

LastGenre performs lossy genre reduction within the normal genre field using a genre tree and whitelist. It does not produce a separately declared, unique canonical genre. beets-genrecanon treats the existing GENRE as immutable source metadata and writes the user’s classification to a separate GENRE_CANON tag and genre_canon beets field.

For example:

GENRE=Symphonic Rock
GENRE_CANON=Rock

The detailed source genre is preserved, while the smaller personal taxonomy can be used for queries and playlist generation.

The mappings are explicit and entirely user-controlled. If an unknown genre is encountered, the plugin asks where it belongs instead of replacing it, discarding it, or automatically traversing a predefined genre hierarchy.

beets-genrecanon is therefore not another genre-cleanup feature. It never modifies or replaces the source genre. It adds a separate, non-destructive classification layer that can be used alongside genre-fetching and genre-cleanup plugins.

Because the original genre is preserved, the canonical taxonomy can be changed and regenerated at any time without losing the source metadata.