Add album art search, auto-match and a whole-album tag editor

Search iTunes, Deezer, MusicBrainz, DuckDuckGo and Google for square covers,
embed them and/or save cover.jpg, auto-match covers for albums, and edit an
album's shared tags and track list in one place.

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

internal/engine/artwork.go

@@ -0,0 +1,565 @@
+package engine
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"unicode"
+
+	"github.com/cdnutter/playlink/internal/art"
+	"github.com/cdnutter/playlink/internal/fsops"
+	"github.com/cdnutter/playlink/internal/store"
+	"github.com/cdnutter/playlink/internal/tags"
+)
+
+// FolderCoverName is the album-folder image playlink writes (read by Plex,
+// Jellyfin, Navidrome and most players).
+const FolderCoverName = "cover.jpg"
+
+var folderCoverNames = []string{"cover.jpg", "folder.jpg", "cover.png", "folder.png", "front.jpg"}
+
+// SetArt enables album art search and preparation.
+func (e *Engine) SetArt(c *art.Client, s *art.Store) { e.artClient, e.artStore = c, s }
+
+func (e *Engine) preparedArt(token string) (string, error) {
+	if e.artStore == nil {
+		return "", errors.New("album art is not available")
+	}
+	return e.artStore.Path(token)
+}
+
+// ---- settings ----
+
+// ArtSettings are the album art options (Settings -> Album art).
+type ArtSettings struct {
+	Sources   []string `json:"sources"`
+	GoogleKey string   `json:"google_key"`
+	GoogleCX  string   `json:"google_cx"`
+	MaxSize   int      `json:"max_size"` // longest side of prepared covers; 0 keeps the original
+	MinSize   int      `json:"min_size"` // smallest search result shown
+}
+
+func (e *Engine) ArtSettings(ctx context.Context) ArtSettings {
+	s := ArtSettings{
+		GoogleKey: e.st.Setting(ctx, "art_google_key", ""),
+		GoogleCX:  e.st.Setting(ctx, "art_google_cx", ""),
+	}
+	src := e.st.Setting(ctx, "art_sources", strings.Join([]string{art.ITunes, art.Deezer, art.MusicBrainz, art.DuckDuckGo, art.Google}, ","))
+	for _, x := range strings.Split(src, ",") {
+		if x != "" {
+			s.Sources = append(s.Sources, x)
+		}
+	}
+	s.MaxSize, _ = strconv.Atoi(e.st.Setting(ctx, "art_max_size", "1000"))
+	s.MinSize, _ = strconv.Atoi(e.st.Setting(ctx, "art_min_size", "500"))
+	return s
+}
+
+func (e *Engine) SetArtSettings(ctx context.Context, s ArtSettings) error {
+	known := map[string]bool{}
+	for _, x := range art.AllSources {
+		known[x] = true
+	}
+	var src []string
+	for _, x := range s.Sources {
+		if !known[x] {
+			return fmt.Errorf("unknown art source %q", x)
+		}
+		src = append(src, x)
+	}
+	if s.MaxSize != 0 && (s.MaxSize < 300 || s.MaxSize > 4000) {
+		return errors.New("cover size must be 300-4000 pixels, or 0 to keep the original")
+	}
+	if s.MinSize < 100 || s.MinSize > 3000 {
+		return errors.New("minimum search result size must be 100-3000 pixels")
+	}
+	for k, v := range map[string]string{"art_sources": strings.Join(src, ","), "art_google_key": strings.TrimSpace(s.GoogleKey),
+		"art_google_cx": strings.TrimSpace(s.GoogleCX), "art_max_size": strconv.Itoa(s.MaxSize), "art_min_size": strconv.Itoa(s.MinSize)} {
+		if err := e.st.SetSetting(ctx, k, v); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (e *Engine) artConfig(ctx context.Context, sources []string) art.Config {
+	s := e.ArtSettings(ctx)
+	enabled := map[string]bool{}
+	for _, x := range s.Sources {
+		enabled[x] = true
+	}
+	var use []string
+	for _, x := range sources {
+		if enabled[x] {
+			use = append(use, x)
+		}
+	}
+	if len(sources) == 0 {
+		use = s.Sources
+	}
+	return art.Config{Sources: use, GoogleKey: s.GoogleKey, GoogleCX: s.GoogleCX, MinSize: s.MinSize}
+}
+
+// SearchArt searches album art (square images only).
+func (e *Engine) SearchArt(ctx context.Context, q art.Query, sources []string) ([]art.Result, map[string]string, error) {
+	if e.artClient == nil {
+		return nil, nil, errors.New("album art is not available")
+	}
+	res, errs := e.artClient.Search(ctx, q, e.artConfig(ctx, sources))
+	if res == nil {
+		res = []art.Result{}
+	}
+	return res, errs, nil
+}
+
+// PrepareArtURL downloads and prepares an image for applying.
+func (e *Engine) PrepareArtURL(ctx context.Context, u string) (art.Prepared, error) {
+	if e.artClient == nil || e.artStore == nil {
+		return art.Prepared{}, errors.New("album art is not available")
+	}
+	b, err := e.artClient.FetchImage(ctx, u)
+	if err != nil {
+		return art.Prepared{}, err
+	}
+	return e.artStore.Prepare(ctx, b, e.ArtSettings(ctx).MaxSize)
+}
+
+// PrepareArtUpload prepares an uploaded image.
+func (e *Engine) PrepareArtUpload(ctx context.Context, r io.Reader) (art.Prepared, error) {
+	if e.artStore == nil {
+		return art.Prepared{}, errors.New("album art is not available")
+	}
+	b, err := io.ReadAll(io.LimitReader(r, art.MaxImageBytes+1))
+	if err != nil {
+		return art.Prepared{}, err
+	}
+	if len(b) > art.MaxImageBytes {
+		return art.Prepared{}, errors.New("the image is larger than 20 MB")
+	}
+	return e.artStore.Prepare(ctx, b, e.ArtSettings(ctx).MaxSize)
+}
+
+func (e *Engine) PreparedArtPath(token string) (string, error) { return e.preparedArt(token) }
+
+// FetchArtThumb downloads a search result thumbnail for display.
+func (e *Engine) FetchArtThumb(ctx context.Context, u string) ([]byte, error) {
+	if e.artClient == nil {
+		return nil, errors.New("album art is not available")
+	}
+	return e.artClient.FetchImage(ctx, u)
+}
+
+// ---- reading covers ----
+
+// Cover returns the art for a song (embedded) or an album folder (its image
+// file), as image bytes.
+func (e *Engine) Cover(ctx context.Context, pairID int64, side, rel string) ([]byte, error) {
+	l, err := e.loadPair(ctx, pairID)
+	if err != nil {
+		return nil, err
+	}
+	root, err := sideRoot(l, side)
+	if err != nil {
+		return nil, err
+	}
+	abs := root.Path
+	if rel != "" {
+		if abs, err = root.Resolve(rel); err != nil {
+			return nil, err
+		}
+	}
+	fi, err := os.Lstat(abs)
+	if err != nil {
+		return nil, err
+	}
+	if fi.IsDir() {
+		for _, n := range folderCoverNames {
+			p := filepath.Join(abs, n)
+			if in, err := fsops.RegularFile(p); err == nil && in.Size < art.MaxImageBytes {
+				return os.ReadFile(p)
+			}
+		}
+		return nil, nil
+	}
+	if !fi.Mode().IsRegular() {
+		return nil, fsops.ErrNotRegular
+	}
+	return e.tagTools.Cover(ctx, abs)
+}
+
+// AlbumSong is one song in the album editor.
+type AlbumSong struct {
+	TagFile
+	HasCover   bool `json:"has_cover"`
+	EmbedCover bool `json:"embed_cover"` // the format can hold embedded art
+}
+
+// Album is an album folder with its songs (disc folders included).
+type Album struct {
+	Folder      string      `json:"folder"`
+	Songs       []AlbumSong `json:"songs"`
+	FolderCover string      `json:"folder_cover,omitempty"` // name of the folder image, if any
+}
+
+func (e *Engine) AlbumSongs(ctx context.Context, pairID int64, side, folder string) (Album, error) {
+	a := Album{Folder: folder, Songs: []AlbumSong{}}
+	if !e.TagEditing() {
+		return a, ErrNoTagTools
+	}
+	l, err := e.loadPair(ctx, pairID)
+	if err != nil {
+		return a, err
+	}
+	root, err := sideRoot(l, side)
+	if err != nil {
+		return a, err
+	}
+	dir := root.Path
+	if folder != "" {
+		if dir, err = root.Resolve(folder); err != nil {
+			return a, err
+		}
+	}
+	for _, n := range folderCoverNames {
+		if _, err := fsops.RegularFile(filepath.Join(dir, n)); err == nil {
+			a.FolderCover = n
+			break
+		}
+	}
+	var rels []string
+	collect := func(d, prefix string) {
+		ents, _ := os.ReadDir(d)
+		for _, en := range ents {
+			if en.Type().IsRegular() && l.hasExt(en.Name()) && !strings.HasPrefix(en.Name(), ".") {
+				rels = append(rels, filepath.Join(prefix, en.Name()))
+			}
+		}
+	}
+	collect(dir, folder)
+	ents, _ := os.ReadDir(dir)
+	for _, en := range ents {
+		if en.IsDir() && discFolder.MatchString(en.Name()) {
+			collect(filepath.Join(dir, en.Name()), filepath.Join(folder, en.Name()))
+		}
+	}
+	if len(rels) == 0 {
+		return a, nil
+	}
+	if len(rels) > maxTagFiles {
+		return a, fmt.Errorf("%w: the folder has more than %d songs", ErrInvalidBulk, maxTagFiles)
+	}
+	files, err := e.ReadTags(ctx, pairID, side, rels)
+	if err != nil {
+		return a, err
+	}
+	for _, f := range files {
+		s := AlbumSong{TagFile: f}
+		if fm, ok := tags.FormatOf(f.Rel); ok {
+			s.EmbedCover = fm.EmbedsCover()
+		}
+		if f.Editable {
+			if abs, err := root.Resolve(f.Rel); err == nil {
+				s.HasCover = e.tagTools.HasCover(ctx, abs)
+			}
+		}
+		a.Songs = append(a.Songs, s)
+	}
+	return a, nil
+}
+
+// ---- folder image ----
+
+type coverDetail struct {
+	Side    string `json:"side"`
+	Existed bool   `json:"existed"`
+	Size    int64  `json:"size"`
+	Mtime   int64  `json:"mtime"`
+}
+
+// writeFolderCover writes cover.jpg into an album folder. An existing one is
+// kept in quarantine first; the operation can be undone.
+func (e *Engine) writeFolderCover(ctx context.Context, l *libs, side, folder, src string) error {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	root, _ := sideRoot(l, side)
+	rel := filepath.Join(folder, FolderCoverName)
+	abs, err := root.Resolve(rel)
+	if err != nil {
+		return err
+	}
+	o := store.Operation{PairID: l.pair.ID, Action: store.ActCover, QuarantineSide: side, Trigger: "art"}
+	setSidePath(&o, side, rel)
+	old, oldErr := fsops.RegularFile(abs)
+	d := coverDetail{Side: side, Existed: oldErr == nil}
+	o.Detail, _ = json.Marshal(d)
+	if err := e.begin(ctx, &o); err != nil {
+		return err
+	}
+	if o.DryRun {
+		return nil
+	}
+	tmp := filepath.Join(filepath.Dir(abs), fsops.TmpPrefix+"cover.jpg")
+	_ = os.Remove(tmp)
+	err = func() error {
+		if d.Existed {
+			q := quarantinePath(l, o.ID, side, rel)
+			if err := fsops.MkdirAllLike(filepath.Dir(q)); err != nil {
+				return err
+			}
+			if err := fsops.LinkNew(abs, old, q); err != nil {
+				return fmt.Errorf("quarantine: %w", err)
+			}
+			e.setQuarantine(ctx, o.ID, q)
+		}
+		if err := fsops.CopyNew(src, tmp, 0o644); err != nil {
+			return err
+		}
+		if err := os.Rename(tmp, abs); err != nil {
+			_ = os.Remove(tmp)
+			return err
+		}
+		in, _ := fsops.Lstat(abs)
+		d.Size, d.Mtime = in.Size, in.MtimeNs
+		det, _ := json.Marshal(d)
+		_, _ = e.st.DB.ExecContext(ctx, `UPDATE operations SET detail = ? WHERE id = ?`, string(det), o.ID)
+		return fsops.SyncDir(filepath.Dir(abs))
+	}()
+	return e.finish(ctx, &o, err)
+}
+
+// undoCover restores the previous folder image, or removes the new one.
+func (e *Engine) undoCover(l *libs, o store.Operation) error {
+	var d coverDetail
+	if err := json.Unmarshal(o.Detail, &d); err != nil {
+		return err
+	}
+	root, err := sideRoot(l, d.Side)
+	if err != nil {
+		return err
+	}
+	rel := o.RelSlave
+	if d.Side == SideMaster {
+		rel = o.RelMaster
+	}
+	abs, err := root.Resolve(rel)
+	if err != nil {
+		return err
+	}
+	cur, err := fsops.RegularFile(abs)
+	if err != nil {
+		return err
+	}
+	if !cur.Unchanged(d.Size, d.Mtime) {
+		return fmt.Errorf("%s changed after it was written; refusing to undo", rel)
+	}
+	if d.Existed {
+		qi, err := e.quarantined(l, o.QuarantinePath)
+		if err != nil {
+			return err
+		}
+		if err := fsops.ReplaceWithLink(o.QuarantinePath, qi, abs); err != nil {
+			return err
+		}
+		dropQuarantine(l, o.QuarantinePath, qi)
+		return nil
+	}
+	if err := os.Remove(abs); err != nil {
+		return err
+	}
+	return fsops.SyncDir(filepath.Dir(abs))
+}
+
+// ---- automatic matching ----
+
+// ArtMatch are the options of an automatic match.
+type ArtMatch struct {
+	Side        string `json:"side"`
+	Folder      string `json:"folder"`
+	OnlyMissing bool   `json:"only_missing"`
+	Embed       bool   `json:"embed"`
+	FolderFile  bool   `json:"folder_file"`
+}
+
+// matchKey normalizes an artist or album name for comparison: case,
+// punctuation, a leading "The" and release labels such as "(Deluxe)" are
+// ignored.
+func matchKey(s string) string {
+	s = stripRelease(s)
+	s = strings.TrimPrefix(strings.ToLower(strings.TrimSpace(s)), "the ")
+	var b strings.Builder
+	for _, r := range accentFold.Replace(s) {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+// bestArt picks a confident match: artist and album must both closely match.
+func bestArt(results []art.Result, artist, album string) (art.Result, float64, bool) {
+	ak, bk := matchKey(artist), matchKey(album)
+	var best art.Result
+	bestScore := 0.0
+	for _, r := range results {
+		if r.Artist == "" || r.Title == "" {
+			continue
+		}
+		sa := levenshteinRatio(matchKey(r.Artist), ak)
+		sb := levenshteinRatio(matchKey(r.Title), bk)
+		if sa < 0.85 || sb < 0.85 {
+			continue
+		}
+		score := sa*0.4 + sb*0.6 + float64(min(r.Width, 3000))/100000
+		if score > bestScore {
+			best, bestScore = r, score
+		}
+	}
+	return best, bestScore, bestScore > 0
+}
+
+// StartArtAutoMatch finds and applies covers for the albums in a folder.
+func (e *Engine) StartArtAutoMatch(pairID int64, m ArtMatch) (*Job, error) {
+	if !e.TagEditing() {
+		return nil, ErrNoTagTools
+	}
+	if e.artClient == nil || e.artStore == nil {
+		return nil, errors.New("album art is not available")
+	}
+	if m.Side != SideMaster && m.Side != SideSlave {
+		return nil, fmt.Errorf("%w: side must be master or slave", ErrInvalidBulk)
+	}
+	if !m.Embed && !m.FolderFile {
+		return nil, fmt.Errorf("%w: choose where the art goes", ErrInvalidBulk)
+	}
+	return e.startJob(pairID, "art-auto-match", func(ctx context.Context, j *Job) error {
+		l, err := e.loadPair(ctx, pairID)
+		if err != nil {
+			return err
+		}
+		root, _ := sideRoot(l, m.Side)
+		start := root
+		if m.Folder != "" {
+			abs, err := root.Resolve(m.Folder)
+			if err != nil {
+				return err
+			}
+			if start, err = fsops.NewRoot(abs); err != nil {
+				return err
+			}
+		}
+		files := map[string]fsops.Info{}
+		if _, err := walk(ctx, l, start, files); err != nil {
+			return err
+		}
+		type album struct {
+			artist, title string
+			rels          []string
+		}
+		albums := map[string]*album{}
+		var order []string
+		j.phase("Reading tags", int64(len(files)))
+		for _, rel := range sortedKeys(files) {
+			j.tick()
+			full := filepath.Join(m.Folder, rel)
+			fields, err := e.tagCache.get(ctx, e.tagTools, filepath.Join(start.Path, rel), files[rel])
+			if err != nil {
+				continue
+			}
+			v := valuesOf(fields)
+			if v.artist == "" || v.album == "" {
+				j.skip(full + ": missing artist or album tag")
+				continue
+			}
+			key := matchKey(v.artist) + "|" + matchKey(v.album)
+			if albums[key] == nil {
+				albums[key] = &album{artist: v.artist, title: v.album}
+				order = append(order, key)
+			}
+			albums[key].rels = append(albums[key].rels, full)
+		}
+		j.phase("Finding covers", int64(len(order)))
+		for _, key := range order {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+			a := albums[key]
+			label := a.artist + " – " + a.title
+			j.tick()
+			need := a.rels
+			if m.OnlyMissing {
+				need = nil
+				for _, rel := range a.rels {
+					abs, _ := root.Resolve(rel)
+					if fm, ok := tags.FormatOf(rel); ok && fm.EmbedsCover() && m.Embed && !e.tagTools.HasCover(ctx, abs) {
+						need = append(need, rel)
+					}
+				}
+				folderMissing := false
+				if m.FolderFile {
+					for _, f := range albumFolders(a.rels) {
+						if abs, err := root.Resolve(f); err == nil && !hasFolderCover(abs) {
+							folderMissing = true
+						}
+					}
+				}
+				if len(need) == 0 && !folderMissing {
+					j.count("already have art")
+					continue
+				}
+			}
+			res, _ := e.artClient.Search(ctx, art.Query{Artist: a.artist, Album: a.title}, e.artConfig(ctx, art.MatchSources))
+			best, _, ok := bestArt(res, a.artist, a.title)
+			if !ok {
+				j.skip(label + ": no confident match")
+				continue
+			}
+			b, err := e.artClient.FetchImage(ctx, best.URL)
+			if err != nil {
+				j.skip(label + ": download failed: " + err.Error())
+				continue
+			}
+			p, err := e.artStore.Prepare(ctx, b, e.ArtSettings(ctx).MaxSize)
+			if err != nil {
+				j.skip(label + ": " + err.Error())
+				continue
+			}
+			cover, _ := e.artStore.Path(p.Token)
+			if m.Embed {
+				for _, rel := range need {
+					if err := e.editTagsOne(ctx, j, l, m.Side, rel, nil, cover, false); err != nil {
+						j.skip(rel + ": " + err.Error())
+					}
+				}
+			}
+			if m.FolderFile {
+				for _, f := range albumFolders(a.rels) {
+					abs, _ := root.Resolve(f)
+					if m.OnlyMissing && hasFolderCover(abs) {
+						continue
+					}
+					if err := e.writeFolderCover(ctx, l, m.Side, f, cover); err != nil {
+						j.skip(f + " cover.jpg: " + err.Error())
+					}
+				}
+			}
+			j.count("albums matched")
+			j.note(fmt.Sprintf("%s: %s (%dx%d)", label, best.Source, p.Width, p.Height))
+		}
+		return nil
+	})
+}
+
+func hasFolderCover(dir string) bool {
+	for _, n := range folderCoverNames {
+		if _, err := fsops.RegularFile(filepath.Join(dir, n)); err == nil {
+			return true
+		}
+	}
+	return false
+}

internal/engine/artwork_test.go

@@ -0,0 +1,181 @@
+package engine
+
+import (
+	"bytes"
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/cdnutter/playlink/internal/art"
+	"github.com/cdnutter/playlink/internal/store"
+	"github.com/cdnutter/playlink/internal/tags"
+)
+
+func squarePNG(n int) []byte {
+	img := image.NewRGBA(image.Rect(0, 0, n, n))
+	for i := 0; i < n; i++ {
+		img.Set(i, i, color.RGBA{0, 0, 200, 255})
+	}
+	var b bytes.Buffer
+	png.Encode(&b, img)
+	return b.Bytes()
+}
+
+// artEnv is a tag-editing env with an art store and a fake iTunes that knows
+// one album: Avenged Sevenfold - Nightmare.
+func artEnv(t *testing.T) *env {
+	t.Helper()
+	ev := tagEnv(t, false)
+	var base string
+	mux := http.NewServeMux()
+	mux.HandleFunc("/search", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, `{"results":[{"artistName":"Avenged Sevenfold","collectionName":"Nightmare (Deluxe Edition)","artworkUrl100":"%s/img/100x100bb.jpg"}]}`, base)
+	})
+	mux.HandleFunc("/img/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.Write(squarePNG(1200))
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	base = srv.URL
+	c := art.New("test")
+	c.HTTP = srv.Client()
+	c.ITunesURL = base
+	ff, _ := exec.LookPath("ffmpeg")
+	ev.e.SetArt(c, &art.Store{Dir: filepath.Join(ev.root, "art-cache"), FFmpeg: ff})
+	ev.st.SetSetting(ctx, "art_sources", "itunes")
+	return ev
+}
+
+func prepared(t *testing.T, ev *env) string {
+	t.Helper()
+	p, err := ev.e.artStore.Prepare(ctx, squarePNG(800), 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return p.Token
+}
+
+func TestAlbumEditWithArt(t *testing.T) {
+	ev := artEnv(t)
+	dir := "Avenged Sevenfold/Nightmare"
+	mkTagged(t, filepath.Join(ev.slave, dir, "a.mp3"), "title", "x", "artist", "Avenged Sevenfold", "album", "Nightmar")
+	mkTagged(t, filepath.Join(ev.slave, dir, "Disc 2/b.flac"), "title", "y", "artist", "Avenged Sevenfold", "album", "Nightmar")
+	mkTagged(t, filepath.Join(ev.slave, dir, "c.ogg"), "title", "z", "artist", "Avenged Sevenfold", "album", "Nightmar")
+
+	a, err := ev.e.AlbumSongs(ctx, ev.pair.ID, SideSlave, dir)
+	if err != nil || len(a.Songs) != 3 {
+		t.Fatalf("album should include the disc folder: %+v %v", a, err)
+	}
+	req := TagEdit{Side: SideSlave, Set: map[string]string{tags.Album: "Nightmare", tags.Genre: "Metal", tags.TrackTotal: "3"},
+		Files: []FileEdit{
+			{Path: dir + "/a.mp3", Set: map[string]string{tags.Title: "Nightmare", tags.Track: "1"}},
+			{Path: dir + "/Disc 2/b.flac", Set: map[string]string{tags.Title: "Welcome to the Family", tags.Track: "2"}},
+			{Path: dir + "/c.ogg", Set: map[string]string{tags.Title: "Danger Line", tags.Track: "3"}},
+		},
+		Art: &ArtApply{Token: prepared(t, ev), Embed: true, FolderFile: true}}
+	if _, err := ev.e.StartTagEdit(ev.pair.ID, req); err != nil {
+		t.Fatal(err)
+	}
+	j := ev.wait()
+	if j.Results["edited"] != 3 || j.Results["folder art"] != 1 {
+		t.Fatalf("results %+v %v", j.Results, j.Skipped)
+	}
+	for rel, title := range map[string]string{"a.mp3": "Nightmare", "Disc 2/b.flac": "Welcome to the Family", "c.ogg": "Danger Line"} {
+		p := filepath.Join(ev.slave, dir, rel)
+		f, _ := ev.e.tagTools.Read(ctx, p)
+		if f.Fields[tags.Title] != title || f.Fields[tags.Album] != "Nightmare" || f.Fields[tags.Genre] != "Metal" {
+			t.Errorf("%s: fields %+v", rel, f.Fields)
+		}
+		wantCover := !strings.HasSuffix(rel, ".ogg")
+		if ev.e.tagTools.HasCover(ctx, p) != wantCover {
+			t.Errorf("%s: embedded cover should be %v", rel, wantCover)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(ev.slave, dir, "cover.jpg")); err != nil {
+		t.Fatal("the album folder should get cover.jpg")
+	}
+	// Undo the folder image: it is removed again.
+	ops, _, _ := ev.st.Ops(ctx, store.OpFilter{PairID: ev.pair.ID})
+	for _, o := range ops {
+		if o.Action == store.ActCover {
+			if err := ev.e.Undo(ctx, o.ID); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	if _, err := os.Stat(filepath.Join(ev.slave, dir, "cover.jpg")); !os.IsNotExist(err) {
+		t.Fatal("undo should remove the new cover.jpg")
+	}
+}
+
+func TestFolderCoverReplaceKeepsOld(t *testing.T) {
+	ev := artEnv(t)
+	dir := "A/B"
+	mkTagged(t, filepath.Join(ev.slave, dir, "s.flac"), "title", "S", "artist", "A", "album", "B")
+	old := filepath.Join(ev.slave, dir, "cover.jpg")
+	os.WriteFile(old, []byte("old cover"), 0o644)
+	ev.e.StartTagEdit(ev.pair.ID, TagEdit{Side: SideSlave, Paths: []string{dir + "/s.flac"}, Art: &ArtApply{Token: prepared(t, ev), FolderFile: true}})
+	ev.wait()
+	if b, _ := os.ReadFile(old); string(b) == "old cover" {
+		t.Fatal("cover.jpg should be replaced")
+	}
+	ops, _, _ := ev.st.Ops(ctx, store.OpFilter{PairID: ev.pair.ID, Limit: 1})
+	if ops[0].Action != store.ActCover || ops[0].QuarantinePath == "" {
+		t.Fatalf("old cover should be quarantined: %+v", ops[0])
+	}
+	if err := ev.e.Undo(ctx, ops[0].ID); err != nil {
+		t.Fatal(err)
+	}
+	if b, _ := os.ReadFile(old); string(b) != "old cover" {
+		t.Fatal("undo should restore the old cover.jpg")
+	}
+}
+
+func TestAutoMatchArt(t *testing.T) {
+	ev := artEnv(t)
+	mkTagged(t, filepath.Join(ev.slave, "Avenged Sevenfold/Nightmare/01.mp3"), "title", "Nightmare", "artist", "Avenged Sevenfold", "album", "Nightmare")
+	mkTagged(t, filepath.Join(ev.slave, "Other/Record/01.mp3"), "title", "Song", "artist", "Other Band", "album", "Record")
+	m := ArtMatch{Side: SideSlave, OnlyMissing: true, Embed: true, FolderFile: true}
+	if _, err := ev.e.StartArtAutoMatch(ev.pair.ID, m); err != nil {
+		t.Fatal(err)
+	}
+	j := ev.wait()
+	if j.Results["albums matched"] != 1 || len(j.Notes) != 1 || !strings.Contains(strings.Join(j.Skipped, "\n"), "Other Band – Record: no confident match") {
+		t.Fatalf("results %+v notes %v skipped %v", j.Results, j.Notes, j.Skipped)
+	}
+	if !ev.e.tagTools.HasCover(ctx, filepath.Join(ev.slave, "Avenged Sevenfold/Nightmare/01.mp3")) {
+		t.Fatal("the matched album should get embedded art")
+	}
+	if ev.e.tagTools.HasCover(ctx, filepath.Join(ev.slave, "Other/Record/01.mp3")) {
+		t.Fatal("an unmatched album must not get art")
+	}
+	// Running again: the matched album already has art.
+	ev.e.StartArtAutoMatch(ev.pair.ID, m)
+	if j := ev.wait(); j.Results["already have art"] != 1 {
+		t.Fatalf("second run: %+v", j.Results)
+	}
+}
+
+func TestBestArt(t *testing.T) {
+	res := []art.Result{
+		{Source: "itunes", Artist: "Avenged Sevenfold", Title: "Nightmare (Deluxe Edition)", Width: 1000},
+		{Source: "deezer", Artist: "Avenged Sevenfold", Title: "Hail to the King", Width: 1000},
+		{Source: "deezer", Artist: "Someone Else", Title: "Nightmare", Width: 1000},
+	}
+	best, _, ok := bestArt(res, "Avenged Sevenfold", "Nightmare")
+	if !ok || best.Title != "Nightmare (Deluxe Edition)" {
+		t.Fatalf("got %+v", best)
+	}
+	if _, _, ok := bestArt(res, "The Beatles", "Abbey Road"); ok {
+		t.Fatal("no confident match expected")
+	}
+}

internal/engine/engine.go

@@ -13,6 +13,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/cdnutter/playlink/internal/art"
 	"github.com/cdnutter/playlink/internal/fsops"
 	"github.com/cdnutter/playlink/internal/probe"
 	"github.com/cdnutter/playlink/internal/store"
@@ -45,6 +46,8 @@ type Engine struct {
 	tagTools     tags.Tools
 	beforeAction func(ctx context.Context, reason string) error
 	tagCache     tagCache
+	artClient    *art.Client
+	artStore     *art.Store
 
 	plansMu sync.Mutex
 	plans   map[int64]*organizePlan // latest "rename now" preview per pair
@@ -74,6 +77,7 @@ type Job struct {
 	Error      string         `json:"error"`
 	Results    map[string]int `json:"results"`
 	Skipped    []string       `json:"skipped"`
+	Notes      []string       `json:"notes"`
 	StartedAt  int64          `json:"started_at"`
 	FinishedAt int64          `json:"finished_at,omitempty"`
 
@@ -95,6 +99,15 @@ func (j *Job) tick() { j.update(func(j *Job) { j.Done++ }) }
 
 func (j *Job) count(key string) { j.update(func(j *Job) { j.Results[key]++ }) }
 
+// note records an informational line (e.g. which cover was chosen).
+func (j *Job) note(msg string) {
+	j.update(func(j *Job) {
+		if len(j.Notes) < 300 {
+			j.Notes = append(j.Notes, msg)
+		}
+	})
+}
+
 func (j *Job) skip(msg string) {
 	j.update(func(j *Job) {
 		j.Results["skipped"]++
@@ -118,6 +131,7 @@ func (e *Engine) Job(pairID int64) *Job {
 		cp.Results[k] = v
 	}
 	cp.Skipped = append([]string{}, j.Skipped...) // never nil: the UI expects an array
+	cp.Notes = append([]string{}, j.Notes...)
 	return &cp
 }
 

internal/engine/ops.go

@@ -625,6 +625,16 @@ func (e *Engine) Undo(ctx context.Context, opID int64) error {
 	if err != nil {
 		return err
 	}
+	if o.Action == store.ActCover {
+		if err := e.undoCover(l, o); err != nil {
+			return err
+		}
+		if err := e.st.MarkUndone(ctx, o.ID); err != nil {
+			return err
+		}
+		e.log.Info("folder cover undone", "op", o.ID)
+		return nil
+	}
 	if o.Action == store.ActMove {
 		if err := undoMove(l, o); err != nil {
 			return err

internal/engine/tagedit.go

@@ -194,16 +194,29 @@ func (e *Engine) ReadTags(ctx context.Context, pairID int64, side string, rels [
 type TagEdit struct {
 	Side  string            `json:"side"`
 	Paths []string          `json:"paths"`
-	Set   map[string]string `json:"set"` // field -> new value ("" removes the tag)
+	Set   map[string]string `json:"set"` // field -> new value ("" removes the tag), for every file
+	// Files adds per-song changes (an album's track titles and numbers).
+	Files []FileEdit `json:"files,omitempty"`
+	// Art applies album art to the edited files and/or their album folder.
+	Art *ArtApply `json:"art,omitempty"`
 	// Separate gives a hardlinked file its own edited copy instead of
 	// updating it in place for every linked path.
 	Separate bool `json:"separate"`
 }
 
+type FileEdit struct {
+	Path string            `json:"path"`
+	Set  map[string]string `json:"set"`
+}
+
+// ArtApply is a prepared cover (see art.Store) and where it goes.
+type ArtApply struct {
+	Token      string `json:"token"`
+	Embed      bool   `json:"embed"`       // into each song (MP3, FLAC, M4A)
+	FolderFile bool   `json:"folder_file"` // as cover.jpg in the album folder
+}
+
 func validTagChanges(set map[string]string) error {
-	if len(set) == 0 {
-		return fmt.Errorf("%w: no tags changed", ErrInvalidBulk)
-	}
 	known := map[string]bool{}
 	for _, id := range tags.FieldIDs {
 		known[id] = true
@@ -227,39 +240,118 @@ func (e *Engine) StartTagEdit(pairID int64, req TagEdit) (*Job, error) {
 	if req.Side != SideMaster && req.Side != SideSlave {
 		return nil, fmt.Errorf("%w: side must be master or slave", ErrInvalidBulk)
 	}
-	rels, err := cleanRels(req.Paths)
-	if err != nil {
-		return nil, err
+	// Every file gets the shared changes plus its own.
+	perFile := map[string]map[string]string{}
+	var order []string
+	add := func(p string, set map[string]string) error {
+		c, err := fsops.CleanRel(p)
+		if err != nil {
+			return err
+		}
+		if _, ok := perFile[c]; !ok {
+			perFile[c] = map[string]string{}
+			order = append(order, c)
+		}
+		for k, v := range set {
+			perFile[c][k] = v
+		}
+		return nil
 	}
-	if err := validTagChanges(req.Set); err != nil {
-		return nil, err
+	for _, p := range req.Paths {
+		if err := add(p, req.Set); err != nil {
+			return nil, err
+		}
+	}
+	for _, f := range req.Files {
+		if err := add(f.Path, req.Set); err != nil {
+			return nil, err
+		}
+		if err := add(f.Path, f.Set); err != nil {
+			return nil, err
+		}
+	}
+	if len(order) == 0 {
+		return nil, fmt.Errorf("%w: no files selected", ErrInvalidBulk)
+	}
+	if len(order) > maxTagFiles {
+		return nil, fmt.Errorf("%w: select at most %d files at a time", ErrInvalidBulk, maxTagFiles)
+	}
+	changed := false
+	for _, set := range perFile {
+		if len(set) > 0 {
+			if err := validTagChanges(set); err != nil {
+				return nil, err
+			}
+			changed = true
+		}
+	}
+	var cover string
+	if req.Art != nil && (req.Art.Embed || req.Art.FolderFile) {
+		p, err := e.preparedArt(req.Art.Token)
+		if err != nil {
+			return nil, err
+		}
+		cover = p
+	}
+	if !changed && cover == "" {
+		return nil, fmt.Errorf("%w: nothing changed", ErrInvalidBulk)
 	}
 	return e.startJob(pairID, "edit-tags", func(ctx context.Context, j *Job) error {
 		l, err := e.loadPair(ctx, pairID)
 		if err != nil {
 			return err
 		}
-		j.phase("Editing tags", int64(len(rels)))
-		for _, rel := range rels {
+		embed := ""
+		if cover != "" && req.Art.Embed {
+			embed = cover
+		}
+		j.phase("Editing tags", int64(len(order)))
+		for _, rel := range order {
 			if ctx.Err() != nil {
 				return ctx.Err()
 			}
-			if err := e.editTagsOne(ctx, j, l, req.Side, rel, req.Set, req.Separate); err != nil {
+			if err := e.editTagsOne(ctx, j, l, req.Side, rel, perFile[rel], embed, req.Separate); err != nil {
 				j.skip(rel + ": " + err.Error())
 			}
 			j.tick()
 		}
+		if cover != "" && req.Art.FolderFile {
+			for _, folder := range albumFolders(order) {
+				if err := e.writeFolderCover(ctx, l, req.Side, folder, cover); err != nil {
+					j.skip(folder + " cover.jpg: " + err.Error())
+				} else {
+					j.count("folder art")
+				}
+			}
+		}
 		return nil
 	})
 }
 
+// albumFolders lists the distinct album folders of some songs (disc folders
+// folded into their album).
+func albumFolders(rels []string) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, r := range rels {
+		f := AlbumFolder(r)
+		if f != "" && !seen[f] {
+			seen[f] = true
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
 type tagDetail struct {
 	Side    string               `json:"side"`
 	Mode    string               `json:"mode"`
-	Changes map[string][2]string `json:"changes"` // field -> [old, new]
+	Changes map[string][2]string `json:"changes"`         // field -> [old, new]
+	Cover   bool                 `json:"cover,omitempty"` // new art embedded
 }
 
-func (e *Engine) editTagsOne(ctx context.Context, j *Job, l *libs, side, rel string, set map[string]string, separate bool) error {
+// editTagsOne applies tag changes and/or a new embedded cover to one file.
+func (e *Engine) editTagsOne(ctx context.Context, j *Job, l *libs, side, rel string, set map[string]string, cover string, separate bool) error {
 	e.mu.Lock()
 	defer e.mu.Unlock()
 	root, _ := sideRoot(l, side)
@@ -283,7 +375,15 @@ func (e *Engine) editTagsOne(ctx context.Context, j *Job, l *libs, side, rel str
 			d.Changes[id] = [2]string{f.Fields[id], v}
 		}
 	}
-	if len(changes) == 0 {
+	if cover != "" && !f.Format.EmbedsCover() {
+		cover = "" // Ogg-based files: the folder image carries their art
+		if len(changes) == 0 {
+			j.count("art in folder only")
+			return nil
+		}
+	}
+	d.Cover = cover != ""
+	if len(changes) == 0 && cover == "" {
 		j.count("unchanged")
 		return nil
 	}
@@ -314,10 +414,10 @@ func (e *Engine) editTagsOne(ctx context.Context, j *Job, l *libs, side, rel str
 	tmp := filepath.Join(filepath.Dir(abs), fsops.TmpPrefix+hex.EncodeToString(b[:])+filepath.Ext(abs))
 	defer os.Remove(tmp)
 	err = func() error {
-		if err := e.tagTools.Write(ctx, abs, tmp, f, plan); err != nil {
+		if err := e.tagTools.Write(ctx, abs, tmp, f, plan, cover); err != nil {
 			return err
 		}
-		if err := e.tagTools.Verify(ctx, abs, tmp, changes); err != nil {
+		if err := e.tagTools.Verify(ctx, abs, tmp, changes, cover != ""); err != nil {
 			return err
 		}
 		// Nothing may have touched the original while the new file was made.