feat: per-user volume leveling preference, synced across devices (M464 #4998)

Mode (off, auto, track, album), target (-18, -16, -14 LUFS) and boost
(within headroom, or fully with a limiter), stored per user on the server
so the web player, the Android app and casts apply the same one.

- Server: user_normalization_prefs (migration 0067), GET/PUT
  /api/me/normalization; a whole-body PUT, validated, last write wins.
- Web: Settings > Playback > Volume leveling. Saves at once, restores the
  old choice if the save fails, and caches the value for the player.
- Android: Settings card. The device keeps a copy for offline playback
  (Room v9 with an explicit migration, so the upgrade wipes nothing).
  Writes are offline-first: shown at once, PUT best effort, queued on
  failure (NORMALIZATION_SET, collapsed to the newest). A refresh never
  overwrites a change still queued.

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

internal/library/normalization_prefs.go

@@ -0,0 +1,84 @@
+package library
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// NormalizationPrefs is one user's loudness-normalization preference (M464
+// #4998). It lives on the server so every player applies the same one: the
+// web player and the Android app read it, and the leveled stream for
+// UPnP/Sonos (#5001) renders with it.
+type NormalizationPrefs struct {
+	// Mode is off, auto, track or album. Auto uses album gain while an album
+	// plays in order and track gain otherwise.
+	Mode string `json:"mode"`
+	// TargetLUFS is the loudness tracks are leveled to.
+	TargetLUFS int16 `json:"target_lufs"`
+	// Boost is how a track quieter than the target is raised: headroom stops
+	// at its true peak, limiter goes all the way and limits the peaks.
+	Boost string `json:"boost"`
+}
+
+// The accepted values. Migration 0067's CHECKs hold the same lists.
+var (
+	NormalizationModes   = []string{"off", "auto", "track", "album"}
+	NormalizationTargets = []int16{-18, -16, -14}
+	NormalizationBoosts  = []string{"headroom", "limiter"}
+)
+
+// DefaultNormalizationPrefs applies to a user who has never chosen. It must
+// equal migration 0067's column defaults; a test holds them together.
+var DefaultNormalizationPrefs = NormalizationPrefs{Mode: "auto", TargetLUFS: -18, Boost: "headroom"}
+
+// ErrNormalizationPrefsInvalid is returned for a value outside the lists.
+var ErrNormalizationPrefsInvalid = errors.New("normalization preference out of range")
+
+// Validate reports the first field holding a value the server does not
+// accept.
+func (p NormalizationPrefs) Validate() error {
+	switch {
+	case !slices.Contains(NormalizationModes, p.Mode):
+		return fmt.Errorf("%w: mode %q", ErrNormalizationPrefsInvalid, p.Mode)
+	case !slices.Contains(NormalizationTargets, p.TargetLUFS):
+		return fmt.Errorf("%w: target_lufs %d", ErrNormalizationPrefsInvalid, p.TargetLUFS)
+	case !slices.Contains(NormalizationBoosts, p.Boost):
+		return fmt.Errorf("%w: boost %q", ErrNormalizationPrefsInvalid, p.Boost)
+	}
+	return nil
+}
+
+// LoadNormalizationPrefs returns the user's preference, or the defaults if
+// they have never set one.
+func LoadNormalizationPrefs(ctx context.Context, q *dbq.Queries, userID pgtype.UUID) (NormalizationPrefs, error) {
+	row, err := q.GetNormalizationPrefs(ctx, userID)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return DefaultNormalizationPrefs, nil
+	}
+	if err != nil {
+		return DefaultNormalizationPrefs, err
+	}
+	return NormalizationPrefs{Mode: row.Mode, TargetLUFS: row.TargetLufs, Boost: row.Boost}, nil
+}
+
+// SaveNormalizationPrefs validates and stores the user's preference,
+// returning what was stored.
+func SaveNormalizationPrefs(ctx context.Context, q *dbq.Queries, userID pgtype.UUID, p NormalizationPrefs) (NormalizationPrefs, error) {
+	if err := p.Validate(); err != nil {
+		return p, err
+	}
+	row, err := q.UpsertNormalizationPrefs(ctx, dbq.UpsertNormalizationPrefsParams{
+		UserID: userID, Mode: p.Mode, TargetLufs: p.TargetLUFS, Boost: p.Boost,
+	})
+	if err != nil {
+		return p, err
+	}
+	return NormalizationPrefs{Mode: row.Mode, TargetLUFS: row.TargetLufs, Boost: row.Boost}, nil
+}

internal/library/normalization_prefs_test.go

@@ -0,0 +1,69 @@
+package library
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/dbtest"
+)
+
+func TestNormalizationPrefs_Validate(t *testing.T) {
+	if err := DefaultNormalizationPrefs.Validate(); err != nil {
+		t.Fatalf("the defaults are invalid: %v", err)
+	}
+	for _, p := range []NormalizationPrefs{
+		{Mode: "loud", TargetLUFS: -18, Boost: "headroom"},
+		{Mode: "auto", TargetLUFS: -23, Boost: "headroom"},
+		{Mode: "auto", TargetLUFS: -18, Boost: "max"},
+		// A field left out of a PUT body decodes as its zero value.
+		{Mode: "auto", Boost: "headroom"},
+	} {
+		if err := p.Validate(); !errors.Is(err, ErrNormalizationPrefsInvalid) {
+			t.Errorf("%+v: err = %v, want ErrNormalizationPrefsInvalid", p, err)
+		}
+	}
+}
+
+// A user with no row gets the Go defaults, and a stored row reads back the
+// migration's defaults for any column the insert left out; the two must
+// agree, or a user would hear a different level after their first save.
+func TestNormalizationPrefs_DefaultsAndRoundTrip_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	user, err := q.CreateUser(ctx, dbq.CreateUserParams{
+		Username: dbtest.TestUserPrefix + "norm-prefs", PasswordHash: "x", ApiTokenHash: "norm-prefs-token",
+	})
+	if err != nil {
+		t.Fatalf("user: %v", err)
+	}
+
+	got, err := LoadNormalizationPrefs(ctx, q, user.ID)
+	if err != nil || got != DefaultNormalizationPrefs {
+		t.Fatalf("unset prefs = %+v, %v; want the defaults", got, err)
+	}
+
+	if _, err := pool.Exec(ctx, "INSERT INTO user_normalization_prefs (user_id) VALUES ($1)", user.ID); err != nil {
+		t.Fatalf("insert defaults row: %v", err)
+	}
+	got, err = LoadNormalizationPrefs(ctx, q, user.ID)
+	if err != nil || got != DefaultNormalizationPrefs {
+		t.Errorf("migration defaults = %+v, Go defaults = %+v (err %v)", got, DefaultNormalizationPrefs, err)
+	}
+
+	want := NormalizationPrefs{Mode: "track", TargetLUFS: -14, Boost: "limiter"}
+	if saved, err := SaveNormalizationPrefs(ctx, q, user.ID, want); err != nil || saved != want {
+		t.Fatalf("save = %+v, %v; want %+v", saved, err, want)
+	}
+	if got, _ := LoadNormalizationPrefs(ctx, q, user.ID); got != want {
+		t.Errorf("after save = %+v, want %+v", got, want)
+	}
+	if _, err := SaveNormalizationPrefs(ctx, q, user.ID, NormalizationPrefs{Mode: "x"}); !errors.Is(err, ErrNormalizationPrefsInvalid) {
+		t.Errorf("invalid save: err = %v", err)
+	}
+	if got, _ := LoadNormalizationPrefs(ctx, q, user.ID); got != want {
+		t.Errorf("an invalid save changed the stored prefs to %+v", got)
+	}
+}