From 820ff2013945ac706a398de18d270ae3606697a0 Mon Sep 17 00:00:00 2001
From: BoulderBadgeDad <batmanesignal@gmail.com>
Date: Thu, 18 Jun 2026 09:44:17 -0700
Subject: [PATCH] Settings UI: 'Match singles to their parent album' toggle
 (Library > Post-Processing)

Surfaces metadata_enhancement.single_to_album as a checkbox in the Post-Processing
> Core Features section, next to the cover-art settings (it's about getting the
right album cover). Default OFF, wired like the replaygain toggle (load '=== true',
save raw .checked) since the generic data-config binding defaults a missing key to
ON. Registered the default in settings.py DEFAULT_CONFIG + config.example.json.
---
 config/config.example.json | 3 ++-
 config/settings.py         | 7 ++++++-
 webui/index.html           | 7 +++++++
 webui/static/settings.js   | 2 ++
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/config/config.example.json b/config/config.example.json
index 0543822c..e6adf55c 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -44,7 +44,8 @@
   },
   "metadata_enhancement": {
     "enabled": true,
-    "embed_album_art": true
+    "embed_album_art": true,
+    "single_to_album": false
   },
   "file_organization": {
     "enabled": true,
diff --git a/config/settings.py b/config/settings.py
index 28d1908a..fe03096e 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -662,7 +662,12 @@ class ConfigManager:
                 # source whose art is smaller is skipped so the next source is
                 # tried — stops a low-res Cover Art Archive upload from winning.
                 # 0 disables the size gate.
-                "min_art_size": 1000
+                "min_art_size": 1000,
+                # When a track matches a SINGLE release, look up the parent ALBUM
+                # that contains it and tag it as that album, so it groups with its
+                # album-mates and gets the album cover (not the single's). Off by
+                # default — it's an extra per-import metadata lookup.
+                "single_to_album": False
             },
             "musicbrainz": {
                 "embed_tags": True
diff --git a/webui/index.html b/webui/index.html
index af40adfa..43659fdb 100644
--- a/webui/index.html
+++ b/webui/index.html
@@ -5730,6 +5730,13 @@
                                             <small class="settings-hint">Order the sources to choose whose cover art is used. The first source that has a cover wins; misses fall through to the next, and if none match, your download's own art is kept. Only sources you're connected to are shown — leave all off to keep current behavior.</small>
                                             <div class="hybrid-source-list" id="art-source-list"></div>
                                         </div>
+                                        <div class="form-group">
+                                            <label class="checkbox-label">
+                                                <input type="checkbox" id="single-to-album-enabled">
+                                                Match singles to their parent album
+                                            </label>
+                                            <small class="settings-hint">When a track matches a single release, look up the album that contains it and tag it as that album — so every song in an album gets the same (album) cover instead of some getting the single's art. Off by default: adds an extra metadata lookup per single-matched track.</small>
+                                        </div>
                                         <div class="form-group">
                                             <label class="checkbox-label">
                                                 <input type="checkbox" id="lrclib-enabled" checked>
diff --git a/webui/static/settings.js b/webui/static/settings.js
index d00c79d9..0023acf8 100644
--- a/webui/static/settings.js
+++ b/webui/static/settings.js
@@ -1235,6 +1235,7 @@ async function loadSettingsData() {
         document.getElementById('embed-album-art').checked = settings.metadata_enhancement?.embed_album_art !== false;
         document.getElementById('cover-art-download').checked = settings.metadata_enhancement?.cover_art_download !== false;
         document.getElementById('prefer-caa-art').checked = settings.metadata_enhancement?.prefer_caa_art === true;
+        document.getElementById('single-to-album-enabled').checked = settings.metadata_enhancement?.single_to_album === true;
         document.getElementById('lrclib-enabled').checked = settings.metadata_enhancement?.lrclib_enabled !== false;
         document.getElementById('replaygain-enabled').checked = settings.post_processing?.replaygain_enabled === true;
         document.getElementById('duration-tolerance-seconds').value = settings.post_processing?.duration_tolerance_seconds ?? 0;
@@ -3104,6 +3105,7 @@ async function saveSettings(quiet = false) {
             cover_art_download: document.getElementById('cover-art-download').checked,
             prefer_caa_art: document.getElementById('prefer-caa-art').checked,
             album_art_order: getArtOrder(),
+            single_to_album: document.getElementById('single-to-album-enabled').checked,
             lrclib_enabled: document.getElementById('lrclib-enabled').checked,
             tags: {
                 quality_tag: _getTagConfig('metadata_enhancement.tags.quality_tag'),