feat(library): album loudness from the tracks' summed block histograms (M464 #4996)

Album-mode normalization plays a whole album at one gain. That gain comes
from album_loudness (migration 0066): BS.1770's gated loudness over every
block on the album, computed by summing the tracks' stored histograms and
gating the sum. No audio is decoded again. Album true peak is the loudest
track's.

- Recomputed by the loudness worker each tick, after the track pass and
  whether or not analysis is switched on. ListAlbumsNeedingLoudness lists
  albums whose md5 over (present track id, measurement version and time) no
  longer matches the stored digest. One comparison covers every way
  membership changes (scan retag, duplicate merge, delete, missing and
  restored) without hooking each.
- No album value until every present track has a settled measurement, so
  an album's gain doesn't shift mid-listen as the rest is measured. Silent
  and unreadable tracks count as settled.
- Rows for albums with no present track left are dropped.
- The parser and the merge share trimBins.

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

internal/library/album_loudness.go

@@ -0,0 +1,162 @@
+package library
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// Album loudness (M464 #4996).
+//
+// Album-mode normalization plays a whole album at one gain, so the quiet
+// interlude stays quieter than the single it sits between. That gain comes
+// from the album's loudness: BS.1770's gated loudness over every block on the
+// album, which is what summing the tracks' block histograms and gating the sum
+// computes. An average of the tracks' values is not the same thing: gating
+// over the whole album drops a near-silent hidden track, where averaging
+// would let it drag the album quieter.
+//
+// The values are derived, so they are recomputed rather than maintained: each
+// worker tick lists the albums whose inputs digest has moved (see
+// ListAlbumsNeedingLoudness) and recomputes those from the stored histograms.
+
+// albumLoudnessBatch is how many albums one query hands the album pass.
+// Recomputing an album is a few small reads and arithmetic, no decode.
+const albumLoudnessBatch = 200
+
+// albumLoudness is one album's computed values.
+type albumLoudness struct {
+	// integratedLUFS is nil until every track is settled, or when no block on
+	// the album passed the gate.
+	integratedLUFS *float32
+	truePeakDBTP   *float32
+	total, settled int32
+}
+
+// computeAlbumLoudness sums the present tracks' histograms and gates the sum.
+func computeAlbumLoudness(inputs []dbq.ListAlbumLoudnessInputsRow) albumLoudness {
+	a := albumLoudness{total: int32(len(inputs))}
+	hists := make([]blockHistogram, 0, len(inputs))
+	for _, in := range inputs {
+		if !in.Settled {
+			continue
+		}
+		a.settled++
+		if in.TruePeakDbtp != nil && (a.truePeakDBTP == nil || *in.TruePeakDbtp > *a.truePeakDBTP) {
+			peak := *in.TruePeakDbtp
+			a.truePeakDBTP = &peak
+		}
+		if in.BlockHistStart != nil && len(in.BlockHist) > 0 {
+			hists = append(hists, blockHistogram{start: *in.BlockHistStart, counts: in.BlockHist})
+		}
+	}
+	// Leveling from part of an album would change its gain as the rest is
+	// measured, audibly, mid-listen. Wait for all of it.
+	if a.total == 0 || a.settled < a.total {
+		return a
+	}
+	if lufs, ok := mergeHistograms(hists).gatedLoudness(); ok {
+		v := float32(lufs)
+		a.integratedLUFS = &v
+	}
+	return a
+}
+
+// mergeHistograms sums histograms that may cover different bin ranges into
+// one, trimmed to the occupied range. A histogram reaching past the bin range
+// (only a corrupt row could) is clipped rather than trusted.
+func mergeHistograms(hs []blockHistogram) blockHistogram {
+	var bins [loudnessHistBins]int32
+	for _, h := range hs {
+		for i, c := range h.counts {
+			if b := int(h.start) + i; b >= 0 && b < loudnessHistBins {
+				bins[b] += c
+			}
+		}
+	}
+	return trimBins(&bins)
+}
+
+// AlbumLoudnessResult tallies one album pass.
+type AlbumLoudnessResult struct {
+	Recomputed int
+	Leveled    int // stored with an album loudness
+	Waiting    int // stored without one: a track is not yet measured
+	Failed     int
+	Orphans    int64 // rows dropped because the album has no present track
+}
+
+// albumPass recomputes every album whose inputs changed, keyset-paged on album
+// id so a pass ends even when one album keeps failing to store.
+//
+// The digest stored is the one the list query computed. If a track changes
+// between that query and the read of its inputs, the stored digest is already
+// stale and the next pass recomputes the album again, so the values always
+// converge on the inputs.
+func (w *LoudnessBackfillWorker) albumPass(ctx context.Context) (AlbumLoudnessResult, error) {
+	q := dbq.New(w.pool)
+	var res AlbumLoudnessResult
+	after := pgtype.UUID{Valid: true}
+	for {
+		if err := ctx.Err(); err != nil {
+			return res, err
+		}
+		rows, err := q.ListAlbumsNeedingLoudness(ctx, dbq.ListAlbumsNeedingLoudnessParams{
+			CurrentVersion: loudnessVersion,
+			AfterID:        after,
+			BatchLimit:     w.albumBatch,
+		})
+		if err != nil {
+			return res, fmt.Errorf("list albums needing loudness: %w", err)
+		}
+		if len(rows) == 0 {
+			break
+		}
+		for _, row := range rows {
+			res.Recomputed++
+			if err := storeAlbumLoudness(ctx, q, row.AlbumID, row.Digest, &res); err != nil {
+				res.Failed++
+				w.logger.Warn("album loudness: recompute failed", "album_id", row.AlbumID, "err", err)
+			}
+		}
+		after = rows[len(rows)-1].AlbumID
+	}
+	n, err := q.DeleteOrphanAlbumLoudness(ctx)
+	if err != nil {
+		return res, fmt.Errorf("drop orphan album loudness: %w", err)
+	}
+	res.Orphans = n
+	return res, nil
+}
+
+func storeAlbumLoudness(
+	ctx context.Context, q *dbq.Queries, albumID pgtype.UUID, digest string, res *AlbumLoudnessResult,
+) error {
+	inputs, err := q.ListAlbumLoudnessInputs(ctx, dbq.ListAlbumLoudnessInputsParams{
+		CurrentVersion: loudnessVersion,
+		AlbumID:        albumID,
+	})
+	if err != nil {
+		return fmt.Errorf("read inputs: %w", err)
+	}
+	a := computeAlbumLoudness(inputs)
+	if err := q.UpsertAlbumLoudness(ctx, dbq.UpsertAlbumLoudnessParams{
+		AlbumID:        albumID,
+		IntegratedLufs: a.integratedLUFS,
+		TruePeakDbtp:   a.truePeakDBTP,
+		TracksTotal:    a.total,
+		TracksSettled:  a.settled,
+		InputsDigest:   digest,
+	}); err != nil {
+		return fmt.Errorf("store: %w", err)
+	}
+	if a.integratedLUFS != nil {
+		res.Leveled++
+	} else {
+		res.Waiting++
+	}
+	return nil
+}

internal/library/album_loudness_test.go

@@ -0,0 +1,245 @@
+package library
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"math"
+	"path/filepath"
+	"testing"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// histAt builds a histogram of n blocks all at one loudness.
+func histAt(lufs float64, n int32) blockHistogram {
+	return blockHistogram{
+		start:  int16(math.Round((lufs - loudnessHistFloor) * loudnessHistPerLU)),
+		counts: []int32{n},
+	}
+}
+
+func TestMergeHistograms_SumsAcrossDifferentRanges(t *testing.T) {
+	a := blockHistogram{start: 500, counts: []int32{1, 0, 2}}    // bins 500..502
+	b := blockHistogram{start: 501, counts: []int32{4, 0, 0, 5}} // bins 501..504
+	got := mergeHistograms([]blockHistogram{a, b})
+	want := blockHistogram{start: 500, counts: []int32{1, 4, 2, 0, 5}}
+	if got.start != want.start || len(got.counts) != len(want.counts) {
+		t.Fatalf("merged = %+v, want %+v", got, want)
+	}
+	for i := range want.counts {
+		if got.counts[i] != want.counts[i] {
+			t.Fatalf("merged = %+v, want %+v", got, want)
+		}
+	}
+	// Bins past the range come only from a corrupt row; they are dropped, not
+	// allowed to index out of the array.
+	bad := blockHistogram{start: loudnessHistBins - 1, counts: []int32{1, 9}}
+	if got := mergeHistograms([]blockHistogram{bad}); len(got.counts) != 1 || got.counts[0] != 1 {
+		t.Errorf("out-of-range bin not dropped: %+v", got)
+	}
+	if !mergeHistograms(nil).empty() {
+		t.Errorf("merging nothing gave a non-empty histogram")
+	}
+}
+
+func input(settled bool, peak *float32, h blockHistogram) dbq.ListAlbumLoudnessInputsRow {
+	row := dbq.ListAlbumLoudnessInputsRow{Settled: settled, TruePeakDbtp: peak}
+	if !h.empty() {
+		start := h.start
+		row.BlockHistStart = &start
+		row.BlockHist = h.counts
+	}
+	return row
+}
+
+func TestComputeAlbumLoudness(t *testing.T) {
+	f := func(v float32) *float32 { return &v }
+
+	// Album loudness gates over the whole album. A near-silent hidden track is
+	// dropped by the relative gate, where averaging the tracks' values would
+	// have let it pull the album 15 LU quieter.
+	a := computeAlbumLoudness([]dbq.ListAlbumLoudnessInputsRow{
+		input(true, f(-1.0), histAt(-10, 1800)),
+		input(true, f(-0.2), histAt(-10, 2400)),
+		input(true, f(-30), histAt(-40, 600)),
+	})
+	if a.integratedLUFS == nil || math.Abs(float64(*a.integratedLUFS)-(-10)) > 0.01 {
+		t.Errorf("album loudness = %v, want -10 (the hidden track gated out)", a.integratedLUFS)
+	}
+	if a.truePeakDBTP == nil || *a.truePeakDBTP != -0.2 {
+		t.Errorf("album peak = %v, want the loudest track's -0.2", a.truePeakDBTP)
+	}
+	if a.total != 3 || a.settled != 3 {
+		t.Errorf("total/settled = %d/%d, want 3/3", a.total, a.settled)
+	}
+
+	// Energy, not an average of LUFS: two equally long tracks at -8 and -14
+	// make an album nearer the louder one than the midpoint (-11): -10.037.
+	a = computeAlbumLoudness([]dbq.ListAlbumLoudnessInputsRow{
+		input(true, nil, histAt(-8, 1000)),
+		input(true, nil, histAt(-14, 1000)),
+	})
+	if a.integratedLUFS == nil || math.Abs(float64(*a.integratedLUFS)-(-10.037)) > 0.01 {
+		t.Errorf("album loudness = %v, want -10.037", a.integratedLUFS)
+	}
+
+	// One track not yet measured: no album value until it is.
+	a = computeAlbumLoudness([]dbq.ListAlbumLoudnessInputsRow{
+		input(true, f(-1), histAt(-10, 100)),
+		input(false, nil, blockHistogram{}),
+	})
+	if a.integratedLUFS != nil || a.settled != 1 || a.total != 2 {
+		t.Errorf("partly measured album = %+v, want no loudness, 1 of 2 settled", a)
+	}
+
+	// Settled without blocks (silent, or unreadable): counted as settled and
+	// leveled from the rest.
+	a = computeAlbumLoudness([]dbq.ListAlbumLoudnessInputsRow{
+		input(true, f(-3), histAt(-12, 100)),
+		input(true, nil, blockHistogram{}),
+	})
+	if a.integratedLUFS == nil || math.Abs(float64(*a.integratedLUFS)-(-12)) > 0.01 {
+		t.Errorf("album with a silent track = %v, want -12 from the other track", a.integratedLUFS)
+	}
+
+	// Every track silent: settled, but nothing to level by.
+	a = computeAlbumLoudness([]dbq.ListAlbumLoudnessInputsRow{input(true, nil, blockHistogram{})})
+	if a.integratedLUFS != nil || a.settled != 1 {
+		t.Errorf("all-silent album = %+v, want no loudness", a)
+	}
+}
+
+// TestAlbumLoudness_Integration pins that the album pass computes from the
+// stored histograms, does nothing when nothing changed, and recomputes on
+// each kind of membership change.
+func TestAlbumLoudness_Integration(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+	dir := t.TempDir()
+
+	first, album, artist := seedTrack(t, pool, filepath.Join(dir, "a.mp3"))
+	addTrack := func(name string, albumID dbq.Album) dbq.Track {
+		t.Helper()
+		tr, err := q.UpsertTrack(ctx, dbq.UpsertTrackParams{
+			Title: name, AlbumID: albumID.ID, ArtistID: artist.ID,
+			DurationMs: 1000, FilePath: filepath.Join(dir, name+".mp3"), FileSize: 100, FileFormat: "mp3",
+		})
+		if err != nil {
+			t.Fatalf("track %s: %v", name, err)
+		}
+		return tr
+	}
+	measure := func(tr dbq.Track, lufs float64, peak float32) {
+		t.Helper()
+		h := histAt(lufs, 100)
+		l := float32(lufs)
+		if err := q.UpsertTrackLoudness(ctx, dbq.UpsertTrackLoudnessParams{
+			TrackID: tr.ID, IntegratedLufs: &l, TruePeakDbtp: &peak,
+			BlockHistStart: &h.start, BlockHist: h.counts, AnalysisVersion: loudnessVersion,
+		}); err != nil {
+			t.Fatalf("measure %s: %v", tr.Title, err)
+		}
+	}
+	read := func() (lufs, peak *float32, total, settled int32) {
+		t.Helper()
+		if err := pool.QueryRow(ctx,
+			"SELECT integrated_lufs, true_peak_dbtp, tracks_total, tracks_settled FROM album_loudness WHERE album_id = $1",
+			album.ID).Scan(&lufs, &peak, &total, &settled); err != nil {
+			t.Fatalf("read album loudness: %v", err)
+		}
+		return
+	}
+	w := NewLoudnessBackfillWorker(pool, slog.New(slog.NewTextHandler(io.Discard, nil)), nil)
+	w.albumBatch = 1 // forces the keyset cursor across queries
+	pass := func() AlbumLoudnessResult {
+		t.Helper()
+		res, err := w.albumPass(ctx)
+		if err != nil {
+			t.Fatalf("album pass: %v", err)
+		}
+		return res
+	}
+
+	second := addTrack("b", album)
+	measure(first, -10, -1)
+
+	// 1. One track unmeasured: the album is stored, waiting, without loudness.
+	if res := pass(); res.Recomputed != 1 || res.Waiting != 1 {
+		t.Fatalf("first pass = %+v, want 1 recomputed, waiting", res)
+	}
+	if lufs, _, total, settled := read(); lufs != nil || total != 2 || settled != 1 {
+		t.Fatalf("waiting album = lufs %v, %d/%d settled; want nil, 1/2", lufs, settled, total)
+	}
+
+	// 2. Measuring the second track changes the digest; the album is leveled.
+	measure(second, -10, -0.5)
+	if res := pass(); res.Recomputed != 1 || res.Leveled != 1 {
+		t.Fatalf("second pass = %+v, want 1 leveled", res)
+	}
+	lufs, peak, _, _ := read()
+	if lufs == nil || math.Abs(float64(*lufs)-(-10)) > 0.01 || peak == nil || *peak != -0.5 {
+		t.Fatalf("leveled album = lufs %v peak %v, want -10 and -0.5", lufs, peak)
+	}
+
+	// 3. Nothing changed: nothing recomputed.
+	if res := pass(); res.Recomputed != 0 {
+		t.Fatalf("idle pass = %+v, want nothing recomputed", res)
+	}
+
+	// 4. A track joins (here, retagged onto this album): recomputed.
+	other, err := q.UpsertAlbum(ctx, dbq.UpsertAlbumParams{Title: "Other", SortTitle: "Other", ArtistID: artist.ID})
+	if err != nil {
+		t.Fatalf("other album: %v", err)
+	}
+	loud := addTrack("loud", other)
+	measure(loud, -4, 0.3)
+	pass()
+	if _, err := pool.Exec(ctx, "UPDATE tracks SET album_id = $1 WHERE id = $2", album.ID, loud.ID); err != nil {
+		t.Fatalf("move track: %v", err)
+	}
+	if res := pass(); res.Recomputed < 1 {
+		t.Fatalf("pass after a track joined = %+v, want a recompute", res)
+	}
+	// Two tracks at -10 and one at -4, equally long: -7.003 by energy.
+	if lufs, peak, total, _ := read(); total != 3 || lufs == nil || math.Abs(float64(*lufs)-(-7.003)) > 0.01 ||
+		peak == nil || *peak != 0.3 {
+		t.Fatalf("album after a loud track joined = lufs %v peak %v total %d", lufs, peak, total)
+	}
+
+	// 5. A track's file goes missing: recomputed without it.
+	if _, err := pool.Exec(ctx, "UPDATE tracks SET missing_since = now() WHERE id = $1", loud.ID); err != nil {
+		t.Fatalf("mark missing: %v", err)
+	}
+	pass()
+	if lufs, peak, total, _ := read(); total != 2 || lufs == nil || math.Abs(float64(*lufs)-(-10)) > 0.01 ||
+		peak == nil || *peak != -0.5 {
+		t.Fatalf("album after the loud track went missing = lufs %v peak %v total %d", lufs, peak, total)
+	}
+
+	// 6. A track is deleted (as a duplicate merge does): recomputed.
+	if _, err := pool.Exec(ctx, "DELETE FROM tracks WHERE id = $1", second.ID); err != nil {
+		t.Fatalf("delete track: %v", err)
+	}
+	pass()
+	if _, _, total, _ := read(); total != 1 {
+		t.Fatalf("album after a delete has %d tracks, want 1", total)
+	}
+
+	// 7. Every remaining track missing: the album row is dropped, not left
+	// describing tracks that are gone.
+	if _, err := pool.Exec(ctx, "UPDATE tracks SET missing_since = now() WHERE id = $1", first.ID); err != nil {
+		t.Fatalf("mark missing: %v", err)
+	}
+	if res := pass(); res.Orphans != 1 {
+		t.Fatalf("pass with every track missing = %+v, want 1 orphan dropped", res)
+	}
+	var n int
+	if err := pool.QueryRow(ctx, "SELECT count(*) FROM album_loudness WHERE album_id = $1", album.ID).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if n != 0 {
+		t.Fatalf("album loudness row survived every track going missing")
+	}
+}

internal/library/loudness.go

@@ -220,7 +220,6 @@ var (
 // histogram, and the closing summary.
 type ebur128Parser struct {
 	bins      [loudnessHistBins]int32
-	blocks    int
 	inSummary bool
 	summary   map[string]string
 	lastLines []string
@@ -273,7 +272,6 @@ func (p *ebur128Parser) line(raw string) {
 	}
 	bin := int(math.Round((v - loudnessHistFloor) * loudnessHistPerLU))
 	p.bins[min(bin, loudnessHistBins-1)]++
-	p.blocks++
 }
 
 func (p *ebur128Parser) tail() string {
@@ -281,18 +279,24 @@ func (p *ebur128Parser) tail() string {
 }
 
 func (p *ebur128Parser) histogram() blockHistogram {
-	if p.blocks == 0 {
-		return blockHistogram{}
-	}
+	return trimBins(&p.bins)
+}
+
+// trimBins turns a full-range bin array into a histogram trimmed to its
+// occupied bins; an empty array gives an empty histogram.
+func trimBins(bins *[loudnessHistBins]int32) blockHistogram {
 	first, last := 0, loudnessHistBins-1
-	for p.bins[first] == 0 {
+	for first <= last && bins[first] == 0 {
 		first++
 	}
-	for p.bins[last] == 0 {
+	if first > last {
+		return blockHistogram{}
+	}
+	for bins[last] == 0 {
 		last--
 	}
 	counts := make([]int32, last-first+1)
-	copy(counts, p.bins[first:last+1])
+	copy(counts, bins[first:last+1])
 	return blockHistogram{start: int16(first), counts: counts}
 }
 

internal/library/loudness_backfill.go

@@ -64,11 +64,12 @@ func (r *BackfillLoudnessResult) add(o loudnessOutcome) {
 
 // LoudnessBackfillWorker measures every track that has no current measurement.
 type LoudnessBackfillWorker struct {
-	pool     *pgxpool.Pool
-	logger   *slog.Logger
-	settings *LoudnessSettingsService
-	tick     time.Duration
-	batch    int32
+	pool       *pgxpool.Pool
+	logger     *slog.Logger
+	settings   *LoudnessSettingsService
+	tick       time.Duration
+	batch      int32
+	albumBatch int32
 	// analyze is a field so an integration test pins which tracks a pass
 	// touches, not what ffmpeg prints.
 	analyze func(ctx context.Context, path string, durationMs int32) loudnessResult
@@ -80,12 +81,13 @@ func NewLoudnessBackfillWorker(
 	pool *pgxpool.Pool, logger *slog.Logger, settings *LoudnessSettingsService,
 ) *LoudnessBackfillWorker {
 	return &LoudnessBackfillWorker{
-		pool:     pool,
-		logger:   logger,
-		settings: settings,
-		tick:     loudnessBackfillTick,
-		batch:    loudnessBackfillBatch,
-		analyze:  computeLoudness,
+		pool:       pool,
+		logger:     logger,
+		settings:   settings,
+		tick:       loudnessBackfillTick,
+		batch:      loudnessBackfillBatch,
+		albumBatch: albumLoudnessBatch,
+		analyze:    computeLoudness,
 	}
 }
 
@@ -121,6 +123,18 @@ func (w *LoudnessBackfillWorker) runOnce(ctx context.Context) {
 			"processed", res.Processed, "measured", res.Measured, "silent", res.Silent,
 			"unreadable", res.Unreadable, "inconclusive", res.Inconclusive)
 	}
+	// Album loudness follows the tracks (#4996). It runs even with analysis
+	// switched off: it decodes nothing, and membership still changes as the
+	// library does.
+	albums, err := w.albumPass(ctx)
+	if err != nil && ctx.Err() == nil {
+		w.logger.Warn("album loudness: pass failed", "err", err, "recomputed", albums.Recomputed)
+	}
+	if albums.Recomputed > 0 || albums.Orphans > 0 {
+		w.logger.Info("album loudness: pass complete",
+			"recomputed", albums.Recomputed, "leveled", albums.Leveled,
+			"waiting", albums.Waiting, "failed", albums.Failed, "orphans", albums.Orphans)
+	}
 }
 
 // pass walks every track needing a measurement once, keyset-paged on id. The