cmd/minstrel/main.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/jackc/pgx/v5/pgxpool"
 
+	"git.fabledsword.com/bvandeusen/minstrel/internal/acoustid"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/config"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/coplay"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
@@ -139,6 +140,15 @@ func run() error {
 		logger.Warn("loudness settings: using defaults", "err", loudErr)
 	}
 
+	// AcoustID lookup settings (M401): shared by the lookup worker and the
+	// admin API. A load failure leaves the lookup off.
+	acoustIDSettings, acoustIDErr := library.NewAcoustIDSettingsService(ctx, pool)
+	if acoustIDErr != nil {
+		logger.Warn("acoustid settings: using defaults (lookup off)", "err", acoustIDErr)
+	}
+	acoustIDLookup := library.NewAcoustIDLookupWorker(pool, logger.With("component", "acoustid_lookup"),
+		acoustIDSettings, acoustid.New(acoustid.DefaultBaseURL))
+
 	contact := cfg.Library.ContactEmail
 	if contact == "" {
 		contact = "https://git.fabledsword.com/bvandeusen/minstrel"
@@ -240,6 +250,11 @@ func run() error {
 	// measurement. See internal/library/loudness_backfill.go.
 	go library.NewLoudnessBackfillWorker(pool, logger.With("component", "loudness_backfill"), loudSettings).Run(ctx)
 
+	// AcoustID lookup (M401): fills the recording MBIDs untagged tracks lack,
+	// so the similarity arms can see them. Idle until the operator adds a key
+	// and switches it on. See internal/library/acoustid_lookup.go.
+	go acoustIDLookup.Run(ctx)
+
 	// Duplicate sweep (M400 #3910): proposes groups of tracks holding one
 	// recording, from the fingerprints above. Sweeps only when fingerprints have
 	// changed since the last sweep.
@@ -390,6 +405,7 @@ func run() error {
 	srv.TagSettings = tagSettings
 	srv.FingerprintSettings = fpSettings
 	srv.LoudnessSettings = loudSettings
+	srv.AcoustIDLookup = acoustIDLookup
 	// The sweeper above holds this same instance, so a save from the admin
 	// card changes what it does on its next tick (#3936).
 	srv.ReacqSettings = reacqSettings

internal/acoustid/client.go

@@ -0,0 +1,267 @@
+// Package acoustid looks up MusicBrainz recording ids by acoustic fingerprint
+// through the AcoustID web service (M401).
+//
+// What it relies on, from https://acoustid.org/webservice (read 2026-10-06):
+//   - POST https://api.acoustid.org/v2/lookup with client, duration (whole
+//     seconds), fingerprint (fpcalc's compressed string) and meta. A gzip body
+//     with Content-Encoding: gzip is accepted and preferred, because
+//     fingerprints are long.
+//   - meta=recordings returns each recording's title, duration and artists,
+//     which the worker needs to tell several candidates apart (M401 D5).
+//   - "Do not make more than 3 requests per second."
+//   - The service is free for non-commercial use only.
+//
+// Error codes are the server's own, from acoustid-server's
+// acoustid/api/errors.py.
+package acoustid
+
+import (
+	"bytes"
+	"cmp"
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"slices"
+	"strconv"
+	"sync"
+	"time"
+)
+
+// DefaultBaseURL is the lookup endpoint.
+const DefaultBaseURL = "https://api.acoustid.org/v2/lookup"
+
+const (
+	// minInterval keeps to AcoustID's 3 requests a second with headroom: one
+	// every 400ms is 2.5 a second.
+	minInterval = 400 * time.Millisecond
+	// lookupTimeout bounds one request, connection included (rule 156). A
+	// lookup answers in well under a second; 20s is the line past which slow
+	// has become never.
+	lookupTimeout = 20 * time.Second
+	// bodyLimit caps the response read. A lookup with meta=recordings for a
+	// popular song runs to tens of kilobytes.
+	bodyLimit = 2 << 20
+	userAgent = "Minstrel ( https://git.fabledsword.com/bvandeusen/minstrel )"
+)
+
+// The server's error codes that the worker treats differently.
+const (
+	codeInvalidFingerprint = 3
+	codeInvalidAPIKey      = 4
+	codeServiceUnavailable = 13
+	codeTooManyRequests    = 14
+	codeUnknownApplication = 17
+)
+
+var (
+	// ErrInvalidKey: the operator's application key was refused. No lookup
+	// can succeed until it is changed, so the worker stops and says so.
+	ErrInvalidKey = errors.New("acoustid: the API key was refused")
+	// ErrInvalidFingerprint: AcoustID rejected this track's fingerprint. A
+	// verdict on the track, not on the service.
+	ErrInvalidFingerprint = errors.New("acoustid: the fingerprint was rejected")
+	// ErrUnavailable: the service could not answer now (unreachable, timed
+	// out, overloaded or rate limiting). Says nothing about the track, so the
+	// lookup is tried again later.
+	ErrUnavailable = errors.New("acoustid: the service is unavailable")
+)
+
+// Recording is one MusicBrainz recording a fingerprint matched.
+type Recording struct {
+	ID    string
+	Title string
+	// DurationSec is MusicBrainz's length for the recording; 0 when unknown.
+	DurationSec int
+	Artists     []string
+}
+
+// Candidate is a recording with the score of the best AcoustID result that
+// linked to it.
+type Candidate struct {
+	Recording
+	Score float64
+}
+
+// Client calls the lookup endpoint, at most one request per minInterval.
+type Client struct {
+	baseURL string
+	http    *http.Client
+
+	mu       sync.Mutex
+	lastCall time.Time
+}
+
+// New returns a client for baseURL (DefaultBaseURL in production).
+func New(baseURL string) *Client {
+	return &Client{baseURL: baseURL, http: &http.Client{Timeout: lookupTimeout}}
+}
+
+// Lookup asks which recordings match fingerprint, a compressed chromaprint
+// of audio durationSec long. It returns every candidate, best score first;
+// choosing among them is the caller's job. No match is an empty slice and
+// no error.
+func (c *Client) Lookup(ctx context.Context, apiKey, fingerprint string, durationSec int) ([]Candidate, error) {
+	if err := c.wait(ctx); err != nil {
+		return nil, err
+	}
+	body, err := gzipForm(url.Values{
+		"client":      {apiKey},
+		"duration":    {strconv.Itoa(durationSec)},
+		"fingerprint": {fingerprint},
+		"meta":        {"recordings"},
+		"format":      {"json"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	reqCtx, cancel := context.WithTimeout(ctx, lookupTimeout)
+	defer cancel()
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.baseURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("acoustid: build request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Content-Encoding", "gzip")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", userAgent)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		// The caller giving up is not the service failing.
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+		return nil, fmt.Errorf("%w: %v", ErrUnavailable, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, bodyLimit))
+	if err != nil {
+		return nil, fmt.Errorf("%w: read body: %v", ErrUnavailable, err)
+	}
+	return parseLookup(resp.StatusCode, raw)
+}
+
+// wait blocks until minInterval has passed since the last request, then
+// claims the slot.
+func (c *Client) wait(ctx context.Context) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if d := time.Until(c.lastCall.Add(minInterval)); d > 0 {
+		t := time.NewTimer(d)
+		defer t.Stop()
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-t.C:
+		}
+	}
+	c.lastCall = time.Now()
+	return nil
+}
+
+func gzipForm(v url.Values) ([]byte, error) {
+	var buf bytes.Buffer
+	zw := gzip.NewWriter(&buf)
+	if _, err := zw.Write([]byte(v.Encode())); err != nil {
+		return nil, fmt.Errorf("acoustid: compress request: %w", err)
+	}
+	if err := zw.Close(); err != nil {
+		return nil, fmt.Errorf("acoustid: compress request: %w", err)
+	}
+	return buf.Bytes(), nil
+}
+
+type lookupResponse struct {
+	Status string `json:"status"`
+	Error  *struct {
+		Code    int    `json:"code"`
+		Message string `json:"message"`
+	} `json:"error"`
+	Results []struct {
+		ID         string  `json:"id"`
+		Score      float64 `json:"score"`
+		Recordings []struct {
+			ID       string  `json:"id"`
+			Title    string  `json:"title"`
+			Duration float64 `json:"duration"`
+			Artists  []struct {
+				Name string `json:"name"`
+			} `json:"artists"`
+		} `json:"recordings"`
+	} `json:"results"`
+}
+
+// parseLookup reads a lookup response. AcoustID reports its errors in the
+// body with a code, alongside a 4xx or 5xx status, so the body is read first
+// and the status only decides when the body says nothing usable.
+func parseLookup(status int, raw []byte) ([]Candidate, error) {
+	var r lookupResponse
+	if err := json.Unmarshal(raw, &r); err != nil {
+		if status != http.StatusOK {
+			return nil, fmt.Errorf("%w: status %d", ErrUnavailable, status)
+		}
+		return nil, fmt.Errorf("%w: unreadable response: %v", ErrUnavailable, err)
+	}
+	if r.Status != "ok" {
+		return nil, lookupError(status, r)
+	}
+	return candidates(r), nil
+}
+
+func lookupError(status int, r lookupResponse) error {
+	if r.Error == nil {
+		return fmt.Errorf("%w: status %d", ErrUnavailable, status)
+	}
+	switch r.Error.Code {
+	case codeInvalidAPIKey, codeUnknownApplication:
+		return fmt.Errorf("%w: %s", ErrInvalidKey, r.Error.Message)
+	case codeInvalidFingerprint:
+		return fmt.Errorf("%w: %s", ErrInvalidFingerprint, r.Error.Message)
+	case codeServiceUnavailable, codeTooManyRequests:
+		return fmt.Errorf("%w: %s", ErrUnavailable, r.Error.Message)
+	}
+	if status >= http.StatusInternalServerError {
+		return fmt.Errorf("%w: %s", ErrUnavailable, r.Error.Message)
+	}
+	// Any other code is a request this client built wrongly. Retrying would
+	// repeat it, so it is named rather than folded into unavailable.
+	return fmt.Errorf("acoustid: error %d: %s", r.Error.Code, r.Error.Message)
+}
+
+// candidates flattens the results into one entry per recording. The same
+// recording can hang off several AcoustID results (one audio, fingerprinted
+// from different sources); it keeps the best score it was seen with.
+// Results with no linked recording are fingerprints AcoustID knows but nobody
+// has tied to MusicBrainz, and carry nothing to fill.
+func candidates(r lookupResponse) []Candidate {
+	out := []Candidate{}
+	at := map[string]int{}
+	for _, res := range r.Results {
+		for _, rec := range res.Recordings {
+			if rec.ID == "" {
+				continue
+			}
+			if i, ok := at[rec.ID]; ok {
+				out[i].Score = max(out[i].Score, res.Score)
+				continue
+			}
+			c := Candidate{
+				Recording: Recording{ID: rec.ID, Title: rec.Title, DurationSec: int(rec.Duration + 0.5)},
+				Score:     res.Score,
+			}
+			for _, a := range rec.Artists {
+				c.Artists = append(c.Artists, a.Name)
+			}
+			at[rec.ID] = len(out)
+			out = append(out, c)
+		}
+	}
+	// Best first, keeping AcoustID's order among equals.
+	slices.SortStableFunc(out, func(a, b Candidate) int { return cmp.Compare(b.Score, a.Score) })
+	return out
+}

internal/acoustid/client_test.go

@@ -0,0 +1,220 @@
+package acoustid
+
+import (
+	"compress/gzip"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+)
+
+// docSample is the meta=recordings response printed in AcoustID's own
+// documentation (https://acoustid.org/webservice), artists and release groups
+// as given.
+const docSample = `{
+  "status": "ok",
+  "results": [{
+    "score": 1.0,
+    "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
+    "recordings": [{
+      "duration": 639,
+      "releasegroups": [{"type": "Album", "id": "ddaa2d4d-314e-3e7c-b1d0-f6d207f5aa2f", "title": "Before the Dawn Heals Us"}],
+      "title": "Lower Your Eyelids to Die With the Sun",
+      "id": "cd2e7c47-16f5-46c6-a37c-a1eb7bf599ff",
+      "artists": [{"id": "6d7b7cd4-254b-4c25-83f6-dd20f98ceacd", "name": "M83"}]
+    }]
+  }]
+}`
+
+// severalSample is the shape the worker has to disambiguate: one audio linked
+// to two recordings (an album and a single release), the album recording
+// reached again through a weaker second result, and a third result that
+// AcoustID knows but nobody has tied to MusicBrainz.
+const severalSample = `{
+  "status": "ok",
+  "results": [
+    {"score": 0.71, "id": "a2", "recordings": [{"id": "rec-album", "title": "Song", "duration": 200.4}]},
+    {"score": 0.93, "id": "a1", "recordings": [
+      {"id": "rec-album", "title": "Song", "duration": 200.4, "artists": [{"name": "A"}, {"name": "B"}]},
+      {"id": "rec-single", "title": "Song (radio edit)", "duration": 181}
+    ]},
+    {"score": 0.88, "id": "a3"}
+  ]
+}`
+
+func TestParseLookup(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+		want []Candidate
+	}{
+		{"single match", docSample, []Candidate{{
+			Recording: Recording{
+				ID: "cd2e7c47-16f5-46c6-a37c-a1eb7bf599ff", Title: "Lower Your Eyelids to Die With the Sun",
+				DurationSec: 639, Artists: []string{"M83"},
+			},
+			Score: 1.0,
+		}}},
+		{"several recordings", severalSample, []Candidate{
+			{Recording: Recording{ID: "rec-album", Title: "Song", DurationSec: 200}, Score: 0.93},
+			{Recording: Recording{ID: "rec-single", Title: "Song (radio edit)", DurationSec: 181}, Score: 0.93},
+		}},
+		// Choosing a threshold is the worker's; the parser carries the score.
+		{"below threshold", `{"status":"ok","results":[{"score":0.31,"id":"x","recordings":[{"id":"rec"}]}]}`,
+			[]Candidate{{Recording: Recording{ID: "rec"}, Score: 0.31}}},
+		{"no results", `{"status":"ok","results":[]}`, []Candidate{}},
+		{"results with no recordings", `{"status":"ok","results":[{"score":0.99,"id":"x"}]}`, []Candidate{}},
+	}
+	for _, c := range cases {
+		got, err := parseLookup(http.StatusOK, []byte(c.body))
+		if err != nil {
+			t.Errorf("%s: err = %v", c.name, err)
+			continue
+		}
+		if !sameCandidates(got, c.want) {
+			t.Errorf("%s:\n got %+v\nwant %+v", c.name, got, c.want)
+		}
+	}
+}
+
+// The first result's recording is the album one with both artists; the
+// weaker repeat must not replace its fields, only fail to lower its score.
+func TestParseLookup_RepeatedRecordingKeepsBestScoreAndFirstFields(t *testing.T) {
+	got, err := parseLookup(http.StatusOK, []byte(severalSample))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got[0].ID != "rec-album" || got[0].Score != 0.93 {
+		t.Errorf("album recording = %+v, want score 0.93", got[0])
+	}
+}
+
+func TestParseLookup_Errors(t *testing.T) {
+	cases := []struct {
+		name   string
+		status int
+		body   string
+		want   error
+	}{
+		{"invalid key", 400, `{"status":"error","error":{"code":4,"message":"invalid API key"}}`, ErrInvalidKey},
+		{"unknown application", 400, `{"status":"error","error":{"code":17,"message":"unknown application"}}`, ErrInvalidKey},
+		{"bad fingerprint", 400, `{"status":"error","error":{"code":3,"message":"invalid fingerprint"}}`, ErrInvalidFingerprint},
+		{"rate limited", 429, `{"status":"error","error":{"code":14,"message":"rate limit (3.000000 requests per second) exceeded, try again later"}}`, ErrUnavailable},
+		{"down", 503, `{"status":"error","error":{"code":13,"message":"service currently unavailable, try again later"}}`, ErrUnavailable},
+		{"internal error", 500, `{"status":"error","error":{"code":5,"message":"internal error"}}`, ErrUnavailable},
+		{"proxy page", 502, `<html>Bad Gateway</html>`, ErrUnavailable},
+	}
+	for _, c := range cases {
+		_, err := parseLookup(c.status, []byte(c.body))
+		if !errors.Is(err, c.want) {
+			t.Errorf("%s: err = %v, want %v", c.name, err, c.want)
+		}
+	}
+
+	// A code this client caused (here a missing parameter) is neither the
+	// key nor the service, so it must not read as either: retrying repeats it.
+	_, err := parseLookup(400, []byte(`{"status":"error","error":{"code":2,"message":"missing required parameter \"fingerprint\""}}`))
+	if err == nil || errors.Is(err, ErrUnavailable) || errors.Is(err, ErrInvalidKey) || !strings.Contains(err.Error(), "missing required parameter") {
+		t.Errorf("missing parameter: err = %v", err)
+	}
+}
+
+// The request is what AcoustID documents: a gzip form POST carrying the key,
+// whole-second duration, fingerprint and meta=recordings.
+func TestLookup_SendsACompressedForm(t *testing.T) {
+	var form url.Values
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost || r.Header.Get("Content-Encoding") != "gzip" {
+			t.Errorf("request %s with Content-Encoding %q, want a gzip POST", r.Method, r.Header.Get("Content-Encoding"))
+		}
+		zr, err := gzip.NewReader(r.Body)
+		if err != nil {
+			t.Fatalf("body is not gzip: %v", err)
+		}
+		raw, _ := io.ReadAll(zr)
+		form, _ = url.ParseQuery(string(raw))
+		_, _ = io.WriteString(w, docSample)
+	}))
+	defer srv.Close()
+
+	got, err := New(srv.URL).Lookup(context.Background(), "key123", "AQADtE", 241)
+	if err != nil || len(got) != 1 {
+		t.Fatalf("Lookup = %+v, %v", got, err)
+	}
+	for k, want := range map[string]string{
+		"client": "key123", "duration": "241", "fingerprint": "AQADtE", "meta": "recordings", "format": "json",
+	} {
+		if form.Get(k) != want {
+			t.Errorf("form %s = %q, want %q", k, form.Get(k), want)
+		}
+	}
+}
+
+func TestLookup_DeadlineIsUnavailable(t *testing.T) {
+	release := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { <-release }))
+	defer srv.Close()
+	defer close(release)
+
+	c := New(srv.URL)
+	c.http.Timeout = 50 * time.Millisecond
+	_, err := c.Lookup(context.Background(), "k", "f", 1)
+	if !errors.Is(err, ErrUnavailable) {
+		t.Errorf("err = %v, want ErrUnavailable", err)
+	}
+}
+
+// A cancelled caller is reported as such, never as the service being down.
+func TestLookup_CancelledCallerIsNotUnavailable(t *testing.T) {
+	release := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { <-release }))
+	defer srv.Close()
+	defer close(release)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	_, err := New(srv.URL).Lookup(ctx, "k", "f", 1)
+	if !errors.Is(err, context.DeadlineExceeded) || errors.Is(err, ErrUnavailable) {
+		t.Errorf("err = %v, want the caller's own deadline", err)
+	}
+}
+
+func TestLookup_KeepsToTheRateLimit(t *testing.T) {
+	var at []time.Time
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		at = append(at, time.Now())
+		_, _ = io.WriteString(w, `{"status":"ok","results":[]}`)
+	}))
+	defer srv.Close()
+
+	c := New(srv.URL)
+	for range 3 {
+		if _, err := c.Lookup(context.Background(), "k", "f", 1); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for i := 1; i < len(at); i++ {
+		// A little slack for the server's own clock reading.
+		if gap := at[i].Sub(at[i-1]); gap < minInterval-10*time.Millisecond {
+			t.Errorf("requests %d and %d were %s apart, want at least %s", i-1, i, gap, minInterval)
+		}
+	}
+}
+
+func sameCandidates(a, b []Candidate) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i].ID != b[i].ID || a[i].Title != b[i].Title || a[i].DurationSec != b[i].DurationSec ||
+			a[i].Score != b[i].Score || strings.Join(a[i].Artists, "|") != strings.Join(b[i].Artists, "|") {
+			return false
+		}
+	}
+	return true
+}

internal/api/admin_acoustid.go

@@ -0,0 +1,171 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
+)
+
+// AcoustID recording-id lookup, admin side (M401 #3922).
+
+// acoustIDUnsettledLimit caps the admin list of tracks a lookup could not
+// settle. It is a list to read, not to page through.
+const acoustIDUnsettledLimit = 200
+
+// acoustIDSettingsResp never carries the key, only whether one is stored.
+type acoustIDSettingsResp struct {
+	Enabled   bool    `json:"enabled"`
+	MinScore  float32 `json:"min_score"`
+	APIKeySet bool    `json:"api_key_set"`
+}
+
+func acoustIDSettingsRespOf(s library.AcoustIDSettings) acoustIDSettingsResp {
+	return acoustIDSettingsResp{Enabled: s.Enabled, MinScore: s.MinScore, APIKeySet: s.APIKey != ""}
+}
+
+type acoustIDStatusResp struct {
+	Running    bool       `json:"running"`
+	LastPassAt *time.Time `json:"last_pass_at"`
+	// Problem is why the last pass stopped short, in words for the card.
+	Problem string `json:"problem"`
+}
+
+// acoustIDCoverageResp: from_tag + from_acoustid + the tracks with no MBID =
+// total. ambiguous, no_match and failed are lookup states of tracks with no
+// MBID; pending is what the worker still has to look at.
+type acoustIDCoverageResp struct {
+	Total        int64 `json:"total"`
+	FromTag      int64 `json:"from_tag"`
+	FromAcoustID int64 `json:"from_acoustid"`
+	Ambiguous    int64 `json:"ambiguous"`
+	NoMatch      int64 `json:"no_match"`
+	Failed       int64 `json:"failed"`
+	Pending      int64 `json:"pending"`
+}
+
+type acoustIDResp struct {
+	Settings acoustIDSettingsResp `json:"settings"`
+	// Ready is whether the worker will call AcoustID at all: switched on
+	// and holding a key.
+	Ready    bool                 `json:"ready"`
+	Status   acoustIDStatusResp   `json:"status"`
+	Coverage acoustIDCoverageResp `json:"coverage"`
+}
+
+// handleGetAcoustID implements GET /api/admin/library/acoustid: the settings,
+// what the worker is doing, and how much of the library has an MBID by source.
+func (h *handlers) handleGetAcoustID(w http.ResponseWriter, r *http.Request) {
+	row, err := library.AcoustIDCoverage(r.Context(), h.pool)
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin: get acoustid coverage", apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	cfg := h.acoustIDLookup.Settings().Get()
+	st := h.acoustIDLookup.Status()
+	resp := acoustIDResp{
+		Settings: acoustIDSettingsRespOf(cfg),
+		Ready:    cfg.Ready(),
+		Status:   acoustIDStatusResp{Running: st.Running, Problem: st.Problem},
+		Coverage: acoustIDCoverageResp{
+			Total:        row.Total,
+			FromTag:      row.FromTag,
+			FromAcoustID: row.FromAcoustid,
+			Ambiguous:    row.Ambiguous,
+			NoMatch:      row.NoMatch,
+			Failed:       row.Failed,
+			Pending:      row.Pending,
+		},
+	}
+	if !st.LastPassAt.IsZero() {
+		at := st.LastPassAt.UTC()
+		resp.Status.LastPassAt = &at
+	}
+	writeJSON(w, http.StatusOK, resp)
+}
+
+// acoustIDSettingsReq is the PUT body. api_key left out keeps the stored key;
+// an empty string clears it.
+type acoustIDSettingsReq struct {
+	Enabled  bool    `json:"enabled"`
+	MinScore float32 `json:"min_score"`
+	APIKey   *string `json:"api_key"`
+}
+
+// handleUpdateAcoustIDSettings implements PUT /api/admin/library/acoustid-settings.
+func (h *handlers) handleUpdateAcoustIDSettings(w http.ResponseWriter, r *http.Request) {
+	var req acoustIDSettingsReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeErr(w, apierror.BadRequest("invalid_body", "malformed JSON"))
+		return
+	}
+	saved, err := h.acoustIDLookup.Settings().Set(r.Context(), library.AcoustIDSettingsUpdate{
+		Enabled: req.Enabled, MinScore: req.MinScore, APIKey: req.APIKey,
+	})
+	if err != nil {
+		if errors.Is(err, library.ErrAcoustIDSettingOutOfRange) {
+			writeErr(w, apierror.BadRequest("invalid_setting", err.Error()))
+			return
+		}
+		writeErrWithLog(w, h.logger, "admin acoustid settings: update failed", apierror.Internal(err))
+		return
+	}
+	writeJSON(w, http.StatusOK, acoustIDSettingsRespOf(saved))
+}
+
+// handleRunAcoustIDLookup implements POST /api/admin/library/acoustid/run:
+// start a pass now rather than at the next tick. 409 when the lookup is off
+// or has no key, so the card can say so rather than appear to do nothing.
+func (h *handlers) handleRunAcoustIDLookup(w http.ResponseWriter, _ *http.Request) {
+	if !h.acoustIDLookup.Settings().Get().Ready() {
+		writeErr(w, apierror.Conflict("not_ready",
+			"Switch the AcoustID lookup on and add an API key first."))
+		return
+	}
+	h.acoustIDLookup.Kick()
+	w.WriteHeader(http.StatusAccepted)
+}
+
+type acoustIDUnsettledResp struct {
+	TrackID    string    `json:"track_id"`
+	Title      string    `json:"title"`
+	Artist     string    `json:"artist"`
+	Album      string    `json:"album"`
+	FilePath   string    `json:"file_path"`
+	State      string    `json:"state"`
+	BestScore  *float32  `json:"best_score"`
+	Candidates int32     `json:"candidates"`
+	Detail     *string   `json:"detail"`
+	LookedUpAt time.Time `json:"looked_up_at"`
+}
+
+// handleListUnsettledAcoustID implements GET /api/admin/library/acoustid/unsettled:
+// the tracks a lookup could not settle (ambiguous or failed), so they can be
+// found and tagged by hand.
+func (h *handlers) handleListUnsettledAcoustID(w http.ResponseWriter, r *http.Request) {
+	rows, err := dbq.New(h.pool).ListUnsettledAcoustIDLookups(r.Context(), acoustIDUnsettledLimit)
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin: list unsettled acoustid lookups", apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	out := make([]acoustIDUnsettledResp, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, acoustIDUnsettledResp{
+			TrackID:    uuidToString(row.ID),
+			Title:      row.Title,
+			Artist:     row.ArtistName,
+			Album:      row.AlbumTitle,
+			FilePath:   row.FilePath,
+			State:      row.State,
+			BestScore:  row.BestScore,
+			Candidates: row.Candidates,
+			Detail:     row.Detail,
+			LookedUpAt: row.LookedUpAt.Time.UTC(),
+		})
+	}
+	writeJSON(w, http.StatusOK, out)
+}

internal/api/api.go

@@ -35,7 +35,7 @@ import (
 // Mount attaches /api/* handlers to r. Public endpoints (login) are outside
 // RequireUser; everything else is gated by the middleware. The events writer
 // is shared with the Subsonic mount so /rest/scrobble feeds the same store.
-func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, tagSettings *tags.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte, netSettings *netsettings.Service, reacqSettings *reacquisition.SettingsService, fpSettings *library.FingerprintSettingsService, loudSettings *library.LoudnessSettingsService) {
+func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, tagSettings *tags.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte, netSettings *netsettings.Service, reacqSettings *reacquisition.SettingsService, fpSettings *library.FingerprintSettingsService, loudSettings *library.LoudnessSettingsService, acoustIDLookup *library.AcoustIDLookupWorker) {
 	rng := rand.New(rand.NewSource(rand.Int63()))
 	setupToken, err := auth.NewSetupToken()
 	if err != nil {
@@ -67,6 +67,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		reacqSettings:       reacqSettings,
 		fingerprintSettings: fpSettings,
 		loudnessSettings:    loudSettings,
+		acoustIDLookup:      acoustIDLookup,
 		leveled:             newLeveledRenderer(dataDir, loudSettings, logger),
 		librarySize:         recommendation.NewLibrarySize(nil),
 		loginGuard:          auth.NewLoginGuard(),
@@ -251,6 +252,10 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Get("/library/loudness", h.handleGetLoudnessCoverage)
 				admin.Get("/library/loudness-settings", h.handleGetLoudnessSettings)
 				admin.Put("/library/loudness-settings", h.handleUpdateLoudnessSettings)
+				admin.Get("/library/acoustid", h.handleGetAcoustID)
+				admin.Put("/library/acoustid-settings", h.handleUpdateAcoustIDSettings)
+				admin.Post("/library/acoustid/run", h.handleRunAcoustIDLookup)
+				admin.Get("/library/acoustid/unsettled", h.handleListUnsettledAcoustID)
 				// Duplicates report (#3912): proposals from the duplicate sweep, a
 				// trigger to sweep now, dismissal, and the merge (#3911), which deletes
 				// the removed copies' files after moving their history onto the kept one.
@@ -348,6 +353,9 @@ type handlers struct {
 	// loudnessSettings is the loudness analysis policy (M464 #4995), the same
 	// instance the loudness backfill reads. Nil serves the defaults.
 	loudnessSettings *library.LoudnessSettingsService
+	// acoustIDLookup is the AcoustID lookup worker (M401): its settings, its
+	// status and "look up now". Nil serves the defaults (off).
+	acoustIDLookup *library.AcoustIDLookupWorker
 	// leveled renders the leveled streams handed to Sonos/UPnP speakers
 	// (M464 #5001). Nil when its cache directory cannot be made: a level
 	// request then gets the plain stream.

internal/api/library_test.go

@@ -465,7 +465,7 @@ func TestRoutesRegisteredInMount(t *testing.T) {
 	r := chi.NewRouter()
 	w := playevents.NewWriter(h.pool, slog.New(slog.NewTextHandler(io.Discard, nil)),
 		30*time.Minute, 0.5, 30000)
-	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.tagSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil, h.netSettings, nil, nil, nil)
+	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.tagSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil, h.netSettings, nil, nil, nil, nil)
 
 	paths := []string{
 		"/api/artists",

internal/db/dbq/acoustid.sql.go

@@ -0,0 +1,309 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: acoustid.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const clearTrackAcoustIDMbid = `-- name: ClearTrackAcoustIDMbid :exec
+UPDATE tracks
+   SET mbid = NULL, mbid_source = NULL
+ WHERE id = $1
+   AND mbid_source = 'acoustid'
+`
+
+// A re-lookup of changed bytes that no longer matches takes back the id an
+// earlier lookup wrote. A tag id is never touched.
+func (q *Queries) ClearTrackAcoustIDMbid(ctx context.Context, id pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, clearTrackAcoustIDMbid, id)
+	return err
+}
+
+const deleteAcoustIDLookup = `-- name: DeleteAcoustIDLookup :exec
+DELETE FROM track_acoustid_lookups WHERE track_id = $1
+`
+
+// The scan drops the lookup of bytes that are gone, so the worker checks the
+// new ones.
+func (q *Queries) DeleteAcoustIDLookup(ctx context.Context, trackID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteAcoustIDLookup, trackID)
+	return err
+}
+
+const getAcoustIDSettings = `-- name: GetAcoustIDSettings :one
+SELECT id, enabled, api_key, min_score, updated_at FROM acoustid_settings WHERE id = true
+`
+
+func (q *Queries) GetAcoustIDSettings(ctx context.Context) (AcoustidSetting, error) {
+	row := q.db.QueryRow(ctx, getAcoustIDSettings)
+	var i AcoustidSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ApiKey,
+		&i.MinScore,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getMbidCoverage = `-- name: GetMbidCoverage :one
+SELECT count(*)::bigint AS total,
+       count(*) FILTER (WHERE t.mbid_source = 'tag')::bigint AS from_tag,
+       count(*) FILTER (WHERE t.mbid_source = 'acoustid')::bigint AS from_acoustid,
+       count(*) FILTER (WHERE l.state = 'ambiguous')::bigint AS ambiguous,
+       count(*) FILTER (WHERE l.state = 'no_match')::bigint AS no_match,
+       count(*) FILTER (WHERE l.state = 'failed')::bigint AS failed,
+       count(*) FILTER (
+           WHERE l.track_id IS NULL AND (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+       )::bigint AS pending
+  FROM tracks t
+  LEFT JOIN track_acoustid_lookups l ON l.track_id = t.id
+ WHERE t.missing_since IS NULL
+`
+
+type GetMbidCoverageRow struct {
+	Total        int64
+	FromTag      int64
+	FromAcoustid int64
+	Ambiguous    int64
+	NoMatch      int64
+	Failed       int64
+	Pending      int64
+}
+
+// The admin gauge: present tracks by where their MBID came from, and the
+// lookup states of those a lookup has seen. pending is what the worker's
+// queue holds.
+func (q *Queries) GetMbidCoverage(ctx context.Context) (GetMbidCoverageRow, error) {
+	row := q.db.QueryRow(ctx, getMbidCoverage)
+	var i GetMbidCoverageRow
+	err := row.Scan(
+		&i.Total,
+		&i.FromTag,
+		&i.FromAcoustid,
+		&i.Ambiguous,
+		&i.NoMatch,
+		&i.Failed,
+		&i.Pending,
+	)
+	return i, err
+}
+
+const listTracksNeedingAcoustIDLookup = `-- name: ListTracksNeedingAcoustIDLookup :many
+
+SELECT t.id, t.file_path, t.title, t.duration_ms
+  FROM tracks t
+ WHERE (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+   AND t.missing_since IS NULL
+   AND t.id > $1::uuid
+   AND NOT EXISTS (SELECT 1 FROM track_acoustid_lookups l WHERE l.track_id = t.id)
+ ORDER BY t.id
+ LIMIT $2
+`
+
+type ListTracksNeedingAcoustIDLookupParams struct {
+	AfterID    pgtype.UUID
+	BatchLimit int32
+}
+
+type ListTracksNeedingAcoustIDLookupRow struct {
+	ID         pgtype.UUID
+	FilePath   string
+	Title      string
+	DurationMs int32
+}
+
+// AcoustID recording-id lookup (M401). Migration 0069 says what each
+// lookup state means.
+// The lookup worker's queue: present tracks with no tag MBID and no lookup
+// since their file last changed. A looked-up id is included once its row is
+// gone (the file changed), so the new bytes are checked rather than trusted.
+// Keyset-paged on id, as the loudness queue is, so a pass ends even when
+// every attempt is inconclusive and writes nothing.
+func (q *Queries) ListTracksNeedingAcoustIDLookup(ctx context.Context, arg ListTracksNeedingAcoustIDLookupParams) ([]ListTracksNeedingAcoustIDLookupRow, error) {
+	rows, err := q.db.Query(ctx, listTracksNeedingAcoustIDLookup, arg.AfterID, arg.BatchLimit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTracksNeedingAcoustIDLookupRow
+	for rows.Next() {
+		var i ListTracksNeedingAcoustIDLookupRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.FilePath,
+			&i.Title,
+			&i.DurationMs,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listUnsettledAcoustIDLookups = `-- name: ListUnsettledAcoustIDLookups :many
+SELECT t.id, t.title, t.file_path, ar.name AS artist_name, al.title AS album_title,
+       l.state, l.best_score, l.candidates, l.detail, l.looked_up_at
+  FROM track_acoustid_lookups l
+  JOIN tracks t ON t.id = l.track_id
+  JOIN artists ar ON ar.id = t.artist_id
+  JOIN albums al ON al.id = t.album_id
+ WHERE l.state IN ('ambiguous', 'failed')
+   AND t.missing_since IS NULL
+ ORDER BY ar.name, al.title, t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.title
+ LIMIT $1
+`
+
+type ListUnsettledAcoustIDLookupsRow struct {
+	ID         pgtype.UUID
+	Title      string
+	FilePath   string
+	ArtistName string
+	AlbumTitle string
+	State      string
+	BestScore  *float32
+	Candidates int32
+	Detail     *string
+	LookedUpAt pgtype.Timestamptz
+}
+
+// The admin list of tracks a lookup could not settle (ambiguous or failed),
+// so they are findable rather than silently empty.
+func (q *Queries) ListUnsettledAcoustIDLookups(ctx context.Context, rowLimit int32) ([]ListUnsettledAcoustIDLookupsRow, error) {
+	rows, err := q.db.Query(ctx, listUnsettledAcoustIDLookups, rowLimit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListUnsettledAcoustIDLookupsRow
+	for rows.Next() {
+		var i ListUnsettledAcoustIDLookupsRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.Title,
+			&i.FilePath,
+			&i.ArtistName,
+			&i.AlbumTitle,
+			&i.State,
+			&i.BestScore,
+			&i.Candidates,
+			&i.Detail,
+			&i.LookedUpAt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const recordAcoustIDLookup = `-- name: RecordAcoustIDLookup :exec
+INSERT INTO track_acoustid_lookups (track_id, state, best_score, candidates, recording_mbid, detail)
+VALUES ($1, $2, $3, $4,
+        $5, $6)
+ON CONFLICT (track_id) DO UPDATE SET
+    state          = EXCLUDED.state,
+    best_score     = EXCLUDED.best_score,
+    candidates     = EXCLUDED.candidates,
+    recording_mbid = EXCLUDED.recording_mbid,
+    detail         = EXCLUDED.detail,
+    looked_up_at   = now()
+`
+
+type RecordAcoustIDLookupParams struct {
+	TrackID       pgtype.UUID
+	State         string
+	BestScore     *float32
+	Candidates    int32
+	RecordingMbid *string
+	Detail        *string
+}
+
+func (q *Queries) RecordAcoustIDLookup(ctx context.Context, arg RecordAcoustIDLookupParams) error {
+	_, err := q.db.Exec(ctx, recordAcoustIDLookup,
+		arg.TrackID,
+		arg.State,
+		arg.BestScore,
+		arg.Candidates,
+		arg.RecordingMbid,
+		arg.Detail,
+	)
+	return err
+}
+
+const setTrackMbidFromAcoustID = `-- name: SetTrackMbidFromAcoustID :execrows
+UPDATE tracks
+   SET mbid = $1, mbid_source = 'acoustid'
+ WHERE id = $2
+   AND (mbid IS NULL OR mbid_source = 'acoustid')
+`
+
+type SetTrackMbidFromAcoustIDParams struct {
+	Mbid *string
+	ID   pgtype.UUID
+}
+
+// Never over a tag id (D4): the guard is here, not only in the worker, so a
+// tag the scan read between the worker's list and this write still wins.
+// updated_at is left alone: it gates the scan's mtime skip, and moving it
+// past a file's mtime would hide a change made just before the lookup.
+func (q *Queries) SetTrackMbidFromAcoustID(ctx context.Context, arg SetTrackMbidFromAcoustIDParams) (int64, error) {
+	result, err := q.db.Exec(ctx, setTrackMbidFromAcoustID, arg.Mbid, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
+const updateAcoustIDSettings = `-- name: UpdateAcoustIDSettings :one
+UPDATE acoustid_settings
+   SET enabled    = $1,
+       min_score  = $2,
+       api_key    = CASE WHEN $3::boolean
+                         THEN NULLIF($4::text, '')
+                         ELSE api_key END,
+       updated_at = now()
+ WHERE id = true
+RETURNING id, enabled, api_key, min_score, updated_at
+`
+
+type UpdateAcoustIDSettingsParams struct {
+	Enabled   bool
+	MinScore  float32
+	SetApiKey bool
+	ApiKey    string
+}
+
+// The key is write-only from the admin card: set_api_key false keeps the
+// stored one, and an empty api_key with set_api_key true clears it.
+func (q *Queries) UpdateAcoustIDSettings(ctx context.Context, arg UpdateAcoustIDSettingsParams) (AcoustidSetting, error) {
+	row := q.db.QueryRow(ctx, updateAcoustIDSettings,
+		arg.Enabled,
+		arg.MinScore,
+		arg.SetApiKey,
+		arg.ApiKey,
+	)
+	var i AcoustidSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ApiKey,
+		&i.MinScore,
+		&i.UpdatedAt,
+	)
+	return i, err
+}

internal/db/dbq/events.sql.go

@@ -261,7 +261,7 @@ func (q *Queries) InsertSkipEvent(ctx context.Context, arg InsertSkipEventParams
 }
 
 const listRecentSessionTracks = `-- name: ListRecentSessionTracks :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since FROM tracks t
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source FROM tracks t
 JOIN play_events pe ON pe.track_id = t.id
 WHERE pe.session_id = $1
   AND pe.started_at < $2
@@ -307,6 +307,7 @@ func (q *Queries) ListRecentSessionTracks(ctx context.Context, arg ListRecentSes
 			&i.TagSourcesVersion,
 			&i.TagReadVersion,
 			&i.MissingSince,
+			&i.MbidSource,
 		); err != nil {
 			return nil, err
 		}

internal/db/dbq/history.sql.go

@@ -14,7 +14,7 @@ import (
 const listUserHistory = `-- name: ListUserHistory :many
 SELECT pe.id           AS event_id,
        pe.started_at,
-       t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+       t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
        albums.title    AS album_title,
        artists.name    AS artist_name
   FROM play_events pe
@@ -81,6 +81,7 @@ func (q *Queries) ListUserHistory(ctx context.Context, arg ListUserHistoryParams
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {

internal/db/dbq/likes.sql.go

@@ -259,7 +259,7 @@ func (q *Queries) ListLikedTrackIDs(ctx context.Context, userID pgtype.UUID) ([]
 }
 
 const listLikedTrackRows = `-- name: ListLikedTrackRows :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since FROM tracks t
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source FROM tracks t
 JOIN general_likes l ON l.track_id = t.id
 WHERE l.user_id = $1
 ORDER BY l.liked_at DESC
@@ -301,6 +301,7 @@ func (q *Queries) ListLikedTrackRows(ctx context.Context, arg ListLikedTrackRows
 			&i.TagSourcesVersion,
 			&i.TagReadVersion,
 			&i.MissingSince,
+			&i.MbidSource,
 		); err != nil {
 			return nil, err
 		}

internal/db/dbq/merge.sql.go

@@ -196,7 +196,7 @@ func (q *Queries) MergeCopyTrackTags(ctx context.Context, arg MergeCopyTrackTags
 
 const mergeInheritTrackMbid = `-- name: MergeInheritTrackMbid :exec
 UPDATE tracks AS survivor
-   SET mbid = loser.mbid
+   SET mbid = loser.mbid, mbid_source = loser.mbid_source
   FROM tracks AS loser
  WHERE survivor.id = $1::uuid
    AND loser.id = $2::uuid

internal/db/dbq/models.go

@@ -187,6 +187,14 @@ func (ns NullLidarrRequestStatus) Value() (driver.Value, error) {
 	return string(ns.LidarrRequestStatus), nil
 }
 
+type AcoustidSetting struct {
+	ID        bool
+	Enabled   bool
+	ApiKey    *string
+	MinScore  float32
+	UpdatedAt pgtype.Timestamptz
+}
+
 type Album struct {
 	ID                     pgtype.UUID
 	Title                  string
@@ -720,6 +728,17 @@ type Track struct {
 	TagSourcesVersion int32
 	TagReadVersion    int16
 	MissingSince      pgtype.Timestamptz
+	MbidSource        *string
+}
+
+type TrackAcoustidLookup struct {
+	TrackID       pgtype.UUID
+	State         string
+	BestScore     *float32
+	Candidates    int32
+	RecordingMbid *string
+	Detail        *string
+	LookedUpAt    pgtype.Timestamptz
 }
 
 type TrackFingerprint struct {

internal/db/dbq/recommendation.sql.go

@@ -208,7 +208,7 @@ WITH plays AS (
     WHERE user_id = $2 AND was_skipped = false
     GROUP BY track_id
 )
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -270,6 +270,7 @@ func (q *Queries) ListMostPlayedTracksForArtist(ctx context.Context, arg ListMos
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -290,7 +291,7 @@ WITH plays AS (
     WHERE user_id = $1 AND was_skipped = false
     GROUP BY track_id
 )
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -354,6 +355,7 @@ func (q *Queries) ListMostPlayedTracksForUser(ctx context.Context, arg ListMostP
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -691,7 +693,7 @@ func (q *Queries) ListRediscoverArtistsForUser(ctx context.Context, arg ListRedi
 
 const loadRadioCandidates = `-- name: LoadRadioCandidates :many
 SELECT
-    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
@@ -772,6 +774,7 @@ func (q *Queries) LoadRadioCandidates(ctx context.Context, arg LoadRadioCandidat
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,
@@ -904,7 +907,7 @@ random_fill AS (
     LIMIT $9
 )
 SELECT
-    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
@@ -1031,6 +1034,7 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,

internal/db/dbq/tracks.sql.go

@@ -233,7 +233,7 @@ func (q *Queries) FindMissingTrackByMbid(ctx context.Context, mbid string) ([]Fi
 }
 
 const getTrackByID = `-- name: GetTrackByID :one
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since FROM tracks WHERE id = $1
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source FROM tracks WHERE id = $1
 `
 
 func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, error) {
@@ -259,12 +259,13 @@ func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, erro
 		&i.TagSourcesVersion,
 		&i.TagReadVersion,
 		&i.MissingSince,
+		&i.MbidSource,
 	)
 	return i, err
 }
 
 const getTrackByPath = `-- name: GetTrackByPath :one
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since FROM tracks WHERE file_path = $1
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source FROM tracks WHERE file_path = $1
 `
 
 func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, error) {
@@ -290,12 +291,13 @@ func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, e
 		&i.TagSourcesVersion,
 		&i.TagReadVersion,
 		&i.MissingSince,
+		&i.MbidSource,
 	)
 	return i, err
 }
 
 const getTracksByIDs = `-- name: GetTracksByIDs :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since FROM tracks WHERE id = ANY($1::uuid[])
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source FROM tracks WHERE id = ANY($1::uuid[])
 `
 
 // Batched lookup used by /api/library/sync to hydrate upsert payloads
@@ -329,6 +331,7 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 			&i.TagSourcesVersion,
 			&i.TagReadVersion,
 			&i.MissingSince,
+			&i.MbidSource,
 		); err != nil {
 			return nil, err
 		}
@@ -341,7 +344,7 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 }
 
 const listArtistTracksForUser = `-- name: ListArtistTracksForUser :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -401,6 +404,7 @@ func (q *Queries) ListArtistTracksForUser(ctx context.Context, arg ListArtistTra
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -501,7 +505,7 @@ func (q *Queries) ListMissingTracks(ctx context.Context, arg ListMissingTracksPa
 }
 
 const listRandomTracksForUser = `-- name: ListRandomTracksForUser :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -558,6 +562,7 @@ func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTra
 			&i.Track.TagSourcesVersion,
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
+			&i.Track.MbidSource,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -607,7 +612,7 @@ func (q *Queries) ListTrackPathsForReconcile(ctx context.Context) ([]ListTrackPa
 }
 
 const listTracksByAlbum = `-- name: ListTracksByAlbum :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since FROM tracks
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source FROM tracks
 WHERE album_id = $1
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -653,6 +658,7 @@ func (q *Queries) ListTracksByAlbum(ctx context.Context, arg ListTracksByAlbumPa
 			&i.TagSourcesVersion,
 			&i.TagReadVersion,
 			&i.MissingSince,
+			&i.MbidSource,
 		); err != nil {
 			return nil, err
 		}
@@ -726,7 +732,7 @@ func (q *Queries) MarkTracksMissing(ctx context.Context, ids []pgtype.UUID) (int
 }
 
 const searchTracks = `-- name: SearchTracks :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since FROM tracks
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source FROM tracks
 WHERE title ILIKE '%' || $1::text || '%'
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -779,6 +785,7 @@ func (q *Queries) SearchTracks(ctx context.Context, arg SearchTracksParams) ([]T
 			&i.TagSourcesVersion,
 			&i.TagReadVersion,
 			&i.MissingSince,
+			&i.MbidSource,
 		); err != nil {
 			return nil, err
 		}
@@ -792,7 +799,7 @@ func (q *Queries) SearchTracks(ctx context.Context, arg SearchTracksParams) ([]T
 
 const setTrackMbidIfNull = `-- name: SetTrackMbidIfNull :exec
 UPDATE tracks
-   SET mbid = $2, updated_at = now()
+   SET mbid = $2, mbid_source = 'tag', updated_at = now()
  WHERE id = $1 AND mbid IS NULL
 `
 
@@ -812,8 +819,9 @@ const upsertTrack = `-- name: UpsertTrack :one
 INSERT INTO tracks (
     title, album_id, artist_id, track_number, disc_number,
     duration_ms, file_path, file_size, file_format, bitrate, mbid, genre,
-    tag_read_version
+    tag_read_version, mbid_source
-) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13,
+          CASE WHEN $11::text IS NOT NULL THEN 'tag' END)
 ON CONFLICT (file_path) DO UPDATE SET
     title = EXCLUDED.title,
     album_id = EXCLUDED.album_id,
@@ -824,13 +832,17 @@ ON CONFLICT (file_path) DO UPDATE SET
     file_size = EXCLUDED.file_size,
     file_format = EXCLUDED.file_format,
     bitrate = EXCLUDED.bitrate,
-    mbid = EXCLUDED.mbid,
+    -- Both read the row as it was before this statement.
+    mbid = CASE WHEN EXCLUDED.mbid IS NULL AND tracks.mbid_source = 'acoustid'
+                THEN tracks.mbid ELSE EXCLUDED.mbid END,
+    mbid_source = CASE WHEN EXCLUDED.mbid IS NOT NULL THEN 'tag'
+                       WHEN tracks.mbid_source = 'acoustid' THEN 'acoustid' END,
     genre = EXCLUDED.genre,
     -- Stamped on update too, so a tag-repair pass marks rows as done and the
     -- next scan can short-circuit them again (#2499).
     tag_read_version = EXCLUDED.tag_read_version,
     updated_at = now()
-RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since
+RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source
 `
 
 type UpsertTrackParams struct {
@@ -850,6 +862,8 @@ type UpsertTrackParams struct {
 }
 
 // file_path is the canonical identity for library scan; mbid is secondary.
+// mbid is the file's tag. A looked-up id (mbid_source 'acoustid', M401)
+// survives a re-read that finds no tag id, and a tag id replaces it (D4).
 func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track, error) {
 	row := q.db.QueryRow(ctx, upsertTrack,
 		arg.Title,
@@ -887,6 +901,7 @@ func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track
 		&i.TagSourcesVersion,
 		&i.TagReadVersion,
 		&i.MissingSince,
+		&i.MbidSource,
 	)
 	return i, err
 }

internal/db/migrations/0069_acoustid_lookup.down.sql

@@ -0,0 +1,7 @@
+DROP TABLE IF EXISTS acoustid_settings;
+DROP TABLE IF EXISTS track_acoustid_lookups;
+-- Looked-up ids go with the lookups; a tag id stays.
+UPDATE tracks SET mbid = NULL WHERE mbid_source = 'acoustid';
+ALTER TABLE tracks DROP CONSTRAINT IF EXISTS tracks_mbid_source_pair;
+ALTER TABLE tracks DROP CONSTRAINT IF EXISTS tracks_mbid_source_check;
+ALTER TABLE tracks DROP COLUMN IF EXISTS mbid_source;

internal/db/migrations/0069_acoustid_lookup.up.sql

@@ -0,0 +1,69 @@
+-- 0069_acoustid_lookup.up.sql — recording MBIDs looked up through AcoustID
+-- for tracks whose tags carry none (Scribe milestone #401).
+--
+-- A track with no recording MBID is invisible to the ListenBrainz similarity
+-- arm in both directions, so this fills the ids the tags leave empty.
+
+-- Where tracks.mbid came from. The file's own tag always outranks a lookup
+-- (M401 D4): the scan's upsert keeps a looked-up id while the tag carries
+-- none, and replaces it the moment the tag carries one.
+ALTER TABLE tracks ADD COLUMN mbid_source text;
+-- Every id stored so far was read from a tag (the scan or the tag backfill),
+-- or inherited from a merged duplicate's tag.
+UPDATE tracks SET mbid_source = 'tag' WHERE mbid IS NOT NULL;
+ALTER TABLE tracks
+    ADD CONSTRAINT tracks_mbid_source_check CHECK (mbid_source IN ('tag', 'acoustid')),
+    ADD CONSTRAINT tracks_mbid_source_pair CHECK ((mbid IS NULL) = (mbid_source IS NULL));
+
+-- What happened the last time a track was looked up. A table of its own, as
+-- track_loudness is (0065): tracks is read with SELECT * on the hot path.
+--
+-- What a row means, which the lookup worker depends on:
+--   no row       never looked up, or the file changed since (the scan deletes
+--                the row): look it up
+--   matched      one recording cleared the score threshold, or one was left
+--                after disambiguating by title and length; recording_mbid is it
+--   ambiguous    several recordings cleared it and nothing told them apart.
+--                Nothing is written: a wrong MBID would feed similarity the
+--                wrong neighbours, which is worse than none (M401 D5)
+--   no_match     AcoustID linked nothing at or above the threshold
+--   failed       fpcalc rejected the file, or AcoustID rejected its print
+-- Every state is settled until the file changes. A failure that says nothing
+-- about the file (AcoustID unreachable, a timeout, a cancelled pass) writes no
+-- row, so the worker tries again.
+CREATE TABLE track_acoustid_lookups (
+    track_id       uuid        PRIMARY KEY REFERENCES tracks (id) ON DELETE CASCADE,
+    state          text        NOT NULL,
+    -- The best score any linked recording had; NULL when none was linked.
+    best_score     real,
+    -- How many distinct recordings were linked, at any score.
+    candidates     integer     NOT NULL DEFAULT 0,
+    recording_mbid text,
+    -- Why a lookup failed, for the admin list.
+    detail         text,
+    looked_up_at   timestamptz NOT NULL DEFAULT now(),
+
+    CONSTRAINT track_acoustid_lookups_state_check
+        CHECK (state IN ('matched', 'ambiguous', 'no_match', 'failed')),
+    CONSTRAINT track_acoustid_lookups_matched_has_mbid
+        CHECK ((state = 'matched') = (recording_mbid IS NOT NULL))
+);
+CREATE INDEX track_acoustid_lookups_state ON track_acoustid_lookups (state);
+
+-- AcoustID's knobs, in admin Settings (rule 25). Singleton in the style of
+-- loudness_settings (0065).
+CREATE TABLE acoustid_settings (
+    id         boolean     PRIMARY KEY DEFAULT true,
+    -- Off by default (rule 26): AcoustID needs a key the operator registers,
+    -- and the lookup sends fingerprints to a third party.
+    enabled    boolean     NOT NULL DEFAULT false,
+    api_key    text,
+    -- The score a recording needs before it is considered at all. AcoustID
+    -- scores a true match close to 1; 0.85 leaves room for a lossy encode.
+    min_score  real        NOT NULL DEFAULT 0.85,
+    updated_at timestamptz NOT NULL DEFAULT now(),
+
+    CONSTRAINT acoustid_settings_singleton CHECK (id = true),
+    CONSTRAINT acoustid_settings_min_score_range CHECK (min_score >= 0.5 AND min_score <= 1)
+);
+INSERT INTO acoustid_settings (id) VALUES (true) ON CONFLICT (id) DO NOTHING;

internal/db/queries/acoustid.sql

@@ -0,0 +1,99 @@
+-- AcoustID recording-id lookup (M401). Migration 0069 says what each
+-- lookup state means.
+
+-- name: ListTracksNeedingAcoustIDLookup :many
+-- The lookup worker's queue: present tracks with no tag MBID and no lookup
+-- since their file last changed. A looked-up id is included once its row is
+-- gone (the file changed), so the new bytes are checked rather than trusted.
+-- Keyset-paged on id, as the loudness queue is, so a pass ends even when
+-- every attempt is inconclusive and writes nothing.
+SELECT t.id, t.file_path, t.title, t.duration_ms
+  FROM tracks t
+ WHERE (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+   AND t.missing_since IS NULL
+   AND t.id > sqlc.arg(after_id)::uuid
+   AND NOT EXISTS (SELECT 1 FROM track_acoustid_lookups l WHERE l.track_id = t.id)
+ ORDER BY t.id
+ LIMIT sqlc.arg(batch_limit);
+
+-- name: RecordAcoustIDLookup :exec
+INSERT INTO track_acoustid_lookups (track_id, state, best_score, candidates, recording_mbid, detail)
+VALUES (sqlc.arg(track_id), sqlc.arg(state), sqlc.narg(best_score), sqlc.arg(candidates),
+        sqlc.narg(recording_mbid), sqlc.narg(detail))
+ON CONFLICT (track_id) DO UPDATE SET
+    state          = EXCLUDED.state,
+    best_score     = EXCLUDED.best_score,
+    candidates     = EXCLUDED.candidates,
+    recording_mbid = EXCLUDED.recording_mbid,
+    detail         = EXCLUDED.detail,
+    looked_up_at   = now();
+
+-- name: SetTrackMbidFromAcoustID :execrows
+-- Never over a tag id (D4): the guard is here, not only in the worker, so a
+-- tag the scan read between the worker's list and this write still wins.
+-- updated_at is left alone: it gates the scan's mtime skip, and moving it
+-- past a file's mtime would hide a change made just before the lookup.
+UPDATE tracks
+   SET mbid = sqlc.arg(mbid), mbid_source = 'acoustid'
+ WHERE id = sqlc.arg(id)
+   AND (mbid IS NULL OR mbid_source = 'acoustid');
+
+-- name: ClearTrackAcoustIDMbid :exec
+-- A re-lookup of changed bytes that no longer matches takes back the id an
+-- earlier lookup wrote. A tag id is never touched.
+UPDATE tracks
+   SET mbid = NULL, mbid_source = NULL
+ WHERE id = sqlc.arg(id)
+   AND mbid_source = 'acoustid';
+
+-- name: DeleteAcoustIDLookup :exec
+-- The scan drops the lookup of bytes that are gone, so the worker checks the
+-- new ones.
+DELETE FROM track_acoustid_lookups WHERE track_id = $1;
+
+-- name: GetMbidCoverage :one
+-- The admin gauge: present tracks by where their MBID came from, and the
+-- lookup states of those a lookup has seen. pending is what the worker's
+-- queue holds.
+SELECT count(*)::bigint AS total,
+       count(*) FILTER (WHERE t.mbid_source = 'tag')::bigint AS from_tag,
+       count(*) FILTER (WHERE t.mbid_source = 'acoustid')::bigint AS from_acoustid,
+       count(*) FILTER (WHERE l.state = 'ambiguous')::bigint AS ambiguous,
+       count(*) FILTER (WHERE l.state = 'no_match')::bigint AS no_match,
+       count(*) FILTER (WHERE l.state = 'failed')::bigint AS failed,
+       count(*) FILTER (
+           WHERE l.track_id IS NULL AND (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+       )::bigint AS pending
+  FROM tracks t
+  LEFT JOIN track_acoustid_lookups l ON l.track_id = t.id
+ WHERE t.missing_since IS NULL;
+
+-- name: ListUnsettledAcoustIDLookups :many
+-- The admin list of tracks a lookup could not settle (ambiguous or failed),
+-- so they are findable rather than silently empty.
+SELECT t.id, t.title, t.file_path, ar.name AS artist_name, al.title AS album_title,
+       l.state, l.best_score, l.candidates, l.detail, l.looked_up_at
+  FROM track_acoustid_lookups l
+  JOIN tracks t ON t.id = l.track_id
+  JOIN artists ar ON ar.id = t.artist_id
+  JOIN albums al ON al.id = t.album_id
+ WHERE l.state IN ('ambiguous', 'failed')
+   AND t.missing_since IS NULL
+ ORDER BY ar.name, al.title, t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.title
+ LIMIT sqlc.arg(row_limit);
+
+-- name: GetAcoustIDSettings :one
+SELECT * FROM acoustid_settings WHERE id = true;
+
+-- name: UpdateAcoustIDSettings :one
+-- The key is write-only from the admin card: set_api_key false keeps the
+-- stored one, and an empty api_key with set_api_key true clears it.
+UPDATE acoustid_settings
+   SET enabled    = sqlc.arg(enabled),
+       min_score  = sqlc.arg(min_score),
+       api_key    = CASE WHEN sqlc.arg(set_api_key)::boolean
+                         THEN NULLIF(sqlc.arg(api_key)::text, '')
+                         ELSE api_key END,
+       updated_at = now()
+ WHERE id = true
+RETURNING *;

internal/db/queries/merge.sql

@@ -88,7 +88,7 @@ ON CONFLICT (track_a_id, track_b_id, source) DO NOTHING;
 -- A recording MBID is what the similarity pipeline keys on. If only the removed
 -- copy carried one, the survivor takes it rather than going dark to similarity.
 UPDATE tracks AS survivor
-   SET mbid = loser.mbid
+   SET mbid = loser.mbid, mbid_source = loser.mbid_source
   FROM tracks AS loser
  WHERE survivor.id = sqlc.arg(survivor_id)::uuid
    AND loser.id = sqlc.arg(loser_id)::uuid

internal/db/queries/tracks.sql

@@ -1,10 +1,13 @@
 -- name: UpsertTrack :one
 -- file_path is the canonical identity for library scan; mbid is secondary.
+-- mbid is the file's tag. A looked-up id (mbid_source 'acoustid', M401)
+-- survives a re-read that finds no tag id, and a tag id replaces it (D4).
 INSERT INTO tracks (
     title, album_id, artist_id, track_number, disc_number,
     duration_ms, file_path, file_size, file_format, bitrate, mbid, genre,
-    tag_read_version
+    tag_read_version, mbid_source
-) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13,
+          CASE WHEN $11::text IS NOT NULL THEN 'tag' END)
 ON CONFLICT (file_path) DO UPDATE SET
     title = EXCLUDED.title,
     album_id = EXCLUDED.album_id,
@@ -15,7 +18,11 @@ ON CONFLICT (file_path) DO UPDATE SET
     file_size = EXCLUDED.file_size,
     file_format = EXCLUDED.file_format,
     bitrate = EXCLUDED.bitrate,
-    mbid = EXCLUDED.mbid,
+    -- Both read the row as it was before this statement.
+    mbid = CASE WHEN EXCLUDED.mbid IS NULL AND tracks.mbid_source = 'acoustid'
+                THEN tracks.mbid ELSE EXCLUDED.mbid END,
+    mbid_source = CASE WHEN EXCLUDED.mbid IS NOT NULL THEN 'tag'
+                       WHEN tracks.mbid_source = 'acoustid' THEN 'acoustid' END,
     genre = EXCLUDED.genre,
     -- Stamped on update too, so a tag-repair pass marks rows as done and the
     -- next scan can short-circuit them again (#2499).
@@ -39,7 +46,7 @@ SELECT id, file_path
 -- Heal a track's recording MBID only while still NULL — idempotent, so
 -- re-running the backfill is a no-op for already-healed rows.
 UPDATE tracks
-   SET mbid = $2, updated_at = now()
+   SET mbid = $2, mbid_source = 'tag', updated_at = now()
  WHERE id = $1 AND mbid IS NULL;
 
 -- name: GetTrackByID :one

internal/library/acoustid_lookup.go

@@ -0,0 +1,454 @@
+package library
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+	"sync"
+	"time"
+	"unicode"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/acoustid"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// AcoustID lookup worker (M401 #3921).
+//
+// A track whose tags carry no recording MBID is invisible to the ListenBrainz
+// similarity arm: it is never a seed and never comes back as a result. This
+// worker fingerprints such tracks and asks AcoustID which recording they are,
+// writing an id only when the answer is unambiguous (D5). The file's own tag
+// always outranks it (D4).
+//
+// It never gates anything else (rule 164). With no key, switched off or
+// AcoustID unreachable, it idles and says why through Status; scans and
+// playback do not notice.
+
+// acoustIDLookupTick is how often the worker looks for work. A settings save
+// starts a pass at once, so this only paces new tracks and retries after an
+// outage.
+const acoustIDLookupTick = 15 * time.Minute
+
+// acoustIDLookupBatch is how many tracks one query hands the worker.
+const acoustIDLookupBatch = 50
+
+// acoustIDLookupConcurrency is how many files are fingerprinted at once. The
+// client serialises the requests themselves to AcoustID's rate, so this only
+// overlaps fpcalc's decodes; low for the reason the loudness backfill's is.
+const acoustIDLookupConcurrency = 2
+
+// acoustIDDurationToleranceSec is how far a recording's MusicBrainz length may
+// be from the file's and still count as the same take when telling candidates
+// apart. A release's length and a rip's differ by a second or two of
+// silence; a radio edit or a live take differs by far more.
+const acoustIDDurationToleranceSec = 3
+
+// Lookup states, as migration 0069's CHECK has them.
+const (
+	lookupMatched   = "matched"
+	lookupAmbiguous = "ambiguous"
+	lookupNoMatch   = "no_match"
+	lookupFailed    = "failed"
+)
+
+// recordingLookup is the AcoustID client as the worker uses it.
+type recordingLookup interface {
+	Lookup(ctx context.Context, apiKey, fingerprint string, durationSec int) ([]acoustid.Candidate, error)
+}
+
+// AcoustIDLookupStatus is what the admin card shows about the worker.
+type AcoustIDLookupStatus struct {
+	Running    bool
+	LastPassAt time.Time
+	// Problem says why the last pass stopped short, in words for the card:
+	// the key was refused, or AcoustID could not be reached. Empty when the
+	// last pass ran to the end.
+	Problem string
+}
+
+// AcoustIDLookupResult tallies one pass.
+type AcoustIDLookupResult struct {
+	Processed    int
+	Matched      int
+	Ambiguous    int
+	NoMatch      int
+	Failed       int
+	Inconclusive int // nothing stored; tried again on a later pass
+}
+
+func (r *AcoustIDLookupResult) add(state string) {
+	r.Processed++
+	switch state {
+	case lookupMatched:
+		r.Matched++
+	case lookupAmbiguous:
+		r.Ambiguous++
+	case lookupNoMatch:
+		r.NoMatch++
+	case lookupFailed:
+		r.Failed++
+	default:
+		r.Inconclusive++
+	}
+}
+
+// errPassStopped ends a pass early: every further lookup would fail the same
+// way, so asking again would only spend the rate limit.
+type errPassStopped struct{ reason string }
+
+func (e errPassStopped) Error() string { return e.reason }
+
+// AcoustIDLookupWorker fills recording MBIDs through AcoustID.
+type AcoustIDLookupWorker struct {
+	pool     *pgxpool.Pool
+	logger   *slog.Logger
+	settings *AcoustIDSettingsService
+	client   recordingLookup
+	tick     time.Duration
+	batch    int32
+	// fingerprint is a field so an integration test pins which tracks a pass
+	// touches, not what fpcalc prints.
+	fingerprint func(ctx context.Context, path string) (lookupFingerprint, error)
+	kick        chan struct{}
+
+	mu     sync.Mutex
+	status AcoustIDLookupStatus
+}
+
+// NewAcoustIDLookupWorker builds a worker with the production cadence.
+func NewAcoustIDLookupWorker(
+	pool *pgxpool.Pool, logger *slog.Logger, settings *AcoustIDSettingsService, client recordingLookup,
+) *AcoustIDLookupWorker {
+	return &AcoustIDLookupWorker{
+		pool:        pool,
+		logger:      logger,
+		settings:    settings,
+		client:      client,
+		tick:        acoustIDLookupTick,
+		batch:       acoustIDLookupBatch,
+		fingerprint: computeLookupFingerprint,
+		kick:        make(chan struct{}, 1),
+	}
+}
+
+// Kick asks for a pass now, for the admin card's "look up now". A pass
+// already running absorbs it.
+func (w *AcoustIDLookupWorker) Kick() {
+	if w == nil {
+		return
+	}
+	select {
+	case w.kick <- struct{}{}:
+	default:
+	}
+}
+
+// Settings is the settings service the worker reads, for the admin API. A
+// nil worker has none, which serves the defaults.
+func (w *AcoustIDLookupWorker) Settings() *AcoustIDSettingsService {
+	if w == nil {
+		return nil
+	}
+	return w.settings
+}
+
+// Status reports the worker's state for the admin card.
+func (w *AcoustIDLookupWorker) Status() AcoustIDLookupStatus {
+	if w == nil {
+		return AcoustIDLookupStatus{}
+	}
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.status
+}
+
+// Run blocks until ctx is cancelled: one pass at start, then one per tick, on
+// a kick, and after every settings save.
+func (w *AcoustIDLookupWorker) Run(ctx context.Context) {
+	w.runOnce(ctx)
+	t := time.NewTicker(w.tick)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		case <-w.kick:
+		case <-w.settings.Changed():
+		}
+		w.runOnce(ctx)
+	}
+}
+
+// runOnce contains a pass so that nothing it does (an error, a panic) can stop
+// the next one from starting (rule 157).
+func (w *AcoustIDLookupWorker) runOnce(ctx context.Context) {
+	w.setStatus(func(s *AcoustIDLookupStatus) { s.Running = true })
+	problem := ""
+	defer func() {
+		if r := recover(); r != nil {
+			w.logger.Error("acoustid lookup: pass panicked", "panic", r)
+			problem = "The last lookup pass stopped on an internal error; see the server log."
+		}
+		w.setStatus(func(s *AcoustIDLookupStatus) {
+			s.Running, s.LastPassAt, s.Problem = false, time.Now(), problem
+		})
+	}()
+	res, err := w.pass(ctx)
+	var stopped errPassStopped
+	switch {
+	case errors.As(err, &stopped):
+		problem = stopped.reason
+		w.logger.Warn("acoustid lookup: pass stopped", "reason", stopped.reason, "processed", res.Processed)
+	case err != nil && ctx.Err() == nil:
+		problem = "The last lookup pass failed; see the server log."
+		w.logger.Warn("acoustid lookup: pass failed", "err", err, "processed", res.Processed)
+	}
+	if res.Processed > 0 {
+		w.logger.Info("acoustid lookup: pass complete",
+			"processed", res.Processed, "matched", res.Matched, "ambiguous", res.Ambiguous,
+			"no_match", res.NoMatch, "failed", res.Failed, "inconclusive", res.Inconclusive)
+	}
+}
+
+func (w *AcoustIDLookupWorker) setStatus(f func(*AcoustIDLookupStatus)) {
+	w.mu.Lock()
+	f(&w.status)
+	w.mu.Unlock()
+}
+
+// pass walks the queue once, keyset-paged on id so it ends even when every
+// attempt is inconclusive. Settings are read before every batch, so switching
+// the lookup off or changing the threshold applies at the next batch.
+func (w *AcoustIDLookupWorker) pass(ctx context.Context) (AcoustIDLookupResult, error) {
+	q := dbq.New(w.pool)
+	var res AcoustIDLookupResult
+	after := pgtype.UUID{Valid: true}
+	for {
+		if err := ctx.Err(); err != nil {
+			return res, err
+		}
+		cfg := w.settings.Get()
+		if !cfg.Ready() {
+			return res, nil
+		}
+		rows, err := q.ListTracksNeedingAcoustIDLookup(ctx, dbq.ListTracksNeedingAcoustIDLookupParams{
+			AfterID:    after,
+			BatchLimit: w.batch,
+		})
+		if err != nil {
+			return res, fmt.Errorf("list tracks needing a lookup: %w", err)
+		}
+		if len(rows) == 0 {
+			return res, nil
+		}
+		if err := w.lookupBatch(ctx, cfg, rows, &res); err != nil {
+			return res, err
+		}
+		after = rows[len(rows)-1].ID
+	}
+}
+
+// lookupBatch looks up one batch, acoustIDLookupConcurrency at a time. The
+// first track that stops the pass stops the batch: the tracks already started
+// finish, no new ones start.
+func (w *AcoustIDLookupWorker) lookupBatch(
+	ctx context.Context, cfg AcoustIDSettings, rows []dbq.ListTracksNeedingAcoustIDLookupRow, res *AcoustIDLookupResult,
+) error {
+	ctx, cancel := context.WithCancelCause(ctx)
+	defer cancel(nil)
+	var (
+		mu  sync.Mutex
+		wg  sync.WaitGroup
+		sem = make(chan struct{}, acoustIDLookupConcurrency)
+	)
+	for _, row := range rows {
+		if ctx.Err() != nil {
+			break
+		}
+		sem <- struct{}{}
+		// The slot may have come free because a lookup just stopped the pass.
+		if ctx.Err() != nil {
+			<-sem
+			break
+		}
+		wg.Add(1)
+		go func(row dbq.ListTracksNeedingAcoustIDLookupRow) {
+			defer wg.Done()
+			defer func() { <-sem }()
+			defer func() {
+				if r := recover(); r != nil {
+					w.logger.Error("acoustid lookup: track panicked", "path", row.FilePath, "panic", r)
+				}
+			}()
+			state, err := w.lookupTrack(ctx, cfg, row)
+			if err != nil {
+				cancel(err)
+			}
+			mu.Lock()
+			res.add(state)
+			mu.Unlock()
+		}(row)
+	}
+	wg.Wait()
+	if cause := context.Cause(ctx); cause != nil && !errors.Is(cause, context.Canceled) {
+		return cause
+	}
+	return nil
+}
+
+// lookupTrack fingerprints one file, asks AcoustID and stores the answer. It
+// returns the state stored ("" when nothing was), and an errPassStopped when
+// no further lookup can succeed this pass.
+func (w *AcoustIDLookupWorker) lookupTrack(
+	ctx context.Context, cfg AcoustIDSettings, row dbq.ListTracksNeedingAcoustIDLookupRow,
+) (string, error) {
+	fp, err := w.fingerprint(ctx, row.FilePath)
+	if err != nil {
+		if isInconclusive(err) {
+			return "", nil
+		}
+		// fpcalc ran and rejected the file: a verdict, settled until it changes.
+		return w.store(ctx, row, lookupDecision{state: lookupFailed, detail: err.Error()}), nil
+	}
+	cands, err := w.client.Lookup(ctx, cfg.APIKey, fp.fingerprint, fp.durationSec)
+	switch {
+	case err == nil:
+	case errors.Is(err, acoustid.ErrInvalidKey):
+		return "", errPassStopped{"AcoustID refused the API key. Check it in Settings."}
+	case errors.Is(err, acoustid.ErrUnavailable):
+		return "", errPassStopped{"AcoustID could not be reached; lookups resume on the next pass."}
+	case errors.Is(err, acoustid.ErrInvalidFingerprint):
+		return w.store(ctx, row, lookupDecision{state: lookupFailed, detail: err.Error()}), nil
+	default:
+		// The caller's cancellation, or a request this client built wrongly.
+		// Neither is a verdict on the track.
+		if ctx.Err() == nil {
+			w.logger.Warn("acoustid lookup: lookup failed", "path", row.FilePath, "err", err)
+		}
+		return "", nil
+	}
+	return w.store(ctx, row, chooseRecording(cands, cfg.MinScore, row.Title, row.DurationMs)), nil
+}
+
+// store records a decision and applies it to tracks.mbid in one transaction,
+// so the gauge never shows a match whose id was not written. A failed write
+// stores nothing and the track is tried again.
+func (w *AcoustIDLookupWorker) store(ctx context.Context, row dbq.ListTracksNeedingAcoustIDLookupRow, d lookupDecision) string {
+	err := pgx.BeginFunc(ctx, w.pool, func(tx pgx.Tx) error {
+		q := dbq.New(tx)
+		params := dbq.RecordAcoustIDLookupParams{
+			TrackID: row.ID, State: d.state, Candidates: int32(d.candidates),
+		}
+		if d.candidates > 0 {
+			params.BestScore = &d.bestScore
+		}
+		if d.recording != "" {
+			params.RecordingMbid = &d.recording
+		}
+		if d.detail != "" {
+			params.Detail = &d.detail
+		}
+		if err := q.RecordAcoustIDLookup(ctx, params); err != nil {
+			return err
+		}
+		if d.state == lookupMatched {
+			_, err := q.SetTrackMbidFromAcoustID(ctx, dbq.SetTrackMbidFromAcoustIDParams{ID: row.ID, Mbid: &d.recording})
+			return err
+		}
+		// A re-lookup of changed bytes that no longer matches takes back the
+		// id the earlier lookup wrote.
+		return q.ClearTrackAcoustIDMbid(ctx, row.ID)
+	})
+	if err != nil {
+		if ctx.Err() == nil {
+			w.logger.Warn("acoustid lookup: storing the result failed", "path", row.FilePath, "err", err)
+		}
+		return ""
+	}
+	return d.state
+}
+
+// lookupDecision is what one lookup settles on.
+type lookupDecision struct {
+	state      string
+	recording  string // set only when matched
+	bestScore  float32
+	candidates int
+	detail     string
+}
+
+// chooseRecording applies D5 to AcoustID's candidates (best score first):
+// only recordings at or above minScore count, one of them is a match, and
+// several are told apart by the track's title and length or not at all. A
+// wrong MBID would feed similarity the wrong neighbours, which is worse than
+// none, so anything left unresolved is ambiguous and writes nothing.
+func chooseRecording(cands []acoustid.Candidate, minScore float32, title string, durationMs int32) lookupDecision {
+	d := lookupDecision{candidates: len(cands)}
+	if len(cands) > 0 {
+		d.bestScore = float32(cands[0].Score)
+	}
+	var above []acoustid.Candidate
+	for _, c := range cands {
+		if float32(c.Score) >= minScore {
+			above = append(above, c)
+		}
+	}
+	switch len(above) {
+	case 0:
+		d.state = lookupNoMatch
+		return d
+	case 1:
+		d.state, d.recording = lookupMatched, above[0].ID
+		return d
+	}
+	want := normalizeTitle(title)
+	var same []acoustid.Candidate
+	for _, c := range above {
+		if normalizeTitle(c.Title) == want && sameLength(c.DurationSec, durationMs) {
+			same = append(same, c)
+		}
+	}
+	if len(same) == 1 {
+		d.state, d.recording = lookupMatched, same[0].ID
+		return d
+	}
+	d.state = lookupAmbiguous
+	return d
+}
+
+// sameLength reports whether a recording's length (0 when MusicBrainz has
+// none) fits the file's. An unknown length on either side tells nothing, so
+// it does not rule a candidate out.
+func sameLength(recordingSec int, fileMs int32) bool {
+	if recordingSec <= 0 || fileMs <= 0 {
+		return true
+	}
+	diff := recordingSec*1000 - int(fileMs)
+	return diff <= acoustIDDurationToleranceSec*1000 && diff >= -acoustIDDurationToleranceSec*1000
+}
+
+// normalizeTitle compares titles by their letters and digits alone, case
+// folded, so "Don't Stop" and "Dont stop" match while "Song (Radio Edit)"
+// and "Song" do not.
+func normalizeTitle(s string) string {
+	var b strings.Builder
+	for _, r := range strings.ToLower(s) {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+// AcoustIDCoverage reports where the library's recording MBIDs came from and
+// what the lookups found, for the admin gauge.
+func AcoustIDCoverage(ctx context.Context, pool *pgxpool.Pool) (dbq.GetMbidCoverageRow, error) {
+	return dbq.New(pool).GetMbidCoverage(ctx)
+}

internal/library/acoustid_lookup_test.go

@@ -0,0 +1,371 @@
+package library
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/acoustid"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/dbtest"
+)
+
+func cand(id, title string, sec int, score float64) acoustid.Candidate {
+	return acoustid.Candidate{Recording: acoustid.Recording{ID: id, Title: title, DurationSec: sec}, Score: score}
+}
+
+// D5, as a table over what decides it: how many candidates clear the
+// threshold, and whether title and length leave exactly one of them.
+func TestChooseRecording(t *testing.T) {
+	const (
+		minScore = 0.85
+		title    = "Don't Stop"
+		fileMs   = 200_400
+	)
+	cases := []struct {
+		name  string
+		cands []acoustid.Candidate
+		state string
+		rec   string
+	}{
+		{"no candidates", nil, lookupNoMatch, ""},
+		{"all below the threshold", []acoustid.Candidate{cand("a", title, 200, 0.84)}, lookupNoMatch, ""},
+		{"one above the threshold", []acoustid.Candidate{cand("a", "Other title", 999, 0.9), cand("b", title, 200, 0.4)}, lookupMatched, "a"},
+		{"exactly at the threshold counts", []acoustid.Candidate{cand("a", title, 200, 0.85)}, lookupMatched, "a"},
+		{"several, one with the title and length",
+			[]acoustid.Candidate{cand("album", "Dont stop", 201, 0.95), cand("edit", "Don't Stop (Radio Edit)", 181, 0.95)},
+			lookupMatched, "album"},
+		{"several, title alike but only one length fits",
+			[]acoustid.Candidate{cand("live", title, 260, 0.9), cand("studio", title, 198, 0.9)},
+			lookupMatched, "studio"},
+		{"several with the same title and length",
+			[]acoustid.Candidate{cand("r1", title, 200, 0.95), cand("r2", title, 201, 0.95)},
+			lookupAmbiguous, ""},
+		{"several, none with the title",
+			[]acoustid.Candidate{cand("x", "Something", 200, 0.95), cand("y", "Else", 200, 0.95)},
+			lookupAmbiguous, ""},
+		// An unknown length rules nothing out, so it cannot break a tie on
+		// its own: both stay and the lookup is ambiguous.
+		{"unknown lengths do not disambiguate",
+			[]acoustid.Candidate{cand("r1", title, 0, 0.95), cand("r2", title, 0, 0.95)},
+			lookupAmbiguous, ""},
+	}
+	for _, c := range cases {
+		d := chooseRecording(c.cands, minScore, title, fileMs)
+		if d.state != c.state || d.recording != c.rec {
+			t.Errorf("%s: got %s %q, want %s %q", c.name, d.state, d.recording, c.state, c.rec)
+		}
+		if d.candidates != len(c.cands) {
+			t.Errorf("%s: candidates = %d, want %d", c.name, d.candidates, len(c.cands))
+		}
+	}
+	if d := chooseRecording([]acoustid.Candidate{cand("a", title, 200, 0.97)}, minScore, title, fileMs); d.bestScore != 0.97 {
+		t.Errorf("best score = %v, want 0.97", d.bestScore)
+	}
+}
+
+func TestNormalizeTitle(t *testing.T) {
+	if normalizeTitle("Don't Stop!") != normalizeTitle("dont   stop") {
+		t.Error("punctuation and case should not separate titles")
+	}
+	if normalizeTitle("Song (Radio Edit)") == normalizeTitle("Song") {
+		t.Error("an edit's title must not match the original's")
+	}
+	if normalizeTitle("Ænima") != "ænima" {
+		t.Errorf("non-ASCII letters must survive: %q", normalizeTitle("Ænima"))
+	}
+}
+
+// fakeLookup answers by fingerprint. The worker passes each file's path
+// through as its fingerprint (see testWorker), so a test keys answers by file.
+type fakeLookup struct {
+	mu      sync.Mutex
+	answers map[string][]acoustid.Candidate
+	err     error
+	calls   int
+}
+
+func (f *fakeLookup) Lookup(_ context.Context, _ string, fingerprint string, _ int) ([]acoustid.Candidate, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls++
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.answers[fingerprint], nil
+}
+
+func testWorker(t *testing.T, pool *pgxpool.Pool, client recordingLookup) *AcoustIDLookupWorker {
+	t.Helper()
+	ctx := context.Background()
+	settings, err := NewAcoustIDSettingsService(ctx, pool)
+	if err != nil {
+		t.Fatal(err)
+	}
+	key := "test-key"
+	if _, err := settings.Set(ctx, AcoustIDSettingsUpdate{Enabled: true, MinScore: 0.85, APIKey: &key}); err != nil {
+		t.Fatal(err)
+	}
+	w := NewAcoustIDLookupWorker(pool, slog.New(slog.NewTextHandler(io.Discard, nil)), settings, client)
+	w.fingerprint = func(_ context.Context, path string) (lookupFingerprint, error) {
+		return lookupFingerprint{fingerprint: path, durationSec: 200}, nil
+	}
+	return w
+}
+
+func ptr(s string) *string { return &s }
+
+// mbidOf reads a track's MBID and its source.
+func mbidOf(t *testing.T, pool *pgxpool.Pool, id pgtype.UUID) (string, string) {
+	t.Helper()
+	var mbid, source *string
+	if err := pool.QueryRow(context.Background(),
+		`SELECT mbid, mbid_source FROM tracks WHERE id = $1`, id).Scan(&mbid, &source); err != nil {
+		t.Fatal(err)
+	}
+	deref := func(p *string) string {
+		if p == nil {
+			return ""
+		}
+		return *p
+	}
+	return deref(mbid), deref(source)
+}
+
+func addTrack(t *testing.T, q *dbq.Queries, album dbq.Album, artist dbq.Artist, title, path string, mbid *string) dbq.Track {
+	t.Helper()
+	tr, err := q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
+		Title: title, AlbumID: album.ID, ArtistID: artist.ID, DurationMs: 200_000,
+		FilePath: path, FileSize: 100, FileFormat: "mp3", Mbid: mbid,
+	})
+	if err != nil {
+		t.Fatalf("track %s: %v", title, err)
+	}
+	return tr
+}
+
+// D4: the file's tag outranks a lookup, in both directions. Falsified by
+// restoring `mbid = EXCLUDED.mbid` in UpsertTrack: the first re-read below
+// then erases the looked-up id.
+func TestUpsertTrack_KeepsALookedUpMbidUntilATagCarriesOne_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	dir := t.TempDir()
+	tr, album, artist := seedTrack(t, pool, filepath.Join(dir, "a.mp3"))
+	reread := func(mbid *string) {
+		t.Helper()
+		if _, err := q.UpsertTrack(ctx, dbq.UpsertTrackParams{
+			Title: tr.Title, AlbumID: album.ID, ArtistID: artist.ID, DurationMs: 1000,
+			FilePath: tr.FilePath, FileSize: 100, FileFormat: "mp3", Mbid: mbid,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if _, err := q.SetTrackMbidFromAcoustID(ctx, dbq.SetTrackMbidFromAcoustIDParams{ID: tr.ID, Mbid: ptr("rec-looked-up")}); err != nil {
+		t.Fatal(err)
+	}
+	reread(nil)
+	if m, s := mbidOf(t, pool, tr.ID); m != "rec-looked-up" || s != "acoustid" {
+		t.Errorf("after an untagged re-read: %q from %q, want the looked-up id kept", m, s)
+	}
+
+	reread(ptr("rec-from-tag"))
+	if m, s := mbidOf(t, pool, tr.ID); m != "rec-from-tag" || s != "tag" {
+		t.Errorf("after a tagged re-read: %q from %q, want the tag's id", m, s)
+	}
+
+	// A tag id is the file's to take away: removing the tag clears it, and a
+	// lookup cannot write over one.
+	if n, err := q.SetTrackMbidFromAcoustID(ctx, dbq.SetTrackMbidFromAcoustIDParams{ID: tr.ID, Mbid: ptr("rec-other")}); err != nil || n != 0 {
+		t.Errorf("a lookup wrote over a tag id: %d rows, %v", n, err)
+	}
+	reread(nil)
+	if m, s := mbidOf(t, pool, tr.ID); m != "" || s != "" {
+		t.Errorf("after the tag was removed: %q from %q, want none", m, s)
+	}
+}
+
+func TestAcoustIDLookup_FillsOnlyWhatItCanSettle_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	dir := t.TempDir()
+	_, album, artist := seedTrack(t, pool, filepath.Join(dir, "seed.mp3"))
+	path := func(n string) string { return filepath.Join(dir, n+".mp3") }
+
+	matched := addTrack(t, q, album, artist, "Matched", path("matched"), nil)
+	ambiguous := addTrack(t, q, album, artist, "Twice", path("ambiguous"), nil)
+	none := addTrack(t, q, album, artist, "Unknown", path("none"), nil)
+	tagged := addTrack(t, q, album, artist, "Tagged", path("tagged"), ptr("rec-tag"))
+
+	fake := &fakeLookup{answers: map[string][]acoustid.Candidate{
+		path("matched"):   {cand("rec-matched", "Matched", 200, 0.97)},
+		path("ambiguous"): {cand("rec-1", "Twice", 200, 0.95), cand("rec-2", "Twice", 200, 0.95)},
+		path("tagged"):    {cand("rec-wrong", "Tagged", 200, 0.99)},
+	}}
+	w := testWorker(t, pool, fake)
+	res, err := w.pass(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// seed.mp3 has no answer, so it settles as no_match beside "Unknown".
+	if res.Matched != 1 || res.Ambiguous != 1 || res.NoMatch != 2 {
+		t.Errorf("pass = %+v, want 1 matched, 1 ambiguous, 2 no match", res)
+	}
+	if m, s := mbidOf(t, pool, matched.ID); m != "rec-matched" || s != "acoustid" {
+		t.Errorf("matched track: %q from %q", m, s)
+	}
+	for _, tr := range []dbq.Track{ambiguous, none} {
+		if m, _ := mbidOf(t, pool, tr.ID); m != "" {
+			t.Errorf("%s got MBID %q from an unsettled lookup", tr.Title, m)
+		}
+	}
+	// The tagged track is never looked up, so the fake's wrong answer for it
+	// is never seen.
+	if m, s := mbidOf(t, pool, tagged.ID); m != "rec-tag" || s != "tag" {
+		t.Errorf("tagged track: %q from %q, want its tag untouched", m, s)
+	}
+
+	// Settled tracks are not looked up again.
+	before := fake.calls
+	if res, err := w.pass(ctx); err != nil || res.Processed != 0 || fake.calls != before {
+		t.Errorf("second pass = %+v (err %v, %d new calls), want nothing to do", res, err, fake.calls-before)
+	}
+
+	// The matched file changes and its new bytes no longer match: the scan
+	// drops the lookup, and the re-lookup takes the id back.
+	if err := q.DeleteAcoustIDLookup(ctx, matched.ID); err != nil {
+		t.Fatal(err)
+	}
+	fake.mu.Lock()
+	fake.answers[path("matched")] = nil
+	fake.mu.Unlock()
+	if _, err := w.pass(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if m, s := mbidOf(t, pool, matched.ID); m != "" || s != "" {
+		t.Errorf("after a non-matching re-lookup: %q from %q, want the looked-up id taken back", m, s)
+	}
+
+	cov, err := AcoustIDCoverage(ctx, pool)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cov.Total != 5 || cov.FromTag != 1 || cov.FromAcoustid != 0 || cov.Ambiguous != 1 || cov.NoMatch != 3 || cov.Pending != 0 {
+		t.Errorf("coverage = %+v", cov)
+	}
+}
+
+func TestAcoustIDLookup_StopsWhenTheServiceCannotAnswer_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	dir := t.TempDir()
+	_, album, artist := seedTrack(t, pool, filepath.Join(dir, "seed.mp3"))
+	for i := range 5 {
+		addTrack(t, q, album, artist, fmt.Sprint("T", i), filepath.Join(dir, fmt.Sprint(i, ".mp3")), nil)
+	}
+	for _, c := range []struct {
+		err     error
+		problem string
+	}{
+		{fmt.Errorf("%w: invalid API key", acoustid.ErrInvalidKey), "refused the API key"},
+		{fmt.Errorf("%w: status 503", acoustid.ErrUnavailable), "could not be reached"},
+	} {
+		fake := &fakeLookup{err: c.err}
+		w := testWorker(t, pool, fake)
+		w.runOnce(ctx)
+		// Stopped at the first answer, not one failed call per track. Two may
+		// already be in flight at concurrency 2.
+		if fake.calls > acoustIDLookupConcurrency {
+			t.Errorf("%v: %d lookups made, want the pass to stop at the first", c.err, fake.calls)
+		}
+		if st := w.Status(); st.Running || !strings.Contains(st.Problem, c.problem) {
+			t.Errorf("%v: status = %+v, want a problem mentioning %q", c.err, st, c.problem)
+		}
+		var n int
+		if err := pool.QueryRow(ctx, `SELECT count(*) FROM track_acoustid_lookups`).Scan(&n); err != nil || n != 0 {
+			t.Errorf("%v: %d lookups stored (err %v); a service failure says nothing about a track", c.err, n, err)
+		}
+	}
+}
+
+// The point of the milestone (#3921): once a lookup fills an MBID, the
+// similarity worker picks the track as a seed and can map ListenBrainz's
+// answers back to it.
+func TestAcoustIDLookup_FilledTrackReachesSimilarity_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	dir := t.TempDir()
+	tr, _, _ := seedTrack(t, pool, filepath.Join(dir, "played.mp3"))
+
+	u, err := q.CreateUser(ctx, dbq.CreateUserParams{
+		Username: dbtest.TestUserPrefix + "acoustid", PasswordHash: "x", ApiTokenHash: "acoustid-token",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	now := pgtype.Timestamptz{Time: time.Now(), Valid: true}
+	session, err := q.InsertPlaySession(ctx, dbq.InsertPlaySessionParams{UserID: u.ID, StartedAt: now})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := q.InsertPlayEvent(ctx, dbq.InsertPlayEventParams{
+		UserID: u.ID, TrackID: tr.ID, SessionID: session.ID, StartedAt: now,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	seeds := func() int {
+		t.Helper()
+		rows, err := q.ListPlayedTracksNeedingSimilarity(ctx, 100)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return len(rows)
+	}
+	if n := seeds(); n != 0 {
+		t.Fatalf("an untagged track is already a similarity seed (%d)", n)
+	}
+
+	fake := &fakeLookup{answers: map[string][]acoustid.Candidate{
+		tr.FilePath: {cand("rec-played", tr.Title, 1, 0.99)},
+	}}
+	if _, err := testWorker(t, pool, fake).pass(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if n := seeds(); n != 1 {
+		t.Errorf("after the lookup, %d similarity seeds, want the played track", n)
+	}
+	got, err := q.GetTracksByMBIDs(ctx, []string{"rec-played"})
+	if err != nil || len(got) != 1 || got[0].ID != tr.ID {
+		t.Errorf("GetTracksByMBIDs = %+v (err %v), want the played track", got, err)
+	}
+}
+
+func TestAcoustIDLookup_IdleUntilReady(t *testing.T) {
+	var nilSvc *AcoustIDSettingsService
+	if nilSvc.Get().Ready() {
+		t.Error("the defaults are ready; the lookup must ship off")
+	}
+	for _, s := range []AcoustIDSettings{{Enabled: true}, {APIKey: "k"}} {
+		if s.Ready() {
+			t.Errorf("%+v reads as ready", s)
+		}
+	}
+	if _, err := nilSvc.Set(context.Background(), AcoustIDSettingsUpdate{MinScore: 0.2}); !errors.Is(err, ErrAcoustIDSettingOutOfRange) {
+		t.Errorf("min_score 0.2: err = %v, want out of range", err)
+	}
+}

internal/library/acoustid_settings.go

@@ -0,0 +1,132 @@
+package library
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// AcoustID lookup settings (M401 #3922). Rule 25: a database row, changed
+// without a restart, shared by the worker and the admin API.
+
+// AcoustIDSettings mirrors the acoustid_settings row.
+type AcoustIDSettings struct {
+	Enabled bool
+	// APIKey is the operator's registered application key. Never sent back
+	// to the browser; the API reports only whether one is set.
+	APIKey string
+	// MinScore is the AcoustID score a recording needs to be considered.
+	MinScore float32
+	// UpdatedAt is set by the database.
+	UpdatedAt time.Time
+}
+
+// Ready reports whether the worker may call AcoustID at all.
+func (s AcoustIDSettings) Ready() bool { return s.Enabled && s.APIKey != "" }
+
+// DefaultAcoustIDSettings mirrors migration 0069's defaults: off, no key.
+var DefaultAcoustIDSettings = AcoustIDSettings{MinScore: 0.85}
+
+// The score threshold's bounds, as migration 0069's CHECK has them. Below 0.5
+// AcoustID's own docs call a match doubtful; the floor keeps a typo in the
+// field from filling the library with guesses.
+const (
+	minAcoustIDScore = 0.5
+	maxAcoustIDScore = 1
+)
+
+// ErrAcoustIDSettingOutOfRange is returned by Set for a value the CHECK would
+// reject, so the API answers 400 naming the field.
+var ErrAcoustIDSettingOutOfRange = errors.New("acoustid setting out of range")
+
+// AcoustIDSettingsUpdate is the admin save. A nil APIKey keeps the stored key;
+// an empty one clears it.
+type AcoustIDSettingsUpdate struct {
+	Enabled  bool
+	MinScore float32
+	APIKey   *string
+}
+
+// AcoustIDSettingsService caches the settings and owns their persistence.
+type AcoustIDSettingsService struct {
+	pool *pgxpool.Pool
+
+	mu  sync.RWMutex
+	cur AcoustIDSettings
+	// changed is signalled after every save, so the worker can start a pass
+	// at once instead of waiting out its tick.
+	changed chan struct{}
+}
+
+// NewAcoustIDSettingsService loads once and caches. It always returns a usable
+// service, holding the defaults (off) when the load fails; the error says so.
+func NewAcoustIDSettingsService(ctx context.Context, pool *pgxpool.Pool) (*AcoustIDSettingsService, error) {
+	s := &AcoustIDSettingsService{pool: pool, cur: DefaultAcoustIDSettings, changed: make(chan struct{}, 1)}
+	row, err := dbq.New(pool).GetAcoustIDSettings(ctx)
+	if err != nil {
+		return s, fmt.Errorf("acoustid settings: load: %w", err)
+	}
+	s.cur = acoustIDSettingsFromRow(row)
+	return s, nil
+}
+
+// Get returns the cached settings. A nil service answers with the defaults.
+func (s *AcoustIDSettingsService) Get() AcoustIDSettings {
+	if s == nil {
+		return DefaultAcoustIDSettings
+	}
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.cur
+}
+
+// Set validates, persists and re-caches.
+func (s *AcoustIDSettingsService) Set(ctx context.Context, in AcoustIDSettingsUpdate) (AcoustIDSettings, error) {
+	if in.MinScore < minAcoustIDScore || in.MinScore > maxAcoustIDScore {
+		return AcoustIDSettings{}, fmt.Errorf("%w: min_score must be %.2f-%.2f",
+			ErrAcoustIDSettingOutOfRange, float32(minAcoustIDScore), float32(maxAcoustIDScore))
+	}
+	if s == nil {
+		return AcoustIDSettings{}, errors.New("acoustid settings: no settings service")
+	}
+	params := dbq.UpdateAcoustIDSettingsParams{Enabled: in.Enabled, MinScore: in.MinScore}
+	if in.APIKey != nil {
+		params.SetApiKey = true
+		params.ApiKey = *in.APIKey
+	}
+	row, err := dbq.New(s.pool).UpdateAcoustIDSettings(ctx, params)
+	if err != nil {
+		return AcoustIDSettings{}, fmt.Errorf("acoustid settings: save: %w", err)
+	}
+	out := acoustIDSettingsFromRow(row)
+	s.mu.Lock()
+	s.cur = out
+	s.mu.Unlock()
+	select {
+	case s.changed <- struct{}{}:
+	default:
+	}
+	return out, nil
+}
+
+// Changed is signalled after a save. A nil service never signals.
+func (s *AcoustIDSettingsService) Changed() <-chan struct{} {
+	if s == nil {
+		return nil
+	}
+	return s.changed
+}
+
+func acoustIDSettingsFromRow(row dbq.AcoustidSetting) AcoustIDSettings {
+	out := AcoustIDSettings{Enabled: row.Enabled, MinScore: row.MinScore, UpdatedAt: row.UpdatedAt.Time}
+	if row.ApiKey != nil {
+		out.APIKey = *row.ApiKey
+	}
+	return out
+}

internal/library/duplicate_merge_test.go

@@ -69,7 +69,7 @@ func newMergeFixture(t *testing.T) mergeFixture {
 		}
 	}
 	// Only the copy being removed carries a recording MBID.
-	mustExec(`UPDATE tracks SET mbid = 'rec-www' WHERE id = $1`, f.remove.ID)
+	mustExec(`UPDATE tracks SET mbid = 'rec-www', mbid_source = 'tag' WHERE id = $1`, f.remove.ID)
 
 	user := func(name string) dbq.User {
 		t.Helper()

internal/library/fingerprint.go

@@ -111,6 +111,32 @@ func fpcalcArgs(path string, lengthSec int) []string {
 	}
 }
 
+// lookupFingerprintLengthSec is how much audio the AcoustID lookup print
+// covers (M401). Fixed at fpcalc's default rather than following the
+// duplicate-detection length setting: AcoustID's database is built from
+// prints that taggers such as Picard take at the default, and a lookup print
+// of a different span matches it less well.
+const lookupFingerprintLengthSec = 120
+
+// fpcalcLookupArgs asks for the COMPRESSED fingerprint, fpcalc's default
+// output and the string AcoustID's lookup takes. A second decode beside the
+// raw print, chosen over re-encoding the stored raw array in Go (M401 D1):
+// fpcalc is the reference encoder, while a subtle bug in a port would still
+// produce a well-formed string that AcoustID answers with "no match".
+func fpcalcLookupArgs(path string) []string {
+	return []string{
+		"-length", strconv.Itoa(lookupFingerprintLengthSec),
+		path,
+	}
+}
+
+// lookupFingerprint is what an AcoustID lookup sends for one file.
+type lookupFingerprint struct {
+	fingerprint string
+	// durationSec is the whole file's length, not the span fingerprinted.
+	durationSec int
+}
+
 // fingerprintResult is one attempt at both halves of a track's identity. They
 // fail independently: a file ffmpeg can demux may still defeat fpcalc.
 type fingerprintResult struct {
@@ -244,6 +270,18 @@ func computeChromaprint(ctx context.Context, path string, lengthSec int32) ([]in
 	return parseFpcalcRaw(out)
 }
 
+// computeLookupFingerprint returns the compressed fingerprint and duration an
+// AcoustID lookup needs. It fails as runFingerprintTool does, so a stall or a
+// missing fpcalc reads as inconclusive (isInconclusive) and a file fpcalc
+// rejects as a verdict.
+func computeLookupFingerprint(ctx context.Context, path string) (lookupFingerprint, error) {
+	out, err := runFingerprintTool(ctx, "fpcalc", fpcalcLookupArgs(path))
+	if err != nil {
+		return lookupFingerprint{}, err
+	}
+	return parseFpcalcCompressed(out)
+}
+
 // runFingerprintTool runs one tool under fingerprintTimeout.
 //
 // Any non-zero exit is an error, and that deliberately includes fpcalc's exit 3:
@@ -337,3 +375,50 @@ func parseFpcalcRaw(out []byte) ([]int32, error) {
 	}
 	return nil, errors.New("fpcalc printed no FINGERPRINT= line")
 }
+
+// parseFpcalcCompressed reads fpcalc's default text output:
+//
+//	DURATION=<whole seconds>
+//	FINGERPRINT=<URL-safe base64, unpadded>
+//
+// The fingerprint is kept as the opaque string fpcalc printed. It is checked
+// only for being non-empty and in fpcalc's alphabet, which catches a -raw
+// list or a truncated line; whether it is a GOOD print is AcoustID's to judge.
+func parseFpcalcCompressed(out []byte) (lookupFingerprint, error) {
+	var fp lookupFingerprint
+	var sawDuration bool
+	for _, line := range strings.Split(string(out), "\n") {
+		line = strings.TrimSpace(line)
+		if v, ok := strings.CutPrefix(line, "DURATION="); ok {
+			d, err := strconv.Atoi(v)
+			if err != nil {
+				return lookupFingerprint{}, fmt.Errorf("fpcalc duration %q: %w", v, err)
+			}
+			fp.durationSec, sawDuration = d, true
+		}
+		if v, ok := strings.CutPrefix(line, "FINGERPRINT="); ok {
+			fp.fingerprint = v
+		}
+	}
+	switch {
+	case fp.fingerprint == "":
+		return lookupFingerprint{}, errors.New("fpcalc printed no fingerprint")
+	case strings.IndexFunc(fp.fingerprint, notURLBase64) >= 0:
+		return lookupFingerprint{}, fmt.Errorf("fpcalc fingerprint %.20q… is not a compressed print", fp.fingerprint)
+	case !sawDuration:
+		return lookupFingerprint{}, errors.New("fpcalc printed no DURATION= line")
+	// AcoustID refuses a duration that is not a positive integer, and a file
+	// under a second long has nothing a lookup could match.
+	case fp.durationSec <= 0:
+		return lookupFingerprint{}, fmt.Errorf("fpcalc duration %d is too short to look up", fp.durationSec)
+	}
+	return fp, nil
+}
+
+func notURLBase64(r rune) bool {
+	switch {
+	case r >= 'A' && r <= 'Z', r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-', r == '_':
+		return false
+	}
+	return true
+}

internal/library/fingerprint_test.go

@@ -60,6 +60,67 @@ func TestParseFpcalcRaw(t *testing.T) {
 	}
 }
 
+// The lookup print is fpcalc's default output, kept as the string it printed.
+func TestParseFpcalcCompressed(t *testing.T) {
+	cases := []struct {
+		name    string
+		out     string
+		want    lookupFingerprint
+		wantErr string
+	}{
+		{
+			name: "default output",
+			out:  "DURATION=641\nFINGERPRINT=AQABz0qUkZK4oOfhL-CPc4e5C_wW2H2QH9uDL4cvoT8UNQ-eHtsE8cceeFJx\n",
+			want: lookupFingerprint{fingerprint: "AQABz0qUkZK4oOfhL-CPc4e5C_wW2H2QH9uDL4cvoT8UNQ-eHtsE8cceeFJx", durationSec: 641},
+		},
+		{
+			name: "line order does not matter",
+			out:  "FINGERPRINT=AQAB\nDURATION=3\n",
+			want: lookupFingerprint{fingerprint: "AQAB", durationSec: 3},
+		},
+		// A -raw invocation by mistake: a list of numbers is not a compressed
+		// print, and sent to AcoustID it would only come back as "no match".
+		{name: "raw list is refused", out: "DURATION=213\nFINGERPRINT=-1453821711,17\n", wantErr: "not a compressed print"},
+		{name: "standard base64 is refused", out: "DURATION=213\nFINGERPRINT=AQAB+/==\n", wantErr: "not a compressed print"},
+		{name: "empty fingerprint", out: "DURATION=213\nFINGERPRINT=\n", wantErr: "no fingerprint"},
+		{name: "no duration", out: "FINGERPRINT=AQAB\n", wantErr: "no DURATION= line"},
+		{name: "zero duration", out: "DURATION=0\nFINGERPRINT=AQAB\n", wantErr: "too short"},
+		{name: "fractional duration", out: "DURATION=12.5\nFINGERPRINT=AQAB\n", wantErr: "duration"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseFpcalcCompressed([]byte(tc.out))
+			if tc.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tc.wantErr) {
+					t.Fatalf("err = %v, want one containing %q", err, tc.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected err: %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("got %+v, want %+v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFpcalcLookupArgs_RequestCompressedOutput(t *testing.T) {
+	args := fpcalcLookupArgs("/music/a.flac")
+	for _, flag := range []string{"-raw", "-signed"} {
+		if slices.Contains(args, flag) {
+			t.Errorf("fpcalcLookupArgs has %s, so fpcalc would not print the compressed form: %v", flag, args)
+		}
+	}
+	if !followedBy(args, "-length", "120") {
+		t.Errorf("fpcalcLookupArgs does not fingerprint fpcalc's default 120s: %v", args)
+	}
+	if args[len(args)-1] != "/music/a.flac" {
+		t.Errorf("path is not last: %v", args)
+	}
+}
+
 func TestParseStreamHash(t *testing.T) {
 	// The real value ffmpeg printed for both files of the #3885 pair.
 	const www = "24e2daa3b4a534ff1a8d1a76f67810205869daf89f728d83a16625da4d28a18e"

internal/library/scanner.go

@@ -409,6 +409,12 @@ func (s *Scanner) scanFile(
 		if err := q.DeleteTrackLoudness(ctx, track.ID); err != nil {
 			s.logger.Warn("loudness: clearing stale measurement failed", "path", path, "err", err)
 		}
+		// Likewise an AcoustID lookup (M401): the worker looks the new bytes
+		// up again. A looked-up MBID stays meanwhile and is taken back only if
+		// the new lookup does not match it.
+		if err := q.DeleteAcoustIDLookup(ctx, track.ID); err != nil {
+			s.logger.Warn("acoustid: clearing stale lookup failed", "path", path, "err", err)
+		}
 	}
 
 	if knownTrack {

internal/server/server.go

@@ -108,6 +108,10 @@ type Server struct {
 	// LoudnessSettings is the DB-backed loudness analysis policy (M464 #4995),
 	// shared with the loudness backfill. Nil makes the router load its own.
 	LoudnessSettings *library.LoudnessSettingsService
+	// AcoustIDLookup is the AcoustID lookup worker (M401), whose settings,
+	// status and "look up now" the admin card drives. Nil in test contexts;
+	// one is built (and never run) so the admin routes still answer.
+	AcoustIDLookup *library.AcoustIDLookupWorker
 	// ReacqSettings is the DB-backed missing-file re-acquisition policy
 	// (milestone #290) — the same instance the sweeper in cmd/minstrel/main.go
 	// reads, so a save from the admin card reaches it without a restart
@@ -225,7 +229,15 @@ func (s *Server) Router() http.Handler {
 				s.Logger.Warn("loudness settings unavailable; serving defaults", "err", err)
 			}
 		}
-		api.Mount(r, s.Pool, s.Logger, writer, s.RecommendationCfg, recSettings, lidarrCfg, lidarrReqs, lidarrQuar, tracksSvc, playlistsSvc, s.CoverEnricher, s.CoverSettings, s.TagSettings, s.LibraryScanner, s.ScanCfg, s.DataDir, smtpSender, bus, s.PlaylistScheduler, s.StreamSecret, netSettings, reacqSettings, fpSettings, loudSettings)
+		acoustIDLookup := s.AcoustIDLookup
+		if acoustIDLookup == nil {
+			acoustIDSettings, err := library.NewAcoustIDSettingsService(context.Background(), s.Pool)
+			if err != nil {
+				s.Logger.Warn("acoustid settings unavailable; serving defaults", "err", err)
+			}
+			acoustIDLookup = library.NewAcoustIDLookupWorker(s.Pool, s.Logger, acoustIDSettings, nil)
+		}
+		api.Mount(r, s.Pool, s.Logger, writer, s.RecommendationCfg, recSettings, lidarrCfg, lidarrReqs, lidarrQuar, tracksSvc, playlistsSvc, s.CoverEnricher, s.CoverSettings, s.TagSettings, s.LibraryScanner, s.ScanCfg, s.DataDir, smtpSender, bus, s.PlaylistScheduler, s.StreamSecret, netSettings, reacqSettings, fpSettings, loudSettings, acoustIDLookup)
 		// /api/admin/scan is the only admin route owned by the server package
 		// (it needs the Scanner). Register it as a single inline-middleware
 		// route — using r.Route("/api/admin", ...) here would create a second

web/src/lib/api/admin.ts

@@ -398,6 +398,66 @@ export async function updateLoudnessSettings(s: LoudnessSettings): Promise<Loudn
   return api.put<LoudnessSettings>('/api/admin/library/loudness-settings', s);
 }
 
+// AcoustID recording-id lookup (M401) ---------------------------------------
+
+export type AcoustIDSettings = {
+  enabled: boolean;
+  min_score: number;
+  /** The key itself is never sent back, only whether one is stored. */
+  api_key_set: boolean;
+};
+
+export type AcoustIDOverview = {
+  settings: AcoustIDSettings;
+  /** Switched on and holding a key: the worker will call AcoustID. */
+  ready: boolean;
+  status: { running: boolean; last_pass_at: string | null; problem: string };
+  /** from_tag + from_acoustid + tracks with no MBID = total. */
+  coverage: {
+    total: number;
+    from_tag: number;
+    from_acoustid: number;
+    ambiguous: number;
+    no_match: number;
+    failed: number;
+    pending: number;
+  };
+};
+
+export type AcoustIDUnsettled = {
+  track_id: string;
+  title: string;
+  artist: string;
+  album: string;
+  file_path: string;
+  state: 'ambiguous' | 'failed';
+  best_score: number | null;
+  candidates: number;
+  detail: string | null;
+  looked_up_at: string;
+};
+
+export async function getAcoustID(): Promise<AcoustIDOverview> {
+  return api.get<AcoustIDOverview>('/api/admin/library/acoustid');
+}
+
+/** api_key left out keeps the stored key; an empty string clears it. */
+export async function updateAcoustIDSettings(s: {
+  enabled: boolean;
+  min_score: number;
+  api_key?: string;
+}): Promise<AcoustIDSettings> {
+  return api.put<AcoustIDSettings>('/api/admin/library/acoustid-settings', s);
+}
+
+export async function runAcoustIDLookup(): Promise<void> {
+  await api.post<null>('/api/admin/library/acoustid/run', {});
+}
+
+export async function listUnsettledAcoustID(): Promise<AcoustIDUnsettled[]> {
+  return api.get<AcoustIDUnsettled[]>('/api/admin/library/acoustid/unsettled');
+}
+
 // Cover-art providers ------------------------------------------------------
 
 export type CoverProviderCapability = 'album_cover' | 'artist_thumb' | 'artist_fanart';

web/src/lib/components/AcoustIDCard.svelte

@@ -0,0 +1,337 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import {
+    getAcoustID,
+    listUnsettledAcoustID,
+    runAcoustIDLookup,
+    updateAcoustIDSettings,
+    type AcoustIDOverview,
+    type AcoustIDUnsettled
+  } from '$lib/api/admin';
+  import { errMessage } from '$lib/api/errors';
+  import { pushToast } from '$lib/stores/toast.svelte';
+
+  // AcoustID recording-id lookup (M401): fills the MusicBrainz ids that
+  // untagged tracks lack, so the similarity arms can see them. Off until the
+  // operator adds their own key (rule 26), and it never gates anything else:
+  // when AcoustID is unreachable the card says so and nothing else notices.
+
+  let overview = $state<AcoustIDOverview | null>(null);
+  let enabled = $state(false);
+  let minScore = $state(0.85);
+  // Empty means "keep the stored key". The key itself never comes back.
+  let keyInput = $state('');
+  let saving = $state(false);
+  let starting = $state(false);
+  let loadError = $state(false);
+  let unsettled = $state<AcoustIDUnsettled[] | null>(null);
+
+  const scoreOk = $derived(Number.isFinite(minScore) && minScore >= 0.5 && minScore <= 1);
+  const dirty = $derived(
+    !!overview &&
+      (enabled !== overview.settings.enabled ||
+        minScore !== overview.settings.min_score ||
+        keyInput.trim() !== '')
+  );
+  const withoutId = $derived(
+    overview
+      ? overview.coverage.total - overview.coverage.from_tag - overview.coverage.from_acoustid
+      : 0
+  );
+
+  async function load() {
+    try {
+      overview = await getAcoustID();
+      enabled = overview.settings.enabled;
+      minScore = overview.settings.min_score;
+      loadError = false;
+    } catch {
+      loadError = true;
+    }
+  }
+
+  // The figures move a track every second or two during a pass; a failed read
+  // keeps the last ones rather than blanking the card.
+  async function refresh() {
+    try {
+      overview = await getAcoustID();
+    } catch {
+      // Keep what we had.
+    }
+  }
+
+  onMount(() => {
+    load();
+    const timer = setInterval(refresh, 30_000);
+    return () => clearInterval(timer);
+  });
+
+  async function save() {
+    if (!scoreOk) return;
+    saving = true;
+    try {
+      const key = keyInput.trim();
+      await updateAcoustIDSettings({
+        enabled,
+        min_score: minScore,
+        ...(key ? { api_key: key } : {})
+      });
+      keyInput = '';
+      pushToast('AcoustID settings saved.');
+      await load();
+    } catch (e) {
+      pushToast(errMessage(e), 'error');
+    } finally {
+      saving = false;
+    }
+  }
+
+  async function forgetKey() {
+    saving = true;
+    try {
+      await updateAcoustIDSettings({ enabled, min_score: minScore, api_key: '' });
+      pushToast('AcoustID key removed.');
+      await load();
+    } catch (e) {
+      pushToast(errMessage(e), 'error');
+    } finally {
+      saving = false;
+    }
+  }
+
+  async function runNow() {
+    starting = true;
+    try {
+      await runAcoustIDLookup();
+      pushToast('Looking up untagged tracks.');
+      await refresh();
+    } catch (e) {
+      pushToast(errMessage(e), 'error');
+    } finally {
+      starting = false;
+    }
+  }
+
+  async function toggleUnsettled(e: Event) {
+    if ((e.currentTarget as HTMLDetailsElement).open && unsettled === null) {
+      try {
+        unsettled = await listUnsettledAcoustID();
+      } catch (err) {
+        pushToast(errMessage(err), 'error');
+      }
+    }
+  }
+
+  const rowClass = 'flex items-center justify-between gap-4 py-2';
+  const inputClass =
+    'rounded-md border border-border bg-background px-3 py-1.5 text-sm text-text-primary ' +
+    'placeholder:text-text-muted focus:outline-none focus:ring-2 focus:ring-accent';
+</script>
+
+<section class="space-y-4 rounded-xl border border-border bg-surface p-5" data-testid="acoustid-card">
+  <div class="flex items-center justify-between gap-4">
+    <div>
+      <h3 class="font-display text-lg font-medium text-text-primary">AcoustID</h3>
+      <p class="mt-1 text-sm text-text-secondary">
+        Finds MusicBrainz ids for untagged tracks, so Songs-like and radio can place them.
+      </p>
+    </div>
+    {#if overview}
+      {#if overview.ready && !overview.status.problem}
+        <span
+          class="inline-flex shrink-0 items-center gap-2 rounded-md bg-accent-tint px-3 py-1 text-xs font-medium text-action-primary"
+        >
+          <span class="h-1.5 w-1.5 rounded-full bg-action-primary"></span>
+          {overview.status.running ? 'Looking up' : 'On'}
+        </span>
+      {:else}
+        <span
+          class="inline-flex shrink-0 items-center gap-2 rounded-md border border-border px-3 py-1 text-xs text-text-muted"
+          data-testid="acoustid-state"
+        >
+          <span class="h-1.5 w-1.5 rounded-full bg-text-muted"></span>
+          {#if overview.ready}Needs attention{:else if !overview.settings.api_key_set}Needs a key{:else}Off{/if}
+        </span>
+      {/if}
+    {/if}
+  </div>
+
+  {#if loadError}
+    <p class="text-sm text-action-destructive">
+      Couldn't load AcoustID settings.
+      <button type="button" class="underline hover:no-underline" onclick={load}>Try again</button>
+    </p>
+  {:else if overview === null}
+    <p class="text-sm text-text-secondary">Loading AcoustID settings…</p>
+  {:else}
+    {#if overview.status.problem}
+      <p class="text-sm text-action-destructive" data-testid="acoustid-problem">
+        {overview.status.problem}
+      </p>
+    {/if}
+
+    <div class="divide-y divide-border">
+      <label class={rowClass}>
+        <span>
+          <span class="block text-sm text-text-primary">Look up untagged tracks</span>
+          <span class="block text-xs text-text-secondary">Sends audio fingerprints to AcoustID.</span>
+        </span>
+        <input type="checkbox" bind:checked={enabled} />
+      </label>
+
+      <div class={rowClass}>
+        <label for="acoustid-key">
+          <span class="block text-sm text-text-primary">API key</span>
+          <span class="block text-xs text-text-secondary">
+            Free for non-commercial use.
+            <a
+              href="https://acoustid.org/new-application"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="underline hover:no-underline">Register an application</a
+            >
+          </span>
+        </label>
+        <div class="flex items-center gap-2">
+          <input
+            id="acoustid-key"
+            type="password"
+            autocomplete="off"
+            bind:value={keyInput}
+            placeholder={overview.settings.api_key_set ? 'Stored' : 'Paste key'}
+            class="{inputClass} w-40 font-mono"
+          />
+          {#if overview.settings.api_key_set}
+            <button
+              type="button"
+              class="text-xs text-text-secondary underline hover:no-underline"
+              disabled={saving}
+              onclick={forgetKey}>Remove</button
+            >
+          {/if}
+        </div>
+      </div>
+
+      <label class={rowClass}>
+        <span>
+          <span class="block text-sm text-text-primary">Minimum score</span>
+          <span class="block text-xs text-text-secondary">How sure AcoustID must be, 0.5 to 1.</span>
+        </span>
+        <input
+          type="number"
+          min="0.5"
+          max="1"
+          step="0.01"
+          bind:value={minScore}
+          class="{inputClass} w-24 text-right"
+        />
+      </label>
+    </div>
+
+    {#if !scoreOk}
+      <p class="text-xs text-action-destructive" data-testid="acoustid-problems">
+        Minimum score must be from 0.5 to 1.
+      </p>
+    {/if}
+
+    <div class="flex justify-end">
+      <button
+        type="button"
+        class="rounded-md bg-action-secondary px-4 py-2 text-sm text-action-fg hover:opacity-90
+               focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent
+               disabled:cursor-not-allowed disabled:opacity-50"
+        disabled={!dirty || saving || !scoreOk}
+        onclick={save}
+      >
+        {saving ? 'Saving…' : 'Save'}
+      </button>
+    </div>
+
+    {#if overview.coverage.total > 0}
+      <div class="border-t border-border pt-3" data-testid="acoustid-coverage">
+        <h4 class="text-sm font-medium text-text-primary">Recording ids</h4>
+        <dl class="mt-1 divide-y divide-border text-sm">
+          <div class={rowClass}>
+            <dt class="text-text-secondary">From tags</dt>
+            <dd class="tabular-nums">{overview.coverage.from_tag.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt class="text-text-secondary">Looked up</dt>
+            <dd class="tabular-nums">{overview.coverage.from_acoustid.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt class="text-text-secondary">None</dt>
+            <dd class="tabular-nums">{withoutId.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt class="pl-4 text-text-secondary">Waiting to be looked up</dt>
+            <dd class="tabular-nums">{overview.coverage.pending.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt class="pl-4 text-text-secondary" title="AcoustID knows no recording for these">
+              No match
+            </dt>
+            <dd class="tabular-nums">{overview.coverage.no_match.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt
+              class="pl-4 text-text-secondary"
+              title="Several recordings fit and nothing told them apart, so none was written"
+            >
+              Ambiguous
+            </dt>
+            <dd class="tabular-nums">{overview.coverage.ambiguous.toLocaleString()}</dd>
+          </div>
+          <div class={rowClass}>
+            <dt class="pl-4 text-text-secondary" title="The file couldn't be fingerprinted">
+              Failed
+            </dt>
+            <dd class="tabular-nums">{overview.coverage.failed.toLocaleString()}</dd>
+          </div>
+        </dl>
+        <div class="mt-2 flex justify-end">
+          <button
+            type="button"
+            class="rounded-md border border-border px-4 py-2 text-sm text-text-primary hover:bg-background
+                   focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent
+                   disabled:cursor-not-allowed disabled:opacity-50"
+            disabled={!overview.ready || overview.status.running || starting}
+            title={overview.ready ? undefined : 'Switch the lookup on and add a key first'}
+            onclick={runNow}
+          >
+            {overview.status.running ? 'Looking up…' : 'Look up now'}
+          </button>
+        </div>
+      </div>
+
+      {#if overview.coverage.ambiguous + overview.coverage.failed > 0}
+        <details class="border-t border-border pt-3" ontoggle={toggleUnsettled}>
+          <summary class="cursor-pointer text-sm text-text-primary">
+            Tracks the lookup couldn't settle ({(
+              overview.coverage.ambiguous + overview.coverage.failed
+            ).toLocaleString()})
+          </summary>
+          {#if unsettled === null}
+            <p class="mt-2 text-sm text-text-secondary">Loading tracks…</p>
+          {:else}
+            <ul class="mt-2 divide-y divide-border text-sm" data-testid="acoustid-unsettled">
+              {#each unsettled as t (t.track_id)}
+                <li class="flex items-center justify-between gap-4 py-2">
+                  <span class="min-w-0">
+                    <span class="block truncate text-text-primary">{t.title}</span>
+                    <span class="block truncate text-xs text-text-secondary"
+                      >{t.artist} · {t.album}</span
+                    >
+                  </span>
+                  <span class="shrink-0 text-xs text-text-muted" title={t.detail ?? undefined}>
+                    {t.state === 'ambiguous' ? `${t.candidates} recordings` : 'failed'}
+                  </span>
+                </li>
+              {/each}
+            </ul>
+          {/if}
+        </details>
+      {/if}
+    {/if}
+  {/if}
+</section>

web/src/lib/components/AcoustIDCard.test.ts

@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/svelte";
+import type { AcoustIDOverview } from "$lib/api/admin";
+
+vi.mock("$lib/api/admin", () => ({
+  getAcoustID: vi.fn(),
+  updateAcoustIDSettings: vi.fn(),
+  runAcoustIDLookup: vi.fn(),
+  listUnsettledAcoustID: vi.fn(),
+}));
+
+vi.mock("$lib/stores/toast.svelte", () => ({ pushToast: vi.fn() }));
+
+import AcoustIDCard from "./AcoustIDCard.svelte";
+import {
+  getAcoustID,
+  listUnsettledAcoustID,
+  runAcoustIDLookup,
+  updateAcoustIDSettings,
+} from "$lib/api/admin";
+
+const base: AcoustIDOverview = {
+  settings: { enabled: true, min_score: 0.85, api_key_set: true },
+  ready: true,
+  status: { running: false, last_pass_at: null, problem: "" },
+  coverage: {
+    total: 1000,
+    from_tag: 700,
+    from_acoustid: 150,
+    ambiguous: 12,
+    no_match: 80,
+    failed: 3,
+    pending: 55,
+  },
+};
+
+function overview(over: Partial<AcoustIDOverview> = {}): AcoustIDOverview {
+  return { ...base, ...over, settings: { ...base.settings, ...over.settings } };
+}
+
+afterEach(() => vi.clearAllMocks());
+
+async function renderCard(o: AcoustIDOverview = base) {
+  vi.mocked(getAcoustID).mockResolvedValue(o);
+  render(AcoustIDCard);
+  await screen.findByRole("checkbox", { name: /look up untagged tracks/i });
+}
+
+const saveButton = () => screen.getByRole("button", { name: /^save$/i });
+const lookUpNow = () => screen.getByRole("button", { name: /look up now/i });
+
+describe("AcoustIDCard", () => {
+  test("shows where the library’s recording ids came from", async () => {
+    await renderCard();
+    const cov = screen.getByTestId("acoustid-coverage");
+    // 1000 - 700 - 150 have no id.
+    for (const [label, n] of [
+      ["From tags", "700"],
+      ["Looked up", "150"],
+      ["None", "150"],
+      ["Waiting to be looked up", "55"],
+      ["No match", "80"],
+      ["Ambiguous", "12"],
+      ["Failed", "3"],
+    ]) {
+      const row = [...cov.querySelectorAll("dt")].find(
+        (dt) => dt.textContent?.trim() === label,
+      );
+      expect(row?.nextElementSibling?.textContent?.trim(), label).toBe(n);
+    }
+  });
+
+  test("never shows the stored key, and sends one only when typed", async () => {
+    vi.mocked(updateAcoustIDSettings).mockResolvedValue(base.settings);
+    await renderCard();
+    const key = screen.getByLabelText(/api key/i) as HTMLInputElement;
+    expect(key.value).toBe("");
+    expect(key.placeholder).toBe("Stored");
+    expect(saveButton()).toHaveProperty("disabled", true);
+
+    await fireEvent.input(
+      screen.getByRole("spinbutton", { name: /minimum score/i }),
+      {
+        target: { value: "0.9" },
+      },
+    );
+    await fireEvent.click(saveButton());
+    await waitFor(() =>
+      expect(updateAcoustIDSettings).toHaveBeenCalledWith({
+        enabled: true,
+        min_score: 0.9,
+      }),
+    );
+
+    await fireEvent.input(key, { target: { value: " new-key " } });
+    await fireEvent.click(saveButton());
+    await waitFor(() =>
+      expect(updateAcoustIDSettings).toHaveBeenLastCalledWith({
+        enabled: true,
+        min_score: 0.85,
+        api_key: "new-key",
+      }),
+    );
+  });
+
+  test("a score outside 0.5 to 1 is named and cannot be saved", async () => {
+    await renderCard();
+    await fireEvent.input(
+      screen.getByRole("spinbutton", { name: /minimum score/i }),
+      {
+        target: { value: "0.3" },
+      },
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("acoustid-problems").textContent).toMatch(
+        /0\.5 to 1/,
+      ),
+    );
+    expect(saveButton()).toHaveProperty("disabled", true);
+  });
+
+  // Rule 164: off, keyless or unreachable is a visible state, not a silent one.
+  test("says why it is not looking anything up", async () => {
+    await renderCard(
+      overview({
+        ready: false,
+        settings: { enabled: true, min_score: 0.85, api_key_set: false },
+      }),
+    );
+    expect(screen.getByTestId("acoustid-state").textContent).toMatch(
+      /needs a key/i,
+    );
+    expect(lookUpNow()).toHaveProperty("disabled", true);
+  });
+
+  test("a pass that stopped short says why", async () => {
+    await renderCard(
+      overview({
+        status: {
+          running: false,
+          last_pass_at: "2026-10-07T03:00:00Z",
+          problem: "AcoustID refused the API key. Check it in Settings.",
+        },
+      }),
+    );
+    expect(screen.getByTestId("acoustid-problem").textContent).toMatch(
+      /refused the API key/,
+    );
+    expect(screen.getByTestId("acoustid-state").textContent).toMatch(
+      /needs attention/i,
+    );
+  });
+
+  test("look up now starts a pass", async () => {
+    vi.mocked(runAcoustIDLookup).mockResolvedValue();
+    await renderCard();
+    await fireEvent.click(lookUpNow());
+    await waitFor(() => expect(runAcoustIDLookup).toHaveBeenCalledTimes(1));
+  });
+
+  test("the tracks a lookup could not settle can be found", async () => {
+    vi.mocked(listUnsettledAcoustID).mockResolvedValue([
+      {
+        track_id: "t1",
+        title: "WWW",
+        artist: "Moe Shop",
+        album: "WWW",
+        file_path: "/music/a.mp3",
+        state: "ambiguous",
+        best_score: 0.97,
+        candidates: 2,
+        detail: null,
+        looked_up_at: "2026-10-07T03:00:00Z",
+      },
+    ]);
+    await renderCard();
+    const details = screen
+      .getByText(/couldn't settle \(15\)/i)
+      .closest("details")!;
+    details.open = true;
+    await fireEvent(details, new Event("toggle"));
+    const list = await screen.findByTestId("acoustid-unsettled");
+    expect(list.textContent).toMatch(/WWW/);
+    expect(list.textContent).toMatch(/2 recordings/);
+  });
+
+  test("a failed load offers a retry", async () => {
+    vi.mocked(getAcoustID).mockRejectedValue(new Error("boom"));
+    render(AcoustIDCard);
+    await screen.findByText(/couldn't load acoustid settings/i);
+    expect(screen.getByRole("button", { name: /try again/i })).toBeTruthy();
+  });
+});

web/src/routes/admin/integrations/+page.svelte

@@ -27,6 +27,7 @@
   import { errCode } from '$lib/api/errors';
   import { pushToast } from '$lib/stores/toast.svelte';
   import Modal from '$lib/components/Modal.svelte';
+  import AcoustIDCard from '$lib/components/AcoustIDCard.svelte';
   import NetworkSettingsCard from '$lib/components/NetworkSettingsCard.svelte';
   import PublicAddressCard from '$lib/components/PublicAddressCard.svelte';
   import type { LidarrConfig, LidarrTestResult } from '$lib/api/types';
@@ -549,22 +550,9 @@
     </div>
   </section>
 
-  <!-- MusicBrainz overrides — visually present, not implemented. Foreshadows
+  <!-- AcoustID recording-id lookup (M401). Took the place of a "MusicBrainz
-       future integrations so the page doesn't read like Lidarr-only. -->
+       overrides" placeholder that held the slot for a non-Lidarr integration. -->
-  <section class="space-y-2 rounded-xl border border-border bg-surface p-5 opacity-60">
+  <AcoustIDCard />
-    <div class="flex items-center justify-between">
-      <h3 class="font-display text-lg font-medium text-text-primary">
-        MusicBrainz overrides
-      </h3>
-      <span
-        class="inline-flex items-center gap-2 rounded-md border border-border px-3 py-1 text-xs text-text-muted"
-      >
-        <span class="h-1.5 w-1.5 rounded-full bg-text-muted"></span>
-        unset
-      </span>
-    </div>
-    <p class="text-sm text-text-secondary">Not yet configured.</p>
-  </section>
 
   <!-- Cover art providers -->
   <section class="space-y-4 rounded-xl border border-border bg-surface p-5">

web/src/routes/admin/integrations/integrations.test.ts

@@ -28,7 +28,13 @@ vi.mock('$lib/api/admin', () => ({
   testTagProvider: vi.fn(),
   createSMTPConfigQuery: vi.fn(),
   updateSMTPConfig: vi.fn(),
-  testSMTPConfig: vi.fn()
+  testSMTPConfig: vi.fn(),
+  // AcoustIDCard loads on mount; a never-settling read leaves it on its own
+  // "Loading AcoustID settings…", which the page's /loading…/i queries skip.
+  getAcoustID: vi.fn(() => new Promise(() => {})),
+  updateAcoustIDSettings: vi.fn(),
+  runAcoustIDLookup: vi.fn(),
+  listUnsettledAcoustID: vi.fn()
 }));
 
 import IntegrationsPage from './+page.svelte';