xil/

sfxgen.rs

//! SFX asset generation and stem placement — the generation half of
//! `sfx_common.py`, plus the backends of `sfx_backends.py`.
//!
//! Two phases, as in Python: every unique effect key gets a shared asset in
//! `SFX/` (copied from its declared source, rendered as silence, or
//! generated by a backend), then each script entry gets a copy of that asset
//! under its sequence-numbered stem name. A manifest in the stems directory
//! records what was placed, with a timestamped snapshot per run.

use std::collections::HashSet;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Duration;

use crate::cmd::py_str;
use anyhow::{anyhow, bail};
use serde_json::{Map, Value};
use unicode_normalization::UnicodeNormalization;
use xil_audio::fx::py_repr;
use xil_audio::segment::Segment;
use xil_core::fsutil::basename;
use xil_core::log;
use xil_core::pyfmt::round_to;
use xil_core::pyjson::{dumps, py_float, Style};
use xil_core::sfxlib::shared_sfx_path;
use xil_core::workspace::workspace_root;

use crate::mix::config::{SfxConfig, SfxEntry};

/// One direction entry matched to an effect (`load_sfx_entries` output).
#[derive(Clone, Debug)]
#[allow(dead_code)] // sfx_type, section and scene mirror the Python dict; the producer reads them.
pub struct PlanEntry {
    pub seq: i64,
    pub text: String,
    pub direction_type: Option<String>,
    pub stem_name: String,
    pub sfx_type: String,
    pub section: Value,
    pub scene: Option<String>,
}

/// `file_nonempty(path)`.
pub fn file_nonempty(path: &Path) -> bool {
    fs::metadata(path).map(|m| m.len() > 0).unwrap_or(false)
}

/// `resolve_source_path(source)`: workspace-relative, NFC/NFD tolerant.
pub fn resolve_source_path(source: &str) -> Option<PathBuf> {
    let mut candidates = vec![source.to_string()];
    for form in [
        source.nfc().collect::<String>(),
        source.nfd().collect::<String>(),
    ] {
        if !candidates.contains(&form) {
            candidates.push(form);
        }
    }
    for c in candidates {
        let p = PathBuf::from(&c);
        let p = if p.is_absolute() {
            p
        } else {
            workspace_root().join(p)
        };
        if let Ok(real) = fs::canonicalize(&p) {
            if real.is_file() {
                return Some(real);
            }
        }
    }
    None
}

/// `load_sfx_entries(script, sfx, max_duration, direction_types, local_only, sfx_dir)`.
pub fn load_sfx_entries(
    script_path: &Path,
    cfg: &SfxConfig,
    max_duration: Option<f64>,
    direction_types: Option<&HashSet<&str>>,
    local_only: bool,
    sfx_dir: &Path,
) -> anyhow::Result<Vec<PlanEntry>> {
    let script: Value = serde_json::from_str(&fs::read_to_string(script_path)?)?;
    let mut out = Vec::new();
    for e in script["entries"].as_array().into_iter().flatten() {
        let Some(o) = e.as_object() else { continue };
        if o.get("type").and_then(Value::as_str) != Some("direction") {
            continue;
        }
        let dt = o.get("direction_type").and_then(Value::as_str);
        if let Some(types) = direction_types {
            if !dt.is_some_and(|d| types.contains(d)) {
                continue;
            }
        }
        let text = o.get("text").and_then(Value::as_str).unwrap_or("");
        let Some(effect) = cfg.effects.get(text) else {
            continue;
        };
        if effect.duration_seconds == 0.0 {
            continue;
        }
        if max_duration.is_some_and(|m| effect.duration_seconds > m) {
            continue;
        }
        if local_only
            && effect.type_ == "sfx"
            && effect.source.is_none()
            && !file_nonempty(&shared_sfx_path(sfx_dir, text, "elevenlabs"))
        {
            log::debug(&format!(
                "--local-only: skipping {} (not in SFX/)",
                py_repr(text)
            ));
            continue;
        }
        let seq = o.get("seq").and_then(Value::as_i64).unwrap_or(0);
        let section = o.get("section").cloned().unwrap_or(Value::Null);
        let scene = o
            .get("scene")
            .and_then(Value::as_str)
            .filter(|s| !s.is_empty())
            .map(str::to_string);
        let stem_name = if seq < 0 {
            format!("n{:03}_{}_sfx", seq.abs(), py_str(&section))
        } else {
            let mut s = format!("{seq:03}_{}", py_str(&section));
            if let Some(sc) = &scene {
                s.push('-');
                s.push_str(sc);
            }
            s.push_str("_sfx");
            s
        };
        out.push(PlanEntry {
            seq,
            text: text.to_string(),
            direction_type: dt.map(str::to_string),
            stem_name,
            sfx_type: effect.type_.clone(),
            section,
            scene: o.get("scene").and_then(Value::as_str).map(str::to_string),
        });
    }
    Ok(out)
}

// ── Backends ────────────────────────────────────────────────────────────────

/// `SfxBackend`: `generate_to(out_path, prompt, duration, influence)` + `close()`.
pub trait SfxBackend {
    fn name(&self) -> &'static str;
    /// `asset_comment`, when the backend attaches a provenance note.
    fn asset_comment(&self) -> Option<&'static str> {
        None
    }
    fn generate_to(
        &mut self,
        out_path: &Path,
        prompt: Option<&str>,
        duration_seconds: f64,
        prompt_influence: f64,
    ) -> anyhow::Result<()>;
    fn close(&mut self) -> anyhow::Result<()> {
        Ok(())
    }
}

/// Retry 429 / 5xx / transport failures five times, waiting 10 s, 20 s, …
pub fn with_api_retries<T>(
    mut call: impl FnMut() -> Result<T, xil_api::ApiError>,
) -> anyhow::Result<T> {
    let (max_retries, delay) = (5u64, 10u64);
    for attempt in 1..=max_retries {
        match call() {
            Ok(v) => return Ok(v),
            Err(err) => {
                let status = err.status();
                let rate = status == Some(429);
                let server = status.is_some_and(|s| s >= 500);
                let network = status.is_none();
                if (rate || server || network) && attempt < max_retries {
                    let wait = delay * attempt;
                    let reason = if rate {
                        "429 rate limited".to_string()
                    } else if server {
                        format!("{} server error", status.unwrap_or(0))
                    } else {
                        "network error (TransportError)".to_string()
                    };
                    log::warning(&format!(
                        "[{reason}] — retrying in {wait}s (attempt {attempt}/{max_retries})"
                    ));
                    std::thread::sleep(Duration::from_secs(wait));
                } else {
                    return Err(anyhow!("elevenlabs.core.api_error.ApiError: {err}"));
                }
            }
        }
    }
    unreachable!("the last attempt returns")
}

/// Write `bytes` through a `.tmp` sibling and an atomic rename.
fn write_atomic(out_path: &Path, bytes: &[u8]) -> anyhow::Result<()> {
    let dir = out_path
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or(Path::new("."));
    let tmp = tempfile::Builder::new()
        .prefix("tmp")
        .rand_bytes(8)
        .suffix(".tmp")
        .tempfile_in(dir)?;
    fs::write(tmp.path(), bytes)?;
    tmp.persist(out_path).map_err(|e| anyhow!(e.error))?;
    Ok(())
}

pub struct ElevenLabsBackend {
    pub client: xil_api::elevenlabs::Client,
}

impl SfxBackend for ElevenLabsBackend {
    fn name(&self) -> &'static str {
        "elevenlabs"
    }

    fn generate_to(
        &mut self,
        out_path: &Path,
        prompt: Option<&str>,
        duration_seconds: f64,
        prompt_influence: f64,
    ) -> anyhow::Result<()> {
        let prompt_s = prompt.map(py_repr).unwrap_or_else(|| "None".into());
        log::info(&format!(
            "   [api] text-to-sound-effects → {prompt_s} ({duration_seconds:.1}s)"
        ));
        let text = prompt.unwrap_or("");
        let bytes = with_api_retries(|| {
            self.client
                .sound_generation(text, Some(duration_seconds), Some(prompt_influence))
        })?;
        write_atomic(out_path, &bytes)?;
        log::info(&format!("   [api] saved {}", basename(out_path)));
        Ok(())
    }
}

/// MMAudio via `mmaudio_worker.py` (CC BY-NC 4.0 weights).
pub struct MMAudioBackend {
    python: String,
    script: PathBuf,
    device: String,
    guidance: f64,
    steps: i64,
    negative_prompt: String,
    seed: Option<i64>,
    native_duration: f64,
    worker: Option<xil_workers::Worker>,
}

pub const MMAUDIO_COMMENT: &str =
    "Generated by MMAudio (hkchengrex/MMAudio). Model weights are CC BY-NC 4.0 — NON-COMMERCIAL USE ONLY.";

const MMAUDIO_LICENCE_ERROR: &str = "MMAudio weights are CC BY-NC 4.0 (non-commercial only). Pass --mmaudio-accept-noncommercial to acknowledge that generated audio must not be used in a monetised production.";

pub struct MMAudioOptions<'a> {
    pub python: Option<&'a str>,
    pub cfg: f64,
    pub steps: i64,
    pub negative_prompt: &'a str,
    pub seed: Option<i64>,
    pub duration: f64,
    pub accept_noncommercial: bool,
}

/// `make_sfx_backend(name, ...)`. `Ok(None)` means the caller should exit
/// with status 1 (the error is already logged, as `sys.exit(1)` does).
pub fn make_sfx_backend(
    name: &str,
    client: xil_api::elevenlabs::Client,
    mm: &MMAudioOptions,
) -> anyhow::Result<Option<Box<dyn SfxBackend>>> {
    match name {
        "elevenlabs" => Ok(Some(Box::new(ElevenLabsBackend { client }))),
        "mmaudio" => {
            if !mm.accept_noncommercial {
                bail!("ValueError: {MMAUDIO_LICENCE_ERROR}");
            }
            let package_dir = crate::workers::python_package_dir();
            let Some(python) = xil_core::workspace::resolve_venv_python(
                "venv-mmaudio",
                mm.python,
                package_dir.as_deref(),
            ) else {
                log::error(
                    "Cannot find the venv-mmaudio Python. Pass --mmaudio-python PATH, set XIL_CODEROOT to the directory containing venv-mmaudio/, or build it with: xil setup mmaudio",
                );
                return Ok(None);
            };
            let script = package_dir
                .map(|d| xil_workers::worker_script(&d, "mmaudio_worker.py"))
                .ok_or_else(|| {
                    anyhow!("cannot locate the xil_pipeline package that ships mmaudio_worker.py")
                })?;
            log::warning(
                "MMAudio weights are CC BY-NC 4.0 — NON-COMMERCIAL USE ONLY. Generated assets are tagged .mmaudio and carry the notice in ID3.",
            );
            Ok(Some(Box::new(MMAudioBackend {
                python,
                script,
                device: "cuda".into(),
                guidance: mm.cfg,
                steps: mm.steps,
                negative_prompt: mm.negative_prompt.to_string(),
                seed: mm.seed,
                native_duration: mm.duration,
                worker: None,
            })))
        }
        other => bail!("ValueError: Unknown sfx backend: {}", py_repr(other)),
    }
}

impl MMAudioBackend {
    fn start(&mut self) -> anyhow::Result<()> {
        log::info(&format!(
            "Starting MMAudio worker ({}, {})…",
            self.python, self.device
        ));
        let mut w = xil_workers::Worker::spawn(
            Path::new(&self.python),
            &self.script,
            std::slice::from_ref(&self.device),
        )?;
        let ready = w.wait_ready(|line| log::debug(&format!("MMAudio worker startup: {line}")))?;
        let Some(msg) = ready else {
            bail!(
                "RuntimeError: MMAudio worker exited before sending ready signal. Check that venv-mmaudio is set up (git clone hkchengrex/MMAudio, then pip install -e .) and the weights have downloaded."
            );
        };
        let sr = msg.get("sr").and_then(Value::as_i64).unwrap_or(16000);
        let device = msg
            .get("device")
            .map(py_str)
            .unwrap_or_else(|| self.device.clone());
        log::info(&format!(
            "MMAudio worker ready (sample_rate={sr}, device={device})"
        ));
        self.worker = Some(w);
        Ok(())
    }

    fn generate(
        &mut self,
        prompt: Option<&str>,
        out_path: &Path,
        duration: f64,
    ) -> anyhow::Result<()> {
        if self.worker.is_none() {
            self.start()?;
        }
        let mut req = Map::new();
        req.insert(
            "prompt".into(),
            prompt.map(Value::from).unwrap_or(Value::Null),
        );
        req.insert(
            "out_path".into(),
            out_path.to_string_lossy().into_owned().into(),
        );
        req.insert("duration_seconds".into(), py_float(duration));
        req.insert("guidance_scale".into(), py_float(self.guidance));
        req.insert("num_inference_steps".into(), self.steps.into());
        req.insert(
            "negative_prompt".into(),
            self.negative_prompt.clone().into(),
        );
        req.insert(
            "seed".into(),
            self.seed.map(Value::from).unwrap_or(Value::Null),
        );
        let w = self.worker.as_mut().expect("started");
        w.send(&Value::Object(req))?;
        let raw = w.read_line()?;
        if raw.is_empty() {
            bail!("RuntimeError: MMAudio worker closed pipe unexpectedly.");
        }
        let resp: Value = serde_json::from_str(&raw)?;
        if let Some(err) = resp.get("error") {
            bail!("RuntimeError: MMAudio: {}", py_str(err));
        }
        Ok(())
    }
}

/// `_trim_audio_file(path, seconds)`.
fn trim_audio_file(path: &Path, seconds: f64) -> anyhow::Result<()> {
    let clip = Segment::from_file(path)?;
    let target_ms = (seconds * 1000.0) as i64;
    if clip.len_ms() <= target_ms {
        return Ok(());
    }
    let dir = path
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or(Path::new("."));
    let tmp = tempfile::Builder::new()
        .prefix("tmp")
        .rand_bytes(8)
        .suffix(".mp3")
        .tempfile_in(dir)?
        .into_temp_path();
    clip.slice(None, Some(target_ms as f64))
        .export_ffmpeg(&tmp, "mp3", &[])?;
    fs::rename(&tmp, path)?;
    let _ = tmp.keep();
    Ok(())
}

impl SfxBackend for MMAudioBackend {
    fn name(&self) -> &'static str {
        "mmaudio"
    }

    fn asset_comment(&self) -> Option<&'static str> {
        Some(MMAUDIO_COMMENT)
    }

    fn generate_to(
        &mut self,
        out_path: &Path,
        prompt: Option<&str>,
        duration_seconds: f64,
        _influence: f64,
    ) -> anyhow::Result<()> {
        let target = duration_seconds.max(0.0);
        let gen = self.native_duration.max(target);
        let prompt_s = prompt.map(py_repr).unwrap_or_else(|| "None".into());
        let shown = if target != 0.0 { target } else { gen };
        log::info(&format!(
            "   [mmaudio] {prompt_s} — generating {gen:.1}s (native), trimming to {shown:.1}s"
        ));
        self.generate(prompt, out_path, gen)?;
        if target != 0.0 && target < gen {
            trim_audio_file(out_path, target)?;
        }
        Ok(())
    }

    fn close(&mut self) -> anyhow::Result<()> {
        if let Some(w) = self.worker.take() {
            let _ = w.close();
        }
        Ok(())
    }
}

// ── Shared assets and stems ─────────────────────────────────────────────────

/// `shutil.copy2`: contents, permission bits and timestamps.
pub fn copy2(src: &Path, dst: &Path) -> std::io::Result<()> {
    fs::copy(src, dst)?;
    let meta = fs::metadata(src)?;
    let atime = filetime::FileTime::from_last_access_time(&meta);
    let mtime = filetime::FileTime::from_last_modification_time(&meta);
    filetime::set_file_times(dst, atime, mtime)
}

fn default_influence(cfg: &SfxConfig, effect: &SfxEntry) -> f64 {
    effect.prompt_influence.unwrap_or_else(|| {
        cfg.defaults
            .get("prompt_influence")
            .and_then(|v| crate::mix::config::Num::from_value(v).map(|n| n.f()))
            .unwrap_or(0.3)
    })
}

/// `AudioSegment.silent(duration).export(path, format="mp3")`.
fn export_silence(path: &Path, duration_seconds: f64) -> anyhow::Result<()> {
    let ms = (duration_seconds * 1000.0) as i64;
    fs::File::create(path)?;
    Segment::silent(ms as f64).export_ffmpeg(path, "mp3", &[])?;
    Ok(())
}

/// `ensure_shared_sfx(key, effect, sfx_dir, defaults, show=, backend=)`.
pub fn ensure_shared_sfx(
    key: &str,
    effect: &SfxEntry,
    sfx_dir: &Path,
    cfg: &SfxConfig,
    backend: &mut dyn SfxBackend,
) -> anyhow::Result<PathBuf> {
    let is_model = effect.type_ == "sfx" && effect.source.is_none();
    let path = shared_sfx_path(
        sfx_dir,
        key,
        if is_model {
            backend.name()
        } else {
            "elevenlabs"
        },
    );
    if effect.source.is_none() && file_nonempty(&path) {
        return Ok(path);
    }
    fs::create_dir_all(sfx_dir)?;
    if let Some(source) = &effect.source {
        match resolve_source_path(source) {
            Some(real) => {
                let same = path.exists()
                    && fs::canonicalize(&path).ok().as_deref() == Some(real.as_path());
                if !same {
                    copy2(&real, &path)?;
                }
            }
            None => {
                let Some(prompt) = &effect.prompt else {
                    bail!(
                        "FileNotFoundError: Source file not found: '{source}' (key: '{key}'). Add the file or add a 'prompt' field to generate it."
                    );
                };
                println!(
                    "   [warn] source '{source}' not found — generating via {} for '{key}'",
                    backend.name()
                );
                backend.generate_to(
                    &path,
                    Some(prompt),
                    effect.duration_seconds,
                    default_influence(cfg, effect),
                )?;
                xil_audio::tags::tag_mp3_full(
                    &path,
                    &cfg.show,
                    Some(key),
                    None,
                    None,
                    backend.asset_comment(),
                    None,
                )?;
                return Ok(path);
            }
        }
    } else if effect.type_ == "silence" {
        export_silence(&path, effect.duration_seconds)?;
    } else {
        backend.generate_to(
            &path,
            effect.prompt.as_deref(),
            effect.duration_seconds,
            default_influence(cfg, effect),
        )?;
    }
    xil_audio::tags::tag_mp3_full(
        &path,
        &cfg.show,
        Some(key),
        None,
        None,
        backend.asset_comment(),
        None,
    )?;
    Ok(path)
}

/// `place_episode_stem(shared, stem)` → whether it copied.
pub fn place_episode_stem(shared: &Path, stem: &Path) -> anyhow::Result<bool> {
    if file_nonempty(stem) {
        return Ok(false);
    }
    if let Some(parent) = stem.parent().filter(|p| !p.as_os_str().is_empty()) {
        fs::create_dir_all(parent)?;
    }
    copy2(shared, stem)?;
    Ok(true)
}

type ContentKey = (String, String, String, String, Option<u64>);

fn content_key(e: &Map<String, Value>) -> ContentKey {
    let s = |k: &str| match e.get(k) {
        Some(Value::String(v)) => v.clone(),
        Some(Value::Null) | None => String::new(),
        Some(other) => py_str(other),
    };
    let dur = e
        .get("duration_seconds")
        .and_then(Value::as_f64)
        .map(|d| round_to(d, 3).to_bits());
    (
        s("effect_key"),
        s("sfx_type"),
        s("source_path"),
        s("prompt"),
        dur,
    )
}

/// `generate_sfx(entries, config, stems_dir, sfx_dir=, start_from=, backend=)`.
pub fn generate_sfx(
    entries: &[PlanEntry],
    cfg: &SfxConfig,
    stems_dir: &Path,
    sfx_dir: &Path,
    start_from: i64,
    backend: &mut dyn SfxBackend,
) -> anyhow::Result<()> {
    fs::create_dir_all(stems_dir)?;
    let run_started_at = chrono::Local::now().format("%Y-%m-%dT%H-%M-%S").to_string();
    let tag = basename(stems_dir);
    let mf_path = stems_dir.join(format!("{tag}_sfx_manifest.json"));
    let mut manifest: Value = fs::read_to_string(&mf_path)
        .ok()
        .and_then(|t| serde_json::from_str(&t).ok())
        .unwrap_or_else(|| serde_json::json!({"version": 1, "entries": []}));

    let todo: Vec<&PlanEntry> = entries.iter().filter(|e| e.seq >= start_from).collect();
    log::info(&format!("--- SFX: Processing {} entries ---", todo.len()));

    let mut unique: Vec<&str> = Vec::new();
    for e in &todo {
        if !unique.contains(&e.text.as_str()) {
            unique.push(&e.text);
        }
    }
    let mut shared: std::collections::HashMap<&str, PathBuf> = std::collections::HashMap::new();
    for key in &unique {
        let effect = &cfg.effects[*key];
        let path = ensure_shared_sfx(key, effect, sfx_dir, cfg, backend)?;
        log::info(&format!("   Shared: {}", path.display()));
        shared.insert(key, path);
    }

    let (mut copied, mut skipped, mut omitted) = (0, 0, 0);
    for e in &todo {
        let stem = stems_dir.join(format!("{}.mp3", e.stem_name));
        let shared_path = &shared[e.text.as_str()];
        let effect = &cfg.effects[&e.text];
        if xil_audio::tags::read_sfx_grade(shared_path) == xil_audio::tags::SFX_GRADE_REJECTED {
            if stem.exists() {
                fs::remove_file(&stem)?;
            }
            log::info(&format!(
                "   [grade] omitted (rejected): {}",
                basename(shared_path)
            ));
            omitted += 1;
            continue;
        }
        if place_episode_stem(shared_path, &stem)? {
            log::info(&format!("   Placed: {}", stem.display()));
            log::info(&format!(
                "   SHA256: {}",
                crate::cmd::mp3_hash::hash_file(&stem)?
            ));
            copied += 1;
        } else {
            log::info(&format!("   Exists: {} — skipping", stem.display()));
            skipped += 1;
        }
        if let Ok(sha) = crate::cmd::mp3_hash::hash_file(&stem) {
            let mut entry = Map::new();
            entry.insert("effect_key".into(), e.text.clone().into());
            entry.insert("sfx_type".into(), effect.type_.clone().into());
            entry.insert(
                "source_path".into(),
                effect
                    .source
                    .clone()
                    .map(Value::from)
                    .unwrap_or(Value::Null),
            );
            entry.insert(
                "prompt".into(),
                effect
                    .prompt
                    .clone()
                    .map(Value::from)
                    .unwrap_or(Value::Null),
            );
            entry.insert("duration_seconds".into(), py_float(effect.duration_seconds));
            entry.insert("sha256".into(), sha.into());
            entry.insert("seq_at_placement".into(), e.seq.into());
            entry.insert("stem_filename".into(), basename(&stem).into());
            entry.insert(
                "placed_at".into(),
                chrono::Local::now()
                    .format("%Y-%m-%dT%H:%M:%S")
                    .to_string()
                    .into(),
            );
            upsert(&mut manifest, entry);
        }
    }
    log::info(&format!(
        "--- SFX Complete: {} shared assets, {copied} placed, {skipped} skipped, {omitted} omitted (rejected) ---",
        unique.len()
    ));
    let save = |path: &Path| -> std::io::Result<()> {
        let tmp = PathBuf::from(format!("{}.tmp", path.display()));
        fs::write(&tmp, dumps(&manifest, Style::INDENT2))?;
        fs::rename(&tmp, path)
    };
    let n = manifest["entries"].as_array().map_or(0, Vec::len);
    match save(&mf_path) {
        Ok(()) => {
            log::info(&format!(
                "   SFX Manifest: {} ({n} entries)",
                basename(&mf_path)
            ));
            let snap = PathBuf::from(
                mf_path
                    .to_string_lossy()
                    .replace(".json", &format!("_{run_started_at}.json")),
            );
            match save(&snap) {
                Ok(()) => log::info(&format!("   SFX Snapshot: {}", basename(&snap))),
                Err(e) => log::warning(&format!("Could not write SFX manifest: {e}")),
            }
        }
        Err(e) => log::warning(&format!("Could not write SFX manifest: {e}")),
    }
    Ok(())
}

/// `_sfx_manifest_upsert`: update in place when the content key matches.
fn upsert(manifest: &mut Value, entry: Map<String, Value>) {
    let key = content_key(&entry);
    let list = manifest
        .get_mut("entries")
        .and_then(Value::as_array_mut)
        .expect("manifest has entries");
    // The Python index is built by assignment, so a key maps to the *last*
    // matching entry object — search from the end.
    for existing in list.iter_mut().rev() {
        if let Some(o) = existing.as_object_mut() {
            if content_key(o) == key {
                for (k, v) in entry {
                    o.insert(k, v);
                }
                return;
            }
        }
    }
    list.push(Value::Object(entry));
}

/// `dry_run_sfx(entries, config, stems_dir, sfx_dir=, backend_name=)`.
pub fn dry_run_sfx(
    entries: &[PlanEntry],
    cfg: &SfxConfig,
    stems_dir: &Path,
    sfx_dir: &Path,
    backend_name: &str,
) {
    let is_local = backend_name != "elevenlabs";
    let bar = "=".repeat(70);
    log::info(&format!("\n{bar}"));
    log::info(&format!(
        "SFX DRY RUN — {} entries  (backend: {backend_name})",
        entries.len()
    ));
    log::info(&format!("  stems dir: {}", stems_dir.display()));
    log::info(&format!("  shared dir: {}", sfx_dir.display()));
    log::info(&format!("{bar}\n"));

    let cats = ["MUSIC", "AMBIENCE", "SFX", "silence"];
    let mut new_n = [0usize; 4];
    let mut dur = [0f64; 4];
    let (mut new_count, mut cached, mut exists, mut missing) = (0, 0, 0, 0);
    let mut missing_sources: Vec<String> = Vec::new();

    for e in entries {
        let Some(effect) = cfg.effects.get(&e.text) else {
            continue;
        };
        let stem = stems_dir.join(format!("{}.mp3", e.stem_name));
        let is_source = effect.source.is_some();
        let is_model = effect.type_ == "sfx" && !is_source;
        let shared_backend = if is_model { backend_name } else { "elevenlabs" };
        let shared_file: String = match &effect.source {
            Some(src) => src.clone(),
            None => shared_sfx_path(sfx_dir, &e.text, shared_backend)
                .to_string_lossy()
                .into_owned(),
        };
        let resolved: Option<PathBuf> = if is_source {
            resolve_source_path(effect.source.as_deref().unwrap_or(""))
        } else {
            Some(PathBuf::from(&shared_file))
        };
        let status = if stem.exists() {
            exists += 1;
            "EXISTS"
        } else if is_source && resolved.is_none() {
            missing += 1;
            missing_sources.push(format!("  '{}' → {shared_file}", e.text));
            "MISSING"
        } else if resolved.as_ref().is_some_and(|r| r.exists()) {
            cached += 1;
            "CACHED"
        } else {
            new_count += 1;
            "   NEW"
        };
        let seq_label = if e.seq < 0 {
            format!("n{:03}", e.seq.abs())
        } else {
            format!("{:03}", e.seq)
        };
        if effect.type_ == "silence" {
            log::info(&format!(
                " [{status}] {seq_label} | silence | {:5.1}s | {}",
                effect.duration_seconds, e.text
            ));
            if status == "   NEW" {
                new_n[3] += 1;
                dur[3] += effect.duration_seconds;
            }
        } else if is_source {
            log::info(&format!(
                " [{status}] {seq_label} | copy    |         | ~    0 credits | {}",
                e.text
            ));
            log::info(&format!("            source: {shared_file}"));
        } else {
            let credits = (effect.duration_seconds * 40.0) as i64;
            let bucket = match e.direction_type.as_deref().filter(|d| !d.is_empty()) {
                Some("MUSIC") => 0,
                Some("AMBIENCE") => 1,
                _ => 2,
            };
            if status == "   NEW" {
                new_n[bucket] += 1;
                dur[bucket] += effect.duration_seconds;
            }
            if is_local {
                log::info(&format!(
                    " [{status}] {seq_label} | sfx     | {:5.1}s | local (free)  | {}",
                    effect.duration_seconds, e.text
                ));
            } else {
                log::info(&format!(
                    " [{status}] {seq_label} | sfx     | {:5.1}s | ~{credits:5} credits | {}",
                    effect.duration_seconds, e.text
                ));
            }
            log::info(&format!(
                "            prompt: {}",
                effect.prompt.clone().unwrap_or_else(|| "None".into())
            ));
        }
        log::info(&format!("            stem: {}.mp3", e.stem_name));
        if !is_source {
            log::info(&format!(
                "            shared: {}",
                basename(Path::new(&shared_file))
            ));
        }
        log::info("");
    }

    let total_dur: f64 = dur.iter().sum();
    let total_credits = (total_dur * 40.0) as i64;
    log::info(&bar);
    log::info(&format!(
        "SUMMARY: {} total — {new_count} new, {cached} cached, {exists} on disk, {missing} MISSING  (backend: {backend_name})",
        entries.len()
    ));
    for (i, cat) in cats.iter().take(3).enumerate() {
        let present = entries.iter().any(|e| {
            e.direction_type
                .as_deref()
                .filter(|d| !d.is_empty())
                .unwrap_or("SFX")
                == *cat
        });
        if new_n[i] > 0 || present {
            if is_local {
                log::info(&format!(
                    "  {cat:<9}: {:3} new, {:6.1}s  (local, free)",
                    new_n[i], dur[i]
                ));
            } else {
                log::info(&format!(
                    "  {cat:<9}: {:3} new, {:6.1}s, ~{:6} credits",
                    new_n[i],
                    dur[i],
                    (dur[i] * 40.0) as i64
                ));
            }
        }
    }
    if new_n[3] > 0 {
        log::info(&format!("  {:<9}: {:3} new  (free)", "silence", new_n[3]));
    }
    if is_local {
        log::info(&format!(
            "  {:<9}: {new_count:3},  {total_dur:.1}s  (local generation — no API credits)",
            "TOTAL NEW"
        ));
    } else {
        log::info(&format!("  {:<9}: {new_count:3},  {total_dur:.1}s, ~{total_credits} credits  (silence & cached are free)", "TOTAL NEW"));
    }
    if !missing_sources.is_empty() {
        log::error(&format!(
            "{} source file(s) declared but not found:",
            missing_sources.len()
        ));
        for m in &missing_sources {
            log::error(m);
        }
    }
    log::info(&format!("{bar}\n"));
}