-- 0066_album_loudness.up.sql — album loudness for album-mode normalization
-- (Scribe milestone #464, #4996).
--
-- An album's loudness is the gated loudness of every 400 ms block on the album,
-- not an average of its tracks' values: a quiet interlude and a loud single
-- should keep their difference when the album plays in order. It is computed
-- from the per-track block histograms in track_loudness (0065), summed, so no
-- audio is decoded again.
--
-- A derived value, recomputed by the loudness worker whenever its inputs
-- change. inputs_digest is an md5 over the album's present tracks and the
-- measurement each holds; the worker recomputes every album whose stored digest
-- no longer matches. That one comparison covers every way membership changes
-- (a scan moving a track between albums, a duplicate merge, a delete, a file
-- going missing or coming back) without hooking each of them.
CREATE TABLE album_loudness (
    album_id        uuid        PRIMARY KEY REFERENCES albums (id) ON DELETE CASCADE,
    -- NULL until every present track has a settled measurement: an album
    -- leveled from half its tracks would jump when the rest arrived. Also NULL
    -- for an album with no block above the gate. Clients fall back to track
    -- gain while it is NULL.
    integrated_lufs real,
    -- The loudest true peak of any track on the album, so album gain is held
    -- to the headroom of its loudest track.
    true_peak_dbtp  real,
    tracks_total    integer     NOT NULL,
    -- Tracks with a settled measurement (measured, silent or unreadable).
    tracks_settled  integer     NOT NULL,
    inputs_digest   text        NOT NULL,
    computed_at     timestamptz NOT NULL DEFAULT now()
);