fix(scanner): read multi-value genre frames correctly — #2499

dhowden/tag's readTFrame splits ID3v2 null-separated multi-value text
frames and rejoins them with the EMPTY string, so a file tagged
"Alternative Rock" + "Rock" was stored as "Alternative RockRock". It also
leaves bare numeric ID3v1 references unresolved, which is why the
library showed genres like "4017" and "526617".

This corrupted more than the browse axis added in #367: taste_profile.sql
reads tracks.genre directly, so the welded tokens were entering the taste
profile's tag vocabulary, and recommendation.sql/discover.sql were
comparing them as single opaque tags. Genre counts were wrong everywhere.

ffprobe is not a fix — ffmpeg's read_ttag calls decode_str once with no
loop, keeping only the first value. Truncating multi-genre tags would
blunt the similarity signal genre mainly feeds. So the TCON frame is now
parsed directly (ID3v2.2/2.3/2.4, all four text encodings, per-frame and
tag-level unsynchronisation, numeric and parenthesised ID3v1 references);
everything else still comes from dhowden/tag. Values are stored
";"-delimited, which the read side already splits on, so no query changes.

Existing rows are repaired without an operator-run rebuild: migration
0054 adds tracks.tag_read_version DEFAULT 0, below the scanner's current
tagReadVersion, so the next scan re-reads tags it would otherwise skip on
mtime. Such a re-read reuses the stored duration instead of re-running
ffprobe, keeping a repair pass tag-read-bound rather than one fork+exec
per file. Bumping the constant is how a future extraction fix reaches an
existing library.

Only ID3v2 is in scope — dhowden welds nowhere else. The Vorbis/MP4
repeated-field question is #2500, unproven and deliberately not built.

internal/library/scanner.go

@@ -39,6 +39,21 @@ var audioExtensions = map[string]bool{
 	".wav":  true,
 }
 
+// tagReadVersion is the version of this package's tag-extraction logic. Rows
+// whose tracks.tag_read_version is lower get their tags re-read on the next
+// scan even when the file itself hasn't changed, so a fix reaches an existing
+// library without the operator rebuilding it (migration 0054).
+//
+// Bump this whenever a change to tag extraction should reach already-indexed
+// files, and say why below.
+//
+//	1: genre read from the ID3v2 TCON frame directly and stored ";"-delimited.
+//	   dhowden/tag welds null-separated multi-values into one token
+//	   ("Alternative Rock" + "Rock" -> "Alternative RockRock"), which corrupted
+//	   the genre browse axis and polluted the taste profile's tag vocabulary,
+//	   and left bare ID3v1 numeric references unresolved (#2499).
+const tagReadVersion int16 = 1
+
 type Stats struct {
 	Scanned int `json:"scanned"`
 	Added   int `json:"added"`
@@ -133,12 +148,15 @@ func (s *Scanner) scanFile(
 	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
 		return pgtype.UUID{}, false, fmt.Errorf("lookup: %w", err)
 	}
-	// Incremental skip: only when the file hasn't changed AND we already have
-	// a real duration. The second clause lets older scans that recorded
-	// duration_ms=0 (before ffprobe was wired) get backfilled without forcing
-	// the operator to wipe the library. Once duration is set, subsequent
-	// scans short-circuit as before.
-	if knownTrack && !existing.UpdatedAt.Time.Before(mtime) && existing.DurationMs > 0 {
+	// Incremental skip: only when the file hasn't changed AND we already have a
+	// real duration AND the row's tag-derived columns were written by the
+	// current extraction logic. The duration clause lets older scans that
+	// recorded duration_ms=0 (before ffprobe was wired) get backfilled without
+	// forcing the operator to wipe the library; the tag-version clause does the
+	// same job for tag-extraction fixes (#2499). Once both are current,
+	// subsequent scans short-circuit as before.
+	unchanged := knownTrack && !existing.UpdatedAt.Time.Before(mtime)
+	if unchanged && existing.DurationMs > 0 && existing.TagReadVersion >= tagReadVersion {
 		stats.Skipped++
 		return pgtype.UUID{}, false, nil
 	}
@@ -180,14 +198,26 @@ func (s *Scanner) scanFile(
 
 	trackNum, _ := meta.Track()
 	discNum, _ := meta.Disc()
-	durationMs, err := probeDurationMs(ctx, path)
-	if err != nil {
-		// Missing duration is degraded UX (clients can't scrub) but not a
-		// blocker for ingestion. Record the file with 0ms; the next scan
-		// will retry via the backfill clause in the skip check above.
-		s.logger.Warn("library scan: ffprobe failed", "path", path, "err", err)
-		durationMs = 0
+
+	// An unchanged file being re-read only to refresh tag-derived columns
+	// doesn't need another ffprobe: the stored duration is still accurate, and
+	// the file's bytes haven't moved. This keeps a library-wide tag-repair pass
+	// (a tagReadVersion bump) bound by tag reads rather than costing one
+	// fork+exec per file.
+	var durationMs int32
+	if unchanged && existing.DurationMs > 0 {
+		durationMs = existing.DurationMs
+	} else {
+		probed, perr := probeDurationMs(ctx, path)
+		if perr != nil {
+			// Missing duration is degraded UX (clients can't scrub) but not a
+			// blocker for ingestion. Record the file with 0ms; the next scan
+			// will retry via the backfill clause in the skip check above.
+			s.logger.Warn("library scan: ffprobe failed", "path", path, "err", perr)
+		}
+		durationMs = probed
 	}
+
 	params := dbq.UpsertTrackParams{
 		Title:      trackTitle,
 		AlbumID:    album.ID,
@@ -196,6 +226,8 @@ func (s *Scanner) scanFile(
 		FilePath:   path,
 		FileSize:   info.Size(),
 		FileFormat: strings.TrimPrefix(strings.ToLower(filepath.Ext(path)), "."),
+		// Stamped so a future extraction fix can find this row again.
+		TagReadVersion: tagReadVersion,
 	}
 	if trackNum > 0 {
 		v := int32(trackNum)
@@ -205,7 +237,14 @@ func (s *Scanner) scanFile(
 		v := int32(discNum)
 		params.DiscNumber = &v
 	}
-	if g := meta.Genre(); g != "" {
+	if genres, fellBack := extractGenres(meta, f); len(genres) > 0 {
+		if fellBack {
+			// dhowden/tag's welded value — see genre.go. Logged because the
+			// stored genre for this file is the old, corrupt shape.
+			s.logger.Warn("library scan: genre frame unreadable, using fallback",
+				"path", path, "genre", meta.Genre())
+		}
+		g := strings.Join(genres, genreDelimiter)
 		params.Genre = &g
 	}
 	// Recording MBID feeds the ListenBrainz similarity pipeline.