GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! FCPXML (1.9–1.11) import/export.
//!
//! Mapping between FilmCraft's track model and FCPXML's magnetic model:
//! - V1 is the primary storyline (`spine`): clips, `gap`s and `transition`s.
//! - Other video tracks become connected clips with `lane = track index` (V2 → lane 1); audio-only
//!   items on audio track n become connected clips on lane `-n`. A V1/V2… clip whose linked audio
//!   sits on the same-numbered audio track with identical timing is written as one clip carrying
//!   both (`srcEnable="all"`), otherwise `srcEnable="video"`/`"audio"`.
//! - Rational times (`1001/24000s`) map exactly onto ticks.
//! - Standalone `video` elements reference the picture of an asset (including still images),
//!   without importing that asset's audio. Effect-backed generators are reported as unsupported.
//! - `adjust-conform` (`fit`, the default, and `none`) maps to the clip's scale-to-frame-size flag;
//!   `fill` is reported and imported as `fit`.
//! - `adjust-transform` (position in percent of frame height, FCP y-up, counter-clockwise
//!   rotation), `adjust-blend` (opacity), `adjust-volume` (dB) and their keyframes are mapped;
//!   constant speed, reverse and freeze frames use a two-point `timeMap`.
//! - Markers on primary-storyline elements become sequence markers; markers on connected clips stay
//!   clip markers. Transitions are supported on the primary storyline (and read from secondary
//!   storylines); transitions elsewhere are reported.

use std::collections::{HashMap, HashSet};

use filmcraft_geom::Vec2;
use filmcraft_media::MediaKind;
use filmcraft_project::{
    BinId, ItemId, ItemKind, Keyframe, Label, Marker, MarkerId, MarkerKind, Param, ParamValue, Project, Sequence, TrackItem, TrackKind, Transition,
    TransitionAlign, TransitionId, effect::find_effect_by_name,
};
use filmcraft_time::{FrameRate, TICKS_PER_SECOND, Tick};
use roxmltree::Node;

use crate::common::{
    Builder, MAX_IMPORTED_TRACKS, MediaSpec, base_item, db_to_gain, empty_sequence, file_name, gain_to_db, generator_of, item_media, item_path, kind_from_ext,
    param, param_modified, path_to_file_url, resolve_path, resolve_url, scaled, set_param, settings_for, standard_effects, transition_effect, transition_name,
};
use crate::xml::{child, children, elements, num};
use crate::{Error, ExportOptions, Format, ImportOptions, Imported, Report, Result};

// ---------------------------------------------------------------------------------------------
// Rational time
// ---------------------------------------------------------------------------------------------

fn gcd(mut a: i128, mut b: i128) -> i128 {
    a = a.abs();
    b = b.abs();
    while b != 0 {
        (a, b) = (b, a % b);
    }
    a.max(1)
}

/// Parse an FCPXML time value (`"1001/24000s"`, `"5s"`, `"0s"`, `"3.5s"`) into ticks.
pub(crate) fn parse_time(s: &str) -> Option<Tick> {
    let s = s.trim().strip_suffix('s').unwrap_or(s.trim());
    if s.is_empty() {
        return None;
    }
    if let Some((a, b)) = s.split_once('/') {
        let a: i128 = a.trim().parse().ok()?;
        let b: i128 = b.trim().parse().ok()?;
        if b == 0 {
            return None;
        }
        let n = a * TICKS_PER_SECOND as i128;
        // Exact for every broadcast rate; round to the nearest tick otherwise.
        let q = n.div_euclid(b);
        let r = n.rem_euclid(b);
        return Some(Tick((if 2 * r >= b.abs() { q + 1 } else { q }) as i64));
    }
    if let Ok(i) = s.parse::<i64>() {
        return Some(Tick(i * TICKS_PER_SECOND));
    }
    s.parse::<f64>().ok().map(Tick::from_seconds_f64)
}

/// Format ticks as an FCPXML rational time, frame-based at `rate` when the value is on a frame.
pub(crate) fn fmt_time(t: Tick, rate: FrameRate) -> String {
    if t == Tick::ZERO {
        return "0s".into();
    }
    let f = rate.frame_at(t);
    if rate.tick_of(f) == t {
        let num = f as i128 * rate.den as i128;
        let den = rate.num as i128;
        if num % den == 0 {
            return format!("{}s", num / den);
        }
        return format!("{num}/{den}s");
    }
    let g = gcd(t.0 as i128, TICKS_PER_SECOND as i128);
    let (a, b) = (t.0 as i128 / g, TICKS_PER_SECOND as i128 / g);
    if b == 1 { format!("{a}s") } else { format!("{a}/{b}s") }
}

fn attr_time(n: Node, name: &str) -> Option<Tick> {
    n.attribute(name).and_then(parse_time)
}

fn rate_from_frame_duration(s: &str) -> Option<FrameRate> {
    let s = s.trim().strip_suffix('s')?;
    let (a, b) = s.split_once('/').unwrap_or((s, "1"));
    let (a, b): (i64, i64) = (a.parse().ok()?, b.parse().ok()?);
    // both parts must be positive: a zero or negative numerator of the rate divides by zero later
    (a > 0 && b > 0).then(|| FrameRate::new(b, a))
}

fn audio_rate_str(sr: u32) -> String {
    if sr.is_multiple_of(1000) { format!("{}k", sr / 1000) } else { format!("{}k", sr as f64 / 1000.0) }
}

fn parse_audio_rate(s: &str) -> Option<u32> {
    let s = s.trim();
    let r = match s.strip_suffix('k') {
        Some(k) => k.parse::<f64>().ok().map(|v| (v * 1000.0).round() as u32),
        None => s.parse().ok(),
    };
    r.filter(|&sr| sr > 0 && sr <= 384_000)
}

// ---------------------------------------------------------------------------------------------
// Import
// ---------------------------------------------------------------------------------------------

#[derive(Clone)]
struct Asset {
    item: ItemId,
    start: Tick,
    has_video: bool,
    has_audio: bool,
}

/// Most times truncated media is imported again at a shallower depth.
const MAX_REIMPORTS: usize = 4096;

/// Deepest storyline/element nesting a hostile file may walk. The FCPXML structure can nest
/// connected clips and secondary storylines without limit, and layout recurses once per level
/// (audit: FilmCraft F3).
const MAX_XML_DEPTH: usize = 128;

struct Imp<'a, 'i, 'r> {
    b: Builder,
    opts: &'a ImportOptions,
    report: &'r mut Report,
    formats: HashMap<String, (FrameRate, u32, u32)>,
    asset_nodes: HashMap<String, Node<'a, 'i>>,
    assets: HashMap<String, Asset>,
    media_nodes: HashMap<String, Node<'a, 'i>>,
    media_items: HashMap<String, ItemId>,
    media_active: HashSet<String>,
    /// Traversals cut short by either the media-chain or XML-layout depth limit.
    depth_hits: usize,
    /// Media imported incomplete (a nested one below it was left out), by id: the
    /// (media-chain, XML-layout) depths it was imported at. Retry when neither depth is
    /// worse and at least one is shallower; both limits must still be respected.
    media_truncated_at: HashMap<String, (usize, usize)>,
    /// Re-imports of truncated media still allowed.
    reimports_left: usize,
    effects: HashMap<String, String>,
    /// Current storyline/element nesting, checked against [`MAX_XML_DEPTH`].
    depth: usize,
}

/// Where an element's keyframe times start, the media time it starts at and its playback speed.
#[derive(Clone, Copy)]
struct LocalTiming {
    local_start: Tick,
    src_in: Tick,
    speed: f64,
}

/// Where a written clip element sits: offset in its parent's local time, connected lane, and
/// whether it is on the primary storyline.
#[derive(Clone, Copy)]
struct ClipPlacement {
    offset: Tick,
    lane: Option<i32>,
    primary: bool,
}

/// Placement context of a storyline element.
struct Ctx {
    seq_rate: FrameRate,
    frame: (u32, u32),
}

pub(crate) fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result<Imported> {
    let doc = crate::xml::parse(text).map_err(|e| Error::parse(Format::Fcpxml, e))?;
    let root = doc.root_element();
    if root.tag_name().name() != "fcpxml" {
        return Err(Error::parse(Format::Fcpxml, "root element is not <fcpxml>"));
    }
    if let Some(v) = root.attribute("version") {
        let minor = v.split('.').nth(1).and_then(|m| m.parse::<u32>().ok()).unwrap_or(0);
        if !v.starts_with("1.") || minor > 11 {
            report.info(format!("FCPXML version {v} is newer than 1.11; unknown elements were ignored"));
        }
    }
    let lib_name = child(root, "library").and_then(|l| child(l, "event")).and_then(|e| e.attribute("name")).unwrap_or("Imported FCPXML");
    let mut imp = Imp {
        b: Builder::new(lib_name),
        opts,
        report,
        formats: HashMap::new(),
        asset_nodes: HashMap::new(),
        assets: HashMap::new(),
        media_nodes: HashMap::new(),
        media_items: HashMap::new(),
        media_active: HashSet::new(),
        depth_hits: 0,
        media_truncated_at: HashMap::new(),
        reimports_left: MAX_REIMPORTS,
        effects: HashMap::new(),
        depth: 0,
    };
    if let Some(res) = child(root, "resources") {
        for r in elements(res) {
            let Some(id) = r.attribute("id") else { continue };
            match r.tag_name().name() {
                "format" => {
                    let rate = match r.attribute("frameDuration") {
                        Some(fd) => rate_from_frame_duration(fd).unwrap_or_else(|| {
                            imp.report.warn(format!("format \"{id}\" has an invalid frameDuration \"{fd}\"; the default frame rate was used"));
                            FrameRate::default()
                        }),
                        None => FrameRate::default(),
                    };
                    let w = r.attribute("width").and_then(|v| v.parse().ok()).unwrap_or(1920);
                    let h = r.attribute("height").and_then(|v| v.parse().ok()).unwrap_or(1080);
                    imp.formats.insert(id.into(), (rate, w, h));
                }
                "asset" => {
                    imp.asset_nodes.insert(id.into(), r);
                }
                "media" => {
                    imp.media_nodes.insert(id.into(), r);
                }
                "effect" => {
                    imp.effects.insert(id.into(), r.attribute("name").unwrap_or("").to_string());
                }
                _ => {}
            }
        }
    }
    let mut events: Vec<Node> = Vec::new();
    if let Some(lib) = child(root, "library") {
        events.extend(children(lib, "event"));
    }
    events.extend(children(root, "event"));
    for ev in events {
        let bin = imp.b.bin(ev.attribute("name").unwrap_or("Event"), None);
        for c in elements(ev) {
            match c.tag_name().name() {
                "project" => {
                    if let Some(s) = child(c, "sequence") {
                        let name = c.attribute("name").unwrap_or("Project");
                        let id = imp.sequence(s, name, Some(bin), None);
                        imp.b.top.push(id);
                    }
                }
                "asset-clip" | "clip" => {
                    if let Some(r) = c.attribute("ref") {
                        imp.asset(r, Some(bin));
                    }
                }
                _ => {}
            }
        }
    }
    for p in children(root, "project") {
        if let Some(s) = child(p, "sequence") {
            let id = imp.sequence(s, p.attribute("name").unwrap_or("Project"), None, None);
            imp.b.top.push(id);
        }
    }
    if imp.b.p.items.is_empty() {
        return Err(Error::Empty);
    }
    Ok(imp.b.finish())
}

fn flag(n: Node, name: &str) -> Option<bool> {
    n.attribute(name).map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
}

impl<'a, 'i> Imp<'a, 'i, '_> {
    fn asset(&mut self, id: &str, bin: Option<BinId>) -> Option<Asset> {
        if let Some(a) = self.assets.get(id) {
            return Some(a.clone());
        }
        let n = *self.asset_nodes.get(id)?;
        let name = n.attribute("name").unwrap_or("Asset").to_string();
        let src = child(n, "media-rep").and_then(|m| m.attribute("src")).or_else(|| n.attribute("src"));
        let fmt = n.attribute("format").and_then(|f| self.formats.get(f)).copied();
        let mut has_video = flag(n, "hasVideo").unwrap_or(false);
        let has_audio = flag(n, "hasAudio").unwrap_or(false);
        if !has_video && !has_audio {
            has_video = kind_from_ext(src.unwrap_or(&name)) != MediaKind::AudioOnly;
        }
        let start = attr_time(n, "start").unwrap_or(Tick::ZERO);
        let rate = fmt.map(|f| f.0).unwrap_or_default();
        let spec = MediaSpec {
            duration: attr_time(n, "duration"),
            video: has_video.then(|| fmt.map(|(r, w, h)| (w, h, r)).unwrap_or((1920, 1080, rate))),
            audio: has_audio.then(|| {
                (n.attribute("audioRate").and_then(parse_audio_rate).unwrap_or(48_000), n.attribute("audioChannels").and_then(|c| c.parse().ok()).unwrap_or(2))
            }),
            start_tc: (start != Tick::ZERO).then(|| rate.frame_at(start)),
            kind: None,
        };
        let item = match src {
            Some(url) => {
                let p = resolve_url(url, self.opts.base_dir.as_deref());
                self.b.file_media(&format!("file:{p}"), &name, &p, &spec, bin)
            }
            None => {
                self.report.warn(format!("asset \"{name}\" has no media; imported offline"));
                let p = resolve_path(&name, self.opts.base_dir.as_deref());
                let it = self.b.file_media(&format!("asset:{id}"), &name, &p, &spec, bin);
                if let Some(m) = self.b.p.item_mut(it).and_then(|i| i.as_media_mut()) {
                    m.offline = true;
                }
                it
            }
        };
        let a = Asset { item, start, has_video, has_audio };
        self.assets.insert(id.into(), a.clone());
        Some(a)
    }

    /// Nested sequence from a `<media>` resource.
    fn media(&mut self, id: &str) -> Option<ItemId> {
        let depth = self.media_active.len();
        let mut again = None;
        if let Some(i) = self.media_items.get(id) {
            // Imported with a nested one cut off: import it again (into the same item) where that
            // one now fits.
            let shallower =
                self.media_truncated_at.get(id).is_some_and(|&(media, xml)| depth <= media && self.depth <= xml && (depth < media || self.depth < xml))
                    && !self.media_active.contains(id);
            if !shallower || self.reimports_left == 0 {
                return Some(*i);
            }
            self.reimports_left -= 1;
            again = Some(*i);
        }
        let n = *self.media_nodes.get(id)?;
        let s = child(n, "sequence")?;
        // The active set is the current nesting chain: a long acyclic chain of compound clips
        // would otherwise recurse once per resource.
        if depth >= crate::MAX_NESTING_DEPTH {
            self.depth_hits += 1;
            self.report.warn(format!("FCPXML media resource {id:?} is nested too deeply; imported as a gap"));
            return None;
        }
        if !self.media_active.insert(id.into()) {
            self.report.warn(format!("recursive FCPXML media resource {id:?} ignored"));
            return None;
        }
        // Mark the resource before descending: a compound clip can reference itself through a
        // ref-clip before a completed sequence is available to cache.
        let name = n.attribute("name").unwrap_or("Compound Clip").to_string();
        let hits_before = self.depth_hits;
        let item = self.sequence(s, &name, None, again);
        self.media_active.remove(id);
        self.media_items.insert(id.into(), item);
        if self.depth_hits > hits_before {
            self.media_truncated_at.insert(id.into(), (depth, self.depth));
        } else {
            self.media_truncated_at.remove(id);
        }
        Some(item)
    }

    fn sequence(&mut self, s: Node<'a, 'i>, name: &str, bin: Option<BinId>, reuse: Option<ItemId>) -> ItemId {
        let (rate, w, h) = s.attribute("format").and_then(|f| self.formats.get(f)).copied().unwrap_or((FrameRate::default(), 1920, 1080));
        let df = s.attribute("tcFormat") == Some("DF");
        let mut settings = settings_for(rate, w, h, df);
        if let Some(sr) = s.attribute("audioRate").and_then(parse_audio_rate) {
            settings.sample_rate = sr;
        }
        let id = reuse.unwrap_or_else(|| self.b.reserve_sequence(name, settings.clone(), bin));
        let mut seq = empty_sequence(settings);
        let tc_start = attr_time(s, "tcStart").unwrap_or(Tick::ZERO);
        seq.start_timecode = rate.frame_at(tc_start);
        let ctx = Ctx { seq_rate: rate, frame: (w, h) };
        self.b.ensure_tracks(&mut seq, TrackKind::Video, 1);
        self.b.ensure_tracks(&mut seq, TrackKind::Audio, 1);
        if let Some(spine) = child(s, "spine") {
            // Sequence time origin is tcStart.
            self.storyline(&mut seq, &ctx, spine, -tc_start, 0, true);
        }
        seq.markers.sort_by_key(|m| m.start);
        self.b.put_sequence(id, seq);
        id
    }

    /// Lay out a storyline, refusing nesting past [`MAX_XML_DEPTH`].
    fn storyline(&mut self, seq: &mut Sequence, ctx: &Ctx, spine: Node<'a, 'i>, origin: Tick, lane: i32, primary: bool) {
        if self.depth >= MAX_XML_DEPTH {
            self.depth_hits += 1;
            self.report.warn(format!("XML storylines are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped"));
            return;
        }
        self.depth += 1;
        self.storyline_inner(seq, ctx, spine, origin, lane, primary);
        self.depth -= 1;
    }

    /// Lay out a storyline. `origin` maps the storyline's offsets to timeline time
    /// (`timeline = origin + offset`). `lane` is the storyline's lane (0 = primary).
    fn storyline_inner(&mut self, seq: &mut Sequence, ctx: &Ctx, spine: Node<'a, 'i>, origin: Tick, lane: i32, primary: bool) {
        // (timeline start, timeline end, video clip on this storyline's track)
        let mut laid: Vec<(Tick, Tick, Option<filmcraft_project::ClipId>)> = Vec::new();
        let mut transitions: Vec<(usize, Node)> = Vec::new();
        for el in elements(spine) {
            let tag = el.tag_name().name();
            if tag == "transition" {
                transitions.push((laid.len(), el));
                continue;
            }
            let offset = attr_time(el, "offset").unwrap_or(Tick::ZERO);
            let t0 = origin + offset;
            let (end, clip) = self.element(seq, ctx, el, t0, lane, primary);
            laid.push((t0, end, clip));
        }
        let vidx = if lane >= 0 { lane as usize } else { usize::MAX };
        for (pos, el) in transitions {
            if vidx == usize::MAX {
                self.report.warn("transitions on audio storylines are not supported");
                continue;
            }
            let start = origin + attr_time(el, "offset").unwrap_or(Tick::ZERO);
            let dur = attr_time(el, "duration").unwrap_or(Tick::ZERO);
            if dur <= Tick::ZERO {
                continue;
            }
            let name = child(el, "filter-video")
                .and_then(|f| f.attribute("ref").and_then(|r| self.effects.get(r).cloned()).or_else(|| f.attribute("name").map(str::to_string)))
                .filter(|n| !n.is_empty())
                .or_else(|| el.attribute("name").map(str::to_string))
                .unwrap_or_else(|| "Cross Dissolve".into());
            let prev = pos.checked_sub(1).and_then(|i| laid.get(i)).copied();
            let next = laid.get(pos).copied();
            let from = prev.and_then(|p| p.2.map(|c| (c, p.1)));
            let to = next.and_then(|n| n.2.map(|c| (c, n.0)));
            if from.is_none() && to.is_none() {
                continue;
            }
            let cut = to.map(|t| t.1).or(from.map(|f| f.1)).unwrap_or(start);
            let align = if cut == start {
                TransitionAlign::StartAtCut
            } else if cut == start + dur {
                TransitionAlign::EndAtCut
            } else {
                TransitionAlign::CenterAtCut
            };
            let effect = transition_effect(&name, false, self.report);
            let id = TransitionId(self.b.alloc());
            // The clips may have been moved to another track by placement; find the track holding them.
            let clip = from.or(to).map(|c| c.0);
            if let Some(t) = seq.video_tracks.iter_mut().find(|t| clip.is_some_and(|c| t.item(c).is_some())) {
                t.transitions.push(Transition { id, effect, start, duration: dur, from: from.map(|f| f.0), to: to.map(|t| t.0), align, reverse: false });
                t.sort();
            }
        }
    }

    /// Lay out one element, refusing nesting past [`MAX_XML_DEPTH`].
    fn element(&mut self, seq: &mut Sequence, ctx: &Ctx, el: Node<'a, 'i>, t0: Tick, lane: i32, primary: bool) -> (Tick, Option<filmcraft_project::ClipId>) {
        if self.depth >= MAX_XML_DEPTH {
            self.depth_hits += 1;
            self.report.warn(format!("XML elements are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped"));
            return (t0, None);
        }
        self.depth += 1;
        let out = self.element_inner(seq, ctx, el, t0, lane, primary);
        self.depth -= 1;
        out
    }

    /// Lay out one storyline element at timeline time `t0`. Returns (timeline end, video clip).
    fn element_inner(
        &mut self,
        seq: &mut Sequence,
        ctx: &Ctx,
        el: Node<'a, 'i>,
        t0: Tick,
        lane: i32,
        primary: bool,
    ) -> (Tick, Option<filmcraft_project::ClipId>) {
        let tag = el.tag_name().name();
        let dur = attr_time(el, "duration").unwrap_or(Tick::ZERO);
        let local_start = attr_time(el, "start").unwrap_or(Tick::ZERO);
        let mut vclip = None;
        let mut placed: Vec<(TrackKind, filmcraft_project::ClipId)> = Vec::new();
        let name = el.attribute("name").unwrap_or("Clip").to_string();
        // Media and source in.
        let media: Option<(ItemId, Tick, bool, bool)> = match tag {
            "asset-clip" => el.attribute("ref").and_then(|r| self.asset(r, None)).map(|a| (a.item, a.start, a.has_video, a.has_audio)),
            "video" => {
                // FCPXML 1.10 DTD: video selects an asset's picture, or references a generator.
                // Our media model does not select additional video sources within an asset.
                let asset = el
                    .attribute("srcID")
                    .is_none_or(|id| id == "1")
                    .then(|| el.attribute("ref").and_then(|r| self.asset(r, None)))
                    .flatten()
                    .filter(|a| a.has_video);
                if asset.is_none() {
                    self.report.warn(format!("FCPXML <video> \"{name}\" has no supported video asset/source; clip was skipped"));
                }
                asset.map(|a| (a.item, a.start, true, false))
            }
            "clip" => {
                // A clip wraps video/audio/asset-clip children that reference the asset.
                let inner = elements(el).find(|c| matches!(c.tag_name().name(), "video" | "audio" | "asset-clip") && c.attribute("ref").is_some());
                inner.and_then(|c| {
                    let a = self.asset(c.attribute("ref").unwrap_or(""), None)?;
                    // inner local time = inner.start + (t - inner.offset)
                    let shift = attr_time(c, "start").unwrap_or(Tick::ZERO) - attr_time(c, "offset").unwrap_or(Tick::ZERO);
                    let v = a.has_video && c.tag_name().name() != "audio";
                    let au = a.has_audio && (c.tag_name().name() != "video" || elements(el).any(|x| x.has_tag_name("audio")));
                    Some((a.item, a.start - shift, v, au))
                })
            }
            "ref-clip" => el.attribute("ref").and_then(|r| {
                let item = self.media(r)?;
                let tc = self.b.p.sequence(item).map(|s| s.settings.frame_rate.tick_of(s.start_timecode)).unwrap_or(Tick::ZERO);
                Some((item, tc, true, self.b.p.sequence(item).is_some_and(|s| s.audio_tracks.iter().any(|t| !t.items.is_empty()))))
            }),
            "gap" => None,
            "title" | "audio" | "sync-clip" | "mc-clip" | "live-drawing" => {
                self.report.warn(format!("FCPXML <{tag}> elements are not supported and were skipped"));
                None
            }
            _ => None,
        };
        let (speed, reverse, hold, src_base) = time_map(el, local_start);
        if let Some((item, origin, has_v, has_a)) = media
            && dur > Tick::ZERO
        {
            let src_in = src_base - origin;
            let src_enable = el.attribute("srcEnable").unwrap_or("all");
            let want_v = has_v && src_enable != "audio" && lane >= 0;
            let want_a = has_a && src_enable != "video";
            let link = if want_v && want_a { Some(self.b.link_id()) } else { None };
            for (kind, want) in [(TrackKind::Video, want_v), (TrackKind::Audio, want_a)] {
                if !want {
                    continue;
                }
                let mut ti = self.b.clip(item, kind, &name, t0, dur, src_in.max(Tick::ZERO));
                ti.speed = speed;
                ti.reverse = reverse;
                if hold {
                    ti.frame_hold = Some(src_in.max(Tick::ZERO));
                }
                ti.link = link;
                ti.enabled = flag(el, "enabled").unwrap_or(true);
                if let Some(l) = el.attribute("label").and_then(Label::from_name) {
                    ti.label = l;
                }
                self.adjustments(&mut ti, el, LocalTiming { local_start, src_in, speed }, ctx, kind);
                if !primary || kind == TrackKind::Audio {
                    ti.markers = self.markers(el, local_start, src_in, speed, ctx.seq_rate);
                }
                let pref = match kind {
                    TrackKind::Video => lane.max(0) as usize,
                    TrackKind::Audio => {
                        if lane < 0 {
                            lane.unsigned_abs() as usize - 1
                        } else {
                            lane as usize
                        }
                    }
                };
                let id = ti.id;
                if self.b.place(seq, kind, pref, ti).is_none() {
                    self.report.warn(format!("FCPXML {kind:?} lane exceeds the {MAX_IMPORTED_TRACKS}-track import limit; clip was skipped"));
                    continue;
                }
                placed.push((kind, id));
                if kind == TrackKind::Video {
                    vclip = Some(id);
                }
            }
        }
        if primary {
            // Markers on primary storyline elements are timeline markers.
            for m in self.markers(el, local_start, Tick::ZERO, 1.0, ctx.seq_rate) {
                seq.markers.push(Marker { start: t0 + m.start, ..m });
            }
        }
        // Connected clips and secondary storylines.
        for c in elements(el) {
            let Some(lane_attr) = c.attribute("lane") else { continue };
            let Ok(l) = lane_attr.trim().parse::<i32>() else {
                self.report.warn(format!("<{}> has lane \"{lane_attr}\", which is not a lane a sequence can have; skipped", c.tag_name().name()));
                continue;
            };
            let off = attr_time(c, "offset").unwrap_or(Tick::ZERO);
            let ct0 = t0 + (off - local_start);
            let clane = if lane > 0 && l > 0 { lane.saturating_add(l) } else { l };
            if c.has_tag_name("spine") {
                // Secondary storyline: children offsets are in the storyline's local time.
                let first = elements(c).filter(|x| !x.has_tag_name("transition")).find_map(|x| attr_time(x, "offset")).unwrap_or(Tick::ZERO);
                self.storyline(seq, ctx, c, ct0 - first, clane, false);
            } else {
                self.element(seq, ctx, c, ct0, clane, false);
            }
        }
        let _ = placed;
        (t0 + dur, vclip)
    }

    fn markers(&mut self, el: Node, local_start: Tick, src_in: Tick, speed: f64, rate: FrameRate) -> Vec<Marker> {
        let mut out = Vec::new();
        // FCPXML has no zero-duration marker: a point is written as one frame at the sequence rate.
        let frame = rate.frame_duration();
        for m in elements(el).filter(|m| matches!(m.tag_name().name(), "marker" | "chapter-marker")) {
            let rel = attr_time(m, "start").unwrap_or(Tick::ZERO) - local_start;
            let start = if src_in == Tick::ZERO && speed == 1.0 { rel } else { src_in + scaled(rel, speed) };
            let d = attr_time(m, "duration").unwrap_or(Tick::ZERO);
            out.push(Marker {
                url: String::new(),
                author: String::new(),
                custom_color: None,
                id: MarkerId(self.b.alloc()),
                start,
                duration: if d <= frame { Tick::ZERO } else { d },
                name: m.attribute("value").unwrap_or("").to_string(),
                comment: m.attribute("note").unwrap_or("").to_string(),
                kind: if m.has_tag_name("chapter-marker") { MarkerKind::Chapter } else { MarkerKind::Comment },
                color: if m.has_tag_name("chapter-marker") { Label::Mango } else { Label::Blue },
            });
        }
        out
    }

    fn adjustments(&mut self, ti: &mut TrackItem, el: Node, timing: LocalTiming, ctx: &Ctx, kind: TrackKind) {
        let LocalTiming { local_start, src_in, speed } = timing;
        // keyframe time (element-local) -> media time
        let kt = |t: Tick| src_in + scaled(t - local_start, speed);
        let (fw, fh) = (ctx.frame.0 as f64, ctx.frame.1 as f64);
        let _ = ctx.seq_rate;
        // no `adjust-conform` means `fit`: the picture is scaled into the frame before any transform
        let mut conform = true;
        // a `<clip>` wraps the video it plays, which may carry its own conform; the clip's own overrides it
        if kind == TrackKind::Video
            && el.has_tag_name("clip")
            && let Some(inner) = elements(el).find(|c| matches!(c.tag_name().name(), "video" | "asset-clip") && c.attribute("ref").is_some())
            && let Some(a) = elements(inner).find(|a| a.has_tag_name("adjust-conform"))
        {
            let ty = a.attribute("type").unwrap_or("fit");
            conform = ty != "none";
            // the clip's own adjust-conform overrides this and reports for itself
            if ty == "fill" && !elements(el).any(|c| c.has_tag_name("adjust-conform")) {
                self.report.warn("adjust-conform \"fill\" is not supported; the clip was fitted to the frame instead");
            }
        }
        for a in elements(el) {
            match (a.tag_name().name(), kind) {
                ("adjust-conform", TrackKind::Video) => match a.attribute("type").unwrap_or("fit") {
                    "none" => conform = false,
                    "fill" => {
                        conform = true;
                        self.report.warn("adjust-conform \"fill\" is not supported; the clip was fitted to the frame instead");
                    }
                    _ => conform = true,
                },
                ("adjust-transform", TrackKind::Video) => {
                    let to_px = move |v: &str| {
                        let (x, y) = pair(v);
                        Vec2::new(fw / 2.0 + x * fh / 100.0, fh / 2.0 - y * fh / 100.0)
                    };
                    if let Some(p) = self.kparam(a, "position", &kt, |v| ParamValue::Vec2(to_px(v)))
                        && (p.is_animated() || p.value.as_vec2().is_some_and(|v| (v.x - fw / 2.0).abs() > 1e-9 || (v.y - fh / 2.0).abs() > 1e-9))
                    {
                        set_param(ti, "motion", "position", p);
                    }
                    let mut nonuniform = false;
                    if let Some(p) = self.kparam(a, "scale", &kt, |v| {
                        let (x, y) = pair(v);
                        nonuniform |= (x - y).abs() > 1e-9;
                        ParamValue::Float(x * 100.0)
                    }) {
                        set_param(ti, "motion", "scale", p);
                    }
                    if nonuniform {
                        self.report.warn("non-uniform scale was imported as uniform scale");
                    }
                    if let Some(p) = self.kparam(a, "rotation", &kt, |v| ParamValue::Float(-v.trim().parse::<f64>().unwrap_or(0.0))) {
                        set_param(ti, "motion", "rotation", p);
                    }
                    if let Some(p) = self.kparam(a, "anchor", &kt, |v| ParamValue::Vec2(to_px(v)))
                        && p.value.as_vec2().is_some_and(|v| (v.x - fw / 2.0).abs() > 1e-9 || (v.y - fh / 2.0).abs() > 1e-9)
                    {
                        set_param(ti, "motion", "anchor", p);
                    }
                }
                ("adjust-blend", TrackKind::Video) => {
                    if let Some(p) = self.kparam(a, "amount", &kt, |v| ParamValue::Float(v.trim().parse::<f64>().unwrap_or(1.0) * 100.0)) {
                        set_param(ti, "opacity", "opacity", p);
                    }
                }
                ("adjust-volume", TrackKind::Audio) => {
                    if let Some(p) = self.kparam(a, "amount", &kt, |v| ParamValue::Float(parse_db(v))) {
                        set_param(ti, "volume", "level", p);
                    }
                }
                ("filter-video", TrackKind::Video) | ("filter-audio", TrackKind::Audio) => {
                    let name =
                        a.attribute("ref").and_then(|r| self.effects.get(r).cloned()).or_else(|| a.attribute("name").map(str::to_string)).unwrap_or_default();
                    match find_effect_by_name(&name).filter(|d| !d.intrinsic) {
                        Some(d) => {
                            let mut inst = d.instance();
                            inst.enabled = flag(a, "enabled").unwrap_or(true);
                            for p in children(a, "param") {
                                let (Some(k), Some(v)) = (p.attribute("key").or(p.attribute("name")), p.attribute("value")) else { continue };
                                if let (Some(pd), Ok(f)) = (d.params.iter().find(|x| x.id == k || x.label.eq_ignore_ascii_case(k)), v.parse::<f64>())
                                    && matches!(pd.default, ParamValue::Float(_))
                                {
                                    inst.params.insert(pd.id.to_string(), Param::new(ParamValue::Float(f)));
                                }
                            }
                            ti.effects.push(inst);
                        }
                        None => self.report.warn(format!("effect \"{name}\" is not supported and was skipped")),
                    }
                }
                _ => {}
            }
        }
        if kind == TrackKind::Video {
            ti.scale_to_frame = conform;
        }
    }

    /// A parameter from an adjustment attribute plus optional `<param name><keyframeAnimation>`.
    fn kparam(&mut self, a: Node, name: &str, kt: &dyn Fn(Tick) -> Tick, mut map: impl FnMut(&str) -> ParamValue) -> Option<Param> {
        let attr = a.attribute(name);
        let pnode = children(a, "param").find(|p| p.attribute("name") == Some(name));
        let mut p = Param::new(map(attr.or(pnode.and_then(|p| p.attribute("value")))?));
        if let Some(anim) = pnode.and_then(|p| child(p, "keyframeAnimation")) {
            for k in children(anim, "keyframe") {
                let (Some(t), Some(v)) = (attr_time(k, "time"), k.attribute("value")) else { continue };
                let mut kf = Keyframe::new(kt(t), map(v));
                if k.attribute("interp") == Some("hold") {
                    kf.interp = filmcraft_project::Interpolation::Hold;
                }
                p.keyframes.push(kf);
            }
            p.keyframes.sort_by_key(|k| k.time);
            if let Some(k) = p.keyframes.first() {
                p.value = k.value.clone();
            }
        }
        Some(p)
    }
}

fn pair(v: &str) -> (f64, f64) {
    let mut it = v.split_whitespace().filter_map(|s| s.parse::<f64>().ok());
    let x = it.next().unwrap_or(0.0);
    (x, it.next().unwrap_or(x))
}

fn parse_db(v: &str) -> f64 {
    let s = v.trim();
    let s = s.strip_suffix("dB").or_else(|| s.strip_suffix("db")).unwrap_or(s);
    s.trim().parse().unwrap_or(0.0)
}

/// (speed, reverse, freeze, source time at the element's local start) from a `timeMap`.
fn time_map(el: Node, local_start: Tick) -> (f64, bool, bool, Tick) {
    let Some(tm) = child(el, "timeMap") else { return (1.0, false, false, local_start) };
    let pts: Vec<(Tick, Tick)> = children(tm, "timept").filter_map(|p| Some((attr_time(p, "time")?, attr_time(p, "value")?))).collect();
    if pts.len() < 2 {
        return (1.0, false, false, pts.first().map(|p| p.1).unwrap_or(local_start));
    }
    let (t0, v0) = pts[0];
    let (t1, v1) = pts[pts.len() - 1];
    let dt = (t1 - t0).0 as f64;
    let dv = (v1 - v0).0 as f64;
    let at_start = |s: f64| v0 + Tick(((local_start - t0).0 as f64 * s).round() as i64);
    if dv == 0.0 {
        return (1.0, false, true, v0);
    }
    let s = (dv / dt * 1_000_000.0).round() / 1_000_000.0;
    if s < 0.0 {
        // Reverse: source runs from v0 down; our source_in is the lowest source time used.
        let speed = -s;
        let hi = at_start(s);
        let len = (t1 - local_start).max(Tick::ZERO);
        return (speed, true, false, hi - scaled(len, speed));
    }
    (s, false, false, at_start(s))
}

// ---------------------------------------------------------------------------------------------
// Export
// ---------------------------------------------------------------------------------------------

struct Res {
    id: String,
}

struct Exp<'a, 'r> {
    p: &'a Project,
    report: &'r mut Report,
    formats: Vec<(String, FrameRate, u32, u32)>,
    assets: HashMap<ItemId, Res>,
    medias: HashMap<ItemId, Res>,
    effects: HashMap<String, Res>,
    next: usize,
    /// Resource XML fragments, written before the library.
    res_out: Vec<String>,
    building: Vec<ItemId>,
}

pub(crate) fn export(p: &Project, seq_id: ItemId, opts: &ExportOptions, report: &mut Report) -> Result<String> {
    crate::warn_marker_metadata_loss(p, seq_id, report);
    let seq = p.sequence(seq_id).ok_or(Error::NoSequence(seq_id))?;
    let mut x = Exp {
        p,
        report,
        formats: Vec::new(),
        assets: HashMap::new(),
        medias: HashMap::new(),
        effects: HashMap::new(),
        next: 1,
        res_out: Vec::new(),
        building: Vec::new(),
    };
    let fmt = x.format(seq.settings.frame_rate, seq.settings.width, seq.settings.height);
    let name = opts.name.clone().unwrap_or_else(|| p.item(seq_id).map(|i| i.name.clone()).unwrap_or_default());
    let body = x.sequence_xml(seq_id, &fmt, 4);
    let mut out =
        format!("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE fcpxml>\n<fcpxml version=\"{}\">\n  <resources>\n", opts.fcpxml_version.as_str());
    for r in &x.res_out {
        out.push_str(r);
    }
    out.push_str("  </resources>\n");
    out.push_str(&format!("  <library>\n    <event name=\"{}\">\n", crate::xml::escape_attr(&p.name)));
    out.push_str(&format!("      <project name=\"{}\">\n", crate::xml::escape_attr(&name)));
    out.push_str(&body);
    out.push_str("      </project>\n    </event>\n  </library>\n</fcpxml>\n");
    Ok(out)
}

/// One storyline element being written.
struct El {
    start: Tick,
    end: Tick,
    /// Local time of the element at its start.
    local: Tick,
    xml_open: String,
    children: Vec<String>,
    close: String,
}

impl Exp<'_, '_> {
    fn rid(&mut self) -> String {
        let r = format!("r{}", self.next);
        self.next += 1;
        r
    }

    fn format(&mut self, rate: FrameRate, w: u32, h: u32) -> String {
        if let Some(f) = self.formats.iter().find(|f| f.1 == rate && f.2 == w && f.3 == h) {
            return f.0.clone();
        }
        let id = self.rid();
        self.res_out.push(format!(
            "    <format id=\"{id}\" name=\"FFVideoFormat{h}p{}\" frameDuration=\"{}/{}s\" width=\"{w}\" height=\"{h}\"/>\n",
            rate.label().replace('.', ""),
            rate.den,
            rate.num
        ));
        self.formats.push((id.clone(), rate, w, h));
        id
    }

    fn asset(&mut self, item: ItemId, rate: FrameRate) -> String {
        if let Some(r) = self.assets.get(&item) {
            return r.id.clone();
        }
        let Some(m) = item_media(self.p, item) else {
            self.report.warn("clip without media skipped");
            return String::new();
        };
        let name = self.p.item(item).map(|i| i.name.clone()).unwrap_or_default();
        let fmt = m.info.video.as_ref().map(|v| self.format(m.interpret.frame_rate.unwrap_or(v.frame_rate), v.width, v.height));
        let id = self.rid();
        let mrate = m.info.video.as_ref().map(|v| v.frame_rate).unwrap_or(rate);
        let start = m.info.start_timecode.map(|f| mrate.tick_of(f)).unwrap_or(Tick::ZERO);
        let mut a = format!(
            "    <asset id=\"{id}\" name=\"{}\" start=\"{}\" duration=\"{}\" hasVideo=\"{}\" hasAudio=\"{}\"",
            crate::xml::escape_attr(&name),
            fmt_time(start, mrate),
            fmt_time(m.info.duration, mrate),
            m.info.video.is_some() as u8,
            m.info.has_audio() as u8
        );
        if let Some(f) = fmt {
            a.push_str(&format!(" format=\"{f}\""));
        }
        if let Some(au) = m.info.audio() {
            a.push_str(&format!(" audioSources=\"1\" audioChannels=\"{}\" audioRate=\"{}\"", au.channels, au.sample_rate));
        }
        let path = item_path(self.p, item).unwrap_or("");
        let src = if crate::common::is_absolute(path) { path_to_file_url(path, false) } else { path.to_string() };
        a.push_str(&format!(">\n      <media-rep kind=\"original-media\" src=\"{}\"/>\n    </asset>\n", crate::xml::escape_attr(&src)));
        self.res_out.push(a);
        self.assets.insert(item, Res { id: id.clone() });
        let _ = file_name;
        id
    }

    fn media(&mut self, item: ItemId) -> String {
        if let Some(r) = self.medias.get(&item) {
            return r.id.clone();
        }
        let Some(s) = self.p.sequence(item) else {
            self.report.warn("missing nested sequence skipped");
            return String::new();
        };
        let fmt = self.format(s.settings.frame_rate, s.settings.width, s.settings.height);
        let id = self.rid();
        self.medias.insert(item, Res { id: id.clone() });
        self.building.push(item);
        let body = self.sequence_xml(item, &fmt, 3);
        self.building.pop();
        let name = self.p.item(item).map(|i| i.name.clone()).unwrap_or_default();
        self.res_out.push(format!("    <media id=\"{id}\" name=\"{}\">\n{body}    </media>\n", crate::xml::escape_attr(&name)));
        id
    }

    fn effect(&mut self, name: &str, id_hint: &str) -> String {
        if let Some(r) = self.effects.get(name) {
            return r.id.clone();
        }
        let id = self.rid();
        self.res_out.push(format!(
            "    <effect id=\"{id}\" name=\"{}\" uid=\"filmcraft.{}\"/>\n",
            crate::xml::escape_attr(name),
            crate::xml::escape_attr(id_hint)
        ));
        self.effects.insert(name.to_string(), Res { id: id.clone() });
        id
    }

    fn sequence_xml(&mut self, seq_id: ItemId, fmt: &str, indent: usize) -> String {
        let Some(seq) = self.p.sequence(seq_id) else { return String::new() };
        let rate = seq.settings.frame_rate;
        let df = seq.settings.drop_frame && rate.supports_drop_frame();
        let tc0 = rate.tick_of(seq.start_timecode);
        let pad = "  ".repeat(indent);
        let mut o = format!(
            "{pad}<sequence format=\"{fmt}\" duration=\"{}\" tcStart=\"{}\" tcFormat=\"{}\" audioLayout=\"stereo\" audioRate=\"{}\">\n{pad}  <spine>\n",
            fmt_time(seq.duration(), rate),
            fmt_time(tc0, rate),
            if df { "DF" } else { "NDF" },
            audio_rate_str(seq.settings.sample_rate)
        );
        // Which audio items merge into video clips (same index track, linked, identical timing).
        let mut merged: HashMap<filmcraft_project::ClipId, filmcraft_project::ClipId> = HashMap::new();
        for (vi, vt) in seq.video_tracks.iter().enumerate() {
            let Some(at) = seq.audio_tracks.get(vi) else { continue };
            for v in &vt.items {
                if let Some(a) = at.items.iter().find(|a| {
                    a.link.is_some()
                        && a.link == v.link
                        && a.item == v.item
                        && a.start == v.start
                        && a.duration == v.duration
                        && a.source_in == v.source_in
                        && a.speed == v.speed
                        && a.reverse == v.reverse
                        && a.frame_hold == v.frame_hold
                        && a.enabled == v.enabled
                }) {
                    merged.insert(v.id, a.id);
                }
            }
        }
        let merged_audio: std::collections::HashSet<_> = merged.values().copied().collect();
        if seq.all_tracks().skip(1).any(|t| !t.transitions.is_empty()) {
            self.report.warn("FCPXML export keeps transitions on V1 only; transitions on other tracks were dropped");
        }
        // Primary storyline from V1 (gaps fill holes, plus a trailing gap covering connected clips).
        let v1 = seq.video_tracks.first();
        let mut els: Vec<El> = Vec::new();
        let mut trans_after: Vec<(usize, String)> = Vec::new();
        let mut t = Tick::ZERO;
        let push_gap = |els: &mut Vec<El>, a: Tick, b: Tick| {
            els.push(El {
                start: a,
                end: b,
                local: tc0 + a,
                xml_open: format!(
                    "<gap name=\"Gap\" offset=\"{}\" start=\"{}\" duration=\"{}\"",
                    fmt_time(tc0 + a, rate),
                    fmt_time(tc0 + a, rate),
                    fmt_time(b - a, rate)
                ),
                children: vec![],
                close: "gap".into(),
            })
        };
        if let Some(v1) = v1 {
            for it in &v1.items {
                if it.start > t {
                    push_gap(&mut els, t, it.start);
                }
                for tr in v1.transitions.iter().filter(|tr| tr.to == Some(it.id)) {
                    trans_after.push((els.len(), self.transition_xml(tr, tc0, rate)));
                }
                let audio = merged.get(&it.id).and_then(|a| seq.audio_tracks[0].item(*a));
                let el = self.clip_el(it, audio, TrackKind::Video, ClipPlacement { offset: tc0 + it.start, lane: None, primary: true }, seq);
                els.push(el);
                for tr in v1.transitions.iter().filter(|tr| tr.from == Some(it.id) && tr.to.is_none()) {
                    trans_after.push((els.len(), self.transition_xml(tr, tc0, rate)));
                }
                t = it.end();
            }
        }
        let last_start = seq.all_tracks().skip(1).flat_map(|tr| tr.items.iter().map(|i| i.start)).chain(seq.markers.iter().map(|m| m.start)).max();
        if let Some(ls) = last_start
            && ls >= t
        {
            let end = seq.duration().max(ls + rate.frame_duration());
            push_gap(&mut els, t, end);
        }
        // Connected clips.
        for (kind, tracks) in [(TrackKind::Video, &seq.video_tracks), (TrackKind::Audio, &seq.audio_tracks)] {
            for (ti, track) in tracks.iter().enumerate() {
                if kind == TrackKind::Video && ti == 0 {
                    continue;
                }
                let lane = if kind == TrackKind::Video { ti as i32 } else { -(ti as i32 + 1) };
                for it in &track.items {
                    if merged_audio.contains(&it.id) {
                        continue;
                    }
                    if let Some(what) = self.unsupported(it, rate) {
                        self.report.warn(format!("{what}: it is left out and is not read back on import"));
                        continue;
                    }
                    let Some(pi) = els.iter().position(|e| e.start <= it.start && it.start < e.end) else {
                        self.report.warn("a connected clip could not be attached and was dropped");
                        continue;
                    };
                    let local = els[pi].local + (it.start - els[pi].start);
                    let audio =
                        if kind == TrackKind::Video { merged.get(&it.id).and_then(|a| seq.audio_tracks.get(ti).and_then(|t| t.item(*a))) } else { None };
                    let el = self.clip_el(it, audio, kind, ClipPlacement { offset: local, lane: Some(lane), primary: false }, seq);
                    let s = self.render_el(&el, 0);
                    els[pi].children.push(s);
                }
            }
        }
        // Sequence markers on the covering primary element.
        for m in &seq.markers {
            match els.iter().position(|e| e.start <= m.start && m.start < e.end) {
                Some(pi) => {
                    let local = els[pi].local + (m.start - els[pi].start);
                    let s = marker_xml(m, local, rate);
                    els[pi].children.push(s);
                }
                None => self.report.warn("a sequence marker past the end of the timeline was dropped"),
            }
        }
        let inner = format!("{pad}    ");
        let mut ti = 0;
        for (i, e) in els.iter().enumerate() {
            while ti < trans_after.len() && trans_after[ti].0 == i {
                o.push_str(&format!("{inner}{}\n", trans_after[ti].1));
                ti += 1;
            }
            o.push_str(&self.render_el(e, indent + 2));
        }
        while ti < trans_after.len() {
            o.push_str(&format!("{inner}{}\n", trans_after[ti].1));
            ti += 1;
        }
        o.push_str(&format!("{pad}  </spine>\n{pad}</sequence>\n"));
        o
    }

    fn render_el(&self, e: &El, indent: usize) -> String {
        let pad = "  ".repeat(indent);
        if e.children.is_empty() {
            return format!("{pad}{}/>\n", e.xml_open);
        }
        let mut s = format!("{pad}{}>\n", e.xml_open);
        for c in &e.children {
            for line in c.lines() {
                s.push_str(&format!("{pad}  {line}\n"));
            }
        }
        s.push_str(&format!("{pad}</{}>\n", e.close));
        s
    }

    fn transition_xml(&mut self, tr: &Transition, tc0: Tick, rate: FrameRate) -> String {
        let name = transition_name(&tr.effect);
        let r = self.effect(&name, &tr.effect.effect);
        format!(
            "<transition name=\"{n}\" offset=\"{}\" duration=\"{}\"><filter-video ref=\"{r}\" name=\"{n}\"/></transition>",
            fmt_time(tc0 + tr.start, rate),
            fmt_time(tr.duration, rate),
            n = crate::xml::escape_attr(&name)
        )
    }

    /// How the report names a clip FCPXML cannot carry (a generator, a title, an adjustment layer); `None` for any
    /// other clip. Such a clip has no asset to reference, and an empty `ref` is not a valid IDREF: Final Cut Pro
    /// rejects the whole file. A `<gap>` exists only in a spine, so a connected one is left out instead.
    fn unsupported(&self, it: &TrackItem, rate: FrameRate) -> Option<String> {
        if let Some(g) = generator_of(self.p, base_item(self.p, it.item)) {
            return Some(format!("generator \"{}\" is not supported in FCPXML", g.label()));
        }
        crate::common::uncarried_clip(self.p, it, rate).map(|clip| format!("{clip} is not supported in FCPXML"))
    }

    /// A clip element at `offset` (in its parent's local time).
    fn clip_el(&mut self, it: &TrackItem, audio: Option<&TrackItem>, kind: TrackKind, at: ClipPlacement, seq: &Sequence) -> El {
        let ClipPlacement { offset, lane, primary } = at;
        let rate = seq.settings.frame_rate;
        let base = base_item(self.p, it.item);
        let is_seq = matches!(self.p.item(base).map(|i| &i.kind), Some(ItemKind::Sequence(_)));
        let lane_attr = lane.map(|l| format!(" lane=\"{l}\"")).unwrap_or_default();
        let name = crate::xml::escape_attr(&it.name);
        // In the primary storyline, a clip FCPXML cannot carry becomes a gap that keeps the timing
        // (connected ones never get here: see `unsupported`).
        if let Some(what) = self.unsupported(it, rate) {
            self.report.warn(format!("{what}: it is written as a gap and is not read back on import"));
            return gap_el(it, &name, offset, rate);
        }
        // Local timeline of the element: origin + source time (retimed clips use a timeMap).
        let (tag, r, origin) = if is_seq {
            let r = if self.building.contains(&base) {
                self.report.warn("recursive nested sequence");
                String::new()
            } else {
                self.media(base)
            };
            let origin = self.p.sequence(base).map(|s| s.settings.frame_rate.tick_of(s.start_timecode)).unwrap_or(Tick::ZERO);
            ("ref-clip", r, origin)
        } else {
            let r = self.asset(base, rate);
            let m = item_media(self.p, base);
            let mrate = m.and_then(|m| m.info.video.as_ref().map(|v| v.frame_rate)).unwrap_or(rate);
            let st = m.and_then(|m| m.info.start_timecode).map(|f| mrate.tick_of(f)).unwrap_or(Tick::ZERO);
            ("asset-clip", r, st)
        };
        let retimed = it.speed != 1.0 || it.reverse || it.frame_hold.is_some();
        let local = origin + it.source_in;
        let has_audio = item_media(self.p, base).is_some_and(|m| m.info.has_audio()) || (is_seq && audio.is_some());
        let has_video = item_media(self.p, base).is_none_or(|m| m.info.video.is_some());
        let src_enable = match (kind, audio.is_some()) {
            (TrackKind::Video, true) => "",
            (TrackKind::Video, false) if has_audio => " srcEnable=\"video\"",
            (TrackKind::Audio, _) if has_video => " srcEnable=\"audio\"",
            _ => "",
        };
        let enabled = if it.enabled { "" } else { " enabled=\"0\"" };
        let mut children = Vec::new();
        if retimed {
            let v0 = origin + it.frame_hold.unwrap_or(it.source_in);
            let (a, b) = if let Some(h) = it.frame_hold {
                (origin + h, origin + h)
            } else if it.reverse {
                (v0 + scaled(it.duration, it.speed), v0)
            } else {
                (v0, v0 + scaled(it.duration, it.speed))
            };
            children.push(format!(
                "<timeMap>\n  <timept time=\"{}\" value=\"{}\" interp=\"linear\"/>\n  <timept time=\"{}\" value=\"{}\" interp=\"linear\"/>\n</timeMap>",
                fmt_time(local, rate),
                fmt_time(a, rate),
                fmt_time(local + it.duration, rate),
                fmt_time(b, rate)
            ));
        }
        // keyframe media time -> element local time
        let to_local = |t: Tick| -> Tick {
            if it.speed == 0.0 || it.frame_hold.is_some() { local } else { local + Tick(((t - it.source_in).0 as f64 / it.speed).round() as i64) }
        };
        if kind == TrackKind::Video {
            // a clip without scale-to-frame keeps its native pixels; an absent element would mean `fit`
            if !it.scale_to_frame {
                children.push("<adjust-conform type=\"none\"/>".into());
            }
            self.transform(it, seq, &to_local, &mut children);
        }
        if let Some(a) = audio.or((kind == TrackKind::Audio).then_some(it)) {
            if param_modified(a, "volume", "level") || a.gain_db != 0.0 {
                let g = a.gain_db;
                children.push(kparam_xml(
                    "adjust-volume",
                    "amount",
                    param(a, "volume", "level"),
                    rate,
                    &to_local,
                    |v| format!("{}dB", num(v.as_f64().unwrap_or(0.0) + g)),
                    "0dB",
                ));
            }
            if param_modified(a, "panner", "balance") || param_modified(a, "channel_volume", "left") || param_modified(a, "channel_volume", "right") {
                self.report.warn("pan and channel volume are not exported to FCPXML");
            }
        }
        for e in standard_effects(it) {
            let n = e.def().map(|d| filmcraft_project::interchange_name(d).to_string()).unwrap_or_else(|| e.effect.clone());
            let r = self.effect(&n, &e.effect);
            let tag = if kind == TrackKind::Video { "filter-video" } else { "filter-audio" };
            let mut s = format!("<{tag} ref=\"{r}\" name=\"{}\"", crate::xml::escape_attr(&n));
            if !e.enabled {
                s.push_str(" enabled=\"0\"");
            }
            let floats: Vec<_> =
                e.params.iter().filter_map(|(k, p)| p.value.as_f64().filter(|_| matches!(p.value, ParamValue::Float(_))).map(|v| (k, v))).collect();
            if floats.is_empty() {
                s.push_str("/>");
            } else {
                s.push_str(">\n");
                for (k, v) in floats {
                    s.push_str(&format!("  <param name=\"{k}\" key=\"{k}\" value=\"{}\"/>\n", num(v)));
                }
                s.push_str(&format!("</{tag}>"));
            }
            self.report.info(format!("effect \"{n}\" written as an FCPXML filter reference (FilmCraft-specific)"));
            children.push(s);
        }
        if !primary || kind == TrackKind::Audio {
            for m in &it.markers {
                children.push(marker_xml(m, to_local(m.start), rate));
            }
        } else if !it.markers.is_empty() {
            self.report.info("clip markers on V1 are written as primary-storyline markers and import as sequence markers");
            for m in &it.markers {
                children.push(marker_xml(m, to_local(m.start), rate));
            }
        }
        El {
            start: it.start,
            end: it.end(),
            local,
            xml_open: format!(
                "<{tag} ref=\"{r}\"{lane_attr} name=\"{name}\" offset=\"{}\" start=\"{}\" duration=\"{}\"{src_enable}{enabled}",
                fmt_time(offset, rate),
                fmt_time(local, rate),
                fmt_time(it.duration, rate)
            ),
            children,
            close: tag.into(),
        }
    }

    fn transform(&mut self, it: &TrackItem, seq: &Sequence, to_local: &dyn Fn(Tick) -> Tick, out: &mut Vec<String>) {
        let rate = seq.settings.frame_rate;
        let (fw, fh) = (seq.settings.width as f64, seq.settings.height as f64);
        let pos = |v: &ParamValue| {
            let p = v.as_vec2().unwrap_or(Vec2::new(f64::NAN, f64::NAN));
            let x = if p.x.is_nan() { 0.0 } else { (p.x - fw / 2.0) / fh * 100.0 };
            let y = if p.y.is_nan() { 0.0 } else { -(p.y - fh / 2.0) / fh * 100.0 };
            format!("{} {}", num(x), num(y))
        };
        let changed = ["position", "scale", "rotation", "anchor"].iter().any(|p| param_modified(it, "motion", p));
        if changed {
            if param_modified(it, "motion", "scale_width") || param(it, "motion", "uniform_scale").and_then(|p| p.value.as_bool()) == Some(false) {
                self.report.warn("non-uniform scale is not exported to FCPXML");
            }
            let mut attrs = Vec::new();
            let mut params = Vec::new();
            for (id, attr, f) in [
                ("position", "position", &pos as &dyn Fn(&ParamValue) -> String),
                ("scale", "scale", &|v: &ParamValue| {
                    let s = v.as_f64().unwrap_or(100.0) / 100.0;
                    format!("{} {}", num(s), num(s))
                }),
                ("rotation", "rotation", &|v: &ParamValue| num(-v.as_f64().unwrap_or(0.0))),
                ("anchor", "anchor", &pos),
            ] {
                let Some(p) = param(it, "motion", id) else { continue };
                if !param_modified(it, "motion", id) {
                    continue;
                }
                attrs.push(format!(" {attr}=\"{}\"", f(&p.value)));
                if p.is_animated() {
                    let mut s = format!("  <param name=\"{attr}\">\n    <keyframeAnimation>\n");
                    for k in &p.keyframes {
                        let interp = if k.interp == filmcraft_project::Interpolation::Hold { " interp=\"hold\"" } else { "" };
                        s.push_str(&format!("      <keyframe time=\"{}\" value=\"{}\"{interp}/>\n", fmt_time(to_local(k.time), rate), f(&k.value)));
                    }
                    s.push_str("    </keyframeAnimation>\n  </param>");
                    params.push(s);
                }
            }
            out.push(wrap("adjust-transform", &attrs.concat(), &params));
        }
        if param_modified(it, "opacity", "opacity") {
            out.push(kparam_xml("adjust-blend", "amount", param(it, "opacity", "opacity"), rate, to_local, |v| num(v.as_f64().unwrap_or(100.0) / 100.0), "1"));
        }
        if param(it, "opacity", "blend").and_then(|p| p.value.as_f64()).is_some_and(|b| b != 0.0) {
            self.report.warn("blend modes are not exported to FCPXML");
        }
        let _ = (db_to_gain(0.0), gain_to_db(1.0));
    }
}

/// A primary-storyline `<gap>` standing in for a clip FCPXML cannot carry; it keeps the clip's place and length.
fn gap_el(it: &TrackItem, name: &str, offset: Tick, rate: FrameRate) -> El {
    El {
        start: it.start,
        end: it.end(),
        local: offset,
        xml_open: format!(
            "<gap name=\"{name}\" offset=\"{}\" start=\"{}\" duration=\"{}\"",
            fmt_time(offset, rate),
            fmt_time(offset, rate),
            fmt_time(it.duration, rate)
        ),
        children: vec![],
        close: "gap".into(),
    }
}

fn wrap(tag: &str, attrs: &str, params: &[String]) -> String {
    if params.is_empty() { format!("<{tag}{attrs}/>") } else { format!("<{tag}{attrs}>\n{}\n</{tag}>", params.join("\n")) }
}

fn kparam_xml(
    tag: &str,
    name: &str,
    p: Option<&Param>,
    rate: FrameRate,
    to_local: &dyn Fn(Tick) -> Tick,
    f: impl Fn(&ParamValue) -> String,
    default: &str,
) -> String {
    let Some(p) = p else { return format!("<{tag} {name}=\"{default}\"/>") };
    let attrs = format!(" {name}=\"{}\"", f(&p.value));
    let mut params = Vec::new();
    if p.is_animated() {
        let mut s = format!("  <param name=\"{name}\">\n    <keyframeAnimation>\n");
        for k in &p.keyframes {
            let interp = if k.interp == filmcraft_project::Interpolation::Hold { " interp=\"hold\"" } else { "" };
            s.push_str(&format!("      <keyframe time=\"{}\" value=\"{}\"{interp}/>\n", fmt_time(to_local(k.time), rate), f(&k.value)));
        }
        s.push_str("    </keyframeAnimation>\n  </param>");
        params.push(s);
    }
    wrap(tag, &attrs, &params)
}

fn marker_xml(m: &Marker, local: Tick, rate: FrameRate) -> String {
    let tag = if m.kind == MarkerKind::Chapter { "chapter-marker" } else { "marker" };
    let dur = if m.duration > Tick::ZERO { m.duration } else { rate.frame_duration() };
    let note = if m.comment.is_empty() { String::new() } else { format!(" note=\"{}\"", crate::xml::escape_attr(&m.comment)) };
    format!("<{tag} start=\"{}\" duration=\"{}\" value=\"{}\"{note}/>", fmt_time(local, rate), fmt_time(dur, rate), crate::xml::escape_attr(&m.name))
}

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

    #[test]
    fn rational_times_are_exact() {
        let r = FrameRate::FPS_23_976;
        assert_eq!(parse_time("1001/24000s"), Some(r.frame_duration()));
        assert_eq!(parse_time("3600s"), Some(Tick(3600 * TICKS_PER_SECOND)));
        assert_eq!(parse_time("0s"), Some(Tick::ZERO));
        assert_eq!(fmt_time(r.tick_of(1), r), "1001/24000s");
        assert_eq!(fmt_time(r.tick_of(24000), r), "1001s");
        assert_eq!(fmt_time(FrameRate::FPS_25.tick_of(50), FrameRate::FPS_25), "2s");
        for rate in FrameRate::COMMON {
            for f in [0, 1, 7, 1799, 1800, 86_313, 1_000_003] {
                let t = rate.tick_of(f);
                assert_eq!(parse_time(&fmt_time(t, rate)), Some(t), "{rate} {f}");
            }
        }
        let odd = Tick(12_345);
        assert_eq!(parse_time(&fmt_time(odd, r)), Some(odd));
        assert_eq!(rate_from_frame_duration("1001/30000s"), Some(FrameRate::FPS_29_97));
        assert_eq!(rate_from_frame_duration("100/2500s"), Some(FrameRate::FPS_25));
        for bad in ["100/0s", "0/100s", "-100/2500s", "100/-2500s", "0s", "x"] {
            assert_eq!(rate_from_frame_duration(bad), None, "{bad}");
        }
    }

    /// A zero frame duration denominator gave the format a zero frame rate, and export then
    /// divided by zero (`fmt_time`) as soon as the sequence had a start timecode or a marker.
    #[test]
    fn zero_frame_duration_falls_back_to_the_default_rate() {
        for fd in ["100/0s", "0/100s", "-100/2500s"] {
            let xml = format!(
                r#"<?xml version="1.0"?><fcpxml version="1.10"><resources><format id="f1" frameDuration="{fd}" width="1920" height="1080"/>
<asset id="a1" name="c" start="0s" duration="10s" hasVideo="1" format="f1"><media-rep kind="original-media" src="file:///tmp/c.mov"/></asset></resources>
<library><event name="E"><project name="P"><sequence format="f1" tcStart="3600/1s" tcFormat="DF"><spine>
<asset-clip ref="a1" offset="3600s" duration="5s"><marker start="1s" duration="1/25s" value="m"/></asset-clip></spine></sequence></project></event></library></fcpxml>"#
            );
            let (imported, report) = crate::import(xml.as_bytes(), crate::Format::Fcpxml, None).expect("import succeeds");
            for seq in &imported.sequences {
                crate::export(&imported.project, *seq, crate::Format::Fcpxml, &crate::ExportOptions::default()).expect("export succeeds");
            }
            assert!(report.mentions("invalid frameDuration"), "{fd}: {report}");
        }
    }
}