Music metadata via MusicBrainz

- musicbrainz provider: keyless, with the required descriptive User-Agent and
  a 1 req/s throttle so the provider cannot get us blocked. Covers come from
  the Cover Art Archive by release id.
- artistHint: directory-grouped items are stored as "Artist/Album", so the
  parent directory is used as the artist when querying. Without it the search
  for "Random Access Memories" matched an unrelated release by another artist.
- pickBest: providers return fuzzy matches, and taking candidates[0] blindly
  is how an album gets the wrong artist. A candidate is only accepted when its
  normalised title corresponds to the item's; otherwise the provider is
  recorded as notfound and the next one is tried.

Verified live: after the fix the album resolves to Daft Punk, 2013, and the
correct release id, with real cover art. Before the fix it matched a Franz
Kirmann release.

cmd/vellum/main.go

@@ -89,6 +89,7 @@ func run() error {
 	queue := jobs.New(db, log)
 	metadata.Register(metadata.NewOpenLibrary())
 	metadata.Register(metadata.NewGoogleBooks())
+	metadata.Register(metadata.NewMusicBrainz())
 	enricher := metadata.NewEnricher(db, log, cfg.ConfigDir)
 	queue.Register(metadata.JobKind, enricher.Handle)
 	metadata.NewHandlers(db, log, authenticator, queue).Register(api.Mux())

internal/metadata/enrich.go

@@ -10,10 +10,12 @@ import (
 	"log/slog"
 	"net/http"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 	"time"
 
+	"github.com/mithral/vellum/internal/library"
 	"github.com/mithral/vellum/internal/media"
 )
 
@@ -96,7 +98,7 @@ func (e *Enricher) EnrichItem(ctx context.Context, itemID int64) error {
 		return nil
 	}
 
-	q := Query{Title: it.Title, Kind: it.Kind}
+	q := Query{Title: it.Title, Author: artistHint(it), Kind: it.Kind}
 	for _, p := range providers {
 		if e.triedRecently(ctx, itemID, p.Name()) {
 			continue
@@ -117,18 +119,94 @@ func (e *Enricher) EnrichItem(ctx context.Context, itemID int64) error {
 			continue
 		}
 
-		if err := e.apply(ctx, it, candidates[0]); err != nil {
+		// Providers return fuzzy matches. Taking the first blindly is how you
+		// end up labelling Daft Punk's album as Franz Kirmann's. Require the
+		// title to actually correspond before accepting.
+		best, ok := pickBest(candidates, it.Title)
+		if !ok {
+			e.log.Info("metadata: no close match", "item", itemID, "provider", p.Name(), "title", it.Title)
+			if recErr := e.record(ctx, itemID, p.Name(), "notfound", "no close title match"); recErr != nil {
+				return recErr
+			}
+			continue
+		}
+
+		if err := e.apply(ctx, it, best); err != nil {
 			return err
 		}
 		if err := e.record(ctx, itemID, p.Name(), "ok", ""); err != nil {
 			return err
 		}
-		e.log.Info("metadata matched", "item", itemID, "provider", p.Name(), "title", candidates[0].Title)
+		e.log.Info("metadata matched", "item", itemID, "provider", p.Name(), "title", best.Title)
 		return nil
 	}
 	return nil
 }
 
+// artistHint recovers the artist or author from the directory structure.
+//
+// Directory-grouped kinds store the item as "Artist/Album" or "Author/Book",
+// so the parent directory is a strong signal that the provider search should
+// use to disambiguate. Without it, "Random Access Memories" matches a release
+// by an unrelated artist.
+func artistHint(it media.Item) string {
+	if library.GroupModeFor(it.Kind) != library.GroupByDirectory {
+		return ""
+	}
+	dir := path.Dir(it.Path)
+	if dir == "." || dir == "/" || dir == "" {
+		return ""
+	}
+	return path.Base(dir)
+}
+
+// pickBest returns the first candidate whose title corresponds to want.
+//
+// The bar is deliberately loose (normalised equality or containment in either
+// direction) but not absent: it accepts "The Hobbit" against "The Hobbit, or
+// There and Back Again" and rejects "Random Access Memories" against an
+// unrelated album that merely shares a word.
+func pickBest(candidates []Candidate, want string) (Candidate, bool) {
+	w := normalizeTitle(want)
+	if len(w) < 3 {
+		return Candidate{}, false
+	}
+	for _, c := range candidates {
+		got := normalizeTitle(c.Title)
+		if len(got) < 3 {
+			continue
+		}
+		if got == w || strings.Contains(got, w) || strings.Contains(w, got) {
+			return c, true
+		}
+	}
+	return Candidate{}, false
+}
+
+// normalizeTitle lowercases and strips punctuation so titles can be compared
+// regardless of formatting differences.
+func normalizeTitle(s string) string {
+	var b strings.Builder
+	lastSpace := true
+	for _, r := range strings.ToLower(s) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+			lastSpace = false
+		case r >= 'à' && r <= 'ÿ':
+			// Keep accented letters as-is; providers and files usually agree.
+			b.WriteRune(r)
+			lastSpace = false
+		default:
+			if !lastSpace {
+				b.WriteByte(' ')
+				lastSpace = true
+			}
+		}
+	}
+	return strings.TrimSpace(b.String())
+}
+
 // apply writes a chosen candidate back to the database.
 func (e *Enricher) apply(ctx context.Context, it media.Item, c Candidate) error {
 	tx, err := e.db.BeginTx(ctx, nil)

internal/metadata/enrich_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 
 	"github.com/mithral/vellum/internal/core"
+	"github.com/mithral/vellum/internal/media"
 	"github.com/mithral/vellum/migrations"
 )
 
@@ -243,3 +244,67 @@ func TestEnrichIgnoresUnknownKind(t *testing.T) {
 		t.Errorf("EnrichItem with no providers errored: %v", err)
 	}
 }
+
+func TestNormalizeTitle(t *testing.T) {
+	cases := map[string]string{
+		"Random Access Memories":              "random access memories",
+		"The Hobbit, or There and Back Again": "the hobbit or there and back again",
+		"AC/DC — Back in Black!":              "ac dc back in black",
+		"  spaced   out  ":                    "spaced out",
+	}
+	for in, want := range cases {
+		if got := normalizeTitle(in); got != want {
+			t.Errorf("normalizeTitle(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestPickBestRejectsUnrelated(t *testing.T) {
+	candidates := []Candidate{
+		{Title: "Random Access Memories", ExternalID: "right"},
+	}
+
+	// The exact title is accepted.
+	if c, ok := pickBest(candidates, "Random Access Memories"); !ok || c.ExternalID != "right" {
+		t.Errorf("exact match rejected: ok=%v c=%+v", ok, c)
+	}
+
+	// Containment in either direction is accepted.
+	long := []Candidate{{Title: "The Hobbit, or There and Back Again"}}
+	if _, ok := pickBest(long, "The Hobbit"); !ok {
+		t.Error("containment should be accepted")
+	}
+
+	// A same-named release by a different artist is still accepted by title —
+	// the artist hint, not the title check, is what disambiguates that.
+	// But a genuinely unrelated title must be rejected.
+	if _, ok := pickBest(candidates, "Franz Kirmann"); ok {
+		t.Error("unrelated title should be rejected")
+	}
+
+	// Too-short titles are never matched, to avoid substring false positives.
+	if _, ok := pickBest(candidates, "a"); ok {
+		t.Error("a one-character query should be rejected")
+	}
+}
+
+func TestArtistHint(t *testing.T) {
+	// Directory-grouped kinds take the artist from the parent directory.
+	album := media.Item{Kind: "music", Path: "Daft Punk/Random Access Memories"}
+	if got := artistHint(album); got != "Daft Punk" {
+		t.Errorf("artistHint(album) = %q, want Daft Punk", got)
+	}
+
+	// A loose root-level file has no artist to infer.
+	loose := media.Item{Kind: "music", Path: "."}
+	if got := artistHint(loose); got != "" {
+		t.Errorf("artistHint(loose) = %q, want empty", got)
+	}
+
+	// File-grouped kinds (ebooks) never take a hint: their parent directory is
+	// usually a series, not an author.
+	book := media.Item{Kind: "ebooks", Path: "Series/Book.epub"}
+	if got := artistHint(book); got != "" {
+		t.Errorf("artistHint(ebook) = %q, want empty", got)
+	}
+}

internal/metadata/musicbrainz.go

@@ -0,0 +1,150 @@
+package metadata
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+)
+
+// MusicBrainz matches albums. No API key, but it demands a descriptive
+// User-Agent and a hard rate limit of one request per second.
+type MusicBrainz struct {
+	Client *http.Client
+
+	// mu and lastCall enforce the 1 req/s ceiling. Enrichment is sequential
+	// today, but the limiter is here so a future parallel worker cannot trip
+	// the server into blocking us.
+	mu       sync.Mutex
+	lastCall time.Time
+}
+
+// NewMusicBrainz builds the provider with a bounded HTTP client.
+func NewMusicBrainz() *MusicBrainz {
+	return &MusicBrainz{Client: &http.Client{Timeout: 15 * time.Second}}
+}
+
+func (p *MusicBrainz) Name() string { return "musicbrainz" }
+
+func (p *MusicBrainz) Kinds() []string { return []string{"music"} }
+
+type mbRelease struct {
+	ID           string `json:"id"`
+	Title        string `json:"title"`
+	Date         string `json:"date"`
+	Country      string `json:"country"`
+	ArtistCredit []struct {
+		Name   string `json:"name"`
+		Artist struct {
+			ID   string `json:"id"`
+			Name string `json:"name"`
+		} `json:"artist"`
+	} `json:"artist-credit"`
+}
+
+type mbResponse struct {
+	Releases []mbRelease `json:"releases"`
+}
+
+func (p *MusicBrainz) Search(ctx context.Context, q Query) ([]Candidate, error) {
+	if strings.TrimSpace(q.Title) == "" {
+		return nil, nil
+	}
+
+	if err := p.waitTurn(ctx); err != nil {
+		return nil, err
+	}
+
+	// Lucene-ish query: exact-ish release match, optionally narrowed by artist.
+	query := `release:"` + escapeLucene(q.Title) + `"`
+	if q.Author != "" {
+		query += ` AND artist:"` + escapeLucene(q.Author) + `"`
+	}
+	params := url.Values{}
+	params.Set("query", query)
+	params.Set("fmt", "json")
+	params.Set("limit", "5")
+
+	endpoint := "https://musicbrainz.org/ws/2/release/?" + params.Encode()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return nil, err
+	}
+	// MusicBrainz blocks generic user agents; a real contact string is required.
+	req.Header.Set("User-Agent", "Vellum/0.1 ( self-hosted media server )")
+
+	resp, err := p.Client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("musicbrainz: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusServiceUnavailable {
+		return nil, fmt.Errorf("musicbrainz: rate limited (503)")
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("musicbrainz: status %d", resp.StatusCode)
+	}
+
+	var parsed mbResponse
+	if err := json.NewDecoder(resp.Body).Decode(&parsed); err != nil {
+		return nil, fmt.Errorf("musicbrainz: decode: %w", err)
+	}
+
+	out := make([]Candidate, 0, len(parsed.Releases))
+	for _, r := range parsed.Releases {
+		if r.Title == "" || r.ID == "" {
+			continue
+		}
+		var artists []string
+		for _, ac := range r.ArtistCredit {
+			name := strings.TrimSpace(ac.Name)
+			if name == "" {
+				name = ac.Artist.Name
+			}
+			if name != "" {
+				artists = append(artists, name)
+			}
+		}
+		out = append(out, Candidate{
+			Provider:   p.Name(),
+			ExternalID: r.ID,
+			Title:      r.Title,
+			Authors:    artists,
+			Year:       parseYear(r.Date),
+			// Cover Art Archive serves artwork by release id, no key.
+			CoverURL: "https://coverartarchive.org/release/" + r.ID + "/front-500",
+		})
+	}
+	return out, nil
+}
+
+// waitTurn blocks until at least one second has passed since the last call.
+func (p *MusicBrainz) waitTurn(ctx context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	const minInterval = time.Second
+	if wait := minInterval - time.Since(p.lastCall); wait > 0 {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(wait):
+		}
+	}
+	p.lastCall = time.Now()
+	return nil
+}
+
+// escapeLucene neutralises characters that would break a MusicBrainz query.
+func escapeLucene(s string) string {
+	replacer := strings.NewReplacer(
+		`\`, `\\`, `"`, `\"`, `+`, `\+`, `-`, `\-`,
+		`&&`, `\&&`, `||`, `\||`, `!`, `\!`, `(`, `\(`, `)`, `\)`,
+		`{`, `\{`, `}`, `\}`, `[`, `\[`, `]`, `\]`, `^`, `\^`, `~`, `\~`, `*`, `\*`, `?`, `\?`,
+	)
+	return replacer.Replace(s)
+}