Add opt-in approximate matching and upgrade recommendations

A per-pair "Approximate matching" setting adds a second pass for slave
files the strict rules could not place. It searches the same album with
disc folders (Disc 02, CD2, ...) ignored, then the top-level folder, and
scores titles by edit distance and word containment against a configurable
threshold (default 85%), with a small track-number bonus.

Guards against false matches: version words (live, remix, reprise,
instrumental, ...) must agree, near-tied candidates are left unmatched,
and approximate matches always go to manual review, never auto-link.
Each match records a human-readable reason.

Review now flags matches where the master copy is better as upgrades,
with an Upgrades filter and count and an "Upgrade to master copy" action.
The redundant "master is lossless" warning note is dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/engine/approx.go

@@ -0,0 +1,257 @@
+package engine
+
+import (
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"unicode"
+)
+
+// Approximate matching is an opt-in, per-pair second pass for slave files the
+// strict rules could not place. It tolerates disc subfolders ("Disc 02/",
+// "CD2/") and slightly different titles, but never auto-links: every result
+// goes to manual review.
+
+// discFolder matches disc/side subfolders such as "Disc 02", "CD2", "Disk 1 - Bonus".
+var discFolder = regexp.MustCompile(`(?i)^(disc|disk|cd|dvd|side|vol|volume)[\s._-]*\d+\b.*$`)
+
+// trackNum extracts the leading track number ("07 Memory", "2-07 Memory").
+var trackNum = regexp.MustCompile(`^\s*(?:\d{1,2}[-.]\s*)?(\d{1,3})(?:\s*[-._)]\s*|\s+)`)
+
+// versionWords mark a different recording or arrangement. Two titles only
+// match approximately if they carry the same set of these words, so
+// "Memory (Live)" never matches "Memory".
+var versionWords = map[string]bool{
+	"live": true, "remix": true, "mix": true, "acoustic": true, "demo": true, "instrumental": true,
+	"edit": true, "version": true, "reprise": true, "karaoke": true, "cover": true, "extended": true,
+	"radio": true, "unplugged": true, "orchestral": true, "piano": true, "clean": true, "acapella": true,
+	"cappella": true, "interlude": true, "intro": true, "outro": true, "skit": true, "vip": true, "dub": true,
+	"sped": true, "slowed": true, "nightcore": true, "reverb": true, "mashup": true, "bootleg": true,
+}
+
+// albumKey is the lower-cased directory with disc folders removed.
+func albumKey(rel string) string {
+	var parts []string
+	for _, p := range strings.Split(filepath.Dir(rel), string(filepath.Separator)) {
+		if p != "." && !discFolder.MatchString(p) {
+			parts = append(parts, strings.ToLower(p))
+		}
+	}
+	return strings.Join(parts, "/")
+}
+
+func hasDiscFolder(rel string) bool {
+	for _, p := range strings.Split(filepath.Dir(rel), string(filepath.Separator)) {
+		if discFolder.MatchString(p) {
+			return true
+		}
+	}
+	return false
+}
+
+type titleInfo struct {
+	norm     string          // normTitle: letters+digits only
+	words    []string        // non-version words
+	versions map[string]bool // version words present
+	track    int             // 0 = unknown
+}
+
+func parseTitle(name string) titleInfo {
+	stem := strings.TrimSuffix(name, filepath.Ext(name))
+	ti := titleInfo{norm: normTitle(name), versions: map[string]bool{}}
+	if m := trackNum.FindStringSubmatch(stem); m != nil {
+		ti.track, _ = strconv.Atoi(m[1])
+		if s := trackNum.ReplaceAllString(stem, ""); strings.TrimSpace(s) != "" {
+			stem = s
+		}
+	}
+	for _, w := range strings.FieldsFunc(strings.ToLower(stem), func(r rune) bool {
+		return !unicode.IsLetter(r) && !unicode.IsDigit(r)
+	}) {
+		if versionWords[w] {
+			ti.versions[w] = true
+		} else {
+			ti.words = append(ti.words, w)
+		}
+	}
+	return ti
+}
+
+func sameVersions(a, b map[string]bool) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for k := range a {
+		if !b[k] {
+			return false
+		}
+	}
+	return true
+}
+
+// levenshteinRatio is 1 - editDistance/maxLen over runes.
+func levenshteinRatio(a, b string) float64 {
+	ra, rb := []rune(a), []rune(b)
+	if len(ra) == 0 || len(rb) == 0 {
+		return 0
+	}
+	prev := make([]int, len(rb)+1)
+	cur := make([]int, len(rb)+1)
+	for j := range prev {
+		prev[j] = j
+	}
+	for i := 1; i <= len(ra); i++ {
+		cur[0] = i
+		for j := 1; j <= len(rb); j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
+		}
+		prev, cur = cur, prev
+	}
+	return 1 - float64(prev[len(rb)])/float64(max(len(ra), len(rb)))
+}
+
+// wordContainment scores titles where one adds words to the other
+// ("Memory" vs "Memory from Cats"). It needs at least two shared words so a
+// one-word title like "Love" cannot swallow "Love Story".
+func wordContainment(a, b []string) float64 {
+	if len(a) > len(b) {
+		a, b = b, a
+	}
+	if len(a) < 2 {
+		return 0
+	}
+	set := map[string]bool{}
+	for _, w := range b {
+		set[w] = true
+	}
+	hit := 0
+	for _, w := range a {
+		if set[w] {
+			hit++
+		}
+	}
+	if hit != len(a) {
+		return 0
+	}
+	return 0.9 // a full subset is strong but never a perfect match
+}
+
+// titleScore is the similarity of two titles in [0,1], or -1 if they are
+// different versions of a song.
+func titleScore(a, b titleInfo) float64 {
+	if a.norm == "" || b.norm == "" || !sameVersions(a.versions, b.versions) {
+		return -1
+	}
+	s := max(levenshteinRatio(a.norm, b.norm), wordContainment(a.words, b.words))
+	if a.track > 0 && b.track > 0 {
+		if a.track == b.track {
+			s += 0.05
+		} else {
+			s -= 0.05
+		}
+	}
+	return min(s, 1)
+}
+
+type approxIndex struct {
+	byAlbum map[string][]string // albumKey -> master rels
+	byTop   map[string][]string // lower(top folder) -> master rels
+	titles  map[string]titleInfo
+}
+
+func buildApproxIndex(files []string) *approxIndex {
+	ax := &approxIndex{byAlbum: map[string][]string{}, byTop: map[string][]string{}, titles: map[string]titleInfo{}}
+	for _, rel := range files {
+		ax.titles[rel] = parseTitle(filepath.Base(rel))
+		k := albumKey(rel)
+		ax.byAlbum[k] = append(ax.byAlbum[k], rel)
+		if top := firstComponent(rel); top != "" {
+			t := strings.ToLower(top)
+			ax.byTop[t] = append(ax.byTop[t], rel)
+		}
+	}
+	return ax
+}
+
+type scored struct {
+	rel   string
+	score float64
+}
+
+// approxMargin is how far the best candidate must beat the runner-up.
+const approxMargin = 0.05
+
+// find returns the best approximate master match for a slave file, plus a
+// human-readable reason. The album (disc folders ignored) is searched first,
+// then the whole top-level folder.
+func (ax *approxIndex) find(relSlave string, threshold float64) (string, string) {
+	st := parseTitle(filepath.Base(relSlave))
+	scopes := []struct {
+		name  string
+		cands []string
+	}{
+		{"same album", ax.byAlbum[albumKey(relSlave)]},
+	}
+	if top := firstComponent(relSlave); top != "" {
+		scopes = append(scopes, struct {
+			name  string
+			cands []string
+		}{"same top-level folder, different album folder", ax.byTop[strings.ToLower(top)]})
+	}
+	for _, sc := range scopes {
+		var best []scored
+		for _, rel := range sc.cands {
+			if s := titleScore(st, ax.titles[rel]); s >= threshold {
+				best = append(best, scored{rel, s})
+			}
+		}
+		if len(best) == 0 {
+			continue
+		}
+		sort.Slice(best, func(i, j int) bool {
+			if best[i].score != best[j].score {
+				return best[i].score > best[j].score
+			}
+			return extRank(best[i].rel) < extRank(best[j].rel)
+		})
+		// Several formats of the same title in one folder are one song.
+		top := best[0]
+		ambiguous := false
+		for _, o := range best[1:] {
+			sameSong := filepath.Dir(o.rel) == filepath.Dir(top.rel) &&
+				strings.TrimSuffix(filepath.Base(o.rel), filepath.Ext(o.rel)) == strings.TrimSuffix(filepath.Base(top.rel), filepath.Ext(top.rel))
+			if !sameSong && top.score-o.score < approxMargin {
+				ambiguous = true
+				break
+			}
+		}
+		if ambiguous {
+			return "", ""
+		}
+		return top.rel, approxReason(relSlave, top.rel, st, ax.titles[top.rel], top.score, sc.name)
+	}
+	return "", ""
+}
+
+func approxReason(relSlave, relMaster string, st, mt titleInfo, score float64, scope string) string {
+	parts := []string{fmt.Sprintf("title %d%% similar", int(score*100+0.5))}
+	if st.track > 0 && mt.track > 0 {
+		if st.track == mt.track {
+			parts = append(parts, fmt.Sprintf("track %02d matches", st.track))
+		} else {
+			parts = append(parts, fmt.Sprintf("track numbers differ (%02d vs %02d)", st.track, mt.track))
+		}
+	}
+	if filepath.Dir(relSlave) != filepath.Dir(relMaster) && albumKey(relSlave) == albumKey(relMaster) {
+		parts = append(parts, "disc folder ignored")
+	}
+	parts = append(parts, scope)
+	return strings.Join(parts, " · ")
+}

internal/engine/approx_test.go

@@ -0,0 +1,126 @@
+package engine
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/cdnutter/playlink/internal/store"
+)
+
+func enableApprox(t *testing.T, ev *env) {
+	t.Helper()
+	ev.pair.ApproxMatching = true
+	ev.pair.ApproxThreshold = 85
+	if err := ev.st.SavePair(ctx, &ev.pair); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// The user's example: the master album has disc folders, the slave does not.
+func TestApproxDiscFolderUpgrade(t *testing.T) {
+	ev := setup(t, false)
+	master := ev.write(ev.master, "Andrew Lloyd Webber/Cats/Disc 02/07 Memory.flac", "lossless")
+	ev.write(ev.master, "Andrew Lloyd Webber/Cats/Disc 01/07 Macavity.flac", "other")
+	ev.write(ev.master, "Andrew Lloyd Webber/Evita/03 Memory.flac", "same title, other album")
+	ev.write(ev.slave, "Andrew Lloyd Webber/Cats/07 Memory.mp3", "lossy")
+
+	// Off by default: the title exists on two albums, so nothing matches.
+	ev.scan()
+	if m := ev.match("Andrew Lloyd Webber/Cats/07 Memory.mp3"); m.Status != store.StatusUnmatched {
+		t.Fatalf("approximate matching must be opt-in, got %s/%s", m.Status, m.Kind)
+	}
+
+	enableApprox(t, ev)
+	ev.scan()
+	m := ev.match("Andrew Lloyd Webber/Cats/07 Memory.mp3")
+	if m.Kind != store.KindApprox || m.Status != store.StatusSimilar || m.RelMaster != "Andrew Lloyd Webber/Cats/Disc 02/07 Memory.flac" {
+		t.Fatalf("unexpected match %s %s -> %s", m.Status, m.Kind, m.RelMaster)
+	}
+	if !strings.Contains(m.Reason, "disc folder ignored") || !strings.Contains(m.Reason, "track 07 matches") {
+		t.Fatalf("reason should explain the match, got %q", m.Reason)
+	}
+
+	// Linking upgrades the slave: it gets the master's FLAC in its own folder.
+	if _, err := ev.e.Link(ctx, m.ID, LinkOptions{}); err != nil {
+		t.Fatal(err)
+	}
+	upgraded := filepath.Join(ev.slave, "Andrew Lloyd Webber/Cats/07 Memory.flac")
+	if !sameInode(t, master, upgraded) {
+		t.Fatal("slave should now hold a hardlink of the master FLAC")
+	}
+}
+
+func TestApproxTitleVariations(t *testing.T) {
+	ev := setup(t, false)
+	enableApprox(t, ev)
+	ev.write(ev.master, "Band/Album/CD1/03 - Dont Stop Believin.flac", "a")
+	ev.write(ev.slave, "Band/Album/3 Don't Stop Believing.mp3", "b") // typo-level difference
+	ev.write(ev.master, "Band/Album/CD1/04 - Song.flac", "c")
+	ev.write(ev.slave, "Band/Album/04 Song (Live).mp3", "d") // different version: must not match
+	ev.write(ev.master, "Band/Album/CD2/05 Totally Different.flac", "e")
+	ev.write(ev.slave, "Band/Album/05 Something Else.mp3", "f") // too dissimilar
+	ev.scan()
+
+	if m := ev.match("Band/Album/3 Don't Stop Believing.mp3"); m.Kind != store.KindApprox {
+		t.Fatalf("near-identical title should match approximately, got %s", m.Kind)
+	}
+	if m := ev.match("Band/Album/04 Song (Live).mp3"); m.Status != store.StatusUnmatched {
+		t.Fatalf("live version must not match the studio track, got %s -> %s", m.Kind, m.RelMaster)
+	}
+	if m := ev.match("Band/Album/05 Something Else.mp3"); m.Status != store.StatusUnmatched {
+		t.Fatalf("dissimilar titles must not match, got %s -> %s", m.Kind, m.RelMaster)
+	}
+}
+
+func TestApproxAmbiguousIsLeftAlone(t *testing.T) {
+	ev := setup(t, false)
+	enableApprox(t, ev)
+	// Two discs each carry an equally good candidate: refuse to guess.
+	ev.write(ev.master, "Band/Album/Disc 1/Anthem.flac", "a")
+	ev.write(ev.master, "Band/Album/Disc 2/Anthem.flac", "b")
+	ev.write(ev.slave, "Band/Album/Anthem.mp3", "c")
+	ev.scan()
+	if m := ev.match("Band/Album/Anthem.mp3"); m.Status != store.StatusUnmatched {
+		t.Fatalf("ambiguous candidates must not be matched, got %s -> %s", m.Kind, m.RelMaster)
+	}
+}
+
+func TestApproxAlbumFolderRename(t *testing.T) {
+	ev := setup(t, false)
+	enableApprox(t, ev)
+	ev.write(ev.master, "Cast/Cats (Original London Cast)/Disc 2/07 Memory.flac", "a")
+	ev.write(ev.slave, "Cast/Cats/07. Memory.mp3", "b")
+	ev.scan()
+	m := ev.match("Cast/Cats/07. Memory.mp3")
+	if m.Kind != store.KindApprox || !strings.Contains(m.Reason, "different album folder") {
+		t.Fatalf("should match across album folder names, got %s %q", m.Kind, m.Reason)
+	}
+}
+
+func TestTitleScore(t *testing.T) {
+	cases := []struct {
+		a, b string
+		min  float64
+		max  float64
+	}{
+		{"07 Memory.flac", "07 Memory.mp3", 1, 1},
+		{"07 Memory.flac", "08 Memory.mp3", 0.9, 0.96},
+		{"Memory.flac", "Memory (Live).flac", -1, -1},
+		{"Song (Remix).flac", "Song (Remix).mp3", 1, 1},
+		{"Love.flac", "Love Story.flac", 0, 0.6},
+		{"Memory from Cats.flac", "Memory from Cats Remastered.flac", 0.85, 1},
+	}
+	for _, c := range cases {
+		got := titleScore(parseTitle(c.a), parseTitle(c.b))
+		if got < c.min-1e-9 || got > c.max+1e-9 {
+			t.Errorf("titleScore(%q, %q) = %.3f, want [%.2f, %.2f]", c.a, c.b, got, c.min, c.max)
+		}
+	}
+	if k := albumKey("A/Cats/Disc 02/07 Memory.flac"); k != "a/cats" {
+		t.Errorf("albumKey = %q", k)
+	}
+	if k := albumKey("A/Cats/CD2 - Bonus/x.flac"); k != "a/cats" {
+		t.Errorf("albumKey = %q", k)
+	}
+}

internal/engine/engine.go

@@ -280,6 +280,12 @@ func (e *Engine) NormalizePair(p *store.Pair) ([]string, error) {
 	if p.RetentionDays < 0 || p.ScanIntervalMinutes < 0 || p.SettleMinutes < 0 {
 		return nil, errors.New("intervals must not be negative")
 	}
+	if p.ApproxThreshold == 0 {
+		p.ApproxThreshold = 85
+	}
+	if p.ApproxThreshold < 60 || p.ApproxThreshold > 100 {
+		return nil, errors.New("approximate match threshold must be between 60 and 100 percent")
+	}
 	if p.ScanIntervalMinutes > 0 && p.ScanIntervalMinutes < 5 {
 		return nil, errors.New("scan interval must be 0 (manual) or at least 5 minutes")
 	}

internal/engine/scan.go

@@ -104,11 +104,19 @@ type masterIndex struct {
 	lower   map[string]string   // lower(rel) -> rel
 	byDir   map[string][]string // lower(dir) -> rels
 	byTitle map[string][]string // lower(top folder)|normTitle -> rels
+
+	approx    *approxIndex // nil unless the pair enables approximate matching
+	threshold float64
 }
 
-func buildIndex(files map[string]fsops.Info) *masterIndex {
+func buildIndex(files map[string]fsops.Info, p store.Pair) *masterIndex {
 	ix := &masterIndex{files: files, lower: map[string]string{}, byDir: map[string][]string{}, byTitle: map[string][]string{}}
-	for _, rel := range sortedKeys(files) {
+	rels := sortedKeys(files)
+	if p.ApproxMatching {
+		ix.approx = buildApproxIndex(rels)
+		ix.threshold = float64(p.ApproxThreshold) / 100
+	}
+	for _, rel := range rels {
 		ix.lower[strings.ToLower(rel)] = rel
 		d := strings.ToLower(filepath.Dir(rel))
 		ix.byDir[d] = append(ix.byDir[d], rel)
@@ -130,13 +138,14 @@ func extRank(rel string) int {
 	return 2
 }
 
-// find locates the master counterpart of a slave file.
-func (ix *masterIndex) find(relSlave string) (string, string) {
+// find locates the master counterpart of a slave file. The reason is only
+// set for approximate matches.
+func (ix *masterIndex) find(relSlave string) (rel, kind, reason string) {
 	if _, ok := ix.files[relSlave]; ok {
-		return relSlave, store.KindPath
+		return relSlave, store.KindPath, ""
 	}
 	if r, ok := ix.lower[strings.ToLower(relSlave)]; ok {
-		return r, store.KindPathCase
+		return r, store.KindPathCase, ""
 	}
 	dir := strings.ToLower(filepath.Dir(relSlave))
 	base := filepath.Base(relSlave)
@@ -158,17 +167,25 @@ func (ix *masterIndex) find(relSlave string) (string, string) {
 				best = r
 			}
 		}
-		return best, store.KindExtension
+		return best, store.KindExtension, ""
 	}
 	if len(fuzzyHits) == 1 {
-		return fuzzyHits[0], store.KindFuzzy
+		return fuzzyHits[0], store.KindFuzzy, ""
+	}
+	// Approximate matching runs before the top-folder fallback because it
+	// searches the album (disc folders ignored) first, which resolves titles
+	// that appear on several albums.
+	if ix.approx != nil {
+		if r, why := ix.approx.find(relSlave, ix.threshold); r != "" {
+			return r, store.KindApprox, why
+		}
 	}
 	if top := firstComponent(relSlave); top != "" && norm != "" {
 		if hits := ix.byTitle[strings.ToLower(top)+"|"+norm]; len(hits) == 1 {
-			return hits[0], store.KindElsewhere
+			return hits[0], store.KindElsewhere, ""
 		}
 	}
-	return "", store.KindNone
+	return "", store.KindNone, ""
 }
 
 // classify fills in status, probes and verdict for a match, reusing cached
@@ -269,7 +286,7 @@ func (e *Engine) scan(ctx context.Context, j *Job, pairID int64, trigger string)
 		_ = e.st.FinishScan(ctx, pairID, started.Unix(), err.Error(), warns)
 		return err
 	}
-	ix := buildIndex(masterFiles)
+	ix := buildIndex(masterFiles, l.pair)
 	prev, err := e.st.AllMatches(ctx, pairID)
 	if err != nil {
 		return err
@@ -284,7 +301,7 @@ func (e *Engine) scan(ctx context.Context, j *Job, pairID int64, trigger string)
 		}
 		si := slaveFiles[rel]
 		m := store.Match{PairID: pairID, RelSlave: rel}
-		m.RelMaster, m.Kind = ix.find(rel)
+		m.RelMaster, m.Kind, m.Reason = ix.find(rel)
 		var pm *store.Match
 		if p, ok := prev[rel]; ok {
 			pm = &p
@@ -304,7 +321,7 @@ func (e *Engine) scan(ctx context.Context, j *Job, pairID int64, trigger string)
 
 	// Layout warnings based on what was actually found.
 	if ss.files > 0 {
-		if n := kinds[store.KindElsewhere] + kinds[store.KindNone]; n*4 > ss.files {
+		if n := kinds[store.KindElsewhere] + kinds[store.KindApprox] + kinds[store.KindNone]; n*4 > ss.files {
 			warns = append(warns, fmt.Sprintf("%d of %d slave files have no counterpart at the same path in the master library. "+
 				"Check that both libraries use the same folder layout.", n, ss.files))
 		}
@@ -426,7 +443,7 @@ func (e *Engine) refresh(ctx context.Context, l *libs, relSlave string) {
 		if pm != nil && pm.RelMaster != "" {
 			if in, err := fsops.RegularFile(filepath.Join(l.master.Path, pm.RelMaster)); err == nil {
 				mi = in
-				m.RelMaster, m.Kind = pm.RelMaster, pm.Kind
+				m.RelMaster, m.Kind, m.Reason = pm.RelMaster, pm.Kind, pm.Reason
 			}
 		}
 	}