fix(audio): stabilize loudness normalization and streaming startup behavior

Improve normalization consistency by separating cache refresh for non-playing tracks, hardening track-id cache lookups, and keeping UI gain state aligned with actual playback. Also reduce startup stalls by preferring non-seekable streaming when format hints are missing and by tuning ALSA/analysis paths to avoid underrun-prone churn.
2026-07-22 07:15:47 +00:00 · 2026-04-25 22:09:38 +03:00
parent 93b724fc65
commit 86704473ed
14 changed files with 2092 additions and 37 deletions
@@ -0,0 +1,559 @@
+use std::path::PathBuf;
+use std::io::Cursor;
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use ebur128::{EbuR128, Mode as Ebur128Mode};
+use rusqlite::{params, Connection, OptionalExtension};
+use symphonia::core::audio::SampleBuffer;
+use symphonia::core::codecs::{CODEC_TYPE_NULL, DecoderOptions};
+use symphonia::core::errors::Error as SymphoniaError;
+use symphonia::core::formats::FormatOptions;
+use symphonia::core::io::MediaSourceStream;
+use symphonia::core::meta::MetadataOptions;
+use symphonia::core::probe::Hint;
+use tauri::Manager;
+
+pub const WAVEFORM_ALGO_VERSION: i64 = 1;
+pub const LOUDNESS_ALGO_VERSION: i64 = 1;
+
+#[derive(Debug, Clone)]
+pub struct TrackKey {
+    pub track_id: String,
+    pub md5_16kb: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct WaveformEntry {
+    pub bins: Vec<u8>,
+    pub bin_count: i64,
+    pub is_partial: bool,
+    pub known_until_sec: f64,
+    pub duration_sec: f64,
+    pub updated_at: i64,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct LoudnessEntry {
+    pub integrated_lufs: f64,
+    pub true_peak: f64,
+    pub recommended_gain_db: f64,
+    pub target_lufs: f64,
+    pub updated_at: i64,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct LoudnessSnapshot {
+    pub integrated_lufs: f64,
+    pub true_peak: f64,
+    pub recommended_gain_db: f64,
+    pub target_lufs: f64,
+    pub updated_at: i64,
+}
+
+pub struct AnalysisCache {
+    conn: Mutex<Connection>,
+}
+
+/// Ranged HTTP seeding uses `stream:<subsonicId>` (see `playback_identity`); backfill
+/// and IPC often use the bare `<subsonicId>`. Rows may exist under either key.
+fn track_id_cache_variants(id: &str) -> Vec<String> {
+    let mut out = vec![id.to_string()];
+    if let Some(bare) = id.strip_prefix("stream:") {
+        if !bare.is_empty() {
+            out.push(bare.to_string());
+        }
+    } else {
+        out.push(format!("stream:{id}"));
+    }
+    out
+}
+
+impl AnalysisCache {
+    pub fn init(app: &tauri::AppHandle) -> Result<Self, String> {
+        let db_path = analysis_db_path(app)?;
+        if let Some(parent) = db_path.parent() {
+            std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
+        }
+        let conn = Connection::open(db_path).map_err(|e| e.to_string())?;
+        configure_connection(&conn).map_err(|e| e.to_string())?;
+        migrate_schema(&conn).map_err(|e| e.to_string())?;
+        Ok(Self { conn: Mutex::new(conn) })
+    }
+
+    pub fn touch_track_status(&self, key: &TrackKey, status: &str) -> Result<(), String> {
+        let now = now_unix_ts();
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        conn.execute(
+            r#"
+            INSERT INTO analysis_track (
+                track_id, md5_16kb, status, waveform_algo_version, loudness_algo_version, updated_at
+            ) VALUES (?1, ?2, ?3, ?4, ?5, ?6)
+            ON CONFLICT(track_id, md5_16kb) DO UPDATE SET
+                status = excluded.status,
+                waveform_algo_version = excluded.waveform_algo_version,
+                loudness_algo_version = excluded.loudness_algo_version,
+                updated_at = excluded.updated_at
+            "#,
+            params![
+                key.track_id,
+                key.md5_16kb,
+                status,
+                WAVEFORM_ALGO_VERSION,
+                LOUDNESS_ALGO_VERSION,
+                now
+            ],
+        )
+        .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn upsert_waveform(&self, key: &TrackKey, entry: &WaveformEntry) -> Result<(), String> {
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        conn.execute(
+            r#"
+            INSERT INTO waveform_cache (
+                track_id, md5_16kb, bins, bin_count, is_partial, known_until_sec, duration_sec, updated_at
+            ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+            ON CONFLICT(track_id, md5_16kb) DO UPDATE SET
+                bins = excluded.bins,
+                bin_count = excluded.bin_count,
+                is_partial = excluded.is_partial,
+                known_until_sec = excluded.known_until_sec,
+                duration_sec = excluded.duration_sec,
+                updated_at = excluded.updated_at
+            "#,
+            params![
+                key.track_id,
+                key.md5_16kb,
+                entry.bins,
+                entry.bin_count,
+                if entry.is_partial { 1 } else { 0 },
+                entry.known_until_sec,
+                entry.duration_sec,
+                entry.updated_at
+            ],
+        )
+        .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn upsert_loudness(&self, key: &TrackKey, entry: &LoudnessEntry) -> Result<(), String> {
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        conn.execute(
+            r#"
+            INSERT INTO loudness_cache (
+                track_id, md5_16kb, integrated_lufs, true_peak, recommended_gain_db, target_lufs, updated_at
+            ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
+            ON CONFLICT(track_id, md5_16kb, target_lufs) DO UPDATE SET
+                integrated_lufs = excluded.integrated_lufs,
+                true_peak = excluded.true_peak,
+                recommended_gain_db = excluded.recommended_gain_db,
+                updated_at = excluded.updated_at
+            "#,
+            params![
+                key.track_id,
+                key.md5_16kb,
+                entry.integrated_lufs,
+                entry.true_peak,
+                entry.recommended_gain_db,
+                entry.target_lufs,
+                entry.updated_at
+            ],
+        )
+        .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn get_waveform(&self, key: &TrackKey) -> Result<Option<WaveformEntry>, String> {
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        conn.query_row(
+            r#"
+            SELECT w.bins, w.bin_count, w.is_partial, w.known_until_sec, w.duration_sec, w.updated_at
+            FROM waveform_cache w
+            JOIN analysis_track a
+              ON a.track_id = w.track_id
+             AND a.md5_16kb = w.md5_16kb
+            WHERE w.track_id = ?1
+              AND w.md5_16kb = ?2
+              AND a.waveform_algo_version = ?3
+            "#,
+            params![key.track_id, key.md5_16kb, WAVEFORM_ALGO_VERSION],
+            |row| {
+                Ok(WaveformEntry {
+                    bins: row.get(0)?,
+                    bin_count: row.get(1)?,
+                    is_partial: row.get::<_, i64>(2)? != 0,
+                    known_until_sec: row.get(3)?,
+                    duration_sec: row.get(4)?,
+                    updated_at: row.get(5)?,
+                })
+            },
+        )
+        .optional()
+        .map_err(|e| e.to_string())
+    }
+
+    pub fn get_latest_waveform_for_track(&self, track_id: &str) -> Result<Option<WaveformEntry>, String> {
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        const SQL: &str = r#"
+            SELECT w.bins, w.bin_count, w.is_partial, w.known_until_sec, w.duration_sec, w.updated_at
+            FROM waveform_cache w
+            JOIN analysis_track a
+              ON a.track_id = w.track_id
+             AND a.md5_16kb = w.md5_16kb
+            WHERE w.track_id = ?1
+              AND a.waveform_algo_version = ?2
+            ORDER BY w.updated_at DESC
+            LIMIT 1
+            "#;
+        for tid in track_id_cache_variants(track_id) {
+            let row = conn
+                .query_row(
+                    SQL,
+                    params![tid, WAVEFORM_ALGO_VERSION],
+                    |row| {
+                        Ok(WaveformEntry {
+                            bins: row.get(0)?,
+                            bin_count: row.get(1)?,
+                            is_partial: row.get::<_, i64>(2)? != 0,
+                            known_until_sec: row.get(3)?,
+                            duration_sec: row.get(4)?,
+                            updated_at: row.get(5)?,
+                        })
+                    },
+                )
+                .optional()
+                .map_err(|e| e.to_string())?;
+            if row.is_some() {
+                return Ok(row);
+            }
+        }
+        Ok(None)
+    }
+
+    pub fn get_latest_loudness_for_track(&self, track_id: &str) -> Result<Option<LoudnessSnapshot>, String> {
+        let conn = self.conn.lock().map_err(|_| "analysis_cache lock poisoned".to_string())?;
+        const SQL: &str = r#"
+            SELECT l.integrated_lufs, l.true_peak, l.recommended_gain_db, l.target_lufs, l.updated_at
+            FROM loudness_cache l
+            JOIN analysis_track a
+              ON a.track_id = l.track_id
+             AND a.md5_16kb = l.md5_16kb
+            WHERE l.track_id = ?1
+              AND a.loudness_algo_version = ?2
+            ORDER BY l.updated_at DESC
+            LIMIT 1
+            "#;
+        for tid in track_id_cache_variants(track_id) {
+            let row = conn
+                .query_row(
+                    SQL,
+                    params![tid, LOUDNESS_ALGO_VERSION],
+                    |row| {
+                        Ok(LoudnessSnapshot {
+                            integrated_lufs: row.get(0)?,
+                            true_peak: row.get(1)?,
+                            recommended_gain_db: row.get(2)?,
+                            target_lufs: row.get(3)?,
+                            updated_at: row.get(4)?,
+                        })
+                    },
+                )
+                .optional()
+                .map_err(|e| e.to_string())?;
+            if row.is_some() {
+                return Ok(row);
+            }
+        }
+        Ok(None)
+    }
+}
+
+pub fn recommended_gain_for_target(integrated_lufs: f64, true_peak: f64, target_lufs: f64) -> f64 {
+    let mut recommended_gain_db = target_lufs - integrated_lufs;
+    if true_peak > 0.0 {
+        let true_peak_dbtp = 20.0 * true_peak.log10();
+        let max_gain_db = -1.0 - true_peak_dbtp;
+        if recommended_gain_db > max_gain_db {
+            recommended_gain_db = max_gain_db;
+        }
+    }
+    recommended_gain_db.clamp(-24.0, 24.0)
+}
+
+pub fn seed_from_bytes(app: &tauri::AppHandle, track_id: &str, bytes: &[u8]) -> Result<(), String> {
+    let Some(cache) = app.try_state::<AnalysisCache>() else {
+        return Ok(());
+    };
+    let key = TrackKey {
+        track_id: track_id.to_string(),
+        md5_16kb: md5_first_16kb(bytes),
+    };
+    cache.touch_track_status(&key, "queued")?;
+
+    let waveform = WaveformEntry {
+        bins: derive_waveform_bins(bytes, 500),
+        bin_count: 500,
+        is_partial: false,
+        known_until_sec: 0.0,
+        duration_sec: 0.0,
+        updated_at: now_unix_ts(),
+    };
+    cache.upsert_waveform(&key, &waveform)?;
+
+    if let Some((integrated_lufs, true_peak, recommended_gain_db, target_lufs)) =
+        analyze_loudness_from_audio_bytes(bytes, -16.0)
+    {
+        let loudness = LoudnessEntry {
+            integrated_lufs,
+            true_peak,
+            recommended_gain_db,
+            target_lufs,
+            updated_at: now_unix_ts(),
+        };
+        cache.upsert_loudness(&key, &loudness)?;
+    }
+
+    cache.touch_track_status(&key, "ready")?;
+    Ok(())
+}
+
+fn now_unix_ts() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+fn md5_first_16kb(bytes: &[u8]) -> String {
+    let n = bytes.len().min(16 * 1024);
+    format!("{:x}", md5::compute(&bytes[..n]))
+}
+
+fn derive_waveform_bins(bytes: &[u8], bin_count: usize) -> Vec<u8> {
+    if bin_count == 0 || bytes.is_empty() {
+        return Vec::new();
+    }
+    let mut out = vec![0u8; bin_count];
+    for (i, slot) in out.iter_mut().enumerate() {
+        let start = i * bytes.len() / bin_count;
+        let end = ((i + 1) * bytes.len() / bin_count).max(start + 1).min(bytes.len());
+        let mut peak: u8 = 0;
+        for &b in &bytes[start..end] {
+            let centered = if b >= 128 { b - 128 } else { 128 - b };
+            if centered > peak {
+                peak = centered;
+            }
+        }
+        *slot = ((peak as f32 / 127.0).sqrt().clamp(0.0, 1.0) * 255.0) as u8;
+    }
+    out
+}
+
+fn analyze_loudness_from_audio_bytes(bytes: &[u8], target_lufs: f64) -> Option<(f64, f64, f64, f64)> {
+    if bytes.is_empty() {
+        return None;
+    }
+
+    let source = Box::new(Cursor::new(bytes.to_vec()));
+    let mss = MediaSourceStream::new(source, Default::default());
+    let hint = Hint::new();
+    let probed = symphonia::default::get_probe()
+        .format(&hint, mss, &FormatOptions::default(), &MetadataOptions::default())
+        .ok()?;
+    let mut format = probed.format;
+    let track = format
+        .default_track()
+        .filter(|t| t.codec_params.codec != CODEC_TYPE_NULL)
+        .or_else(|| {
+            format
+                .tracks()
+                .iter()
+                .find(|t| {
+                    t.codec_params.codec != CODEC_TYPE_NULL
+                        && t.codec_params.sample_rate.is_some()
+                        && t.codec_params.channels.is_some()
+                })
+        })
+        .or_else(|| format.tracks().iter().find(|t| t.codec_params.codec != CODEC_TYPE_NULL))?;
+    let track_id = track.id;
+    let codec_params = track.codec_params.clone();
+
+    let mut decoder = match symphonia::default::get_codecs()
+        .make(&codec_params, &DecoderOptions::default())
+    {
+        Ok(v) => v,
+        Err(e) => {
+            crate::app_deprintln!("[analysis] decoder make failed: {}", e);
+            return None;
+        }
+    };
+    let mut ebu: Option<EbuR128> = None;
+    let mut ebu_channels: u32 = 0;
+    let mut sample_peak_abs = 0.0_f64;
+    let mut fed_any_frames = false;
+    let mut loop_i: u32 = 0;
+
+    loop {
+        let packet = match format.next_packet() {
+            Ok(packet) => packet,
+            Err(_) => break,
+        };
+        if packet.track_id() != track_id {
+            continue;
+        }
+
+        let decoded = match decoder.decode(&packet) {
+            Ok(buf) => buf,
+            Err(SymphoniaError::DecodeError(_)) => continue,
+            Err(SymphoniaError::ResetRequired) => break,
+            Err(_) => break,
+        };
+
+        let spec = *decoded.spec();
+        if ebu.is_none() {
+            let ch = spec.channels.count() as u32;
+            let sr = spec.rate;
+            match EbuR128::new(ch, sr, Ebur128Mode::I | Ebur128Mode::TRUE_PEAK) {
+                Ok(v) => {
+                    ebu = Some(v);
+                    ebu_channels = ch;
+                }
+                Err(e) => {
+                    crate::app_deprintln!(
+                        "[analysis] EbuR128 init failed: channels={} sample_rate={} err={}",
+                        ch,
+                        sr,
+                        e
+                    );
+                    return None;
+                }
+            }
+        }
+        let mut samples = SampleBuffer::<f32>::new(decoded.capacity() as u64, spec);
+        samples.copy_interleaved_ref(decoded);
+        for &s in samples.samples() {
+            let v = (s as f64).abs();
+            if v.is_finite() && v > sample_peak_abs {
+                sample_peak_abs = v;
+            }
+        }
+        let Some(ref mut ebu) = ebu else {
+            crate::app_deprintln!("[analysis] loudness failed: ebu not initialized");
+            return None;
+        };
+        match ebu.add_frames_f32(samples.samples()) {
+            Ok(_) => fed_any_frames = true,
+            Err(e) => {
+                crate::app_deprintln!("[analysis] loudness add_frames failed: {}", e);
+                return None;
+            }
+        }
+        loop_i = loop_i.wrapping_add(1);
+        if loop_i % 128 == 0 {
+            std::thread::yield_now();
+        }
+    }
+
+    if !fed_any_frames {
+        crate::app_deprintln!("[analysis] loudness failed: no decoded frames");
+        return None;
+    }
+    let Some(ebu) = ebu else {
+        crate::app_deprintln!("[analysis] loudness failed: no decoder output");
+        return None;
+    };
+    let integrated_lufs = match ebu.loudness_global() {
+        Ok(v) => v,
+        Err(e) => {
+            crate::app_deprintln!("[analysis] loudness_global failed: {}", e);
+            return None;
+        }
+    };
+    if !integrated_lufs.is_finite() {
+        crate::app_deprintln!("[analysis] loudness failed: integrated_lufs not finite");
+        return None;
+    }
+    let mut true_peak = 0.0_f64;
+    let mut true_peak_ok = true;
+    for ch in 0..ebu_channels {
+        match ebu.true_peak(ch) {
+            Ok(v) if v.is_finite() && v > true_peak => true_peak = v,
+            Ok(_) => {}
+            Err(e) => {
+                true_peak_ok = false;
+                crate::app_deprintln!("[analysis] true_peak unavailable: {}", e);
+                break;
+            }
+        }
+    }
+    if !true_peak_ok {
+        // Fallback to sample peak if true-peak is not available for this stream/codec.
+        true_peak = sample_peak_abs;
+    }
+
+    let recommended_gain_db = recommended_gain_for_target(integrated_lufs, true_peak, target_lufs);
+    Some((integrated_lufs, true_peak, recommended_gain_db, target_lufs))
+}
+
+fn analysis_db_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let base = app
+        .path()
+        .app_config_dir()
+        .map_err(|e| e.to_string())?;
+    Ok(base.join("audio-analysis.sqlite"))
+}
+
+fn configure_connection(conn: &Connection) -> rusqlite::Result<()> {
+    conn.pragma_update(None, "journal_mode", "WAL")?;
+    conn.pragma_update(None, "synchronous", "NORMAL")?;
+    conn.pragma_update(None, "temp_store", "MEMORY")?;
+    conn.pragma_update(None, "foreign_keys", "ON")?;
+    Ok(())
+}
+
+fn migrate_schema(conn: &Connection) -> rusqlite::Result<()> {
+    conn.execute_batch(
+        r#"
+        CREATE TABLE IF NOT EXISTS analysis_track (
+            track_id TEXT NOT NULL,
+            md5_16kb TEXT NOT NULL,
+            status TEXT NOT NULL,
+            waveform_algo_version INTEGER NOT NULL,
+            loudness_algo_version INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL,
+            PRIMARY KEY (track_id, md5_16kb)
+        );
+
+        CREATE TABLE IF NOT EXISTS waveform_cache (
+            track_id TEXT NOT NULL,
+            md5_16kb TEXT NOT NULL,
+            bins BLOB NOT NULL,
+            bin_count INTEGER NOT NULL,
+            is_partial INTEGER NOT NULL,
+            known_until_sec REAL NOT NULL,
+            duration_sec REAL NOT NULL,
+            updated_at INTEGER NOT NULL,
+            PRIMARY KEY (track_id, md5_16kb)
+        );
+
+        CREATE TABLE IF NOT EXISTS loudness_cache (
+            track_id TEXT NOT NULL,
+            md5_16kb TEXT NOT NULL,
+            integrated_lufs REAL NOT NULL,
+            true_peak REAL NOT NULL,
+            recommended_gain_db REAL NOT NULL,
+            target_lufs REAL NOT NULL,
+            updated_at INTEGER NOT NULL,
+            PRIMARY KEY (track_id, md5_16kb, target_lufs)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_analysis_track_status
+            ON analysis_track(status);
+        "#,
+    )?;
+    Ok(())
+}
@@ -21,7 +21,41 @@ use symphonia::core::{
    units::{self, Time},
 };
 use futures_util::StreamExt;
-use tauri::{AppHandle, Emitter, State};
+use tauri::{AppHandle, Emitter, Manager, State};
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct PartialWaveformPayload {
+    track_id: Option<String>,
+    bins: Vec<u8>,
+    known_until_sec: f64,
+    duration_sec: f64,
+    is_partial: bool,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct PartialLoudnessPayload {
+    track_id: Option<String>,
+    gain_db: f32,
+    target_lufs: f32,
+    is_partial: bool,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct WaveformUpdatedPayload {
+    track_id: String,
+    is_partial: bool,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct NormalizationStatePayload {
+    engine: String,
+    current_gain_db: Option<f32>,
+    target_lufs: f32,
+}
+

 // ─── 10-Band Graphic Equalizer ────────────────────────────────────────────────

@@ -1021,17 +1055,20 @@ async fn track_download_task(
    gen: u64,
    gen_arc: Arc<AtomicU64>,
    http_client: reqwest::Client,
+    app: AppHandle,
    url: String,
    initial_response: reqwest::Response,
    mut prod: HeapProducer<u8>,
    done: Arc<AtomicBool>,
    promote_cache_slot: Arc<Mutex<Option<PreloadedTrack>>>,
+    normalization_target_lufs: Arc<AtomicU32>,
 ) {
    let mut downloaded: u64 = 0;
    let mut reconnects: u32 = 0;
    let mut next_response: Option<reqwest::Response> = Some(initial_response);
    let mut capture: Vec<u8> = Vec::new();
    let mut capture_over_limit = false;
+    let mut last_partial_loudness_emit = Instant::now() - Duration::from_secs(5);
    'outer: loop {
        let response = if let Some(r) = next_response.take() {
            r
@@ -1120,12 +1157,29 @@ async fn track_download_task(
                            capture_over_limit = true;
                        }
                    }
+                    if !capture_over_limit
+                        && last_partial_loudness_emit.elapsed() >= Duration::from_millis(PARTIAL_LOUDNESS_EMIT_INTERVAL_MS)
+                    {
+                        let target_lufs = f32::from_bits(normalization_target_lufs.load(Ordering::Relaxed));
+                        emit_partial_loudness_from_bytes(&app, &url, &capture, target_lufs);
+                        last_partial_loudness_emit = Instant::now();
+                    }
                    offset += pushed;
                    downloaded += pushed as u64;
                }
            }
        }
        if !capture_over_limit && !capture.is_empty() {
+            if let Some(track_id) = playback_identity(&url) {
+                if let Err(e) = crate::analysis_cache::seed_from_bytes(&app, &track_id, &capture) {
+                    crate::app_eprintln!("[analysis] track seed failed for {}: {}", track_id, e);
+                } else {
+                    let _ = app.emit(
+                        "analysis:waveform-updated",
+                        WaveformUpdatedPayload { track_id, is_partial: false },
+                    );
+                }
+            }
            *promote_cache_slot.lock().unwrap() = Some(PreloadedTrack {
                url: url.clone(),
                data: capture,
@@ -1144,12 +1198,15 @@ async fn ranged_download_task(
    gen: u64,
    gen_arc: Arc<AtomicU64>,
    http_client: reqwest::Client,
+    app: AppHandle,
+    duration_hint: f64,
    url: String,
    initial_response: reqwest::Response,
    buf: Arc<Mutex<Vec<u8>>>,
    downloaded_to: Arc<AtomicUsize>,
    done: Arc<AtomicBool>,
    promote_cache_slot: Arc<Mutex<Option<PreloadedTrack>>>,
+    normalization_target_lufs: Arc<AtomicU32>,
 ) {
    let total_size = buf.lock().unwrap().len();
    let mut downloaded: usize = 0;
@@ -1157,6 +1214,8 @@ async fn ranged_download_task(
    let mut next_response: Option<reqwest::Response> = Some(initial_response);
    let dl_started = Instant::now();
    let mut next_progress_mb: usize = 1;
+    let mut last_partial_emit = Instant::now();
+    let mut last_partial_loudness_emit = Instant::now() - Duration::from_secs(5);

    'outer: loop {
        let response = if let Some(r) = next_response.take() {
@@ -1231,6 +1290,51 @@ async fn ranged_download_task(
            }
            downloaded += n;
            downloaded_to.store(downloaded, Ordering::SeqCst);
+            if downloaded >= 4096
+                && total_size > 0
+                && last_partial_emit.elapsed() >= partial_waveform_emit_min_interval(downloaded)
+            {
+                let bins =
+                    derive_partial_waveform_bins_short_locks(&buf, downloaded, 500);
+                if last_partial_loudness_emit.elapsed() >= Duration::from_millis(PARTIAL_LOUDNESS_EMIT_INTERVAL_MS) {
+                    let target_lufs = f32::from_bits(normalization_target_lufs.load(Ordering::Relaxed));
+                    if let Some(provisional_db) = provisional_loudness_gain_from_progress(downloaded, total_size, target_lufs) {
+                        let _ = app.emit(
+                            "analysis:loudness-partial",
+                            PartialLoudnessPayload {
+                                track_id: playback_identity(&url),
+                                gain_db: provisional_db,
+                                target_lufs,
+                                is_partial: true,
+                            },
+                        );
+                        crate::app_deprintln!(
+                            "[normalization] partial-loudness provisional progress={:.2}% gain_db={:.2} target_lufs={:.2} track_id={:?}",
+                            (downloaded as f32 / total_size as f32) * 100.0,
+                            provisional_db,
+                            target_lufs,
+                            playback_identity(&url)
+                        );
+                    }
+                    last_partial_loudness_emit = Instant::now();
+                };
+                let known_until_sec = if duration_hint > 0.0 {
+                    (duration_hint * downloaded as f64 / total_size as f64).clamp(0.0, duration_hint)
+                } else {
+                    0.0
+                };
+                let _ = app.emit(
+                    "analysis:waveform-partial",
+                    PartialWaveformPayload {
+                        track_id: playback_identity(&url),
+                        bins,
+                        known_until_sec,
+                        duration_sec: duration_hint.max(0.0),
+                        is_partial: true,
+                    },
+                );
+                last_partial_emit = Instant::now();
+            }
            let mb = downloaded / (1024 * 1024);
            if mb >= next_progress_mb {
                let pct = (downloaded as f64 / total_size as f64 * 100.0) as u32;
@@ -1262,11 +1366,144 @@ async fn ranged_download_task(

    if downloaded == total_size && total_size > 0 && total_size <= TRACK_STREAM_PROMOTE_MAX_BYTES {
        let data = buf.lock().unwrap().clone();
+        if let Some(track_id) = playback_identity(&url) {
+            if let Err(e) = crate::analysis_cache::seed_from_bytes(&app, &track_id, &data) {
+                crate::app_eprintln!("[analysis] ranged seed failed for {}: {}", track_id, e);
+            } else {
+                let _ = app.emit(
+                    "analysis:waveform-updated",
+                    WaveformUpdatedPayload { track_id, is_partial: false },
+                );
+            }
+        }
        *promote_cache_slot.lock().unwrap() = Some(PreloadedTrack { url, data });
        crate::app_deprintln!("[stream] promoted to stream_completed_cache for replay");
    }
 }

+/// Wall-clock spacing for `analysis:waveform-partial` — larger buffers cost more
+/// to summarize, so we slow emits and keep UI responsive without CPU spikes.
+fn partial_waveform_emit_min_interval(downloaded: usize) -> Duration {
+    const MB: usize = 1024 * 1024;
+    if downloaded <= 3 * MB {
+        Duration::from_millis(280)
+    } else if downloaded <= 10 * MB {
+        Duration::from_millis(650)
+    } else {
+        Duration::from_millis(1100)
+    }
+}
+
+/// Max centered-byte samples examined per bin for partial waveforms (full track
+/// analysis still uses dense scans elsewhere). Keeps work O(bin_count × cap).
+const PARTIAL_WAVEFORM_SAMPLES_PER_BIN_CAP: usize = 2048;
+
+fn peak_centered_byte_sampled(region: &[u8]) -> u8 {
+    if region.is_empty() {
+        return 0;
+    }
+    let cap = PARTIAL_WAVEFORM_SAMPLES_PER_BIN_CAP;
+    let mut peak: u8 = 0;
+    if region.len() <= cap {
+        for &b in region {
+            let centered = if b >= 128 { b - 128 } else { 128 - b };
+            if centered > peak {
+                peak = centered;
+            }
+        }
+    } else {
+        let step = (region.len() / cap).max(1);
+        let mut i = 0;
+        while i < region.len() {
+            let b = region[i];
+            let centered = if b >= 128 { b - 128 } else { 128 - b };
+            if centered > peak {
+                peak = centered;
+            }
+            i = i.saturating_add(step);
+        }
+        let b = region[region.len() - 1];
+        let centered = if b >= 128 { b - 128 } else { 128 - b };
+        if centered > peak {
+            peak = centered;
+        }
+    }
+    peak
+}
+
+/// Partial waveform without cloning the whole download buffer and without
+/// holding `buf` locked across all bins (that would stall the decoder's `read()`).
+fn derive_partial_waveform_bins_short_locks(
+    buf: &Arc<Mutex<Vec<u8>>>,
+    downloaded: usize,
+    bin_count: usize,
+) -> Vec<u8> {
+    if downloaded == 0 || bin_count == 0 {
+        return Vec::new();
+    }
+    let len = downloaded;
+    let mut out = vec![0u8; bin_count];
+    for (i, slot) in out.iter_mut().enumerate() {
+        let start = i * len / bin_count;
+        let end = ((i + 1) * len / bin_count).max(start + 1).min(len);
+        let peak = {
+            let b = buf.lock().unwrap();
+            if start >= b.len() {
+                0u8
+            } else {
+                let end = end.min(b.len());
+                peak_centered_byte_sampled(&b[start..end])
+            }
+        };
+        *slot = ((peak as f32 / 127.0).sqrt().clamp(0.0, 1.0) * 255.0) as u8;
+    }
+    out
+}
+
+fn emit_partial_loudness_from_bytes(app: &AppHandle, url: &str, bytes: &[u8], target_lufs: f32) {
+    if bytes.len() < PARTIAL_LOUDNESS_MIN_BYTES {
+        crate::app_deprintln!(
+            "[normalization] partial-loudness skip reason=insufficient-bytes bytes={} min_bytes={}",
+            bytes.len(),
+            PARTIAL_LOUDNESS_MIN_BYTES
+        );
+        return;
+    }
+    // Lightweight fallback based on buffered bytes count to keep CPU low.
+    let mb = bytes.len() as f32 / (1024.0 * 1024.0);
+    let floor_db = (target_lufs + 11.0).clamp(-6.0, -1.5);
+    let gain_db = (-(mb * 0.7)).max(floor_db).min(0.0);
+    crate::app_deprintln!(
+        "[normalization] partial-loudness emit bytes={} gain_db={:.2} target_lufs={:.2} track_id={:?}",
+        bytes.len(),
+        gain_db,
+        target_lufs,
+        playback_identity(url)
+    );
+    let _ = app.emit(
+        "analysis:loudness-partial",
+        PartialLoudnessPayload {
+            track_id: playback_identity(url),
+            gain_db: gain_db as f32,
+            target_lufs,
+            is_partial: true,
+        },
+    );
+}
+
+fn provisional_loudness_gain_from_progress(downloaded: usize, total_size: usize, target_lufs: f32) -> Option<f32> {
+    if total_size == 0 || downloaded == 0 {
+        return None;
+    }
+    let progress = (downloaded as f32 / total_size as f32).clamp(0.0, 1.0);
+    // Move from startup attenuation toward a more realistic late-stream level.
+    // This avoids staying near -2 dB and then jumping hard when final LUFS lands.
+    let start_db = LOUDNESS_STARTUP_ATTENUATION_DB.min(0.0);
+    let end_db = (target_lufs + 6.0).clamp(-10.0, -3.0).min(0.0);
+    let shaped = progress.powf(0.75);
+    Some(start_db + (end_db - start_db) * shaped)
+}
+
 fn content_type_to_hint(ct: &str) -> Option<String> {
    let ct = ct.to_ascii_lowercase();
    if ct.contains("mpeg") || ct.contains("mp3") { Some("mp3".into()) }
@@ -1999,6 +2236,10 @@ pub struct AudioEngine {
    /// When true, audio_play chains sources to the existing Sink instead of
    /// creating a new one, achieving sample-accurate gapless transitions.
    pub gapless_enabled: Arc<AtomicBool>,
+    /// 0=off, 1=replaygain, 2=loudness (future runtime loudness engine).
+    pub normalization_engine: Arc<AtomicU32>,
+    /// Target loudness in LUFS for loudness engine (future use).
+    pub normalization_target_lufs: Arc<AtomicU32>,
    /// Info about the next-up chained track (gapless mode).
    /// The progress task reads this when `current_source_done` fires.
    pub(crate) chained_info: Arc<Mutex<Option<ChainedInfo>>>,
@@ -2015,6 +2256,10 @@ pub struct AudioEngine {
    /// Active radio session state.  None for regular (non-radio) tracks.
    /// Dropping the value aborts the HTTP download task via RadioLiveState::Drop.
    pub(crate) radio_state: Mutex<Option<RadioLiveState>>,
+    /// URL last committed to `AudioCurrent` — used so `audio_update_replay_gain` can
+    /// resolve LUFS / startup trim when the frontend passes `loudnessGainDb: null`
+    /// (otherwise `compute_gain` would treat that as unity gain and playback "jumps").
+    pub(crate) current_playback_url: Arc<Mutex<Option<String>>>,
 }

 pub struct AudioCurrent {
@@ -2190,11 +2435,13 @@ pub fn create_engine() -> (AudioEngine, std::thread::JoinHandle<()>) {
            // Set PipeWire / PulseAudio latency hints before the first open.
            #[cfg(target_os = "linux")]
            {
+                // Match cpal ALSA ~200 ms headroom: larger quantum reduces underruns when
+                // the decoder thread catches up after seek or competes with other work.
                if std::env::var("PIPEWIRE_LATENCY").is_err() {
-                    std::env::set_var("PIPEWIRE_LATENCY", "4096/48000");
+                    std::env::set_var("PIPEWIRE_LATENCY", "8192/48000");
                }
                if std::env::var("PULSE_LATENCY_MSEC").is_err() {
-                    std::env::set_var("PULSE_LATENCY_MSEC", "85");
+                    std::env::set_var("PULSE_LATENCY_MSEC", "170");
                }
            }

@@ -2276,12 +2523,15 @@ pub fn create_engine() -> (AudioEngine, std::thread::JoinHandle<()>) {
        crossfade_secs: Arc::new(AtomicU32::new(3.0f32.to_bits())),
        fading_out_sink: Arc::new(Mutex::new(None)),
        gapless_enabled: Arc::new(AtomicBool::new(false)),
+        normalization_engine: Arc::new(AtomicU32::new(0)),
+        normalization_target_lufs: Arc::new(AtomicU32::new((-16.0f32).to_bits())),
        chained_info: Arc::new(Mutex::new(None)),
        samples_played: Arc::new(AtomicU64::new(0)),
        current_sample_rate: Arc::new(AtomicU32::new(0)),
        current_channels: Arc::new(AtomicU32::new(2)),
        gapless_switch_at: Arc::new(AtomicU64::new(0)),
        radio_state: Mutex::new(None),
+        current_playback_url: Arc::new(Mutex::new(None)),
    };

    (engine, thread)
@@ -2343,6 +2593,101 @@ fn same_playback_target(a_url: &str, b_url: &str) -> bool {
    }
 }

+fn resolve_loudness_gain_from_cache(
+    app: &AppHandle,
+    url: &str,
+    target_lufs: f32,
+    requested_loudness_gain_db: Option<f32>,
+) -> Option<f32> {
+    // Never trust `requested` alone: the frontend may pass the *next* track's gain
+    // while `current_playback_url` still lags one play behind. Always prefer a
+    // cache row for **this** URL's track_id; use `requested` only on cache miss
+    // (provisional / pre-seed from JS).
+    let Some(track_id) = playback_identity(url) else {
+        if let Some(r) = requested_loudness_gain_db {
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=request-no-identity arg={:.4}",
+                r
+            );
+        }
+        return requested_loudness_gain_db;
+    };
+    let Some(cache) = app.try_state::<crate::analysis_cache::AnalysisCache>() else {
+        if let Some(r) = requested_loudness_gain_db {
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=request-no-cache arg={:.4} track_id={}",
+                r,
+                track_id
+            );
+        }
+        return requested_loudness_gain_db;
+    };
+    // Also touch waveform row here so playback path verifies current context is present.
+    let _ = cache.get_latest_waveform_for_track(&track_id);
+    match cache.get_latest_loudness_for_track(&track_id) {
+        Ok(Some(row)) if row.integrated_lufs.is_finite() => {
+            let recommended = crate::analysis_cache::recommended_gain_for_target(
+                row.integrated_lufs,
+                row.true_peak,
+                target_lufs as f64,
+            ) as f32;
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=cache track_id={} gain_db={:.2} target_lufs={:.2} integrated_lufs={:.2} updated_at={}",
+                track_id,
+                recommended,
+                target_lufs,
+                row.integrated_lufs,
+                row.updated_at
+            );
+            Some(recommended)
+        }
+        Ok(Some(row)) => {
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=cache-invalid track_id={} integrated_lufs={}",
+                track_id,
+                row.integrated_lufs
+            );
+            None
+        }
+        Ok(None) => {
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=cache-miss track_id={}",
+                track_id
+            );
+            if let Some(r) = requested_loudness_gain_db {
+                crate::app_deprintln!(
+                    "[normalization] resolve_loudness_gain source=request-fallback track_id={} arg={:.4}",
+                    track_id,
+                    r
+                );
+                Some(r)
+            } else {
+                None
+            }
+        }
+        Err(e) => {
+            crate::app_deprintln!(
+                "[normalization] resolve_loudness_gain source=cache-error track_id={} err={}",
+                track_id,
+                e
+            );
+            None
+        }
+    }
+}
+
+/// LUFS mode: use cache / explicit `requested`, else a **conservative** trim until
+/// analysis exists — must never return `None` here or `compute_gain` uses unity.
+fn loudness_gain_db_or_startup(
+    app: &AppHandle,
+    url: &str,
+    target_lufs: f32,
+    requested: Option<f32>,
+) -> Option<f32> {
+    resolve_loudness_gain_from_cache(app, url, target_lufs, requested)
+        .or(Some(LOUDNESS_STARTUP_ATTENUATION_DB))
+}
+
 /// Take (consume) completed manual-stream bytes if they correspond to `url`.
 pub(crate) fn take_stream_completed_for_url(state: &AudioEngine, url: &str) -> Option<Vec<u8>> {
    let mut guard = state.stream_completed_cache.lock().unwrap();
@@ -2439,23 +2784,104 @@ async fn fetch_data(
 /// can produce inter-sample peaks slightly above ±1.0 → audible distortion.
 /// 10^(-1/20) ≈ 0.891 — inaudible volume difference, eliminates clipping.
 const MASTER_HEADROOM: f32 = 0.891_254;
+const PARTIAL_LOUDNESS_MIN_BYTES: usize = 256 * 1024;
+const PARTIAL_LOUDNESS_EMIT_INTERVAL_MS: u64 = 350;
+/// Until integrated LUFS is known, stay clearly below "full" level so a follow-up
+/// `audio_update_replay_gain(null)` cannot briefly blast louder than this anchor.
+const LOUDNESS_STARTUP_ATTENUATION_DB: f32 = -6.0;

 fn compute_gain(
+    normalization_engine: u32,
    replay_gain_db: Option<f32>,
    replay_gain_peak: Option<f32>,
+    loudness_gain_db: Option<f32>,
    pre_gain_db: f32,
    fallback_db: f32,
    volume: f32,
 ) -> (f32, f32) {
-    let gain_linear = replay_gain_db
-        .map(|db| 10f32.powf((db + pre_gain_db) / 20.0))
-        .unwrap_or_else(|| 10f32.powf(fallback_db / 20.0));
-    let peak = replay_gain_peak.unwrap_or(1.0).max(0.001);
+    let gain_linear = match normalization_engine {
+        2 => loudness_gain_db
+            .map(|db| 10f32.powf(db / 20.0))
+            .unwrap_or(1.0),
+        1 => replay_gain_db
+            .map(|db| 10f32.powf((db + pre_gain_db) / 20.0))
+            .unwrap_or_else(|| 10f32.powf(fallback_db / 20.0)),
+        _ => 1.0,
+    };
+    let peak = if normalization_engine == 1 {
+        replay_gain_peak.unwrap_or(1.0).max(0.001)
+    } else {
+        1.0
+    };
    let gain_linear = gain_linear.min(1.0 / peak);
    let effective = (volume.clamp(0.0, 1.0) * gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
    (gain_linear, effective)
 }

+fn normalization_engine_name(mode: u32) -> &'static str {
+    match mode {
+        1 => "replaygain",
+        2 => "loudness",
+        _ => "off",
+    }
+}
+
+fn gain_linear_to_db(gain_linear: f32) -> Option<f32> {
+    if gain_linear.is_finite() && gain_linear > 0.0 {
+        Some(20.0 * gain_linear.log10())
+    } else {
+        None
+    }
+}
+
+/// `audio:normalization-state` “Now dB” for the UI: omit a number while loudness
+/// mode is still on the **startup safety trim** only (no cache row / no explicit
+/// requested gain from analysis), so users do not read `-6 dB` as measured LUFS.
+fn loudness_ui_current_gain_db(
+    norm_mode: u32,
+    resolved_loudness_gain_db: Option<f32>,
+    gain_linear: f32,
+) -> Option<f32> {
+    if norm_mode == 2 && resolved_loudness_gain_db.is_none() {
+        None
+    } else {
+        gain_linear_to_db(gain_linear)
+    }
+}
+
+fn ramp_sink_volume(sink: Arc<Sink>, from: f32, to: f32) {
+    let from = from.clamp(0.0, 1.0);
+    let to = to.clamp(0.0, 1.0);
+    if (to - from).abs() < 0.002 {
+        sink.set_volume(to);
+        return;
+    }
+    static RAMP_GEN: AtomicU64 = AtomicU64::new(0);
+    let my_gen = RAMP_GEN.fetch_add(1, Ordering::SeqCst) + 1;
+    std::thread::spawn(move || {
+        let delta = (to - from).abs();
+        // Stretch large corrections to avoid audible "step down" moments.
+        let (steps, step_ms): (usize, u64) = if delta > 0.30 {
+            (24, 35)
+        } else if delta > 0.18 {
+            (18, 30)
+        } else if delta > 0.10 {
+            (14, 24)
+        } else {
+            (8, 16)
+        };
+        for i in 1..=steps {
+            if RAMP_GEN.load(Ordering::SeqCst) != my_gen {
+                return;
+            }
+            let t = i as f32 / steps as f32;
+            let v = from + (to - from) * t;
+            sink.set_volume(v.clamp(0.0, 1.0));
+            std::thread::sleep(Duration::from_millis(step_ms));
+        }
+    });
+}
+
 // ─── Commands ─────────────────────────────────────────────────────────────────

 #[tauri::command]
@@ -2465,6 +2891,7 @@ pub async fn audio_play(
    duration_hint: f64,
    replay_gain_db: Option<f32>,
    replay_gain_peak: Option<f32>,
+    loudness_gain_db: Option<f32>,
    pre_gain_db: f32,
    fallback_db: f32,
    manual: bool, // true = user-initiated skip → bypass crossfade, start immediately
@@ -2541,6 +2968,11 @@ pub async fn audio_play(
        old.stop();
    }

+    // Pin the logical playback URL immediately so `audio_update_replay_gain` (e.g. from
+    // a fast `refreshLoudness` after `playTrack`) resolves LUFS for **this** track, not
+    // the previous URL still stored until the sink swap completes.
+    *state.current_playback_url.lock().unwrap() = Some(url.clone());
+
    // Extract format hint from URL for better symphonia probing. Strip the
    // query string first so Subsonic-style URLs (`stream.view?...&v=1.16.1&...`)
    // don't latch onto random query-param substrings; only accept short
@@ -2646,7 +3078,11 @@ pub async fn audio_play(
                .is_some_and(|v| v.to_ascii_lowercase().contains("bytes"));
            let total_size = response.content_length();

-            if let (true, Some(total)) = (supports_range, total_size) {
+            // Guardrail: when format/container hint is unknown, some demuxers may
+            // seek near EOF during probe. With a progressively downloaded ranged
+            // source that can delay first audible samples until most/all bytes are
+            // fetched. Prefer sequential streaming in that case for faster start.
+            if let (true, Some(total), true) = (supports_range, total_size, stream_hint.is_some()) {
                let total_usize = total as usize;
                crate::app_deprintln!(
                    "[stream] RangedHttpSource selected — total={} KB, hint={:?}",
@@ -2660,12 +3096,15 @@ pub async fn audio_play(
                    gen,
                    state.generation.clone(),
                    audio_http_client(&state),
+                    app.clone(),
+                    duration_hint,
                    url.clone(),
                    response,
                    buf.clone(),
                    downloaded_to.clone(),
                    done.clone(),
                    state.stream_completed_cache.clone(),
+                    state.normalization_target_lufs.clone(),
                ));
                let reader = RangedHttpSource {
                    buf,
@@ -2683,8 +3122,8 @@ pub async fn audio_play(
                }
            } else {
                crate::app_deprintln!(
-                    "[stream] legacy AudioStreamReader (non-seekable) — accept-ranges={}, content-length={:?}",
-                    supports_range, total_size
+                    "[stream] legacy AudioStreamReader (non-seekable) — accept-ranges={}, content-length={:?}, hint={:?}",
+                    supports_range, total_size, stream_hint
                );
                let buffer_cap = total_size
                    .map(|n| n as usize)
@@ -2697,11 +3136,13 @@ pub async fn audio_play(
                    gen,
                    state.generation.clone(),
                    audio_http_client(&state),
+                    app.clone(),
                    url.clone(),
                    response,
                    prod,
                    done.clone(),
                    state.stream_completed_cache.clone(),
+                    state.normalization_target_lufs.clone(),
                ));

                let (_new_cons_tx, new_cons_rx) = std::sync::mpsc::channel::<HeapConsumer<u8>>();
@@ -2735,7 +3176,45 @@ pub async fn audio_play(
        return Ok(());
    }

-    let (gain_linear, effective_volume) = compute_gain(replay_gain_db, replay_gain_peak, pre_gain_db, fallback_db, volume);
+    let target_lufs = f32::from_bits(state.normalization_target_lufs.load(Ordering::Relaxed));
+    let resolved_loudness_gain_db = resolve_loudness_gain_from_cache(&app, &url, target_lufs, loudness_gain_db);
+    let norm_mode = state.normalization_engine.load(Ordering::Relaxed);
+    let startup_loudness_gain_db = if norm_mode == 2 {
+        loudness_gain_db_or_startup(&app, &url, target_lufs, loudness_gain_db)
+    } else {
+        resolved_loudness_gain_db
+    };
+    let (gain_linear, effective_volume) = compute_gain(
+        norm_mode,
+        replay_gain_db,
+        replay_gain_peak,
+        startup_loudness_gain_db,
+        pre_gain_db,
+        fallback_db,
+        volume,
+    );
+    let current_gain_db = loudness_ui_current_gain_db(norm_mode, resolved_loudness_gain_db, gain_linear);
+    crate::app_deprintln!(
+        "[normalization] audio_play track_id={:?} engine={} replay_gain_db={:?} replay_gain_peak={:?} loudness_gain_db={:?} gain_linear={:.4} current_gain_db={:?} target_lufs={:.2} volume={:.3} effective_volume={:.3}",
+        playback_identity(&url),
+        normalization_engine_name(norm_mode),
+        replay_gain_db,
+        replay_gain_peak,
+        resolved_loudness_gain_db,
+        gain_linear,
+        current_gain_db,
+        target_lufs,
+        volume,
+        effective_volume
+    );
+    let _ = app.emit(
+        "audio:normalization-state",
+        NormalizationStatePayload {
+            engine: normalization_engine_name(norm_mode).to_string(),
+            current_gain_db,
+            target_lufs,
+        },
+    );

    // Manual skips (user-initiated) bypass crossfade — the track should start immediately.
    let crossfade_enabled = state.crossfade_enabled.load(Ordering::Relaxed) && !manual;
@@ -2999,6 +3478,7 @@ pub async fn audio_play(
        state.current_sample_rate.clone(),
        state.current_channels.clone(),
        state.gapless_switch_at.clone(),
+        state.current_playback_url.clone(),
    );

    Ok(())
@@ -3020,9 +3500,11 @@ pub async fn audio_chain_preload(
    duration_hint: f64,
    replay_gain_db: Option<f32>,
    replay_gain_peak: Option<f32>,
+    loudness_gain_db: Option<f32>,
    pre_gain_db: f32,
    fallback_db: f32,
    hi_res_enabled: bool,
+    app: AppHandle,
    state: State<'_, AudioEngine>,
 ) -> Result<(), String> {
    // Idempotent: already chained this track → nothing to do.
@@ -3087,7 +3569,22 @@ pub async fn audio_chain_preload(
    // current track ends, and `Sink::set_volume` affects the WHOLE Sink (incl.
    // the still-playing current source). Volume for the chained track is
    // applied at the gapless transition in `spawn_progress_task`, not here.
-    let (gain_linear, _effective_volume) = compute_gain(replay_gain_db, replay_gain_peak, pre_gain_db, fallback_db, volume);
+    let target_lufs = f32::from_bits(state.normalization_target_lufs.load(Ordering::Relaxed));
+    let norm_mode = state.normalization_engine.load(Ordering::Relaxed);
+    let chain_loudness_db = if norm_mode == 2 {
+        loudness_gain_db_or_startup(&app, &url, target_lufs, loudness_gain_db)
+    } else {
+        resolve_loudness_gain_from_cache(&app, &url, target_lufs, loudness_gain_db)
+    };
+    let (gain_linear, _effective_volume) = compute_gain(
+        norm_mode,
+        replay_gain_db,
+        replay_gain_peak,
+        chain_loudness_db,
+        pre_gain_db,
+        fallback_db,
+        volume,
+    );

    let done_next = Arc::new(AtomicBool::new(false));
    // Use a dedicated counter for the chained source — it will be swapped into
@@ -3189,6 +3686,7 @@ fn spawn_progress_task(
    sample_rate_arc: Arc<AtomicU32>,
    channels_arc: Arc<AtomicU32>,
    gapless_switch_at: Arc<AtomicU64>,
+    current_playback_url: Arc<Mutex<Option<String>>>,
 ) {
    tokio::spawn(async move {
        let mut near_end_ticks: u32 = 0;
@@ -3239,6 +3737,7 @@ fn spawn_progress_task(
                    // must only be called at the boundary, not at preload.
                    {
                        let mut cur = current_arc.lock().unwrap();
+                        let prev_effective = (cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
                        cur.replay_gain_linear = info.replay_gain_linear;
                        cur.base_volume = info.base_volume;
                        cur.duration_secs = info.duration_secs;
@@ -3246,10 +3745,12 @@ fn spawn_progress_task(
                        cur.play_started = Some(Instant::now());
                        if let Some(sink) = &cur.sink {
                            let effective = (cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
-                            sink.set_volume(effective);
+                            ramp_sink_volume(Arc::clone(sink), prev_effective, effective);
                        }
                    }

+                    *current_playback_url.lock().unwrap() = Some(info.url.clone());
+
                    // Record the gapless switch timestamp for ghost-command guard.
                    let switch_ts = std::time::SystemTime::now()
                        .duration_since(std::time::UNIX_EPOCH)
@@ -3411,6 +3912,7 @@ pub async fn audio_resume(state: State<'_, AudioEngine>, app: AppHandle) -> Resu
 #[tauri::command]
 pub fn audio_stop(state: State<'_, AudioEngine>) {
    state.generation.fetch_add(1, Ordering::SeqCst);
+    *state.current_playback_url.lock().unwrap() = None;
    *state.chained_info.lock().unwrap() = None;
    *state.stream_completed_cache.lock().unwrap() = None;
    // Drop RadioLiveState → triggers Drop → task.abort() → TCP released.
@@ -3525,9 +4027,11 @@ pub fn audio_seek(seconds: f64, state: State<'_, AudioEngine>) -> Result<(), Str
 #[tauri::command]
 pub fn audio_set_volume(volume: f32, state: State<'_, AudioEngine>) {
    let mut cur = state.current.lock().unwrap();
+    let prev_effective = (cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
    cur.base_volume = volume.clamp(0.0, 1.0);
    if let Some(sink) = &cur.sink {
-        sink.set_volume((cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0));
+        let next_effective = (cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
+        ramp_sink_volume(Arc::clone(sink), prev_effective, next_effective);
    }
 }

@@ -3536,17 +4040,67 @@ pub fn audio_update_replay_gain(
    volume: f32,
    replay_gain_db: Option<f32>,
    replay_gain_peak: Option<f32>,
+    loudness_gain_db: Option<f32>,
    pre_gain_db: f32,
    fallback_db: f32,
+    app: AppHandle,
    state: State<'_, AudioEngine>,
 ) {
-    let (gain_linear, effective) = compute_gain(replay_gain_db, replay_gain_peak, pre_gain_db, fallback_db, volume);
+    let norm_mode = state.normalization_engine.load(Ordering::Relaxed);
+    let target_lufs = f32::from_bits(state.normalization_target_lufs.load(Ordering::Relaxed));
+    let url_for_loudness = if norm_mode == 2 {
+        state.current_playback_url.lock().unwrap().clone()
+    } else {
+        None
+    };
+    let resolved_loudness_gain_db = url_for_loudness
+        .as_deref()
+        .and_then(|u| resolve_loudness_gain_from_cache(&app, u, target_lufs, loudness_gain_db));
+    let effective_loudness_db = if norm_mode == 2 {
+        match url_for_loudness.as_deref() {
+            Some(u) => loudness_gain_db_or_startup(&app, u, target_lufs, loudness_gain_db),
+            None => loudness_gain_db.or(Some(LOUDNESS_STARTUP_ATTENUATION_DB)),
+        }
+    } else {
+        loudness_gain_db
+    };
+    let (gain_linear, effective) = compute_gain(
+        norm_mode,
+        replay_gain_db,
+        replay_gain_peak,
+        effective_loudness_db,
+        pre_gain_db,
+        fallback_db,
+        volume,
+    );
+    let current_gain_db = loudness_ui_current_gain_db(norm_mode, resolved_loudness_gain_db, gain_linear);
+    crate::app_deprintln!(
+        "[normalization] audio_update_replay_gain engine={} replay_gain_db={:?} replay_gain_peak={:?} loudness_gain_db={:?} gain_linear={:.4} current_gain_db={:?} target_lufs={:.2} volume={:.3} effective={:.3}",
+        normalization_engine_name(norm_mode),
+        replay_gain_db,
+        replay_gain_peak,
+        loudness_gain_db,
+        gain_linear,
+        current_gain_db,
+        target_lufs,
+        volume,
+        effective
+    );
    let mut cur = state.current.lock().unwrap();
+    let prev_effective = (cur.base_volume * cur.replay_gain_linear * MASTER_HEADROOM).clamp(0.0, 1.0);
    cur.replay_gain_linear = gain_linear;
    cur.base_volume = volume.clamp(0.0, 1.0);
    if let Some(sink) = &cur.sink {
-        sink.set_volume(effective);
+        ramp_sink_volume(Arc::clone(sink), prev_effective, effective);
    }
+    let _ = app.emit(
+        "audio:normalization-state",
+        NormalizationStatePayload {
+            engine: normalization_engine_name(norm_mode).to_string(),
+            current_gain_db,
+            target_lufs,
+        },
+    );
 }

 /// Proxy: fetches https://autoeq.app/entries via Rust to bypass WebView CORS restrictions.
@@ -3636,6 +4190,16 @@ pub async fn audio_preload(
        response.bytes().await.map_err(|e| e.to_string())?.into()
    };
    let _ = duration_hint; // kept in API for compatibility
+    if let Some(track_id) = playback_identity(&url) {
+        if let Err(e) = crate::analysis_cache::seed_from_bytes(&app, &track_id, &data) {
+            crate::app_eprintln!("[analysis] preload seed failed for {}: {}", track_id, e);
+        } else {
+            let _ = app.emit(
+                "analysis:waveform-updated",
+                WaveformUpdatedPayload { track_id, is_partial: false },
+            );
+        }
+    }
    let url_for_emit = url.clone();
    *state.preloaded.lock().unwrap() = Some(PreloadedTrack { url, data });
    let _ = app.emit("audio:preload-ready", url_for_emit);
@@ -3780,6 +4344,8 @@ pub async fn audio_play_radio(
        cur.fadeout_samples   = Some(fadeout_samples);
    }

+    *state.current_playback_url.lock().unwrap() = Some(url.clone());
+
    state.current_sample_rate.store(sample_rate, Ordering::Relaxed);
    state.current_channels.store(channels as u32, Ordering::Relaxed);

@@ -3798,6 +4364,7 @@ pub async fn audio_play_radio(
        state.current_sample_rate.clone(),
        state.current_channels.clone(),
        state.gapless_switch_at.clone(),
+        state.current_playback_url.clone(),
    );

    Ok(())
@@ -3980,6 +4547,36 @@ pub fn audio_set_gapless(enabled: bool, state: State<'_, AudioEngine>) {
    state.gapless_enabled.store(enabled, Ordering::Relaxed);
 }

+#[tauri::command]
+pub fn audio_set_normalization(engine: String, target_lufs: f32, app: AppHandle, state: State<'_, AudioEngine>) {
+    let mode = match engine.as_str() {
+        "replaygain" => 1,
+        "loudness" => 2,
+        _ => 0,
+    };
+    state.normalization_engine.store(mode, Ordering::Relaxed);
+    let target = target_lufs.clamp(-30.0, -8.0);
+    state
+        .normalization_target_lufs
+        .store(target.to_bits(), Ordering::Relaxed);
+    crate::app_deprintln!(
+        "[normalization] audio_set_normalization requested_engine={} resolved_engine={} target_lufs={:.2}",
+        engine,
+        normalization_engine_name(mode),
+        target
+    );
+    let _ = app.emit(
+        "audio:normalization-state",
+        NormalizationStatePayload {
+            engine: normalization_engine_name(mode).to_string(),
+            // At mode-switch time the effective track gain may not be recalculated yet.
+            // Emit `None` and let audio_play/audio_update_replay_gain publish actual value.
+            current_gain_db: None,
+            target_lufs: target,
+        },
+    );
+}
+
 // ─── Device-change watcher ────────────────────────────────────────────────────
 //
 // Polls every 3 s for two conditions:
@@ -2,6 +2,7 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

 mod audio;
+mod analysis_cache;
 pub mod cli;
 mod discord;
 pub(crate) mod logging;
@@ -59,6 +60,12 @@ fn sync_cancel_flags() -> &'static Mutex<HashMap<String, Arc<AtomicBool>>> {
    FLAGS.get_or_init(|| Mutex::new(HashMap::new()))
 }

+/// Tracks analysis backfill jobs already running per track_id.
+fn analysis_backfill_inflight() -> &'static Mutex<std::collections::HashSet<String>> {
+    static SET: OnceLock<Mutex<std::collections::HashSet<String>>> = OnceLock::new();
+    SET.get_or_init(|| Mutex::new(std::collections::HashSet::new()))
+}
+
 /// Holds the live system-tray icon handle.  `None` means the tray is currently hidden/removed.
 /// Dropping the inner `TrayIcon` fully removes it from the OS notification area on all platforms.
 type TrayState = Mutex<Option<TrayIcon>>;
@@ -67,6 +74,34 @@ type TrayState = Mutex<Option<TrayIcon>>;
 /// `None` if souvlaki failed to initialize (e.g. no D-Bus session on Linux).
 type MprisControls = Mutex<Option<souvlaki::MediaControls>>;

+#[derive(serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct WaveformCachePayload {
+    bins: Vec<u8>,
+    bin_count: i64,
+    is_partial: bool,
+    known_until_sec: f64,
+    duration_sec: f64,
+    updated_at: i64,
+}
+
+#[derive(Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct WaveformUpdatedPayload {
+    track_id: String,
+    is_partial: bool,
+}
+
+#[derive(serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct LoudnessCachePayload {
+    integrated_lufs: f64,
+    true_peak: f64,
+    recommended_gain_db: f64,
+    target_lufs: f64,
+    updated_at: i64,
+}
+
 #[tauri::command]
 fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
@@ -1131,6 +1166,126 @@ fn check_dir_accessible(path: String) -> bool {
    std::path::Path::new(&path).is_dir()
 }

+#[tauri::command]
+fn analysis_get_waveform(
+    track_id: String,
+    md5_16kb: String,
+    cache: tauri::State<'_, analysis_cache::AnalysisCache>,
+) -> Result<Option<WaveformCachePayload>, String> {
+    let key = analysis_cache::TrackKey { track_id, md5_16kb };
+    let row = cache.get_waveform(&key)?;
+    Ok(row.map(|v| WaveformCachePayload {
+        bins: v.bins,
+        bin_count: v.bin_count,
+        is_partial: v.is_partial,
+        known_until_sec: v.known_until_sec,
+        duration_sec: v.duration_sec,
+        updated_at: v.updated_at,
+    }))
+}
+
+#[tauri::command]
+fn analysis_get_waveform_for_track(
+    track_id: String,
+    cache: tauri::State<'_, analysis_cache::AnalysisCache>,
+) -> Result<Option<WaveformCachePayload>, String> {
+    let row = cache.get_latest_waveform_for_track(&track_id)?;
+    Ok(row.map(|v| WaveformCachePayload {
+        bins: v.bins,
+        bin_count: v.bin_count,
+        is_partial: v.is_partial,
+        known_until_sec: v.known_until_sec,
+        duration_sec: v.duration_sec,
+        updated_at: v.updated_at,
+    }))
+}
+
+#[tauri::command]
+fn analysis_get_loudness_for_track(
+    track_id: String,
+    target_lufs: Option<f64>,
+    cache: tauri::State<'_, analysis_cache::AnalysisCache>,
+) -> Result<Option<LoudnessCachePayload>, String> {
+    let row = cache.get_latest_loudness_for_track(&track_id)?;
+    Ok(row.map(|v| {
+        let requested_target = target_lufs.unwrap_or(v.target_lufs).clamp(-30.0, -8.0);
+        let recommended_gain_db = analysis_cache::recommended_gain_for_target(
+            v.integrated_lufs,
+            v.true_peak,
+            requested_target,
+        );
+        LoudnessCachePayload {
+        integrated_lufs: v.integrated_lufs,
+        true_peak: v.true_peak,
+        recommended_gain_db,
+        target_lufs: requested_target,
+        updated_at: v.updated_at,
+    }}))
+}
+
+#[tauri::command]
+fn analysis_enqueue_seed_from_url(
+    track_id: String,
+    url: String,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    if track_id.trim().is_empty() || url.trim().is_empty() {
+        return Ok(());
+    }
+    if let Some(cache) = app.try_state::<analysis_cache::AnalysisCache>() {
+        if cache.get_latest_loudness_for_track(&track_id)?.is_some() {
+            crate::app_deprintln!(
+                "[analysis] backfill skip (already cached): {}",
+                track_id
+            );
+            return Ok(());
+        }
+    }
+    {
+        let mut inflight = analysis_backfill_inflight()
+            .lock()
+            .map_err(|_| "analysis backfill lock poisoned".to_string())?;
+        if inflight.contains(&track_id) {
+            return Ok(());
+        }
+        inflight.insert(track_id.clone());
+    }
+    let app_clone = app.clone();
+    tauri::async_runtime::spawn(async move {
+        crate::app_deprintln!("[analysis] backfill queued: {}", track_id);
+        let result = async {
+            let client = reqwest::Client::builder()
+                .user_agent(subsonic_wire_user_agent())
+                .timeout(std::time::Duration::from_secs(120))
+                .build()
+                .map_err(|e| e.to_string())?;
+            let response = client.get(&url).send().await.map_err(|e| e.to_string())?;
+            if !response.status().is_success() {
+                return Err(format!("HTTP {}", response.status().as_u16()));
+            }
+            let bytes = response.bytes().await.map_err(|e| e.to_string())?;
+            if bytes.is_empty() {
+                return Err("empty response".to_string());
+            }
+            let has_loudness = enqueue_analysis_seed(&app_clone, &track_id, &bytes)?;
+            Ok::<bool, String>(has_loudness)
+        }
+        .await;
+        match result {
+            Ok(has_loudness) => crate::app_deprintln!(
+                "[analysis] backfill ready: {} (has_loudness={})",
+                track_id,
+                has_loudness
+            ),
+            Err(e) => crate::app_eprintln!("[analysis] backfill failed for {}: {}", track_id, e),
+        }
+        if let Ok(mut inflight) = analysis_backfill_inflight().lock() {
+            inflight.remove(&track_id);
+        }
+    });
+    Ok(())
+}
+
 // ─── Offline Track Cache ──────────────────────────────────────────────────────

 /// Streams an HTTP response body directly to `dest_path` in small chunks.
@@ -1151,6 +1306,47 @@ async fn stream_to_file(response: reqwest::Response, dest_path: &std::path::Path
    Ok(())
 }

+fn enqueue_analysis_seed(app: &tauri::AppHandle, track_id: &str, bytes: &[u8]) -> Result<bool, String> {
+    analysis_cache::seed_from_bytes(app, track_id, bytes)
+        .map_err(|e| {
+            crate::app_eprintln!("[analysis] failed to seed {}: {}", track_id, e);
+            e
+        })?;
+    let _ = app.emit(
+        "analysis:waveform-updated",
+        WaveformUpdatedPayload {
+            track_id: track_id.to_string(),
+            is_partial: false,
+        },
+    );
+    let has_loudness = app
+        .try_state::<analysis_cache::AnalysisCache>()
+        .and_then(|cache| cache.get_latest_loudness_for_track(track_id).ok().flatten())
+        .is_some();
+    crate::app_deprintln!(
+        "[analysis] seed result track_id={} bytes={} has_loudness={}",
+        track_id,
+        bytes.len(),
+        has_loudness
+    );
+    Ok(has_loudness)
+}
+
+async fn enqueue_analysis_seed_from_file(
+    app: &tauri::AppHandle,
+    track_id: &str,
+    file_path: &std::path::Path,
+) {
+    let bytes = match tokio::fs::read(file_path).await {
+        Ok(v) => v,
+        Err(_) => return,
+    };
+    if bytes.is_empty() {
+        return;
+    }
+    let _ = enqueue_analysis_seed(app, track_id, &bytes);
+}
+
 /// Downloads a single track to the app's offline cache directory.
 /// Returns the absolute file path so TypeScript can store it and later
 /// construct a `psysonic-local://<path>` URL for the audio engine.
@@ -1217,6 +1413,8 @@ async fn download_track_offline(
        .await
        .map_err(|e| e.to_string())?;

+    enqueue_analysis_seed_from_file(&app, &track_id, &file_path).await;
+
    Ok(path_str)
 }

@@ -1765,6 +1963,8 @@ async fn download_track_hot_cache(
        .await
        .map_err(|e| e.to_string())?;

+    enqueue_analysis_seed_from_file(&app, &track_id, &file_path).await;
+
    let size = tokio::fs::metadata(&file_path)
        .await
        .map(|m| m.len())
@@ -1818,6 +2018,8 @@ async fn promote_stream_cache_to_hot_cache(
        .await
        .map_err(|e| e.to_string())?;

+    let _ = enqueue_analysis_seed(&app, &track_id, &bytes);
+
    let size = tokio::fs::metadata(&file_path)
        .await
        .map(|m| m.len())
@@ -3582,6 +3784,13 @@ pub fn run() {
        }))

        .setup(|app| {
+            // ── Analysis cache (SQLite) ───────────────────────────────────
+            {
+                let cache = analysis_cache::AnalysisCache::init(&app.handle())
+                    .map_err(|e| format!("analysis cache init failed: {e}"))?;
+                app.manage(cache);
+            }
+
            // ── Custom title bar on Linux ─────────────────────────────────
            // Remove OS window decorations on all Linux so the React TitleBar
            // can take over.  The frontend checks is_tiling_wm() to decide
@@ -3820,6 +4029,7 @@ pub fn run() {
            audio::audio_play_radio,
            audio::audio_set_crossfade,
            audio::audio_set_gapless,
+            audio::audio_set_normalization,
            audio::audio_list_devices,
            audio::audio_canonicalize_selected_device,
            audio::audio_default_output_device_name,
@@ -3850,6 +4060,10 @@ pub fn run() {
            fetch_json_url,
            fetch_icy_metadata,
            resolve_stream_url,
+            analysis_get_waveform,
+            analysis_get_waveform_for_track,
+            analysis_get_loudness_for_track,
+            analysis_enqueue_seed_from_url,
            download_track_offline,
            delete_offline_track,
            get_offline_cache_size,