Add native support for multiple genres per album/track

[dunkla]

Implements native multi-value genre support following the same pattern as multi-value artists. Adds a 'genres' field that stores genres as a list and writes them as multiple individual genre tags to files.

Features:

• New 'genres' field (MULTI_VALUE_DSV) for albums and tracks
• Bidirectional sync between 'genre' (string) and 'genres' (list)
• Config option 'multi_value_genres' (default: yes) to enable/disable
• Config option 'genre_separator' (default: ', ') for joining genres into the single 'genre' field - matches lastgenre's default separator
• Updated MusicBrainz, Beatport, and LastGenre plugins to populate 'genres' field
• LastGenre plugin now uses global genre_separator when multi_value_genres is enabled for consistency
• Comprehensive test coverage (10 tests for sync logic)
• Full documentation in changelog and reference/config.rst

Backward Compatibility:

• When multi_value_genres=yes: 'genre' field maintained as joined string for backward compatibility, 'genres' is the authoritative list
• When multi_value_genres=no: Preserves old behavior (only first genre)
• Default separator matches lastgenre's default for seamless migration

Migration:

• Most users (using lastgenre's default) need no configuration changes
• Users with custom lastgenre separator should set genre_separator to match their existing data
• Users can opt-out entirely with multi_value_genres: no

Code Review Feedback Addressed:

• Extracted genre separator into configurable option (not hardcoded)
• Fixed Beatport plugin to always populate genres field consistently
• Added tests for None values and edge cases
• Handle None values gracefully in sync logic
• Added migration documentation for smooth user experience
• Made separator user-configurable instead of constant
• Changed default to ', ' for seamless migration (matches lastgenre)

[sourcery-ai]

Hey there - I've reviewed your changes and they look great!

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location> `beetsplug/beatport.py:236-242` </location>
<code_context>
         if "genres" in data:
-            self.genres = [str(x["name"]) for x in data["genres"]]
+            genre_list = [str(x["name"]) for x in data["genres"]]
+            if beets.config["multi_value_genres"]:
+                self.genres = genre_list
+            else:
+                # Even when disabled, populate with first genre for consistency
</code_context>

<issue_to_address>
**suggestion (bug_risk):** Populating genres with all values may introduce duplicates if Beatport returns repeated genre names.

Consider removing duplicate genre names from genre_list before assigning it to self.genres.

```suggestion
        if "genres" in data:
            genre_list = [str(x["name"]) for x in data["genres"]]
            # Remove duplicates while preserving order
            genre_list = list(dict.fromkeys(genre_list))
            if beets.config["multi_value_genres"]:
                self.genres = genre_list
            else:
                # Even when disabled, populate with first genre for consistency
                self.genres = [genre_list[0]] if genre_list else []
```
</issue_to_address>

### Comment 2
<location> `test/test_autotag.py:554-563` </location>
<code_context>
+        assert item.genres == ["Rock", "Alternative", "Indie"]
+        assert item.genre == "Rock, Alternative, Indie"
+
+    def test_sync_genres_priority_list_over_string(self):
+        """When both genre and genres exist, genres list takes priority."""
+        config["multi_value_genres"] = True
+
+        item = Item(genre="Jazz", genres=["Rock", "Alternative"])
+        correct_list_fields(item)
+
+        # genres list should take priority and update genre string
+        assert item.genres == ["Rock", "Alternative"]
+        assert item.genre == "Rock, Alternative"
+
+    def test_sync_genres_none_values(self):
</code_context>

<issue_to_address>
**suggestion (testing):** Consider testing the scenario where both genre and genres are set but have conflicting values and multi_value_genres is disabled.

Please add a test for the case where multi_value_genres is False and genre and genres have different values, to verify which field takes precedence and how synchronization is handled.
</issue_to_address>

### Comment 3
<location> `test/test_autotag.py:581-590` </location>
<code_context>
+        assert item.genre == "Jazz"
+        assert item.genres == ["Jazz"]
+
+    def test_sync_genres_disabled_empty_genres(self):
+        """Handle disabled config with empty genres list."""
+        config["multi_value_genres"] = False
+
+        item = Item(genres=[])
+        correct_list_fields(item)
+
+        # Should handle empty list without errors
+        assert item.genres == []
+        assert item.genre == ""
</code_context>

<issue_to_address>
**suggestion (testing):** Consider adding a test for genres=None when multi_value_genres is False.

Testing genres=None with multi_value_genres=False will help verify correct fallback behavior and error handling.

```suggestion
    def test_sync_genres_disabled_empty_genres(self):
        """Handle disabled config with empty genres list."""
        config["multi_value_genres"] = False

        item = Item(genres=[])
        correct_list_fields(item)

        # Should handle empty list without errors
        assert item.genres == []
        assert item.genre == ""

    def test_sync_genres_disabled_none_genres(self):
        """Handle disabled config with genres=None."""
        config["multi_value_genres"] = False

        item = Item(genres=None)
        correct_list_fields(item)

        # Should handle None without errors
        assert item.genres == []
        assert item.genre == ""
```
</issue_to_address>

### Comment 4
<location> `test/test_library.py:690-693` </location>
<code_context>
         self._assert_dest(b"/base/not_played")

     def test_first(self):
-        self.i.genres = "Pop; Rock; Classical Crossover"
-        self._setf("%first{$genres}")
+        self.i.genre = "Pop; Rock; Classical Crossover"
+        self._setf("%first{$genre}")
         self._assert_dest(b"/base/Pop")
</code_context>

<issue_to_address>
**suggestion (testing):** Tests in test_library.py should be updated to cover the new genres field.

Add tests that assign genres as a list and check template functions like %first to ensure correct handling of the new field.

```suggestion
    def test_first(self):
        self.i.genre = "Pop; Rock; Classical Crossover"
        self._setf("%first{$genre}")
        self._assert_dest(b"/base/Pop")

    def test_first_genres_list(self):
        self.i.genres = ["Pop", "Rock", "Classical Crossover"]
        self._setf("%first{$genres}")
        self._assert_dest(b"/base/Pop")

    def test_first_genres_list_skip(self):
        self.i.genres = ["Pop", "Rock", "Classical Crossover"]
        self._setf("%first{$genres,1,2}")
        self._assert_dest(b"/base/Classical Crossover")
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

❌ Patch coverage is 50.58824% with 42 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.61%. Comparing base (ef59cfa) to head (0266b6c).
⚠️ Report is 124 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beets/library/library.py	25.00%	32 Missing and 1 partial ⚠️
beets/autotag/hooks.py	57.14%	1 Missing and 5 partials ⚠️
beetsplug/lastgenre/__init__.py	86.36%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6169      +/-   ##
==========================================
- Coverage   68.71%   68.61%   -0.11%     
==========================================
  Files         138      138              
  Lines       18558    18605      +47     
  Branches     3062     3073      +11     
==========================================
+ Hits        12753    12765      +12     
- Misses       5154     5186      +32     
- Partials      651      654       +3     

Files with missing lines	Coverage Δ
beets/autotag/__init__.py	87.71% <100.00%> (+0.10%)	⬆️
beets/library/models.py	87.15% <ø> (ø)
beetsplug/beatport.py	43.27% <100.00%> (-0.53%)	⬇️
beetsplug/lastgenre/__init__.py	70.37% <86.36%> (+0.44%)	⬆️
beets/autotag/hooks.py	95.41% <57.14%> (-4.59%)	⬇️
beets/library/library.py	64.42% <25.00%> (-29.02%)	⬇️

🚀 New features to boost your workflow:

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

[snejus]

Hi, thanks for your contribution!

The main bottleneck that we have with a multi-value genres field is that mediafile does not currently support it. We need to add it, and make it behave the same way as, say, artists field does. I can take care of this.

Otherwise, I reckon we should simplify this change by migrating to using genres field for good.

[JOJ0]

Hi @dunkla many many thanks for this contribution! It lately crosses my mind daily that I should probably finally start working on multi-genre support before continuing with my lastgenre masterplan ;-), so thanks again for your motivation to drive this forward.

When I skimmed through it yesterday my first thoughts were that no user and no plugin should have to worry about population both genre and genres, so I'd like to second @snejus here: Writing a genres list should be the only thing that any Beets plugin and user should have to do. Any fallback/opt-in/opt-out scenarios are not necessary and complicate things.

Also @snejus do you think this PR should wait for #6165 to be finished or at least should be based on it (to let @dunkla continue workin on it).

[JOJ0]

Also thanks for offering to implement the mediafile end @snejus! I think we should finalize the current cleanup first though. Then implement genres first thing! beetbox/mediafile#86

[dunkla]

As soon as decisions have been made i'm more than happy to rebase and restructre the approach as wished.

[snejus]

Good news, guys! Apparently, mediafile already supports multivalued genres field! @dunkla you can go ahead and implement the requested changes whenever you have time.

Additionally, I think, we should think of the best way to migrate joined genres from the existing genre field to the new field at the point of this field is created. Unlike in #5540, we have an opportunity to do this properly this time, where we don't need to depend on mbsync / reimports!

[dunkla]

Summary of Changes

Addressed PR Comments

1. Simplify the architecture (snejus's main comment)

• Removed multi_value_genres config option from beets/config_default.yaml
• Removed genre_separator config option from beets/config_default.yaml
• Replaced complex sync_genre_fields() with simple ensure_first_value("genre", "genres") call in beets/autotag/init.py:204
• Simplified all plugins to always write genres as lists (no conditional logic based on config)

2. Update Beatport plugin (snejus's comment)

• Simplified beetsplug/beatport.py:236-239 to always populate genres list
• Removed all conditional multi_value_genres config checks from BeatportRelease and BeatportTrack

3. Update MusicBrainz plugin (snejus's comment)

• Simplified beetsplug/musicbrainz.py:739-743 to write directly to info.genres as list
• Removed config-based conditional logic

4. Update LastGenre plugin (snejus's comment)

• Major refactor of beetsplug/lastgenre/init.py:
  • Changed _get_genre() to return list instead of string
  • Renamed _format_and_stringify() to _format_genres() returning list
  • Removed all separator-related configuration logic
  • Simplified _get_existing_genres() to only read from genres field
  • Updated _fetch_and_log_genre() to write directly to obj.genres

Addressed Issues

Migration concerns (referenced in PR discussion, relates to #5540)

• Added automatic lazy migration in beets/autotag/init.py:167-186
  • Detects comma (", "), semicolon ("; "), and slash (" / ") separated genre strings
  • Automatically splits into genres list on first item access
  • No reimport or mbsync needed for existing libraries
• Added explicit beet migrate genres command for batch processing in beets/ui/commands/migrate.py
  • Supports --pretend flag to preview changes
  • Allows users to migrate entire library at once if preferred
• Migration strategy avoids endless rewrite loops from Stop perpetually writing mb_artistid, mb_albumartistid and albumtypes fields #5540:
  • Proper field synchronization using ensure_first_value()
  • Clears old genre field after splitting to prevent duplication
  • No bidirectional sync complexity

Other Changes

Tests

• Rewrote all genre sync tests in test/test_autotag.py:480-590
• Added 5 new migration test cases covering different separator types
• Updated LastGenre tests in test/plugins/test_lastgenre.py to expect lists instead of strings
• Updated Beatport tests in test/plugins/test_beatport.py to check .genres attribute
• Fixed library tests in test/test_library.py to work with new field sync
• All 44 genre-related tests passing

Documentation

• Updated docs/changelog.rst:15-29 with simplified feature description
• Added comprehensive migration documentation mentioning both automatic and manual options
• Removed documentation for multi_value_genres and genre_separator config options from docs/reference/config.rst

Code Quality

• All linter checks passing (ruff)
• All type checks passing

Implementation Philosophy

The simplified implementation aligns with the maintainer's vision:

• Always use multi-value genres internally
• Automatic backward-compatible sync to genre field via ensure_first_value()
• No configuration complexity
• Clean migration path for existing users
• Consistent behavior across all metadata sources

---

all again with immense help of claude code

[snejus]

Summary of Changes

Addressed PR Comments

1. Simplify the architecture (snejus's main comment)

* Removed `multi_value_genres` config option from beets/config_default.yaml

* Removed `genre_separator` config option from beets/config_default.yaml

* Replaced complex `sync_genre_fields()` with simple `ensure_first_value("genre", "genres")` call in beets/autotag/**init**.py:204

* Simplified all plugins to always write genres as lists (no conditional logic based on config)

2. Update Beatport plugin (snejus's comment)

* Simplified beetsplug/beatport.py:236-239 to always populate `genres` list

* Removed all conditional `multi_value_genres` config checks from BeatportRelease and BeatportTrack

3. Update MusicBrainz plugin (snejus's comment)

* Simplified beetsplug/musicbrainz.py:739-743 to write directly to `info.genres` as list

* Removed config-based conditional logic

4. Update LastGenre plugin (snejus's comment)

* Major refactor of beetsplug/lastgenre/**init**.py:
  
  * Changed `_get_genre()` to return list instead of string
  * Renamed `_format_and_stringify()` to `_format_genres()` returning list
  * Removed all separator-related configuration logic
  * Simplified `_get_existing_genres()` to only read from genres field
  * Updated `_fetch_and_log_genre()` to write directly to `obj.genres`

Addressed Issues

Migration concerns (referenced in PR discussion, relates to #5540)

* Added automatic lazy migration in beets/autotag/**init**.py:167-186
  
  * Detects comma (", "), semicolon ("; "), and slash (" / ") separated genre strings
  * Automatically splits into `genres` list on first item access
  * No reimport or `mbsync` needed for existing libraries

* Added explicit `beet migrate genres` command for batch processing in beets/ui/commands/migrate.py
  
  * Supports `--pretend` flag to preview changes
  * Allows users to migrate entire library at once if preferred

* Migration strategy avoids endless rewrite loops from [Stop perpetually writing `mb_artistid`, `mb_albumartistid` and `albumtypes` fields #5540](https://github.com/beetbox/beets/pull/5540):
  
  * Proper field synchronization using `ensure_first_value()`
  * Clears old genre field after splitting to prevent duplication
  * No bidirectional sync complexity

Other Changes

Tests

* Rewrote all genre sync tests in test/test_autotag.py:480-590

* Added 5 new migration test cases covering different separator types

* Updated LastGenre tests in test/plugins/test_lastgenre.py to expect lists instead of strings

* Updated Beatport tests in test/plugins/test_beatport.py to check `.genres` attribute

* Fixed library tests in test/test_library.py to work with new field sync

* All 44 genre-related tests passing

Documentation

* Updated docs/changelog.rst:15-29 with simplified feature description

* Added comprehensive migration documentation mentioning both automatic and manual options

* Removed documentation for `multi_value_genres` and `genre_separator` config options from docs/reference/config.rst

Code Quality

* All linter checks passing (ruff)

* All type checks passing

Implementation Philosophy

The simplified implementation aligns with the maintainer's vision:

* Always use multi-value `genres` internally

* Automatic backward-compatible sync to `genre` field via `ensure_first_value()`

* No configuration complexity

* Clean migration path for existing users

* Consistent behavior across all metadata sources

all again with immense help of claude code

I love the amount of detail here @dunkla. I will review this shortly!

[snejus]

See comments. Main points:

1. We want to deprecate genre field and convert it to genres inside Info.__init__, and emit a deprecation warning
2. We should perform the migration immediately after the new genres field is created.

[dunkla]

alright, thanks for your effort (going on)