lastgenre: Genre spelling normalization (aliases) by JOJ0 · Pull Request #6466 · beetbox/beets

JOJ0 · 2026-03-27T12:55:34Z

Description

This PR introduces a regex-based normalization (alias) system to unify variant genre tags and improves the plugin's documentation.

The normalization feature uses an ordered list of regular expression aliases to map variant spellings or synonyms to a single canonical name. The mapping keys act as re.Match.expand() templates, supporting \g<N> back-references to regex capture groups:

lastgenre:
    aliases:
        # Maps 'hip-hop' -> 'hip hop' using back-references 
        # (regex full-match)
        \g<1> hop:
            - (hip|trip|jazz)y?[ /-]*hop
        
        # Static normalization examples
        drum and bass:
            - dnb
            - d&b

Where?: Integrated normalize_genre before is_ignored in both the LastFmClient (for clean lookup/filtering) and the core _resolve_genres loop (for uniform processing of existing file tags).
Updated default whitelist and genre tree files for canonical-name consistency, and curated the bundled aliases.yaml from the top 1,000 Last.fm tags to cover common inconsistencies without over-normalizing.
Additional documentation changes:
- Added a Choosing the Right Tool guide. This is for endusers but note that it might even be a primary starting point for maintainer review.
- Added non-whitelist mode details to the Canonicalization chapter.
Additional unrelated changes:
- Fixes a few variable name inconsistencies in the recently merged ignorelist features' tests.

github-actions · 2026-03-27T12:55:52Z

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

codecov · 2026-03-27T13:01:56Z

Codecov Report

❌ Patch coverage is 87.30159% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.13%. Comparing base (3d3f5e3) to head (0eaca9d).

Files with missing lines	Patch %	Lines
beetsplug/lastgenre/__init__.py	91.42%	1 Missing and 2 partials ⚠️
beetsplug/lastgenre/client.py	66.66%	1 Missing and 2 partials ⚠️
beetsplug/lastgenre/utils.py	89.47%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6466      +/-   ##
==========================================
+ Coverage   72.07%   72.13%   +0.05%     
==========================================
  Files         159      159              
  Lines       20633    20681      +48     
  Branches     3273     3287      +14     
==========================================
+ Hits        14871    14918      +47     
+ Misses       5053     5048       -5     
- Partials      709      715       +6

Files with missing lines	Coverage Δ
beetsplug/lastgenre/utils.py	`93.75% <89.47%> (-6.25%)`	⬇️
beetsplug/lastgenre/__init__.py	`82.86% <91.42%> (+1.18%)`	⬆️
beetsplug/lastgenre/client.py	`64.58% <66.66%> (+10.92%)`	⬆️

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-03-29T10:17:45Z

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

JOJ0 · 2026-03-29T10:19:47Z

This is closely related to #6449 and might make sense to have a look when reviewing the former @snejus Many thanks in advance! 🙌

JOJ0 · 2026-03-29T11:28:57Z

+Choosing the Right Tool
+-----------------------
+
+With multiple ways to filter and map genres, here is a quick guide on when to
+use what:
+
+- **Aliases**: Use these first to fix spelling variants and abbreviations (e.g.,
+  ``dnb`` → ``drum and bass``).
+- **Ignorelist**: Use this for error correction when Last.fm results are not
+  accurate, or for precise per-artist or global exclusions (e.g., rejecting
+  ``Metal`` for specific electronic artists).
+- **Canonicalization**: Use this to automatically map specific sub-genres to
+  broader categories (e.g., ``Grindcore`` → ``Metal``).
+- **Whitelist**: Use this to finally limit your library to a predefined set of
+  genres. When combined with canonicalization, the plugin will try to map a
+  sub-genre to its closest whitelisted parent. Anything else is dropped.
+


Reviewers: This new chapter is a good starting point for reviewing and might help thinking through where and when things should happen in the plugin and why multiple filtering features make sense for this plugin!

JOJ0 · 2026-05-01T17:25:55Z

Make sense. Let me know once it's ready!

It's ready now @snejus! I also updated the PR description. Please re-read! Thanks!

Add comment on alias and log in client Refactor aliases load using confuse MappingValues Get rid of drop/norm helper again

which also slightly improves readability after removing the redundant drop_ignore_genres helper.

streamline vars naming in tests

snejus · 2026-05-03T21:18:40Z

Note the tests are failing still!

JOJ0 · 2026-05-04T15:54:47Z

Note the tests are failing still!

Fixed and narrowed some regex along the way. (note that the commit history still is a real mess, I'll clean that up once it's reviewed)

JOJ0 requested a review from a team as a code owner March 27, 2026 12:55

JOJ0 marked this pull request as draft March 27, 2026 12:56

JOJ0 force-pushed the lastgenre_aliases branch 2 times, most recently from 20b2d88 to 90064fa Compare March 28, 2026 22:52

JOJ0 force-pushed the lastgenre_forbidden branch from 66a7d98 to 1785dab Compare March 28, 2026 23:12

JOJ0 added lastgenre lastgenre plugin plugin Pull requests that are plugins related labels Mar 29, 2026

JOJ0 force-pushed the lastgenre_forbidden branch from 1785dab to c5a14d3 Compare March 29, 2026 09:11

JOJ0 force-pushed the lastgenre_aliases branch 4 times, most recently from d0cc527 to 12e7358 Compare March 29, 2026 10:09

JOJ0 marked this pull request as ready for review March 29, 2026 10:17

JOJ0 force-pushed the lastgenre_aliases branch from 12e7358 to f4b9436 Compare March 29, 2026 11:03

JOJ0 commented Mar 29, 2026

View reviewed changes

JOJ0 requested review from henry-oberholtzer and snejus March 29, 2026 11:29

JOJ0 force-pushed the lastgenre_forbidden branch 9 times, most recently from 87c272c to b12b314 Compare April 3, 2026 06:52

JOJ0 force-pushed the lastgenre_aliases branch 3 times, most recently from 133b397 to 67ae26c Compare May 1, 2026 17:02

JOJ0 added 19 commits May 3, 2026 09:31

lastgenre: Test aliases and ship default config

ca16d85

lastgenre: Docs for genre normalization (aliases)

9ed89de

lastgenre: Docs hint on canonical without whitelist

7b2d4b0

lastgenre: Implement genre alias normalization

b1cfe11

Add comment on alias and log in client Refactor aliases load using confuse MappingValues Get rid of drop/norm helper again

lastgenre: Slightly optimize filter_valid performance

5630b17

which also slightly improves readability after removing the redundant drop_ignore_genres helper.

Fixes/additions to default aliases

04fe3e9

Fix normalize_genre docstring wording

2efb8bc

Test invalid alias template catch

56251ec

Catch exception on invalid alias template

95fdc90

fix test aliases

0e979d4

lastgenre: Dedup ignore/alias regex compilation

d60ec41

Streamline in test alias type with ignore naming

a65d0b3

streamline vars naming in tests

Streamline alias type with ignore naming

f56dc28

lastgenre: Fix ignorelist tests naming inconsistencies

271a23f

Add alt rock to default aliases test

1f48c92

Finalize default aliases and fix genres,genres-tree

942221a

Restructure and reduce alias tests

f813e95

Reword comment on config bool/mapping handling

9359a7d

Fixes to default aliases.yaml

0e27872

JOJ0 force-pushed the lastgenre_aliases branch from d2cfdfa to 0e27872 Compare May 3, 2026 07:31

JOJ0 added 3 commits May 4, 2026 17:44

Hypenate post rock in default aliases

dfa54b5

Remove redundant hypens for some default aliases

1123400

Remove redundant slashes for some default aliases

0eaca9d

JOJ0 force-pushed the lastgenre_aliases branch from 40bbd83 to 0eaca9d Compare May 4, 2026 15:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lastgenre: Genre spelling normalization (aliases)#6466

lastgenre: Genre spelling normalization (aliases)#6466
JOJ0 wants to merge 22 commits intomasterfrom
lastgenre_aliases

JOJ0 commented Mar 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

codecov Bot commented Mar 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 29, 2026

Uh oh!

JOJ0 commented Mar 29, 2026

Uh oh!

JOJ0 Mar 29, 2026

Uh oh!

JOJ0 commented May 1, 2026 •

edited

Loading

Uh oh!

snejus commented May 3, 2026

Uh oh!

JOJ0 commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

JOJ0 commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

codecov Bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Mar 29, 2026

Uh oh!

JOJ0 commented Mar 29, 2026

Uh oh!

JOJ0 Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

JOJ0 commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snejus commented May 3, 2026

Uh oh!

JOJ0 commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JOJ0 commented Mar 27, 2026 •

edited

Loading

codecov Bot commented Mar 27, 2026 •

edited

Loading

JOJ0 commented May 1, 2026 •

edited

Loading