Unified search string construction between albums and items.

beets/autotag/match.py

@@ -236,11 +236,30 @@ def _add_candidate(
     )
 
 
+def _parse_search_terms_with_fallbacks(
+    *pairs: tuple[str | None, str],
+) -> tuple[str, ...]:
+    """Given pairs of (search term, fallback), return a tuple of
+    search terms. If **all** search terms are empty, returns the fallback. Otherwise,
+    return the search terms even if some are empty.
+
+    Examples:
+    (("", "F1"), ("B", "F2")) -> ("", "B")
+    (("", "F1"), ("", "F2")) -> ("F1", "F2")
+    (("A", "F1"), (None, "F2")) -> ("A", "")
+    ((None, "F1"), (None, "F2")) -> ("F1", "F2")
+    """
+    if any(term for term, _ in pairs):
+        return tuple(term or "" for term, _ in pairs)
+    else:
+        return tuple(fallback for _, fallback in pairs)
+
+
 def tag_album(
     items,
     search_artist: str | None = None,
     search_album: str | None = None,
-    search_ids: list[str] = [],
+    search_ids: list[str] | None = None,
 ) -> tuple[str, str, Proposal]:
     """Return a tuple of the current artist name, the current album
     name, and a `Proposal` containing `AlbumMatch` candidates.
@@ -294,23 +313,24 @@ def tag_album(
                         Proposal(list(candidates.values()), rec),
                     )
 
-        # Search terms.
-        if not (search_artist and search_album):
-            # No explicit search terms -- use current metadata.
-            search_artist, search_album = cur_artist, cur_album
-        log.debug("Search terms: {} - {}", search_artist, search_album)
+        # Manually provided search terms or fallbacks.
+        _search_artist, _search_album = _parse_search_terms_with_fallbacks(
+            (search_artist, cur_artist),
+            (search_album, cur_album),
+        )
+        log.debug("Search terms: {} - {}", _search_artist, _search_album)
 
         # Is this album likely to be a "various artist" release?
         va_likely = (
             (not consensus["artist"])
-            or (search_artist.lower() in VA_ARTISTS)
+            or (_search_artist.lower() in VA_ARTISTS)
             or any(item.comp for item in items)
         )
         log.debug("Album might be VA: {}", va_likely)
 
         # Get the results from the data sources.
         for matched_candidate in metadata_plugins.candidates(
-            items, search_artist, search_album, va_likely
+            items, _search_artist, _search_album, va_likely
         ):
             _add_candidate(items, candidates, matched_candidate)
 
@@ -322,7 +342,7 @@ def tag_album(
 
 
 def tag_item(
-    item,
+    item: Item,
     search_artist: str | None = None,
     search_title: str | None = None,
     search_ids: list[str] | None = None,
@@ -364,14 +384,18 @@ def tag_item(
         else:
             return Proposal([], Recommendation.none)
 
-    # Search terms.
-    search_artist = search_artist or item.artist
-    search_title = search_title or item.title
-    log.debug("Item search terms: {} - {}", search_artist, search_title)
+    # Manually provided search terms or fallbacks.
+    _search_artist, _search_title = _parse_search_terms_with_fallbacks(
+        (search_artist, item.artist),
+        (search_title, item.title),
+    )
+    log.debug("Item search terms: {} - {}", _search_artist, _search_title)
 
     # Get and evaluate candidate metadata.
     for track_info in metadata_plugins.item_candidates(
-        item, search_artist, search_title
+        item,
+        _search_artist,
+        _search_title,
     ):
         dist = track_distance(item, track_info, incl_artist=True)
         candidates[track_info.track_id] = hooks.TrackMatch(dist, track_info)

beets/metadata_plugins.py

@@ -35,17 +35,21 @@ def find_metadata_source_plugins() -> list[MetadataSourcePlugin]:
 
 
 @notify_info_yielded("albuminfo_received")
-def candidates(*args, **kwargs) -> Iterable[AlbumInfo]:
+def candidates(
+    items: Sequence[Item], artist: str, album: str, va_likely: bool
+) -> Iterable[AlbumInfo]:
     """Return matching album candidates from all metadata source plugins."""
     for plugin in find_metadata_source_plugins():
-        yield from plugin.candidates(*args, **kwargs)
+        yield from plugin.candidates(
+            items=items, artist=artist, album=album, va_likely=va_likely
+        )
 
 
 @notify_info_yielded("trackinfo_received")
-def item_candidates(*args, **kwargs) -> Iterable[TrackInfo]:
-    """Return matching track candidates fromm all metadata source plugins."""
+def item_candidates(item: Item, artist: str, title: str) -> Iterable[TrackInfo]:
+    """Return matching track candidates from all metadata source plugins."""
     for plugin in find_metadata_source_plugins():
-        yield from plugin.item_candidates(*args, **kwargs)
+        yield from plugin.item_candidates(item=item, artist=artist, title=title)
 
 
 def album_for_id(_id: str) -> AlbumInfo | None:
@@ -157,15 +161,22 @@ def candidates(
 
     @abc.abstractmethod
     def item_candidates(
-        self, item: Item, artist: str, title: str
+        self,
+        item: Item,
+        artist: str,
+        title: str,
     ) -> Iterable[TrackInfo]:
         """Return :py:class:`TrackInfo` candidates that match the given track.
 
         Used in the autotag functionality to search for tracks.
 
         :param item: Track item
-        :param artist: Track artist
-        :param title: Track title
+        :param artist: Track artist, either a search manually provided or
+            preprocessed from the item. If no metadata is available an empty string
+            is passed.
+        :param title: Track title, either a search manually provided or
+            preprocessed from the item. If no metadata is available an empty string
+            is passed.
         """
         raise NotImplementedError
 

docs/changelog.rst

@@ -29,6 +29,11 @@ Other changes:
 - The documentation chapter :doc:`dev/paths` has been moved to the "For
   Developers" section and revised to reflect current best practices (pathlib
   usage).
+- Standardized ``search_*`` parameter handling in autotag matchers. Manual album
+  and singleton searches now behave consistently: when a user does not specify a
+  search query in the prompt, the system defaults to using the corresponding
+  value from the metadata. This was already the case for albums but not for
+  singletons.
 
 2.5.1 (October 14, 2025)
 ------------------------

test/autotag/test_match.py

@@ -0,0 +1,40 @@
+import pytest
+
+from beets.autotag.match import _parse_search_terms_with_fallbacks
+
+
+class TestSearchTermHandling:
+    @pytest.mark.parametrize(
+        "input_pairs, expected",
+        [
+            (
+                (("A", "F1"), ("B", "F2")),
+                ("A", "B"),
+            ),
+            (
+                (("", "F1"), ("B", "F2")),
+                ("", "B"),
+            ),
+            (
+                (("", "F1"), ("", "F2")),
+                ("F1", "F2"),
+            ),
+            (
+                (("A", "F1"), (None, "F2")),
+                ("A", ""),
+            ),
+            (
+                ((None, "F1"), (None, "F2")),
+                ("F1", "F2"),
+            ),
+        ],
+    )
+    def test_search_parsing(self, input_pairs, expected):
+        result = _parse_search_terms_with_fallbacks(*input_pairs)
+        assert result == expected
+
+        # Should also apply for the reversed order of inputs
+        reversed_pairs = tuple(reversed(input_pairs))
+        reversed_expected = tuple(reversed(expected))
+        reversed_result = _parse_search_terms_with_fallbacks(*reversed_pairs)
+        assert reversed_result == reversed_expected