GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! Proxies and ingest (Clip ▸ Proxy ▸ Create / Attach / Reconnect Full Resolution, Toggle Proxies,
//! Project Settings ▸ Ingest Settings).
//!
//! - **Create.** A background job transcodes each clip with our own encoders (ProRes 422 Proxy /
//!   LT or H.264 at ¼ or ½ size, audio included) and attaches the results when it finishes
//!   ([`poll`] applies finished jobs; the frontend calls it every frame through
//!   `Session::poll_persistence`).
//! - **Attach.** A proxy must have the original's duration (±1 frame) and frame rate; its frame
//!   size and aspect may differ.
//! - **Toggle.** `media.toggleProxies` flips Preferences ▸ Media ▸ Enable proxies; the media pool
//!   then hands proxies to monitors and playback. Export always uses full resolution.
//! - **Ingest.** With ingest enabled, `file.import` copies (verified by fingerprint), transcodes
//!   and/or creates proxies.

use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};

use filmcraft_export::{ExportSettings, Format, Progress, Report};
use filmcraft_media::{MediaKind, SharedSource};
use filmcraft_project::{IngestAction, ItemId, ItemKind, MediaClip, MediaRef, Project, SequenceSettings, TrackKind};
use filmcraft_time::{Tick, TimeRange};
use serde::Serialize;
use serde_json::{Value, json};

use crate::commands::{CommandSpec, always, bad, bool_p, str_p, u64_p};
use crate::{EngineError, Result, Session};

/// A proxy / transcode preset.
#[derive(Clone, Copy, Debug, Serialize)]
pub struct Preset {
    pub id: &'static str,
    pub label: &'static str,
    #[serde(skip)]
    pub format: Format,
    /// Frame size relative to the original.
    pub scale: f32,
    /// ProRes flavour (`proxy`, `lt`, `hq`) for ProRes presets.
    pub prores: &'static str,
    pub extension: &'static str,
    /// Offered for proxies (else only for transcodes).
    pub proxy: bool,
}

pub const PRESETS: &[Preset] = &[
    Preset {
        id: "prores_proxy_quarter",
        label: "ProRes 422 Proxy, ¼ size",
        format: Format::ProRes,
        scale: 0.25,
        prores: "proxy",
        extension: "mov",
        proxy: true,
    },
    Preset { id: "prores_proxy_half", label: "ProRes 422 Proxy, ½ size", format: Format::ProRes, scale: 0.5, prores: "proxy", extension: "mov", proxy: true },
    Preset { id: "prores_lt_half", label: "ProRes 422 LT, ½ size", format: Format::ProRes, scale: 0.5, prores: "lt", extension: "mov", proxy: true },
    Preset { id: "h264_quarter", label: "H.264, ¼ size", format: Format::H264, scale: 0.25, prores: "", extension: "mp4", proxy: true },
    Preset { id: "h264_half", label: "H.264, ½ size", format: Format::H264, scale: 0.5, prores: "", extension: "mp4", proxy: true },
    Preset { id: "prores_lt", label: "ProRes 422 LT (full size)", format: Format::ProRes, scale: 1.0, prores: "lt", extension: "mov", proxy: false },
    Preset { id: "prores_hq", label: "ProRes 422 HQ (full size)", format: Format::ProRes, scale: 1.0, prores: "hq", extension: "mov", proxy: false },
    Preset { id: "h264", label: "H.264 (full size)", format: Format::H264, scale: 1.0, prores: "", extension: "mp4", proxy: false },
];

pub const DEFAULT_PROXY_PRESET: &str = "prores_proxy_quarter";
pub const DEFAULT_TRANSCODE_PRESET: &str = "prores_lt";

pub fn preset(id: &str) -> Option<&'static Preset> {
    PRESETS.iter().find(|p| p.id == id)
}

/// What to do with a finished job's outputs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OnDone {
    /// Attach outputs as proxies.
    AttachProxies,
    /// Point the clips at the outputs (ingest transcode).
    ReplaceMedia,
    /// Nothing (the job's own result is the product, e.g. Project Manager).
    Nothing,
}

/// A media job whose outputs still have to be applied to the project.
pub struct PendingJob {
    pub job: u64,
    pub on_done: OnDone,
    /// (item, output path) for each finished output.
    pub outputs: Arc<Mutex<Vec<(ItemId, String)>>>,
    /// Length of the source each finished output was transcoded from (the worker's own copy, filled
    /// as it goes): a generated proxy is as long as that source, which a project's stored duration
    /// can overstate.
    pub source_durations: Arc<Mutex<Vec<(ItemId, Tick)>>>,
    /// What each item was when the job started: (item, path, stored duration). An output whose item
    /// has been relinked or refreshed since was made from a different file and is not applied.
    pub started_from: Vec<(ItemId, String, Tick)>,
    /// `Session::document_epoch` when the job started: item ids mean something else in another project.
    pub epoch: u64,
}

/// Transcode `range` (whole media when None) of one media clip to `out` with `preset`, blocking.
/// `progress.total` is the caller's; this adds one per frame to `progress.done`.
pub fn transcode(
    clip: &MediaClip,
    name: &str,
    src: SharedSource,
    range: Option<TimeRange>,
    out: &str,
    preset: &Preset,
    progress: &Progress,
) -> std::result::Result<Report, String> {
    transcode_with_file(clip, name, src, range, Dest { path: out, file: None }, preset, progress)
}

/// Output path, plus the already-open file to write into when the caller holds one.
struct Dest<'a> {
    path: &'a str,
    file: Option<Arc<std::fs::File>>,
}

fn transcode_with_file(
    clip: &MediaClip,
    name: &str,
    src: SharedSource,
    range: Option<TimeRange>,
    dest: Dest<'_>,
    preset: &Preset,
    progress: &Progress,
) -> std::result::Result<Report, String> {
    let Dest { path: out, file: output_file } = dest;
    let info = &clip.info;
    let rate = clip.frame_rate();
    let mut st = SequenceSettings::default();
    if let Some(v) = &info.video {
        st.width = v.width;
        st.height = v.height;
        // pixels in = pixels out: the sequence has the clip's pixel aspect, so nothing is stretched
        st.par = clip.pixel_aspect();
    }
    st.frame_rate = rate;
    st.sample_rate = info.audio().map_or(48_000, |a| a.sample_rate.max(8000));
    let mut p = Project::new("transcode");
    let mut c = clip.clone();
    c.offline = false;
    c.proxy = None;
    let item = p.add_item(name, filmcraft_project::Label::Iris, ItemKind::Media(Box::new(c)), None);
    let has_v = info.video.is_some();
    let has_a = info.has_audio();
    let seq = p.new_sequence("transcode", st, usize::from(has_v), usize::from(has_a), None);
    // the opened source's length, not the project's stored one: a project can claim any duration
    let range = range.unwrap_or(TimeRange { start: Tick::ZERO, duration: src.info().duration });
    let mut placed = Vec::new();
    if has_v && let Some(ti) = p.make_track_item(item, TrackKind::Video, Tick::ZERO, range, rate) {
        placed.push((TrackKind::Video, ti));
    }
    if has_a && let Some(ti) = p.make_track_item(item, TrackKind::Audio, Tick::ZERO, range, rate) {
        placed.push((TrackKind::Audio, ti));
    }
    let q = p.sequence_mut(seq).ok_or("no sequence")?;
    for (k, ti) in placed {
        let t = if k == TrackKind::Video { &mut q.video_tracks[0] } else { &mut q.audio_tracks[0] };
        t.items.push(ti);
    }
    let format = if has_v { preset.format } else { Format::Wav };
    let settings = ExportSettings {
        format,
        path: out.to_string(),
        scale: preset.scale,
        include_audio: has_a,
        quality: 85,
        bitrate_kbps: ((info.video.as_ref().map_or(1920 * 1080, |v| v.width * v.height) as f64 * (preset.scale * preset.scale) as f64) / 200.0).max(800.0)
            as u32,
        part_of_batch: true,
        prores_profile: preset.prores.to_string(),
        output_file,
        ..Default::default()
    };
    let project = Arc::new(p);
    let provider = move |id: ItemId| (id == item).then(|| src.clone());
    filmcraft_export::export(&project, seq, &settings, &provider, progress).map_err(|e| e.to_string())
}

/// An output created exclusively while choosing its name. Unless kept after a successful
/// transcode, dropping it removes only that file (including on a cancelled or rejected job).
struct ReservedOutput {
    path: PathBuf,
    file: Option<Arc<std::fs::File>>,
    keep: bool,
}

impl ReservedOutput {
    fn path(&self) -> &Path {
        &self.path
    }

    fn file(&self) -> Option<Arc<std::fs::File>> {
        self.file.clone()
    }

    fn preserve(&mut self) {
        self.keep = true;
    }
}

impl Drop for ReservedOutput {
    fn drop(&mut self) {
        if !self.keep {
            // Only our own file goes: a replacement someone put at the path is theirs.
            let ours = self.file.as_deref().is_none_or(|f| filmcraft_export::path_is_file(&self.path.to_string_lossy(), f));
            // Release our handle before removal, which is required on Windows.
            self.file.take();
            if ours {
                let _ = std::fs::remove_file(&self.path);
            }
        }
    }
}

/// Reserve a numbered output name without following a later replacement of its pathname.
fn reserve_unique_path(dir: &Path, stem: &str, suffix: &str, ext: &str, taken: &[String]) -> Result<ReservedOutput> {
    std::fs::create_dir_all(dir).map_err(|e| EngineError::Other(format!("{}: {e}", dir.display())))?;
    let mut n = 1;
    loop {
        let name = if n == 1 { format!("{stem}{suffix}.{ext}") } else { format!("{stem}{suffix} {n}.{ext}") };
        let path = dir.join(name);
        if taken.contains(&path.to_string_lossy().into_owned()) {
            n += 1;
            continue;
        }
        match std::fs::OpenOptions::new().read(true).write(true).create_new(true).open(&path) {
            Ok(file) => {
                return Ok(ReservedOutput { path, file: Some(Arc::new(file)), keep: false });
            }
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => n += 1,
            Err(e) => return Err(EngineError::Other(format!("{}: {e}", path.display()))),
        }
    }
}

/// Frames a transcode of `clip` will write (for progress totals).
pub fn frame_count(clip: &MediaClip, range: Option<TimeRange>) -> u64 {
    let rate = clip.frame_rate();
    let d = range.map_or(clip.info.duration, |r| r.duration);
    if clip.info.video.is_none() { 1 } else { rate.frame_at(d).max(1) as u64 }
}

/// `<dir>/<stem><suffix>.<ext>`, numbered when the name is taken.
pub fn unique_path(dir: &Path, stem: &str, suffix: &str, ext: &str, taken: &[String]) -> PathBuf {
    let mut n = 1;
    loop {
        let name = if n == 1 { format!("{stem}{suffix}.{ext}") } else { format!("{stem}{suffix} {n}.{ext}") };
        let p = dir.join(name);
        // a dangling symbolic link is taken too: writing through it would create the file where it points
        if std::fs::symlink_metadata(&p).is_err() && !taken.contains(&p.to_string_lossy().into_owned()) {
            return p;
        }
        n += 1;
    }
}

fn media_path(p: &Project, item: ItemId) -> Option<(MediaClip, String, String)> {
    let it = p.item(item)?;
    let m = it.as_media()?;
    match &m.media {
        MediaRef::File { path } => Some((m.clone(), path.clone(), it.name.clone())),
        MediaRef::Generator(_) => None,
    }
}

fn items_param(s: &Session, p: &Value) -> Vec<ItemId> {
    match p.get("items").and_then(Value::as_array) {
        Some(a) => a.iter().filter_map(Value::as_u64).map(ItemId).collect(),
        None => u64_p(p, "item").map(|i| vec![ItemId(i)]).unwrap_or_else(|| s.state.project_selection.clone()),
    }
}

/// Start a background transcode job over `work` (item, output path, preset). Returns the job id.
fn start_job(s: &mut Session, label: String, work: Vec<(ItemId, ReservedOutput, &'static Preset)>, on_done: OnDone, wait: bool) -> Result<u64> {
    let mut tasks = Vec::new();
    let mut total = 0;
    let mut started_from = Vec::new();
    for (item, output, pr) in work {
        let (clip, path, name) = media_path(&s.project, item).ok_or_else(|| bad("media.createProxies", format!("item {} is not file media", item.0)))?;
        let src = s.media.full_res_source(&s.project, item, &*s.services).ok_or_else(|| EngineError::Other(format!("{name}: no source")))?;
        if s.media.offline_status(item).is_some() {
            return Err(EngineError::Other(format!("{name} is offline; link it first")));
        }
        let source_duration = src.info().duration;
        total += frame_count(&clip, Some(TimeRange { start: Tick::ZERO, duration: source_duration }));
        started_from.push((item, path, clip.info.duration));
        tasks.push((item, clip, name, src, output, pr));
    }
    let id = s.jobs.iter().map(|j| j.id).max().unwrap_or(0) + 1;
    let job = crate::Job { id, label, progress: Default::default(), result: Default::default() };
    job.progress.total.store(total, std::sync::atomic::Ordering::Relaxed);
    let outputs: Arc<Mutex<Vec<(ItemId, String)>>> = Arc::default();
    let source_durations: Arc<Mutex<Vec<(ItemId, Tick)>>> = Arc::default();
    let (prog, res, outs, durs) = (job.progress.clone(), job.result.clone(), outputs.clone(), source_durations.clone());
    // Media jobs run one after another, in the order they were started (#1831); the browser has no
    // threads to wait on, and runs each job where it is started.
    #[cfg(not(target_arch = "wasm32"))]
    let ticket = {
        let ahead = crate::media_queue::MEDIA_JOBS.ahead();
        if ahead > 0 {
            *job.progress.status.lock().unwrap_or_else(|e| e.into_inner()) = format!("Waiting for {ahead} earlier job{}", if ahead == 1 { "" } else { "s" });
        }
        crate::media_queue::MEDIA_JOBS.ticket()
    };
    let (pool, project, services) = (s.media.clone(), s.project.clone(), s.services.clone());
    let run = move || {
        // a job cancelled while it waits raises the same flag the loop below checks
        #[cfg(not(target_arch = "wasm32"))]
        ticket.wait(&prog.cancel);
        let t0 = web_time::Instant::now();
        let mut bytes = 0;
        let mut err = None;
        let n = tasks.len();
        for (k, (item, clip, name, src, mut output, pr)) in tasks.into_iter().enumerate() {
            if prog.cancel.load(std::sync::atomic::Ordering::Relaxed) {
                err = Some("cancelled".to_string());
                break;
            }
            *prog.status.lock().unwrap_or_else(|e| e.into_inner()) = format!("{name} ({} of {n})", k + 1);
            let out = output.path().to_string_lossy().into_owned();
            // its own copy of the file, opened here rather than on the main thread, so the
            // monitors keep their decoder
            let src = pool.own_source(&project, item, &*services).unwrap_or(src);
            // the length of the file actually transcoded: the cached source may be an older read of it
            let source_duration = src.info().duration;
            match transcode_with_file(&clip, &name, src, None, Dest { path: &out, file: output.file() }, pr, &prog) {
                Ok(r) => {
                    bytes += r.bytes;
                    output.preserve();
                    durs.lock().unwrap_or_else(|e| e.into_inner()).push((item, source_duration));
                    outs.lock().unwrap_or_else(|e| e.into_inner()).push((item, out));
                }
                Err(e) => {
                    err = Some(format!("{name}: {e}"));
                    break;
                }
            }
        }
        let secs = t0.elapsed().as_secs_f64();
        let frames = prog.done.load(std::sync::atomic::Ordering::Relaxed);
        let r = match err {
            Some(e) => {
                *prog.error.lock().unwrap_or_else(|x| x.into_inner()) = Some(e.clone());
                Err(e)
            }
            None => Ok(Report { path: String::new(), frames, seconds: secs, bytes, render_fps: frames as f64 / secs.max(1e-6), ..Default::default() }),
        };
        *prog.status.lock().unwrap_or_else(|e| e.into_inner()) = match &r {
            Ok(_) => format!("Done in {secs:.1}s"),
            Err(e) => e.clone(),
        };
        prog.finished.store(true, std::sync::atomic::Ordering::Relaxed);
        *res.lock().unwrap_or_else(|x| x.into_inner()) = Some(r);
    };
    let run = crate::export_tools::guard_job(job.progress.clone(), job.result.clone(), run);
    s.jobs.push(job);
    s.media_jobs.push(PendingJob { job: id, on_done, outputs, source_durations, started_from, epoch: s.document_epoch });
    if wait || cfg!(target_arch = "wasm32") {
        run();
        poll(s);
    } else {
        std::thread::Builder::new().name("filmcraft-proxies".into()).spawn(run).map_err(|e| EngineError::Other(e.to_string()))?;
    }
    Ok(id)
}

/// Apply the outputs of finished media jobs (attach proxies, switch to transcodes).
pub fn poll(s: &mut Session) {
    use std::sync::atomic::Ordering;
    let finished: Vec<usize> = s
        .media_jobs
        .iter()
        .enumerate()
        .filter(|(_, pj)| s.jobs.iter().find(|j| j.id == pj.job).is_none_or(|j| j.progress.finished.load(Ordering::Relaxed)))
        .map(|(i, _)| i)
        .collect();
    for i in finished.into_iter().rev() {
        let pj = s.media_jobs.remove(i);
        let outs = std::mem::take(&mut *pj.outputs.lock().unwrap_or_else(|e| e.into_inner()));
        let source_durations = std::mem::take(&mut *pj.source_durations.lock().unwrap_or_else(|e| e.into_inner()));
        if pj.epoch != s.document_epoch {
            // the project was replaced under the job: its ids may now name unrelated items
            if !outs.is_empty() {
                s.error_toast("job", "the project was replaced; the media copies were not applied");
            }
            continue;
        }
        let (outs, changed): (Vec<_>, Vec<_>) = outs.into_iter().partition(|(item, _)| unchanged_since_start(&s.project, *item, &pj.started_from));
        for (item, _) in &changed {
            let name = s.project.item(*item).map_or_else(|| format!("item {}", item.0), |i| i.name.clone());
            s.error_toast("job", format!("{name} changed while its copy was made; the copy was not applied"));
        }
        if outs.is_empty() {
            continue;
        }
        let r = match pj.on_done {
            OnDone::AttachProxies => attach_checked(s, &outs, false, &source_durations).map(|_| ()),
            OnDone::ReplaceMedia => replace_media(s, &outs),
            OnDone::Nothing => Ok(()),
        };
        if let Err(e) = r {
            s.error_toast("job", e.to_string());
        }
    }
}

/// Whether `item` is still the file (path and stored length) it was when the job started.
pub(crate) fn unchanged_since_start(p: &Project, item: ItemId, started: &[(ItemId, String, Tick)]) -> bool {
    let Some((_, path, dur)) = started.iter().find(|(i, ..)| *i == item) else { return true };
    media_path(p, item).is_some_and(|(clip, now, _)| now == *path && clip.info.duration == *dur)
}

/// Check a proxy file against its clip: duration within one frame, same frame rate.
/// `source_duration`: the length a generated proxy has (the opened source's), when known; otherwise the clip's stored duration.
fn check_proxy(s: &Session, item: ItemId, path: &str, source_duration: Option<Tick>) -> Result<()> {
    let (clip, _, name) = media_path(&s.project, item).ok_or_else(|| bad("media.attachProxies", format!("item {} is not file media", item.0)))?;
    let src = s.media.open_file(path, &*s.services).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
    let pi = src.info();
    let fd = clip.info.frame_rate().frame_duration();
    let expected = source_duration.unwrap_or(clip.info.duration);
    if (pi.duration - expected).0.abs() > fd.0 {
        return Err(EngineError::Other(format!(
            "{}: the proxy is {:.3}s long but {name} is {:.3}s",
            Path::new(path).file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(),
            pi.duration.seconds(),
            expected.seconds()
        )));
    }
    if let (Some(a), Some(b)) = (&pi.video, &clip.info.video)
        && a.frame_rate != b.frame_rate
    {
        return Err(EngineError::Other(format!("the proxy runs at {} fps but {name} at {} fps", a.frame_rate.label(), b.frame_rate.label())));
    }
    if pi.video.is_none() && clip.info.video.is_some() {
        return Err(EngineError::Other("the proxy has no video".into()));
    }
    Ok(())
}

/// Attach proxies (checked unless `force`). One undo step.
pub fn attach(s: &mut Session, pairs: &[(ItemId, String)], force: bool) -> Result<Value> {
    attach_checked(s, pairs, force, &[])
}

/// [`attach`] with the source lengths of generated proxies, which the check uses in place of the stored duration.
fn attach_checked(s: &mut Session, pairs: &[(ItemId, String)], force: bool, source_durations: &[(ItemId, Tick)]) -> Result<Value> {
    if !force {
        for (i, p) in pairs {
            check_proxy(s, *i, p, source_durations.iter().find(|(d, _)| d == i).map(|&(_, t)| t))?;
        }
    }
    let pairs = pairs.to_vec();
    s.edit("Attach Proxies", |proj, _| {
        for (i, p) in &pairs {
            if let Some(m) = proj.item_mut(*i).and_then(|it| it.as_media_mut()) {
                m.proxy = Some(MediaRef::File { path: p.clone() });
            }
        }
        Ok(())
    })?;
    Ok(json!({"attached": pairs.iter().map(|(i, p)| json!({"item": i.0, "path": p})).collect::<Vec<_>>()}))
}

fn replace_media(s: &mut Session, outs: &[(ItemId, String)]) -> Result<()> {
    for (i, p) in outs {
        let q = json!({"item": i.0, "path": p, "force": true, "relinkOthers": false});
        crate::relink::relink(s, &q)?;
    }
    Ok(())
}

/// Where proxies of `media` go: the chosen folder, else `<media dir>/Proxies`.
pub fn proxy_dir(media: &str, dest: Option<&str>) -> PathBuf {
    match dest {
        Some(d) if !d.is_empty() => PathBuf::from(d),
        _ => Path::new(media).parent().unwrap_or(Path::new(".")).join("Proxies"),
    }
}

/// `media.createProxies {items?, preset?, destination?, wait?}`.
pub fn create(s: &mut Session, p: &Value) -> Result<Value> {
    let pr = preset(str_p(p, "preset").unwrap_or(DEFAULT_PROXY_PRESET)).ok_or_else(|| bad("media.createProxies", "unknown preset (see media.proxyPresets)"))?;
    let items = items_param(s, p);
    // default: Project Settings ▸ Scratch Disks ▸ Captured and Generated, else next to the media
    let dest = str_p(p, "destination").map(str::to_string).or_else(|| {
        crate::project_tools::trusted_scratch(s.project.settings.scratch.captured.as_deref(), s.path.as_deref(), &s.prefs.auto_save.scratch_folders)
            .map(|d| d.join("Proxies").to_string_lossy().into_owned())
    });
    let mut work = Vec::new();
    let mut taken = Vec::new();
    let mut skipped = Vec::new();
    for i in items {
        let Some((clip, path, name)) = media_path(&s.project, i) else {
            skipped.push(json!({"item": i.0, "reason": "not file media"}));
            continue;
        };
        if !matches!(clip.info.kind, MediaKind::Movie) || clip.info.video.is_none() {
            skipped.push(json!({"item": i.0, "reason": format!("{name} has no video to proxy")}));
            continue;
        }
        let path = match s.media.follow(&path) {
            Ok(file) => file,
            Err(why) => {
                skipped.push(json!({"item": i.0, "reason": format!("{path} is not opened: {why}")}));
                continue;
            }
        };
        let stem = Path::new(&path).file_stem().map(|n| n.to_string_lossy().into_owned()).unwrap_or(name);
        let output = reserve_unique_path(&proxy_dir(&path, dest.as_deref()), &stem, "_Proxy", pr.extension, &taken)?;
        let out = output.path().to_string_lossy().into_owned();
        taken.push(out.clone());
        work.push((i, output, pr));
    }
    if work.is_empty() {
        return Err(EngineError::Other(format!("nothing to proxy: {}", skipped.iter().filter_map(|v| v["reason"].as_str()).collect::<Vec<_>>().join("; "))));
    }
    let outputs: Vec<Value> = work.iter().map(|(i, o, _)| json!({"item": i.0, "path": o.path()})).collect();
    let n = work.len();
    let label = format!("Create Proxies ({n} clip{})", if n == 1 { "" } else { "s" });
    let attach = bool_p(p, "attach").unwrap_or(true);
    let job = start_job(s, label, work, if attach { OnDone::AttachProxies } else { OnDone::Nothing }, bool_p(p, "wait").unwrap_or(false))?;
    Ok(json!({"job": job, "preset": pr.id, "outputs": outputs, "skipped": skipped}))
}

/// Copy to a new file, numbering collisions without replacing another take. Open the input
/// first and create the output exclusively, so a failed read or a competing copy cannot replace
/// an existing destination. Relink only after the copy's identity has been checked.
fn copy_for_ingest(s: &mut Session, item: ItemId, path: &str, dir: &Path) -> Result<String> {
    let source = Path::new(path);
    let name = source.file_name().ok_or_else(|| bad("ingest", "source has no file name"))?;
    let mut input = std::fs::File::open(source).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
    std::fs::create_dir_all(dir).map_err(|e| EngineError::Other(format!("{}: {e}", dir.display())))?;
    let mut number = 1u64;
    let (out, mut output) = loop {
        let mut next = if number == 1 { name.to_os_string() } else { source.file_stem().unwrap_or(name).to_os_string() };
        if number != 1 {
            next.push(format!(" {number}"));
            if let Some(extension) = source.extension() {
                next.push(".");
                next.push(extension);
            }
        }
        let out = dir.join(next);
        match std::fs::OpenOptions::new().write(true).create_new(true).open(&out) {
            Ok(output) => break (out, output),
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                number = number.checked_add(1).ok_or_else(|| bad("ingest", "no unused destination name"))?;
            }
            Err(e) => return Err(EngineError::Other(format!("{}: {e}", out.display()))),
        }
    };
    let copied = std::io::copy(&mut input, &mut output).and_then(|_| output.set_permissions(input.metadata()?.permissions()));
    drop(output);
    let out_s = out.to_string_lossy().into_owned();
    let linked = copied.map_err(|e| EngineError::Other(format!("copying {path}: {e}"))).and_then(|_| {
        let a = crate::relink::identity_of(&*s.services, path).map_err(|e| EngineError::Other(e.to_string()))?;
        let b = crate::relink::identity_of(&*s.services, &out_s).map_err(|e| EngineError::Other(e.to_string()))?;
        if a != b {
            return Err(EngineError::Other(format!("the copy of {} doesn't match the original", name.to_string_lossy())));
        }
        // The generated suffix may change the name; every other relink check still applies.
        crate::relink::relink(s, &json!({"item": item.0, "path": out_s, "relinkOthers": false, "match": {"fileName": false}}))?;
        Ok(())
    });
    if let Err(error) = linked {
        // Only this operation's exclusively created file can be removed on failure.
        if let Err(cleanup) = std::fs::remove_file(&out) {
            return Err(EngineError::Other(format!("{error}; removing incomplete copy {}: {cleanup}", out.display())));
        }
        return Err(error);
    }
    Ok(out_s)
}

/// Ingest freshly imported items per the project's ingest settings.
pub fn ingest(s: &mut Session, items: &[ItemId]) -> Result<Value> {
    let ing = s.project.settings.ingest.clone();
    if !ing.enabled || items.is_empty() {
        return Ok(Value::Null);
    }
    // Ingest settings travel in a project file. A destination only becomes active after this
    // machine has chosen it, or when it is safely inside the project folder.
    let destination = ing
        .destination
        .as_deref()
        .filter(|d| !d.is_empty())
        .and_then(|d| crate::project_tools::trusted_scratch(Some(d), s.path.as_deref(), &s.prefs.auto_save.scratch_folders));
    if ing.destination.as_deref().is_some_and(|d| !d.is_empty()) && destination.is_none() {
        s.toast("Ingest: ignoring an untrusted project destination; choose it locally in Ingest Settings to enable copying.");
        return Ok(json!({"skipped": "untrusted ingest destination"}));
    }
    let mut copied = Vec::new();
    let copy = matches!(ing.action, IngestAction::Copy | IngestAction::CopyAndCreateProxies);
    if copy {
        for &i in items {
            let Some((_, path, _)) = media_path(&s.project, i) else { continue };
            let dir = match &destination {
                Some(d) => d.clone(),
                _ => Path::new(&path).parent().unwrap_or(Path::new(".")).join("Ingested Media"),
            };
            if Path::new(&path).file_name().is_some_and(|name| Path::new(&path) == dir.join(name)) {
                continue;
            }
            let out_s = copy_for_ingest(s, i, &path, &dir)?;
            copied.push(json!({"item": i.0, "path": out_s}));
        }
    }
    let mut job = Value::Null;
    match ing.action {
        IngestAction::CreateProxies | IngestAction::CopyAndCreateProxies => {
            let p = json!({"items": items.iter().map(|i| i.0).collect::<Vec<_>>(), "preset": if ing.preset.is_empty() { DEFAULT_PROXY_PRESET } else { ing.preset.as_str() }, "destination": destination.as_ref().map(|d| d.to_string_lossy().into_owned())});
            if items.iter().any(|i| s.project.item(*i).and_then(|x| x.as_media()).is_some_and(|m| m.info.video.is_some() && m.info.kind == MediaKind::Movie)) {
                job = create(s, &p)?;
            }
        }
        IngestAction::Transcode => {
            let pr =
                preset(if ing.preset.is_empty() { DEFAULT_TRANSCODE_PRESET } else { ing.preset.as_str() }).ok_or_else(|| bad("ingest", "unknown preset"))?;
            let mut work = Vec::new();
            let mut taken = Vec::new();
            for &i in items {
                let Some((clip, path, name)) = media_path(&s.project, i) else { continue };
                if clip.info.video.is_none() {
                    continue;
                }
                let dir = match &destination {
                    Some(d) => d.clone(),
                    _ => Path::new(&path).parent().unwrap_or(Path::new(".")).join("Ingested Media"),
                };
                let stem = Path::new(&path).file_stem().map(|n| n.to_string_lossy().into_owned()).unwrap_or(name);
                let output = reserve_unique_path(&dir, &stem, "", pr.extension, &taken)?;
                let out = output.path().to_string_lossy().into_owned();
                taken.push(out.clone());
                work.push((i, output, pr));
            }
            if !work.is_empty() {
                let id = start_job(s, format!("Ingest: transcode {} clip(s)", work.len()), work, OnDone::ReplaceMedia, false)?;
                job = json!({"job": id});
            }
        }
        IngestAction::Copy => {}
    }
    Ok(json!({"copied": copied, "job": job}))
}

pub fn commands() -> Vec<CommandSpec> {
    vec![
        CommandSpec {
            id: "media.createProxies",
            label: "Create Proxies…",
            menu: &["Clip", "Proxy"],
            shortcut: None,
            params: r#"{"items":[id]?,"preset":"prores_proxy_quarter|prores_proxy_half|prores_lt_half|h264_quarter|h264_half"?,"destination":str?,"attach":bool=true,"wait":bool=false}"#,
            enabled: has_file_media,
            run: create,
            journal: true,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "media.attachProxies",
            label: "Attach Proxies…",
            menu: &["Clip", "Proxy"],
            shortcut: None,
            params: r#"{"item":id,"path":str}|{"items":[id],"paths":[str]},"force":bool=false"#,
            enabled: has_file_media,
            run: |s, p| {
                let pairs: Vec<(ItemId, String)> = match (p.get("items").and_then(Value::as_array), p.get("paths").and_then(Value::as_array)) {
                    (Some(i), Some(ps)) => i.iter().zip(ps).filter_map(|(i, p)| Some((ItemId(i.as_u64()?), p.as_str()?.to_string()))).collect(),
                    _ => vec![(
                        u64_p(p, "item").map(ItemId).ok_or_else(|| bad("media.attachProxies", "need `item`"))?,
                        str_p(p, "path").ok_or_else(|| bad("media.attachProxies", "need `path`"))?.to_string(),
                    )],
                };
                attach(s, &pairs, bool_p(p, "force").unwrap_or(false))
            },
            journal: true,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "media.detachProxies",
            label: "Detach Proxies",
            menu: &["Clip", "Proxy"],
            shortcut: None,
            params: r#"{"items":[id]?}"#,
            enabled: has_file_media,
            run: |s, p| {
                let items = items_param(s, p);
                let n = s.edit("Detach Proxies", |proj, _| {
                    let mut n = 0;
                    for i in &items {
                        if let Some(m) = proj.item_mut(*i).and_then(|it| it.as_media_mut())
                            && m.proxy.take().is_some()
                        {
                            n += 1;
                        }
                    }
                    Ok(n)
                })?;
                Ok(json!({"detached": n}))
            },
            journal: true,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "media.reconnectFullRes",
            label: "Reconnect Full Resolution Media…",
            menu: &["Clip", "Proxy"],
            shortcut: None,
            params: r#"{"item":id,"path":str}"#,
            enabled: has_file_media,
            run: |s, p| {
                let item = u64_p(p, "item").map(ItemId).ok_or_else(|| bad("media.reconnectFullRes", "need `item`"))?;
                if s.project.item(item).and_then(|i| i.as_media()).is_none_or(|m| m.proxy.is_none()) {
                    return Err(EngineError::Other("the clip has no proxy attached".into()));
                }
                let mut q = p.clone();
                q["match"] = json!({"fileName": false, "extension": false});
                q["relinkOthers"] = json!(false);
                crate::relink::relink(s, &q)
            },
            journal: true,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "media.toggleProxies",
            label: "Toggle Proxies",
            menu: &["View"],
            shortcut: None,
            params: r#"{"enabled":bool?}"#,
            enabled: always,
            run: |s, p| {
                let on = bool_p(p, "enabled").unwrap_or(!s.prefs.media.enable_proxies);
                let mut next = s.prefs.clone();
                next.media.enable_proxies = on;
                s.set_prefs(next).map_err(|e| EngineError::Other(format!("saving preferences: {e}")))?;
                let attached = s.project.items.values().filter(|i| i.as_media().is_some_and(|m| m.proxy.is_some())).count();
                Ok(json!({"enabled": on, "clipsWithProxies": attached}))
            },
            journal: false,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "media.proxyPresets",
            label: "Proxy Presets",
            menu: &[],
            shortcut: None,
            params: "{}",
            enabled: always,
            run: |_, _| Ok(serde_json::to_value(PRESETS).unwrap_or_default()),
            journal: false,
            named: crate::commands::NamedKeys::NONE,
        },
        CommandSpec {
            id: "project.ingestSettings",
            label: "Ingest Settings…",
            menu: &[],
            shortcut: None,
            params: r#"{"enabled":bool?,"action":"copy|transcode|createProxies|copyAndCreateProxies"?,"destination":str?,"preset":str?}"#,
            enabled: always,
            run: |s, p| {
                let mut ing = s.project.settings.ingest.clone();
                if let Some(b) = bool_p(p, "enabled") {
                    ing.enabled = b;
                }
                if let Some(a) = p.get("action") {
                    ing.action = serde_json::from_value(a.clone()).map_err(|e| bad("project.ingestSettings", e.to_string()))?;
                }
                if let Some(d) = p.get("destination") {
                    ing.destination = d.as_str().filter(|d| !d.is_empty()).map(str::to_string);
                    if let Some(d) = ing.destination.as_ref() {
                        crate::project_tools::remember_scratch_folders(s, std::slice::from_ref(d));
                    }
                }
                if let Some(pr) = str_p(p, "preset") {
                    if !pr.is_empty() && preset(pr).is_none() {
                        return Err(bad("project.ingestSettings", format!("unknown preset `{pr}`")));
                    }
                    ing.preset = pr.to_string();
                }
                if ing != s.project.settings.ingest {
                    let v = ing.clone();
                    s.edit("Ingest Settings", |proj, _| {
                        proj.settings.ingest = v;
                        Ok(())
                    })?;
                }
                Ok(serde_json::to_value(&s.project.settings.ingest).unwrap_or_default())
            },
            journal: true,
            named: crate::commands::NamedKeys::NONE,
        },
    ]
}

fn has_file_media(s: &Session) -> std::result::Result<(), String> {
    if s.project.items.values().any(|i| i.as_media().is_some_and(|m| matches!(m.media, MediaRef::File { .. }))) {
        Ok(())
    } else {
        Err("the project has no file-based media".into())
    }
}