Add native support for multiple genres per album/track

Simplify multi-genre implementation based on maintainer feedback (PR #6169).

Changes:
- Remove multi_value_genres and genre_separator config options
- Replace complex sync_genre_fields() with ensure_first_value('genre', 'genres')
- Update all plugins (Beatport, MusicBrainz, LastGenre) to always write genres as lists
- Add automatic migration for comma/semicolon/slash-separated genre strings
- Add 'beet migrate genres' command for explicit batch migration with --pretend flag
- Update all tests to reflect simplified approach (44 tests passing)
- Update documentation

Implementation aligns with maintainer vision of always using multi-value genres
internally with automatic backward-compatible sync to the genre field via
ensure_first_value(), eliminating configuration complexity.

Migration strategy avoids problems from #5540:
- Automatic lazy migration on item access (no reimport/mbsync needed)
- Optional batch migration command for user control
- No endless rewrite loops due to proper field synchronization

Author: jfot-cpu

beets/autotag/__init__.py

@@ -172,7 +172,38 @@ def ensure_first_value(single_field: str, list_field: str) -> None:
         elif list_val:
             setattr(m, single_field, list_val[0])
 
+    def migrate_legacy_genres() -> None:
+        """Migrate comma-separated genre strings to genres list.
+
+        For users upgrading from previous versions, their genre field may
+        contain comma-separated values (e.g., "Rock, Alternative, Indie").
+        This migration splits those values into the genres list on first access,
+        avoiding the need to reimport the entire library.
+        """
+        genre_val = getattr(m, "genre", "")
+        genres_val = getattr(m, "genres", [])
+
+        # Only migrate if genres list is empty and genre contains separators
+        if not genres_val and genre_val:
+            # Try common separators used by lastgenre and other tools
+            for separator in [", ", "; ", " / "]:
+                if separator in genre_val:
+                    # Split and clean the genre string
+                    split_genres = [
+                        g.strip()
+                        for g in genre_val.split(separator)
+                        if g.strip()
+                    ]
+                    if len(split_genres) > 1:
+                        # Found a valid split - populate genres list
+                        setattr(m, "genres", split_genres)
+                        # Clear genre so ensure_first_value sets it correctly
+                        setattr(m, "genre", "")
+                        break
+
     ensure_first_value("albumtype", "albumtypes")
+    migrate_legacy_genres()
+    ensure_first_value("genre", "genres")
 
     if hasattr(m, "mb_artistids"):
         ensure_first_value("mb_artistid", "mb_artistids")

beets/autotag/hooks.py

@@ -68,6 +68,7 @@ def __init__(
         data_source: str | None = None,
         data_url: str | None = None,
         genre: str | None = None,
+        genres: list[str] | None = None,
         media: str | None = None,
         **kwargs,
     ) -> None:
@@ -83,6 +84,7 @@ def __init__(
         self.data_source = data_source
         self.data_url = data_url
         self.genre = genre
+        self.genres = genres or []
         self.media = media
         self.update(kwargs)
 

beets/library/models.py

@@ -241,6 +241,7 @@ class Album(LibModel):
         "albumartists_credit": types.MULTI_VALUE_DSV,
         "album": types.STRING,
         "genre": types.STRING,
+        "genres": types.MULTI_VALUE_DSV,
         "style": types.STRING,
         "discogs_albumid": types.INTEGER,
         "discogs_artistid": types.INTEGER,
@@ -297,6 +298,7 @@ def _types(cls) -> dict[str, types.Type]:
         "albumartists_credit",
         "album",
         "genre",
+        "genres",
         "style",
         "discogs_albumid",
         "discogs_artistid",
@@ -643,6 +645,7 @@ class Item(LibModel):
         "albumartist_credit": types.STRING,
         "albumartists_credit": types.MULTI_VALUE_DSV,
         "genre": types.STRING,
+        "genres": types.MULTI_VALUE_DSV,
         "style": types.STRING,
         "discogs_albumid": types.INTEGER,
         "discogs_artistid": types.INTEGER,

beets/ui/commands/__init__.py

@@ -24,6 +24,7 @@
 from .help import HelpCommand
 from .import_ import import_cmd
 from .list import list_cmd
+from .migrate import migrate_cmd
 from .modify import modify_cmd
 from .move import move_cmd
 from .remove import remove_cmd
@@ -54,12 +55,13 @@ def __getattr__(name: str):
     HelpCommand(),
     import_cmd,
     list_cmd,
-    update_cmd,
+    migrate_cmd,
+    modify_cmd,
+    move_cmd,
     remove_cmd,
     stats_cmd,
+    update_cmd,
     version_cmd,
-    modify_cmd,
-    move_cmd,
     write_cmd,
     config_cmd,
     completion_cmd,

beets/ui/commands/migrate.py

@@ -0,0 +1,98 @@
+"""The 'migrate' command: migrate library data for format changes."""
+
+from beets import logging, ui
+from beets.autotag import correct_list_fields
+
+# Global logger.
+log = logging.getLogger("beets")
+
+
+def migrate_genres(lib, pretend=False):
+    """Migrate comma-separated genre strings to genres list.
+
+    For users upgrading from previous versions, their genre field may
+    contain comma-separated values (e.g., "Rock, Alternative, Indie").
+    This command splits those values into the genres list, avoiding
+    the need to reimport the entire library.
+    """
+    items = lib.items()
+    migrated_count = 0
+    total_items = 0
+
+    ui.print_("Scanning library for items with comma-separated genres...")
+
+    for item in items:
+        total_items += 1
+        genre_val = item.genre or ""
+        genres_val = item.genres or []
+
+        # Check if migration is needed
+        needs_migration = False
+        if not genres_val and genre_val:
+            for separator in [", ", "; ", " / "]:
+                if separator in genre_val:
+                    split_genres = [
+                        g.strip()
+                        for g in genre_val.split(separator)
+                        if g.strip()
+                    ]
+                    if len(split_genres) > 1:
+                        needs_migration = True
+                        break
+
+        if needs_migration:
+            migrated_count += 1
+            old_genre = item.genre
+            old_genres = item.genres or []
+
+            if pretend:
+                # Just show what would change
+                ui.print_(
+                    f"  Would migrate: {item.artist} - {item.title}\n"
+                    f"    genre: {old_genre!r} -> {split_genres[0]!r}\n"
+                    f"    genres: {old_genres!r} -> {split_genres!r}"
+                )
+            else:
+                # Actually migrate
+                correct_list_fields(item)
+                item.store()
+                log.debug(
+                    "migrated: {} - {} ({} -> {})",
+                    item.artist,
+                    item.title,
+                    old_genre,
+                    item.genres,
+                )
+
+    # Show summary
+    if pretend:
+        ui.print_(
+            f"\nWould migrate {migrated_count} of {total_items} items "
+            f"(run without --pretend to apply changes)"
+        )
+    else:
+        ui.print_(
+            f"\nMigrated {migrated_count} of {total_items} items with "
+            f"comma-separated genres"
+        )
+
+
+def migrate_func(lib, opts, args):
+    """Handle the migrate command."""
+    if not args or args[0] == "genres":
+        migrate_genres(lib, pretend=opts.pretend)
+    else:
+        raise ui.UserError(f"unknown migration target: {args[0]}")
+
+
+migrate_cmd = ui.Subcommand(
+    "migrate", help="migrate library data for format changes"
+)
+migrate_cmd.parser.add_option(
+    "-p",
+    "--pretend",
+    action="store_true",
+    help="show what would be changed without applying",
+)
+migrate_cmd.parser.usage = "%prog migrate genres [options]"
+migrate_cmd.func = migrate_func

beetsplug/beatport.py

@@ -234,7 +234,9 @@ def __init__(self, data: JSONDict):
         if "artists" in data:
             self.artists = [(x["id"], str(x["name"])) for x in data["artists"]]
         if "genres" in data:
-            self.genres = [str(x["name"]) for x in data["genres"]]
+            genre_list = [str(x["name"]) for x in data["genres"]]
+            # Remove duplicates while preserving order
+            self.genres = list(dict.fromkeys(genre_list))
 
     def artists_str(self) -> str | None:
         if self.artists is not None:
@@ -306,11 +308,16 @@ def __init__(self, data: JSONDict):
         self.bpm = data.get("bpm")
         self.initial_key = str((data.get("key") or {}).get("shortName"))
 
-        # Use 'subgenre' and if not present, 'genre' as a fallback.
+        # Extract genres list from subGenres or genres
         if data.get("subGenres"):
-            self.genre = str(data["subGenres"][0].get("name"))
+            genre_list = [str(x.get("name")) for x in data["subGenres"]]
         elif data.get("genres"):
-            self.genre = str(data["genres"][0].get("name"))
+            genre_list = [str(x.get("name")) for x in data["genres"]]
+        else:
+            genre_list = []
+
+        # Remove duplicates while preserving order
+        self.genres = list(dict.fromkeys(genre_list))
 
 
 class BeatportPlugin(MetadataSourcePlugin):
@@ -484,6 +491,7 @@ def _get_album_info(self, release: BeatportRelease) -> AlbumInfo:
             data_source=self.data_source,
             data_url=release.url,
             genre=release.genre,
+            genres=release.genres,
             year=release_date.year if release_date else None,
             month=release_date.month if release_date else None,
             day=release_date.day if release_date else None,
@@ -509,6 +517,7 @@ def _get_track_info(self, track: BeatportTrack) -> TrackInfo:
             bpm=track.bpm,
             initial_key=track.initial_key,
             genre=track.genre,
+            genres=track.genres,
         )
 
     def _get_artist(self, artists):

beetsplug/lastgenre/__init__.py

@@ -322,26 +322,23 @@ def fetch_track_genre(self, obj):
 
     # Main processing: _get_genre() and helpers.
 
-    def _format_and_stringify(self, tags: list[str]) -> str:
-        """Format to title_case if configured and return as delimited string."""
+    def _format_genres(self, tags: list[str]) -> list[str]:
+        """Format to title_case if configured and return as list."""
         if self.config["title_case"]:
-            formatted = [tag.title() for tag in tags]
+            return [tag.title() for tag in tags]
         else:
-            formatted = tags
-
-        return self.config["separator"].as_str().join(formatted)
+            return tags
 
     def _get_existing_genres(self, obj: LibModel) -> list[str]:
         """Return a list of genres for this Item or Album. Empty string genres
         are removed."""
-        separator = self.config["separator"].get()
         if isinstance(obj, library.Item):
-            item_genre = obj.get("genre", with_album=False).split(separator)
+            genres_list = obj.get("genres", with_album=False)
         else:
-            item_genre = obj.get("genre").split(separator)
+            genres_list = obj.get("genres")
 
         # Filter out empty strings
-        return [g for g in item_genre if g]
+        return [g for g in genres_list if g] if genres_list else []
 
     def _combine_resolve_and_log(
         self, old: list[str], new: list[str]
@@ -352,8 +349,8 @@ def _combine_resolve_and_log(
         combined = old + new
         return self._resolve_genres(combined)
 
-    def _get_genre(self, obj: LibModel) -> tuple[str | None, ...]:
-        """Get the final genre string for an Album or Item object.
+    def _get_genre(self, obj: LibModel) -> tuple[list[str], str]:
+        """Get the final genre list for an Album or Item object.
 
         `self.sources` specifies allowed genre sources. Starting with the first
         source in this tuple, the following stages run through until a genre is
@@ -363,9 +360,9 @@ def _get_genre(self, obj: LibModel) -> tuple[str | None, ...]:
             - artist, albumartist or "most popular track genre" (for VA-albums)
             - original fallback
             - configured fallback
-            - None
+            - empty list
 
-        A `(genre, label)` pair is returned, where `label` is a string used for
+        A `(genres, label)` pair is returned, where `label` is a string used for
         logging. For example, "keep + artist, whitelist" indicates that existing
         genres were combined with new last.fm genres and whitelist filtering was
         applied, while "artist, any" means only new last.fm genres are included
@@ -382,7 +379,7 @@ def _try_resolve_stage(stage_label: str, keep_genres, new_genres):
                 label = f"{stage_label}, {suffix}"
                 if keep_genres:
                     label = f"keep + {label}"
-                return self._format_and_stringify(resolved_genres), label
+                return self._format_genres(resolved_genres), label
             return None
 
         keep_genres = []
@@ -391,10 +388,7 @@ def _try_resolve_stage(stage_label: str, keep_genres, new_genres):
 
         if genres and not self.config["force"]:
             # Without force pre-populated tags are returned as-is.
-            label = "keep any, no-force"
-            if isinstance(obj, library.Item):
-                return obj.get("genre", with_album=False), label
-            return obj.get("genre"), label
+            return genres, "keep any, no-force"
 
         if self.config["force"]:
             # Force doesn't keep any unless keep_existing is set.
@@ -454,26 +448,33 @@ def _try_resolve_stage(stage_label: str, keep_genres, new_genres):
                     return result
 
         # Nothing found, leave original if configured and valid.
-        if obj.genre and self.config["keep_existing"]:
-            if not self.whitelist or self._is_valid(obj.genre.lower()):
-                return obj.genre, "original fallback"
-
-        # Return fallback string.
+        if genres and self.config["keep_existing"]:
+            # Check if at least one genre is valid
+            valid_genres = [
+                g
+                for g in genres
+                if not self.whitelist or self._is_valid(g.lower())
+            ]
+            if valid_genres:
+                return valid_genres, "original fallback"
+
+        # Return fallback as a list.
         if fallback := self.config["fallback"].get():
-            return fallback, "fallback"
+            return [fallback], "fallback"
 
         # No fallback configured.
-        return None, "fallback unconfigured"
+        return [], "fallback unconfigured"
 
     # Beets plugin hooks and CLI.
 
     def _fetch_and_log_genre(self, obj: LibModel) -> None:
         """Fetch genre and log it."""
         self._log.info(str(obj))
-        obj.genre, label = self._get_genre(obj)
-        self._log.debug("Resolved ({}): {}", label, obj.genre)
+        genres_list, label = self._get_genre(obj)
+        obj.genres = genres_list
+        self._log.debug("Resolved ({}): {}", label, genres_list)
 
-        ui.show_model_changes(obj, fields=["genre"], print_obj=False)
+        ui.show_model_changes(obj, fields=["genres"], print_obj=False)
 
     @singledispatchmethod
     def _process(self, obj: LibModel, write: bool) -> None:

beetsplug/musicbrainz.py

@@ -736,10 +736,11 @@ def album_info(self, release: JSONDict) -> beets.autotag.hooks.AlbumInfo:
             for source in sources:
                 for genreitem in source:
                     genres[genreitem["name"]] += int(genreitem["count"])
-            info.genre = "; ".join(
+            genre_list = [
                 genre
                 for genre, _count in sorted(genres.items(), key=lambda g: -g[1])
-            )
+            ]
+            info.genres = genre_list
 
         # We might find links to external sources (Discogs, Bandcamp, ...)
         external_ids = self.config["external_ids"].get()