feat: leveled FLAC stream for Sonos/UPnP speakers (M464 #5001)

Speakers fetch their own audio, so the phone cannot level it. A cast
token minted with level=true (and the client's asAlbum, which only the
queue holder knows) now returns GET /api/tracks/{id}/leveled.flac: the
track rendered by ffmpeg at the user's gain (volume=XdB, plus
alimiter at -1 dBFS for a limiter-mode boost), metadata stripped, FLAC
at 16 or 24 bits and at most 48 kHz. The gain is computed server-side
from the user's preference and the stored loudness, carried as
?g=<centi-dB>&lim=0|1 and signed into the token, so an edited URL does
not verify. Unity gains get the plain stream.

Renders are written beside the cache file and renamed in, keyed by the
source's size and mtime, coalesced per file (singleflight, detached
from the requesting speaker so a retry finds the render running),
started at mint time so the fetch finds them ready, and evicted least
recently used past leveled_cache_mb, a new admin setting (migration
0068, Loudness analysis card).

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

internal/api/api.go

@@ -7,6 +7,7 @@ package api
 import (
 	"log/slog"
 	"math/rand"
+	"path/filepath"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -66,6 +67,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		reacqSettings:       reacqSettings,
 		fingerprintSettings: fpSettings,
 		loudnessSettings:    loudSettings,
+		leveled:             newLeveledRenderer(dataDir, loudSettings, logger),
 		librarySize:         recommendation.NewLibrarySize(nil),
 		loginGuard:          auth.NewLoginGuard(),
 		setupToken:          setupToken,
@@ -96,6 +98,9 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		// audio format from the path. The {ext} param is consumed by chi
 		// and ignored by the handler (which keys off {id}). See task #610.
 		api.With(auth.OptionalUser(pool, logger)).Get("/tracks/{id}/stream.{ext}", h.handleGetStream)
+		// The leveled stream for Sonos/UPnP (M464 #5001): session or a
+		// leveled token, like the plain stream.
+		api.With(auth.OptionalUser(pool, logger)).Get("/tracks/{id}/leveled.flac", h.handleGetLeveledStream)
 
 		api.Group(func(authed chi.Router) {
 			authed.Use(auth.RequireUser(pool, netSettings.Hops))
@@ -343,6 +348,10 @@ type handlers struct {
 	// loudnessSettings is the loudness analysis policy (M464 #4995), the same
 	// instance the loudness backfill reads. Nil serves the defaults.
 	loudnessSettings *library.LoudnessSettingsService
+	// leveled renders the leveled streams handed to Sonos/UPnP speakers
+	// (M464 #5001). Nil when its cache directory cannot be made: a level
+	// request then gets the plain stream.
+	leveled *library.LeveledRenderer
 	// setupToken must accompany the first registration while no users exist
 	// (see auth.SetupToken). requireSetupToken is set by Mount, the only
 	// production constructor; tests that build handlers directly leave it
@@ -370,3 +379,14 @@ type handlers struct {
 	// anything a client mints), which is the desired slice-1 default.
 	streamSecret []byte
 }
+
+// newLeveledRenderer makes the leveled-stream renderer, caching under the
+// data directory. A failure is logged and leaves leveling off for speakers.
+func newLeveledRenderer(dataDir string, settings *library.LoudnessSettingsService, logger *slog.Logger) *library.LeveledRenderer {
+	r, err := library.NewLeveledRenderer(filepath.Join(dataDir, "leveled-cache"), settings, logger)
+	if err != nil {
+		logger.Error("api: leveled streams unavailable", "err", err)
+		return nil
+	}
+	return r
+}