feat(api): deliver loudness gains to every client (M464 #4997)

ReplayGain 2.0 values (gain to -18 LUFS, linear peak) derived from the
stored track and album loudness:

- Web: GET /api/tracks/replay-gain?ids=... (up to 200), a lookup the
  player calls for its queue, rather than a field on every TrackRef
  surface.
- Android: track_gain/track_peak and album_gain/album_peak on the sync
  views, so cached tracks level offline. Storing a measurement logs a
  track change, and an album's values moving logs an album change, both
  before the write (#2704), so caches pick the gains up.
- OpenSubsonic: replayGain on every song (album, getSong, search3,
  starred), as a JSON object and an XML element.

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

internal/api/library_sync_views_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
 )
 
 // These tests pin the wire-format keys for /api/library/sync upserts.
@@ -53,13 +54,13 @@ func TestArtistSyncView_WireKeys(t *testing.T) {
 
 func TestAlbumSyncView_WireKeys(t *testing.T) {
 	a := dbq.Album{ID: validUUID, ArtistID: validUUID, Title: "Drukqs", SortTitle: "Drukqs"}
-	b, err := json.Marshal(toAlbumSyncView(a))
+	b, err := json.Marshal(toAlbumSyncView(a, library.ReplayGain{}))
 	if err != nil {
 		t.Fatal(err)
 	}
 	assertJSONKeys(t, "album", b, []string{
 		"id", "artist_id", "title", "sort_title",
-		"release_date", "cover_art_path", "mbid",
+		"release_date", "cover_art_path", "mbid", "album_gain", "album_peak",
 	})
 }
 
@@ -69,14 +70,14 @@ func TestTrackSyncView_WireKeys(t *testing.T) {
 		Title: "Avril 14th", DurationMs: 121_000,
 		FilePath: "x", FileFormat: "flac",
 	}
-	b, err := json.Marshal(toTrackSyncView(tr))
+	b, err := json.Marshal(toTrackSyncView(tr, library.ReplayGain{}))
 	if err != nil {
 		t.Fatal(err)
 	}
 	assertJSONKeys(t, "track", b, []string{
 		"id", "album_id", "artist_id", "title", "duration_ms",
 		"track_number", "disc_number", "file_path", "file_format", "genre",
-		"missing",
+		"missing", "track_gain", "track_peak",
 	})
 }
 
@@ -85,17 +86,44 @@ func TestTrackSyncView_WireKeys(t *testing.T) {
 // client's library, a missing one stays playable and fails at the speaker.
 func TestTrackSyncView_MissingReflectsTheMark(t *testing.T) {
 	present := dbq.Track{ID: validUUID, AlbumID: validUUID, ArtistID: validUUID}
-	if toTrackSyncView(present).Missing {
+	if toTrackSyncView(present, library.ReplayGain{}).Missing {
 		t.Error("a track with no missing_since must not be marked missing")
 	}
 
 	gone := present
 	gone.MissingSince = pgtype.Timestamptz{Time: time.Now(), Valid: true}
-	if !toTrackSyncView(gone).Missing {
+	if !toTrackSyncView(gone, library.ReplayGain{}).Missing {
 		t.Error("a track with missing_since must be marked missing")
 	}
 }
 
+// The gains are what Android levels playback by, offline included (#4997):
+// the track's pair rides on the track view and the album's on the album view.
+func TestSyncViews_CarryReplayGain(t *testing.T) {
+	gain, peak := float32(-3.25), float32(0.9441)
+	g := library.ReplayGain{TrackGain: &gain, TrackPeak: &peak, AlbumGain: &gain, AlbumPeak: &peak}
+	tv := toTrackSyncView(dbq.Track{ID: validUUID, AlbumID: validUUID, ArtistID: validUUID}, g)
+	if tv.TrackGain == nil || *tv.TrackGain != gain || tv.TrackPeak == nil || *tv.TrackPeak != peak {
+		t.Errorf("track view gains = %v/%v, want %v/%v", tv.TrackGain, tv.TrackPeak, gain, peak)
+	}
+	av := toAlbumSyncView(dbq.Album{ID: validUUID, ArtistID: validUUID}, g)
+	if av.AlbumGain == nil || *av.AlbumGain != gain || av.AlbumPeak == nil || *av.AlbumPeak != peak {
+		t.Errorf("album view gains = %v/%v, want %v/%v", av.AlbumGain, av.AlbumPeak, gain, peak)
+	}
+	// Unmeasured: explicit nulls, like every other optional sync field.
+	b, err := json.Marshal(toTrackSyncView(dbq.Track{ID: validUUID, AlbumID: validUUID, ArtistID: validUUID}, library.ReplayGain{}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(b, &m); err != nil {
+		t.Fatal(err)
+	}
+	if v, ok := m["track_gain"]; !ok || v != nil {
+		t.Errorf("unmeasured track_gain = %v (present %v), want an explicit null", v, ok)
+	}
+}
+
 func TestPlaylistSyncView_WireKeys(t *testing.T) {
 	variant := "discover"
 	p := dbq.Playlist{