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/cast_token.go

@@ -8,6 +8,7 @@ import (
 
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
 )
 
 const (
@@ -19,6 +20,12 @@ const (
 type castTokenRequest struct {
 	TrackID    string `json:"trackId"`
 	ExpSeconds int    `json:"expSeconds,omitempty"`
+	// Level asks for the leveled stream (M464 #5001): the track rendered at
+	// the user's loudness gain. AsAlbum says the track is playing as part of
+	// its album in order, which picks album gain in auto mode; only the
+	// client holding the queue knows it.
+	Level   bool `json:"level,omitempty"`
+	AsAlbum bool `json:"asAlbum,omitempty"`
 }
 
 type castTokenResponse struct {
@@ -31,6 +38,10 @@ type castTokenResponse struct {
 	// `<res protocolInfo>` and `<dc:title>` without a follow-up round trip.
 	MIME  string `json:"mime"`
 	Title string `json:"title"`
+	// Leveled is true when URL is the leveled stream. A level request still
+	// gets the plain stream when there is nothing to change: leveling off,
+	// the track not yet measured, or a gain of 0.
+	Leveled bool `json:"leveled"`
 }
 
 // mimeForFormat returns the audio MIME type for a cast (Sonos/UPnP) URL.
@@ -89,7 +100,8 @@ func extForFormat(format string) string {
 // Part of the output-picker UPnP slice. See
 // docs/superpowers/specs/2026-06-03-android-output-picker-upnp-design.md.
 func (h *handlers) handleCastStreamToken(w http.ResponseWriter, r *http.Request) {
-	if _, ok := requireUser(w, r); !ok {
+	user, ok := requireUser(w, r)
+	if !ok {
 		return
 	}
 	var req castTokenRequest
@@ -112,6 +124,27 @@ func (h *handlers) handleCastStreamToken(w http.ResponseWriter, r *http.Request)
 	expSec := clampExpSeconds(req.ExpSeconds)
 	exp := time.Now().Add(time.Duration(expSec) * time.Second).Unix()
 	token := SignStreamToken(h.streamSecret, req.TrackID, exp)
+	path := streamURLWithExt(trackUUID, extForFormat(track.FileFormat)) +
+		"?token=" + token + "&exp=" + strconv.FormatInt(exp, 10)
+	mime := mimeForFormat(track.FileFormat)
+	leveled := false
+	if req.Level && h.leveled != nil {
+		g, err := h.leveledGainFor(r.Context(), user.ID, trackUUID, req.AsAlbum)
+		if err != nil {
+			// The plain stream still plays; only the leveling is lost.
+			h.logger.Warn("cast token: leveled gain lookup failed", "track", req.TrackID, "err", err)
+		} else if !g.Unity() {
+			token = SignLeveledStreamToken(h.streamSecret, req.TrackID, exp, g)
+			path = leveledStreamPath(trackUUID) + leveledQuery(g, token, exp)
+			mime = "audio/flac"
+			leveled = true
+			// The speaker fetches the URL shortly; start rendering now so
+			// the fetch finds the file ready.
+			h.leveled.Prerender(library.LeveledSource{
+				TrackID: req.TrackID, Path: track.FilePath, DurationMs: track.DurationMs,
+			}, g)
+		}
+	}
 
 	// Behind a TLS-terminating reverse proxy, r.TLS is nil even though
 	// the public-facing URL is https://. UPnP devices (Sonos especially)
@@ -131,18 +164,16 @@ func (h *handlers) handleCastStreamToken(w http.ResponseWriter, r *http.Request)
 	if h := r.Header.Get("X-Forwarded-Host"); h != "" {
 		host = h
 	}
-	// Include the file extension in the path so Sonos's URL probe sees a
+	// The path carries a file extension so Sonos's URL probe sees a
 	// recognizable audio file. Without it, Sonos reports TrackDuration=0
 	// and seeks past 0s land "after the end" -> early track-skip.
-	url := scheme + "://" + host + streamURLWithExt(trackUUID, extForFormat(track.FileFormat)) +
-		"?token=" + token + "&exp=" + strconv.FormatInt(exp, 10)
-
 	writeJSON(w, http.StatusOK, castTokenResponse{
-		Token: token,
-		Exp:   exp,
-		URL:   url,
-		MIME:  mimeForFormat(track.FileFormat),
-		Title: track.Title,
+		Token:   token,
+		Exp:     exp,
+		URL:     scheme + "://" + host + path,
+		MIME:    mime,
+		Title:   track.Title,
+		Leveled: leveled,
 	})
 }