GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! Shared helpers: fragment builder, track placement, media paths/URLs, effect and transition
//! mapping, frame/tick conversion.

use std::collections::HashMap;

use filmcraft_color::ColorInfo;
use filmcraft_media::{AudioStreamInfo, Generator, MediaInfo, MediaKind, VideoStreamInfo};
use filmcraft_project::{
    BinId, ClipId, EffectInstance, EffectKind, Interpretation, ItemId, ItemKind, Label, MediaClip, MediaRef, Param, Project, Sequence, SequenceSettings, Track,
    TrackId, TrackItem, TrackKind, effect, effect::find_effect_by_name, find_effect,
};
use filmcraft_time::{FrameRate, Tick};

use crate::{Imported, Report};

/// A timeline import may not materialise an unbounded number of sparse track
/// labels. This remains well above common editorial timelines while keeping
/// hostile lane/channel numbers from allocating every intervening track.
pub(crate) const MAX_IMPORTED_TRACKS: usize = 256;

// ---------------------------------------------------------------------------------------------
// Paths and URLs
// ---------------------------------------------------------------------------------------------

fn is_windows_abs(p: &str) -> bool {
    let b = p.as_bytes();
    b.len() >= 3 && b[0].is_ascii_alphabetic() && b[1] == b':' && (b[2] == b'/' || b[2] == b'\\')
}

pub(crate) fn is_absolute(p: &str) -> bool {
    p.starts_with('/') || p.starts_with("\\\\") || is_windows_abs(p)
}

fn percent_decode(s: &str) -> String {
    let b = s.as_bytes();
    let mut out = Vec::with_capacity(b.len());
    let mut i = 0;
    while i < b.len() {
        if b[i] == b'%' && i + 2 < b.len() {
            let h =
                std::str::from_utf8(&b[i + 1..i + 3]).ok().filter(|h| h.bytes().all(|c| c.is_ascii_hexdigit())).and_then(|h| u8::from_str_radix(h, 16).ok());
            if let Some(v) = h {
                out.push(v);
                i += 3;
                continue;
            }
        }
        out.push(b[i]);
        i += 1;
    }
    String::from_utf8(out).unwrap_or_else(|e| String::from_utf8_lossy(e.as_bytes()).into_owned())
}

fn percent_encode_path(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for &c in s.as_bytes() {
        if c.is_ascii_alphanumeric() || b"/-._~!$&'()*+,;=:@".contains(&c) {
            out.push(c as char);
        } else {
            out.push_str(&format!("%{c:02X}"));
        }
    }
    out
}

/// Convert a `file://` URL (`file:///a/b`, `file://localhost/a/b`, `file:///C:/x`) to a path.
/// Strings that are not file URLs are returned unchanged.
pub fn file_url_to_path(url: &str) -> String {
    let lower = url.get(..7).map(|s| s.to_ascii_lowercase());
    if lower.as_deref() != Some("file://") {
        return url.to_string();
    }
    let rest = &url[7..];
    let is_localhost =
        rest.get(..9).is_some_and(|s| s.eq_ignore_ascii_case("localhost")) && rest.get(9..).is_some_and(|after| after.is_empty() || after.starts_with('/'));
    let rest = if is_localhost { &rest[9..] } else { rest };
    let decoded = percent_decode(rest);
    // file:///C:/x -> C:/x
    if decoded.len() >= 3 && decoded.starts_with('/') && is_windows_abs(&decoded[1..]) {
        return decoded[1..].to_string();
    }
    if !decoded.starts_with('/') {
        // file://server/share -> UNC
        return format!("//{decoded}");
    }
    decoded
}

/// Convert an absolute path to a `file://` URL (`localhost` form for FCP7 XML).
pub fn path_to_file_url(path: &str, localhost: bool) -> String {
    let p = path.replace('\\', "/");
    // Windows verbatim paths (`\\?\C:\x`, `\\?\UNC\server\share`, as `canonicalize` returns them)
    // are not network shares: drop the prefix so `?` doesn't become the URL's host.
    let p = if let Some(unc) = p.strip_prefix("//?/UNC/") {
        format!("//{unc}")
    } else if let Some(local) = p.strip_prefix("//?/") {
        local.to_string()
    } else {
        p
    };
    let host = if localhost { "localhost" } else { "" };
    if is_windows_abs(&p) {
        format!("file://{host}/{}", percent_encode_path(&p))
    } else if let Some(unc) = p.strip_prefix("//") {
        format!("file://{}", percent_encode_path(unc))
    } else {
        format!("file://{host}{}", percent_encode_path(&p))
    }
}

/// Join `rel`, a relative media reference, to `base`, the folder of the document that names it.
/// Lexical, like `craft-docpath`, and with the same roots: none (a relative folder), `/`, a drive
/// (`C:\`, or `C:` alone for a drive-relative folder), a share (`\\host\share`, `//host/share`) or a
/// `\\?\` prefix with its drive or `UNC\host\share`. Below the root, empty names (repeated
/// separators) and `.` are dropped, and a `..` takes off the last name: at the root of an absolute
/// folder it is dropped, and past the start of a relative one it is kept. The folder's own `.` and
/// `..` go through the same rule, so a reference starts from where the folder really is. The result
/// keeps the folder's separator: `\` when it has only those, else `/` (#3998).
fn join(base: &str, rel: &str) -> String {
    let sep = if base.contains('\\') && !base.contains('/') { '\\' } else { '/' };
    let (root, absolute, rest) = split_root(base);
    let mut names: Vec<&str> = Vec::new();
    for name in rest.split(['/', '\\']).chain(rel.split(['/', '\\'])) {
        match name {
            "" | "." => {}
            ".." => match names.last() {
                Some(&last) if last != ".." => {
                    names.pop();
                }
                _ if absolute => {}
                _ => names.push(".."),
            },
            n => names.push(n),
        }
    }
    let body = names.join(&sep.to_string());
    if absolute {
        format!("{root}{sep}{body}")
    } else if root.is_empty() && body.is_empty() {
        ".".to_string()
    } else {
        format!("{root}{body}")
    }
}

/// The root `p` starts with, as written (without its last separator), whether it makes `p`
/// absolute, and the rest of `p`.
fn split_root(p: &str) -> (&str, bool, &str) {
    let is_sep = |c: char| c == '/' || c == '\\';
    let seps: Vec<usize> = p.char_indices().filter(|&(_, c)| is_sep(c)).map(|(i, _)| i).collect();
    if seps.starts_with(&[0, 1]) {
        // `\\host\share` and `\\?\C:` take two names after the leading separators,
        // `\\?\UNC\host\share` four. A name runs to the next separator, or to the end.
        let names: Vec<&str> = p.get(2..).unwrap_or_default().split(is_sep).collect();
        let count = match (names.first().copied(), names.get(1)) {
            (Some("?" | "."), Some(u)) if u.eq_ignore_ascii_case("UNC") => 4,
            _ => 2,
        };
        let end = seps.iter().copied().filter(|&i| i >= 2).nth(count - 1).unwrap_or(p.len());
        let (root, rest) = p.split_at(end);
        return (root, true, rest);
    }
    if seps.first() == Some(&0) {
        return ("", true, p);
    }
    let b = p.as_bytes();
    if b.len() >= 2 && b[0].is_ascii_alphabetic() && b[1] == b':' {
        let (root, rest) = p.split_at(2);
        return (root, seps.first() == Some(&2), rest);
    }
    ("", false, p)
}

/// Resolve a media URL from a document (FCPXML `src`, FCP7 `pathurl`, OTIO `target_url`): like
/// [`resolve_path`], with a relative URL percent-decoded as a `file://` URL is (`Clip%20A.mov` is
/// `Clip A.mov`, #2195). Plain file names (EDL, AAF) go through [`resolve_path`] untouched.
#[cfg(test)]
pub fn resolve_url(reference: &str, base_dir: Option<&str>) -> String {
    let r = reference.trim();
    let is_file_url = r.get(..5).is_some_and(|s| s.eq_ignore_ascii_case("file:"));
    if is_file_url || is_absolute(r) { resolve_path(r, base_dir) } else { resolve_path(&percent_decode(r), base_dir) }
}

/// A relative path written as a URL (the inverse of [`resolve_url`]'s decoding).
#[cfg(test)]
pub(crate) fn relative_url(path: &str) -> String {
    percent_encode_path(path)
}

/// Resolve a media reference from a document: file URLs become paths, relative paths are joined to
/// `base_dir` (when given).
pub fn resolve_path(reference: &str, base_dir: Option<&str>) -> String {
    let p = file_url_to_path(reference.trim());
    if is_absolute(&p) {
        return p;
    }
    match base_dir {
        Some(b) if !b.is_empty() => join(b, &p),
        _ => p,
    }
}

/// `path` relative to directory `base`, if `path` lies under it (or shares a prefix).
pub(crate) fn relative_path(path: &str, base: &str) -> Option<String> {
    if !is_absolute(path) || !is_absolute(base) {
        return None;
    }
    let a: Vec<&str> = path.split(['/', '\\']).filter(|s| !s.is_empty()).collect();
    let b: Vec<&str> = base.split(['/', '\\']).filter(|s| !s.is_empty()).collect();
    let common = a.iter().zip(&b).take_while(|(x, y)| x == y).count();
    if common == 0 {
        return None;
    }
    let mut out: Vec<&str> = std::iter::repeat_n("..", b.len() - common).collect();
    out.extend(&a[common..]);
    Some(out.join("/"))
}

/// Final path component.
pub(crate) fn file_name(path: &str) -> &str {
    path.rsplit(['/', '\\']).next().unwrap_or(path)
}

/// File name without extension.
pub(crate) fn file_stem(path: &str) -> &str {
    let n = file_name(path);
    match n.rfind('.') {
        Some(i) if i > 0 => &n[..i],
        _ => n,
    }
}

#[cfg(test)]
pub(crate) fn extension(path: &str) -> String {
    let n = file_name(path);
    n.rfind('.').map(|i| n[i + 1..].to_ascii_lowercase()).unwrap_or_default()
}

/// Media kind guess from a file extension.
#[cfg(test)]
pub(crate) fn kind_from_ext(path: &str) -> MediaKind {
    match extension(path).as_str() {
        "wav" | "aif" | "aiff" | "mp3" | "aac" | "m4a" | "flac" | "ogg" | "opus" | "bwf" => MediaKind::AudioOnly,
        "png" | "jpg" | "jpeg" | "tif" | "tiff" | "psd" | "bmp" | "gif" | "webp" | "exr" | "dpx" | "tga" => MediaKind::Still,
        _ => MediaKind::Movie,
    }
}

// ---------------------------------------------------------------------------------------------
// Frames and rates
// ---------------------------------------------------------------------------------------------

/// Frame count nearest to `t` at `rate`.
pub(crate) fn frames_round(rate: FrameRate, t: Tick) -> i64 {
    let f = rate.frame_at(t);
    let next = f.saturating_add(1);
    if rate.tick_of(next) - t < t - rate.tick_of(f) { next } else { f }
}

/// Whether `t` is exactly on a frame boundary of `rate`.
pub(crate) fn on_frame(rate: FrameRate, t: Tick) -> bool {
    rate.tick_of(rate.frame_at(t)) == t
}

/// FCP7-style `(timebase, ntsc)` for a rate.
#[cfg(test)]
pub(crate) fn timebase(rate: FrameRate) -> (i64, bool) {
    (rate.timecode_base(), rate.is_ntsc())
}

/// Highest rate (per second) an importer accepts. OTIO audio uses sample rates (192000 and more) as
/// time bases, so this is far above any video rate and still far below where frame arithmetic
/// overflows: a rate near `i64::MAX` made `frame_at` clamp to `i64::MAX`, and the `+ 1` after it overflowed.
pub(crate) const MAX_RATE: i64 = 1_000_000;

/// Whether `rate` is positive and at most [`MAX_RATE`] per second.
pub(crate) fn plausible_rate(rate: FrameRate) -> bool {
    rate.num > 0 && rate.den > 0 && i128::from(rate.num) <= i128::from(rate.den) * i128::from(MAX_RATE)
}

/// Rate from FCP7-style `(timebase, ntsc)`; the timebase is limited to `1..=MAX_RATE`.
#[cfg(test)]
pub(crate) fn rate_from_timebase(timebase: i64, ntsc: bool) -> FrameRate {
    let tb = timebase.clamp(1, MAX_RATE);
    if ntsc { FrameRate::new(tb * 1000, 1001) } else { FrameRate::new(tb, 1) }
}

/// Snap a floating rate (OTIO) to an exact rate.
#[cfg(test)]
pub(crate) fn rate_from_f64(r: f64) -> FrameRate {
    if r <= 0.0 || !r.is_finite() || r > MAX_RATE as f64 {
        return FrameRate::FPS_24;
    }
    for c in FrameRate::COMMON {
        if (c.as_f64() - r).abs() < 1e-3 {
            return c;
        }
    }
    let n = (r * 1001.0).round();
    if ((n / 1001.0) - r).abs() < 1e-9 && (n as i64) % 1000 == 0 {
        return FrameRate::new(n as i64, 1001);
    }
    if (r - r.round()).abs() < 1e-9 {
        return FrameRate::new(r.round() as i64, 1);
    }
    FrameRate::new((r * 1_000_000.0).round() as i64, 1_000_000)
}

// ---------------------------------------------------------------------------------------------
// Media descriptions
// ---------------------------------------------------------------------------------------------

/// What a document says about a media file.
#[derive(Clone, Debug, Default)]
pub(crate) struct MediaSpec {
    pub duration: Option<Tick>,
    /// (width, height, rate).
    pub video: Option<(u32, u32, FrameRate)>,
    /// (sample rate, channels).
    pub audio: Option<(u32, u32)>,
    pub start_tc: Option<i64>,
    pub kind: Option<MediaKind>,
}

pub(crate) fn media_info(name: &str, spec: &MediaSpec) -> MediaInfo {
    let kind = spec.kind.unwrap_or(match (spec.video.is_some(), spec.audio.is_some()) {
        (false, true) => MediaKind::AudioOnly,
        _ => MediaKind::Movie,
    });
    MediaInfo {
        name: name.to_string(),
        kind,
        duration: spec.duration.unwrap_or(Tick::ZERO),
        video: spec.video.map(|(w, h, r)| VideoStreamInfo {
            width: w,
            height: h,
            frame_rate: r,
            par: (1, 1),
            codec: String::new(),
            pixel_format: String::new(),
            color: ColorInfo::REC709,
            has_alpha: false,
            bitrate: None,
            hdr: None,
            color_assumed: None,
        }),
        audio_streams: spec
            .audio
            .map(|(sr, ch)| AudioStreamInfo { sample_rate: sr, channels: ch, codec: String::new(), bits_per_sample: None })
            .into_iter()
            .collect(),
        container: String::new(),
        start_timecode: spec.start_tc,
        file_size: None,
    }
}

pub(crate) fn media_clip(media: MediaRef, info: MediaInfo) -> MediaClip {
    MediaClip {
        media,
        info,
        interpret: Interpretation::default(),
        mark_in: None,
        mark_out: None,
        markers: Vec::new(),
        offline: false,
        proxy: None,
        identity: None,
    }
}

/// The file path behind an item (following subclips), if it is file media.
pub(crate) fn item_path(p: &Project, id: ItemId) -> Option<&str> {
    match &item_media(p, id)?.media {
        MediaRef::File { path } => Some(path),
        MediaRef::Generator(_) => None,
    }
}

/// The media clip behind an item (following subclips).
pub(crate) fn item_media(p: &Project, id: ItemId) -> Option<&MediaClip> {
    p.resolve_media(id).map(|(_, m, _)| m)
}

/// The underlying item for exports (subclip → parent media).
pub(crate) fn base_item(p: &Project, id: ItemId) -> ItemId {
    let mut cur = id;
    for _ in 0..16 {
        match p.item(cur).map(|i| &i.kind) {
            Some(ItemKind::Subclip { parent, .. }) => cur = *parent,
            _ => return cur,
        }
    }
    cur
}

/// How an export report names a clip whose source is a graphic (title) or an adjustment layer,
/// which most interchange formats cannot carry: `graphic clip "Title" at frame 48`. `None` for
/// every other clip. A lost title must be named, not folded into a count.
pub(crate) fn uncarried_clip(p: &Project, c: &TrackItem, rate: FrameRate) -> Option<String> {
    let what = match &p.item(c.item)?.kind {
        ItemKind::Graphic { .. } => "graphic clip",
        ItemKind::AdjustmentLayer { .. } => "adjustment layer",
        _ => return None,
    };
    Some(format!("{what} \"{}\" at frame {}", c.name, rate.frame_at(c.start)))
}

pub(crate) fn generator_of(p: &Project, id: ItemId) -> Option<&Generator> {
    match &item_media(p, id)?.media {
        MediaRef::Generator(g) => Some(g),
        MediaRef::File { .. } => None,
    }
}

// ---------------------------------------------------------------------------------------------
// Fragment builder
// ---------------------------------------------------------------------------------------------

pub(crate) struct Builder {
    pub p: Project,
    media: HashMap<String, ItemId>,
    pub top: Vec<ItemId>,
    next_link: u64,
}

impl Builder {
    pub fn new(name: &str) -> Self {
        Self { p: Project::new(name), media: HashMap::new(), top: Vec::new(), next_link: 1 }
    }

    pub fn bin(&mut self, name: &str, parent: Option<BinId>) -> BinId {
        self.p.add_bin(name, parent)
    }

    pub fn find_media(&self, key: &str) -> Option<ItemId> {
        self.media.get(key).copied()
    }

    #[cfg(test)]
    pub fn register_media(&mut self, key: &str, id: ItemId) {
        self.media.insert(key.to_string(), id);
    }

    /// File media deduplicated by `key` (normally the resolved path).
    pub fn file_media(&mut self, key: &str, name: &str, path: &str, spec: &MediaSpec, bin: Option<BinId>) -> ItemId {
        if let Some(id) = self.media.get(key) {
            return *id;
        }
        let info = media_info(name, spec);
        let id = self.p.add_item(name, Label::Iris, ItemKind::Media(Box::new(media_clip(MediaRef::File { path: path.to_string() }, info))), bin);
        self.media.insert(key.to_string(), id);
        id
    }

    #[cfg(test)]
    pub fn generator_media(&mut self, key: &str, name: &str, g: Generator, spec: &MediaSpec, bin: Option<BinId>) -> ItemId {
        if let Some(id) = self.media.get(key) {
            return *id;
        }
        let mut spec = spec.clone();
        spec.kind = Some(MediaKind::Synthetic);
        let info = media_info(name, &spec);
        let id = self.p.add_item(name, Label::Lavender, ItemKind::Media(Box::new(media_clip(MediaRef::Generator(g), info))), bin);
        self.media.insert(key.to_string(), id);
        id
    }

    /// Add an empty sequence item (filled later with [`Builder::put_sequence`]).
    pub fn reserve_sequence(&mut self, name: &str, settings: SequenceSettings, bin: Option<BinId>) -> ItemId {
        let seq = empty_sequence(settings);
        self.p.add_item(name, Label::Forest, ItemKind::Sequence(std::sync::Arc::new(seq)), bin)
    }

    pub fn put_sequence(&mut self, id: ItemId, mut seq: Sequence) {
        for t in seq.all_tracks_mut() {
            t.sort();
        }
        if let Some(s) = self.p.sequence_mut(id) {
            *s = seq;
        }
    }

    pub fn track(&mut self, kind: TrackKind, index: usize) -> Track {
        let id = TrackId(self.p.alloc_id());
        let name = match kind {
            TrackKind::Video => format!("Video {}", index + 1),
            TrackKind::Audio => format!("Audio {}", index + 1),
        };
        Track::new(id, kind, name)
    }

    /// Ensure `n` tracks of one kind exist. Returns false when an imported
    /// label would exceed the supported per-kind track count.
    pub fn ensure_tracks(&mut self, seq: &mut Sequence, kind: TrackKind, n: usize) -> bool {
        if n > MAX_IMPORTED_TRACKS {
            return false;
        }
        while seq.tracks(kind).len() < n {
            let i = seq.tracks(kind).len();
            let t = self.track(kind, i);
            seq.tracks_mut(kind).push(t);
        }
        true
    }

    pub fn link_id(&mut self) -> u64 {
        let l = self.next_link;
        self.next_link += 1;
        l
    }

    pub fn alloc(&mut self) -> u64 {
        self.p.alloc_id()
    }

    /// A track item with the intrinsic effects of its track kind.
    pub fn clip(&mut self, item: ItemId, kind: TrackKind, name: &str, start: Tick, duration: Tick, source_in: Tick) -> TrackItem {
        let label = self.p.item(item).map(|i| i.label).unwrap_or(Label::Iris);
        TrackItem {
            custom_label_color: self.p.item(item).and_then(|i| i.custom_label_color),
            id: ClipId(self.p.alloc_id()),
            item,
            name: name.to_string(),
            label,
            start,
            duration,
            source_in,
            speed: 1.0,
            reverse: false,
            enabled: true,
            link: None,
            group: None,
            effects: match kind {
                TrackKind::Video => effect::intrinsic_video(),
                TrackKind::Audio => effect::intrinsic_audio(),
            },
            markers: Vec::new(),
            gain_db: 0.0,
            frame_hold: None,
            scale_to_frame: false,
            essential: None,
            multicam: None,
            time_interpolation: Default::default(),
            maintain_pitch: false,
            hold_filters: false,
            field_options: None,
            source_channels: Vec::new(),
            audio_stream: 0,
            graphic: None,
        }
    }

    /// Place `item` on the first track at or after `preferred` where it does not overlap anything,
    /// creating tracks as needed. Returns the track index.
    #[cfg(test)]
    pub fn place(&mut self, seq: &mut Sequence, kind: TrackKind, preferred: usize, item: TrackItem) -> Option<usize> {
        let mut i = preferred;
        loop {
            if i >= MAX_IMPORTED_TRACKS || !self.ensure_tracks(seq, kind, i + 1) {
                return None;
            }
            let t = &mut seq.tracks_mut(kind)[i];
            if !t.items.iter().any(|o| o.start < item.end() && item.start < o.end()) {
                t.items.push(item);
                t.sort();
                return Some(i);
            }
            i += 1;
        }
    }

    /// Finish: grow media durations to cover every use, return the fragment.
    pub fn finish(mut self) -> Imported {
        let mut need: HashMap<ItemId, Tick> = HashMap::new();
        for it in self.p.items.values() {
            if let Some(seq) = it.as_sequence() {
                for t in seq.all_tracks() {
                    for ti in &t.items {
                        let e = need.entry(ti.item).or_insert(Tick::ZERO);
                        *e = (*e).max(ti.source_out()).max(ti.source_in + Tick(1));
                    }
                }
            }
        }
        for (id, end) in need {
            if let Some(m) = self.p.item_mut(id).and_then(|i| i.as_media_mut())
                && m.info.duration < end
            {
                m.info.duration = end;
            }
        }
        Imported { project: self.p, sequences: self.top }
    }
}

pub(crate) fn empty_sequence(settings: SequenceSettings) -> Sequence {
    Sequence {
        settings,
        video_tracks: Vec::new(),
        audio_tracks: Vec::new(),
        markers: Vec::new(),
        mark_in: None,
        mark_out: None,
        work_area: None,
        start_timecode: 0,
        master_volume_db: 0.0,
        master_effects: Vec::new(),
        master_mixer: Default::default(),
        submix_tracks: Vec::new(),
        caption_tracks: Vec::new(),
        multicam: None,
        merged: None,
        split: Default::default(),
    }
}

pub(crate) fn settings_for(rate: FrameRate, width: u32, height: u32, drop_frame: bool) -> SequenceSettings {
    SequenceSettings {
        width,
        height,
        frame_rate: rate,
        drop_frame: drop_frame && rate.supports_drop_frame(),
        preset: format!("Custom {width}x{height} {}", rate.label()),
        ..SequenceSettings::default()
    }
}

/// Source time advanced by a timeline duration at `speed` (exact for integral speeds).
///
/// This is the one place the importers multiply a `Tick` by a number from a file: `Tick` has no
/// `Mul`, and its `Add`/`Sub` saturate, so every other sum of durations already clamps. It saturates
/// at the `i64` bounds like those operators do (not at `Tick::MAX`, which the editing code uses as
/// its "no next item" sentinel).
pub(crate) fn scaled(d: Tick, speed: f64) -> Tick {
    let s = speed.abs();
    // saturating: a duration read from a file times a speed from the same file can exceed an i64 of ticks
    if s == s.round() && s < 1e6 { Tick(d.0.saturating_mul(s as i64)) } else { Tick((d.0 as f64 * s).round() as i64) }
}

/// Timeline duration of a source duration at `speed`.
#[cfg(test)]
pub(crate) fn unscaled(d: Tick, speed: f64) -> Tick {
    let s = speed.abs();
    if s == 0.0 {
        return d;
    }
    if s == 1.0 { d } else { Tick((d.0 as f64 / s).round() as i64) }
}

/// Overwrite `item` onto `track` (EDL record semantics): whatever was under it is trimmed/split.
pub(crate) fn overwrite(track: &mut Track, item: TrackItem, alloc: &mut dyn FnMut() -> u64) {
    let (s, e) = (item.start, item.end());
    let mut out = Vec::with_capacity(track.items.len() + 2);
    for o in track.items.drain(..) {
        if o.end() <= s || o.start >= e {
            out.push(o);
            continue;
        }
        if o.start < s {
            let mut l = o.clone();
            l.duration = s - o.start;
            out.push(l);
        }
        if o.end() > e {
            let mut r = o.clone();
            r.id = ClipId(alloc());
            r.source_in = o.source_in + scaled(e - o.start, o.speed);
            r.start = e;
            r.duration = o.end() - e;
            out.push(r);
        }
    }
    out.push(item);
    track.items = out;
    track.sort();
}

// ---------------------------------------------------------------------------------------------
// Effects
// ---------------------------------------------------------------------------------------------

pub(crate) fn param<'a>(ti: &'a TrackItem, effect: &str, param: &str) -> Option<&'a Param> {
    ti.effect(effect).and_then(|e| e.param(param))
}

/// Set a parameter, adding the effect instance (defaults) if the item lacks it.
pub(crate) fn set_param(ti: &mut TrackItem, effect: &str, param: &str, value: Param) {
    if ti.effect(effect).is_none()
        && let Some(d) = find_effect(effect)
    {
        ti.effects.push(d.instance());
    }
    if let Some(e) = ti.effect_mut(effect) {
        e.params.insert(param.to_string(), value);
    }
}

/// Whether a parameter differs from its definition default or is animated.
#[cfg(test)]
pub(crate) fn param_modified(ti: &TrackItem, effect: &str, param_id: &str) -> bool {
    let Some(p) = param(ti, effect, param_id) else { return false };
    if p.is_animated() {
        return true;
    }
    let def = find_effect(effect).and_then(|d| d.param(param_id)).map(|d| d.default.clone());
    match (&p.value, def) {
        (filmcraft_project::ParamValue::Vec2(v), Some(filmcraft_project::ParamValue::Vec2(_))) => !(v.x.is_nan() && v.y.is_nan()),
        (v, Some(d)) => *v != d,
        _ => false,
    }
}

/// Non-intrinsic effects on an item.
pub(crate) fn standard_effects(ti: &TrackItem) -> impl Iterator<Item = &EffectInstance> {
    ti.effects.iter().filter(|e| !e.def().is_some_and(|d| d.intrinsic))
}

/// A transition effect for a document's transition name. Unknown names become Cross Dissolve
/// (Constant Power on audio) with a warning.
pub(crate) fn transition_effect(name: &str, audio: bool, report: &mut Report) -> EffectInstance {
    let n = name.trim().to_ascii_lowercase();
    let alias = match n.as_str() {
        "dissolve" | "cross dissolve" | "smpte_dissolve" | "d" | "crossdissolve" => Some(if audio { "constant_power" } else { "cross_dissolve" }),
        "cross fade (+3db)" | "cross fade +3db" | "crossfade (+3db)" | "cross fade" => Some("constant_power"),
        "cross fade (0db)" | "cross fade 0db" | "crossfade (0db)" => Some("constant_gain"),
        "dip to color dissolve" | "fade in fade out dissolve" | "fade to color" => Some("dip_to_black"),
        "edge wipe" | "wipe" | "smpte_wipe" => Some("wipe"),
        _ => None,
    };
    if let Some(id) = alias
        && let Some(d) = find_effect(id)
    {
        return d.instance();
    }
    let want = if audio { EffectKind::AudioTransition } else { EffectKind::VideoTransition };
    if let Some(d) = find_effect_by_name(name.trim()).filter(|d| d.kind == want) {
        return d.instance();
    }
    let fallback = if audio { "constant_power" } else { "cross_dissolve" };
    report.warn(format!("transition \"{name}\" is not supported; imported as {}", find_effect(fallback).map(|d| d.name).unwrap_or(fallback)));
    find_effect(fallback).map(|d| d.instance()).unwrap_or_else(|| EffectInstance {
        effect: fallback.into(),
        enabled: true,
        params: Default::default(),
        masks: vec![],
        post_fader: false,
        essential: false,
        layer: None,
    })
}

/// Name of a transition in a document (the name an export has always written, so a UI rename does
/// not change the file).
pub(crate) fn transition_name(e: &EffectInstance) -> String {
    e.def().map(|d| filmcraft_project::interchange_name(d).to_string()).unwrap_or_else(|| e.effect.clone())
}

/// Label from a document label name (Premiere label names; FCP7 names like "Good Take" ignored).
#[cfg(test)]
pub(crate) fn label_from(s: &str) -> Option<Label> {
    Label::from_name(s.trim())
}

/// dB ↔ linear gain.
pub(crate) fn db_to_gain(db: f64) -> f64 {
    if db <= -287.0 { 0.0 } else { 10f64.powf(db / 20.0) }
}
pub(crate) fn gain_to_db(g: f64) -> f64 {
    if g <= 1e-15 { -287.5 } else { 20.0 * g.log10() }
}

/// Sanitise a name for fixed-width EDL fields.
pub(crate) fn sanitize_reel(s: &str, max: usize) -> String {
    let r: String = s.chars().map(|c| if c.is_ascii_alphanumeric() || c == '_' || c == '-' { c.to_ascii_uppercase() } else { '_' }).take(max).collect();
    if r.is_empty() { "AX".into() } else { r }
}

#[cfg(test)]
mod tests {
    use super::*;
    use filmcraft_time::TimeRange;

    #[test]
    fn percent_decode_requires_hex_digits() {
        assert_eq!(file_url_to_path("file:///a/100%+5x.mov"), "/a/100%+5x.mov");
        assert_eq!(file_url_to_path("file:///a/100%-1x.mov"), "/a/100%-1x.mov");
        assert_eq!(file_url_to_path("file:///a/100%g0x.mov"), "/a/100%g0x.mov");
        assert_eq!(file_url_to_path("file:///a/b%20c.mov"), "/a/b c.mov");
    }

    #[test]
    fn urls() {
        assert_eq!(file_url_to_path("file://localhost/Users/me/My%20Clip.mov"), "/Users/me/My Clip.mov");
        assert_eq!(file_url_to_path("file:///C:/Media/a.mxf"), "C:/Media/a.mxf");
        assert_eq!(file_url_to_path("/plain/path.mov"), "/plain/path.mov");
        assert_eq!(path_to_file_url("/Users/me/My Clip.mov", true), "file://localhost/Users/me/My%20Clip.mov");
        assert_eq!(path_to_file_url("C:\\Media\\a b.mxf", false), "file:///C:/Media/a%20b.mxf");
        assert_eq!(path_to_file_url("\\\\?\\C:\\Media\\a.mp4", true), "file://localhost/C:/Media/a.mp4");
        assert_eq!(path_to_file_url("\\\\?\\UNC\\srv\\share\\a.mp4", false), "file://srv/share/a.mp4");
        for p in ["/a/b c/ü.mov", "C:/x/y.mp4", "/r/%/#?.mov"] {
            assert_eq!(file_url_to_path(&path_to_file_url(p, true)), p);
            assert_eq!(file_url_to_path(&path_to_file_url(p, false)), p);
        }
    }

    #[test]
    fn file_url_localhost_prefix_host_is_kept() {
        assert_eq!(file_url_to_path("file://localhost-nas/share/a.mov"), "//localhost-nas/share/a.mov");
        assert_eq!(file_url_to_path("file://LOCALHOSTX/a"), "//LOCALHOSTX/a");
        assert_eq!(file_url_to_path("file://localhost/a/b"), "/a/b");
        assert_eq!(file_url_to_path("file://LocalHost/a"), "/a");
    }

    #[test]
    fn paths() {
        assert_eq!(resolve_path("media/a.mov", Some("/proj")), "/proj/media/a.mov");
        assert_eq!(resolve_path("../a.mov", Some("/proj/x/")), "/proj/a.mov");
        assert_eq!(resolve_path("/abs/a.mov", Some("/proj")), "/abs/a.mov");
        // #2195: relative URLs are percent-decoded, plain names are not
        assert_eq!(resolve_url("media/Clip%20A.mov", Some("/proj")), "/proj/media/Clip A.mov");
        assert_eq!(resolve_url("file:///m/Clip%20A.mov", Some("/proj")), "/m/Clip A.mov");
        assert_eq!(resolve_path("Clip%20A.mov", Some("/proj")), "/proj/Clip%20A.mov");
        assert_eq!(resolve_url(&relative_url("a b/100%.mov"), Some("/p")), "/p/a b/100%.mov");
        assert_eq!(relative_path("/proj/media/a.mov", "/proj").as_deref(), Some("media/a.mov"));
        assert_eq!(relative_path("/proj/a.mov", "/proj/edl").as_deref(), Some("../a.mov"));
        assert_eq!(file_stem("/x/y/Clip 01.final.mov"), "Clip 01.final");
    }

    /// `join` over the path forms a document folder can take. Each row is (folder, reference,
    /// expected, the rule it shows).
    #[test]
    fn relative_references_join_their_folder() {
        const ROWS: &[(&str, &str, &str, &str)] = &[
            // POSIX, absolute
            ("/proj", "media/a.mov", "/proj/media/a.mov", "names are appended to the folder"),
            ("/proj/x/", "../a.mov", "/proj/a.mov", "a trailing separator ends the folder; `..` takes off its last name"),
            ("/proj//x", "../a.mov", "/proj/a.mov", "repeated separators are one: `..` takes off `x`, not an empty name"),
            ("/proj/./x", "./a.mov", "/proj/x/a.mov", "`.` is dropped in the folder and in the reference"),
            ("/", "a.mov", "/a.mov", "the root alone"),
            ("/proj", "../../a.mov", "/a.mov", "`..` at an absolute root is dropped"),
            ("/work/edit/..", "../media/b.mov", "/media/b.mov", "the folder's own `..` (std::path::absolute keeps it) is resolved first"),
            ("/work/..", "../media/b.mov", "/media/b.mov", "so the reference never climbs above the root"),
            // POSIX, relative
            ("edit", "../media/a.mov", "media/a.mov", "`..` takes off a relative folder's first name too"),
            ("a/edit", "../../a.mov", "a.mov", "and every name after it"),
            ("edit", "../../a.mov", "../a.mov", "past the start of a relative folder `..` is kept"),
            ("..", "../a.mov", "../../a.mov", "after a `..`, another `..` is kept"),
            ("../", "clip.mov", "../clip.mov", "a `../` folder"),
            (".", "../a.mov", "../a.mov", "a `.` folder is the current one"),
            ("./", "clip.mov", "clip.mov", "and so is `./`: it is not the root"),
            ("edit//sub", "../a.mov", "edit/a.mov", "repeated separators in a relative folder are one too"),
            ("edit/sub/../..", "../a.mov", "../a.mov", "a relative folder's own `..` is resolved first"),
            ("edit", "..", ".", "a reference that comes back to the start is the current folder"),
            // Windows drives, either separator
            (r"C:\proj", r"media\a.mov", r"C:\proj\media\a.mov", "a drive folder keeps its `\\`"),
            (r"C:\proj", r"..\..\a.mov", r"C:\a.mov", "`..` stops at the drive's root"),
            (r"C:\proj\..\..", "a.mov", r"C:\a.mov", "and so does the folder's own `..`"),
            (r"C:\", "a.mov", r"C:\a.mov", "the drive's root alone"),
            ("C:/proj/edit", "../media/a.mov", "C:/proj/media/a.mov", "a drive written with `/` keeps it"),
            (r"C:edit\sub", r"..\a.mov", r"C:edit\a.mov", "a drive-relative folder keeps its drive and is relative below it"),
            // shares and `\\?\` prefixes
            (r"\\srv\share\..\edit", "a.mov", r"\\srv\share\edit\a.mov", "the share is part of the root: `..` can't take it off"),
            (r"\\srv\share", r"..\a.mov", r"\\srv\share\a.mov", "`..` stops at the share"),
            (r"\\srv\share\d", r"..\x\a.mov", r"\\srv\share\x\a.mov", "below the share, `..` takes off names"),
            ("//srv/share/edit", "../../a.mov", "//srv/share/a.mov", "a share written with `/`"),
            (r"\\?\C:\proj", r"..\..\a.mov", r"\\?\C:\a.mov", r"a `\\?\` drive's root is the drive"),
            (r"\\?\UNC\srv\share\d", r"..\..\a.mov", r"\\?\UNC\srv\share\a.mov", r"a `\\?\UNC` root runs to the share"),
            // separator styles
            (r"proj\edit", r"..\media\a.mov", r"proj\media\a.mov", "a relative folder written with `\\` keeps it"),
            ("/proj", r"media\a.mov", "/proj/media/a.mov", "either separator in the reference; the folder's style wins"),
        ];
        for &(folder, reference, expected, rule) in ROWS {
            assert_eq!(resolve_path(reference, Some(folder)), expected, "{rule}: {folder:?} + {reference:?}");
        }
    }

    #[test]
    fn rates() {
        assert_eq!(rate_from_timebase(24, true), FrameRate::FPS_23_976);
        assert_eq!(rate_from_timebase(30, true), FrameRate::FPS_29_97);
        assert_eq!(rate_from_timebase(60, true), FrameRate::FPS_59_94);
        assert_eq!(rate_from_timebase(25, false), FrameRate::FPS_25);
        assert_eq!(rate_from_f64(24000.0 / 1001.0), FrameRate::FPS_23_976);
        assert_eq!(rate_from_f64(23.976), FrameRate::FPS_23_976);
        assert_eq!(rate_from_f64(48000.0), FrameRate::new(48000, 1));
        assert_eq!(rate_from_f64(192_000.0), FrameRate::new(192_000, 1));
        // absurd rates from a hostile file: bounded instead of overflowing frame arithmetic later
        for ntsc in [false, true] {
            let r = rate_from_timebase(i64::MAX, ntsc);
            assert!(plausible_rate(r), "{r}");
            assert_eq!(rate_from_timebase(-5, ntsc), rate_from_timebase(1, ntsc));
        }
        for r in [1e300, 9.3e18, 2_000_000.0, f64::INFINITY, f64::NAN, -1.0] {
            assert_eq!(rate_from_f64(r), FrameRate::FPS_24, "{r}");
        }
        assert!(!plausible_rate(FrameRate::new(i64::MAX, 1)));
        assert!(!plausible_rate(FrameRate { num: 0, den: 1 }));
        assert!(plausible_rate(FrameRate::FPS_23_976));
        assert_eq!(frames_round(FrameRate::FPS_24, FrameRate::FPS_24.tick_of(5) + Tick(10)), 5);
    }

    #[test]
    fn imported_tracks_are_bounded() {
        let mut b = Builder::new("tracks");
        let mut seq = empty_sequence(Default::default());
        assert!(b.ensure_tracks(&mut seq, TrackKind::Video, MAX_IMPORTED_TRACKS));
        assert_eq!(seq.video_tracks.len(), MAX_IMPORTED_TRACKS);
        assert!(!b.ensure_tracks(&mut seq, TrackKind::Video, MAX_IMPORTED_TRACKS + 1));
        assert_eq!(seq.video_tracks.len(), MAX_IMPORTED_TRACKS);
    }

    /// A huge duration at an integral speed saturates instead of overflowing (an EDL with a record-out
    /// timecode of 2147483647 hours and an `M2 ... 72.0` speed change panicked here).
    #[test]
    fn scaled_saturates() {
        assert_eq!(scaled(Tick(i64::MAX / 2), 3.0), Tick(i64::MAX));
        assert_eq!(scaled(Tick(i64::MIN / 2), 3.0), Tick(i64::MIN));
        assert_eq!(scaled(Tick(1000), 3.0), Tick(3000));
        assert_eq!(scaled(Tick(1000), 0.5), Tick(500));
    }

    #[test]
    fn subclip_cycle_resolution_is_bounded() {
        let mut p = Project::new("Cycle Test");
        let info = MediaInfo {
            name: "clip.mp4".into(),
            kind: MediaKind::Movie,
            duration: Tick(100_000),
            video: None,
            audio_streams: vec![],
            container: "mp4".into(),
            start_timecode: None,
            file_size: None,
        };
        let media_id = p.add_item(
            "Clip",
            Label::Iris,
            ItemKind::Media(Box::new(MediaClip {
                media: MediaRef::File { path: "/path/to/clip.mp4".into() },
                info,
                interpret: Default::default(),
                mark_in: None,
                mark_out: None,
                markers: vec![],
                offline: false,
                proxy: None,
                identity: None,
            })),
            None,
        );

        // Normal subclip and chained subclip
        let sub1 = p.add_item(
            "Sub 1",
            Label::Iris,
            ItemKind::Subclip { parent: media_id, range: TimeRange::new(Tick::ZERO, Tick(10_000)), restrict_trims: false },
            None,
        );
        let sub2 =
            p.add_item("Sub 2", Label::Iris, ItemKind::Subclip { parent: sub1, range: TimeRange::new(Tick(1_000), Tick(5_000)), restrict_trims: false }, None);

        assert_eq!(base_item(&p, media_id), media_id);
        assert_eq!(base_item(&p, sub1), media_id);
        assert_eq!(base_item(&p, sub2), media_id);
        assert_eq!(item_path(&p, sub2), Some("/path/to/clip.mp4"));
        assert!(item_media(&p, sub2).is_some());

        // Self-referencing subclip (direct cycle)
        let self_cycle =
            p.add_item("Self Cycle", Label::Iris, ItemKind::Subclip { parent: ItemId(9999), range: TimeRange::default(), restrict_trims: false }, None);
        p.item_mut(self_cycle).unwrap().kind = ItemKind::Subclip { parent: self_cycle, range: TimeRange::default(), restrict_trims: false };

        // Mutual cycle (A -> B -> A)
        let cycle_a = p.add_item("Cycle A", Label::Iris, ItemKind::Subclip { parent: ItemId(9999), range: TimeRange::default(), restrict_trims: false }, None);
        let cycle_b = p.add_item("Cycle B", Label::Iris, ItemKind::Subclip { parent: cycle_a, range: TimeRange::default(), restrict_trims: false }, None);
        p.item_mut(cycle_a).unwrap().kind = ItemKind::Subclip { parent: cycle_b, range: TimeRange::default(), restrict_trims: false };

        // Verify calls that previously caused infinite recursion now safely terminate
        assert_eq!(base_item(&p, self_cycle), self_cycle);
        assert_eq!(item_media(&p, self_cycle), None);
        assert_eq!(item_path(&p, self_cycle), None);

        let base_a = base_item(&p, cycle_a);
        assert!(base_a == cycle_a || base_a == cycle_b);
        assert_eq!(item_media(&p, cycle_a), None);
        assert_eq!(item_path(&p, cycle_a), None);
        assert_eq!(item_media(&p, cycle_b), None);
        assert_eq!(item_path(&p, cycle_b), None);

        // Missing item parent
        let missing_parent = p.add_item(
            "Missing Parent",
            Label::Iris,
            ItemKind::Subclip { parent: ItemId(123456789), range: TimeRange::default(), restrict_trims: false },
            None,
        );
        assert_eq!(base_item(&p, missing_parent), ItemId(123456789));
        assert_eq!(item_media(&p, missing_parent), None);
        assert_eq!(item_path(&p, missing_parent), None);
    }
}