f67d38b35cc5
fcp7.rs
//! Final Cut Pro 7 XML interchange (`xmeml` versions 4 and 5), the dialect Premiere Pro imports
//! and exports.
//!
//! Supported: `project`/`bin`/`clip`/`sequence` structure, video and audio tracks (enabled,
//! locked), `clipitem` (start/end/in/out, `pproTicksIn/Out` for tick-exact source times, enabled,
//! labels, markers, links), master-clip `<clip>` media markers, `file` (pathurl, rate, duration,
//! timecode, media characteristics, references by id), nested sequences (inline or by id),
//! `generatoritem` (Slug, Color, …),
//! `transitionitem` (alignment, Cross Dissolve & friends), and the filters Basic Motion (scale,
//! rotation, center, anchor, anti-flicker), Opacity, Time Remap (constant speed, reverse, freeze),
//! Audio Levels and Audio Pan, all with keyframes. Other effects are written with our effect ids
//! and read back by id or display name; anything unknown is reported.
//!
//! Coordinates: Basic Motion `center` is written relative to the frame centre as a fraction of the
//! frame width/height (0,0 = centred); `centerOffset` (anchor) likewise relative to the source.
//! Keyframe `when` values and clip markers are source (media) frames, like `in`/`out`.
use std::collections::{HashMap, HashSet};
use filmcraft_geom::Vec2;
use filmcraft_media::{DemoScene, Generator, MediaKind};
use filmcraft_project::{
BinId, ClipId, EffectInstance, Interpolation, ItemId, ItemKind, Keyframe, Label, Marker, MarkerId, MarkerKind, Param, ParamValue, Project, Sequence,
TrackItem, TrackKind, Transition, TransitionAlign, TransitionId, effect::find_effect_by_name, find_effect,
};
use filmcraft_time::{FrameRate, Tick, format_timecode_frames};
use roxmltree::Node;
use crate::common::{
Builder, MAX_IMPORTED_TRACKS, MAX_RATE, MediaSpec, base_item, db_to_gain, empty_sequence, file_name, frames_round, gain_to_db, item_media, item_path,
kind_from_ext, label_from, on_frame, param, param_modified, path_to_file_url, rate_from_timebase, resolve_path, resolve_url, set_param, settings_for,
standard_effects, timebase, transition_effect, transition_name, unscaled,
};
use crate::xml::{XmlWriter, bool_str, child, child_bool, child_f64, child_i64, child_text, children, elements, num, path_text};
use crate::{Error, ExportOptions, Format, ImportOptions, Imported, Report, Result};
// ---------------------------------------------------------------------------------------------
// Shared vocabulary
// ---------------------------------------------------------------------------------------------
/// Most members of a link group written into each clip's `<link>` list (a group is a clip's own
/// video and a few audio channels, so real ones are far smaller).
const MAX_LINK_MEMBERS: usize = 64;
struct ClipRemap {
speed: f64,
reverse: bool,
hold: bool,
has_remap: bool,
}
impl Default for ClipRemap {
fn default() -> Self {
Self { speed: 1.0, reverse: false, hold: false, has_remap: false }
}
}
const BLEND_XML: &[(&str, u32)] = &[
("normal", 0),
("darken", 2),
("multiply", 3),
("lighten", 7),
("screen", 8),
("add", 10),
("overlay", 12),
("softlight", 13),
("hardlight", 14),
("difference", 19),
("subtract", 21),
];
fn generator_from(name: &str, id: &str, report: &mut Report) -> Generator {
if let Some(json) = id.strip_prefix("filmcraft:")
&& let Ok(g) = serde_json::from_str::<Generator>(json)
{
return g;
}
match name.to_ascii_lowercase().as_str() {
"slug" | "black video" => Generator::BlackVideo,
"color" | "color matte" | "colour matte" => Generator::ColorMatte { color: [0.0, 0.0, 0.0, 1.0] },
"transparent video" => Generator::TransparentVideo,
"counting leader" | "universal counting leader" => Generator::CountingLeader,
n if n.starts_with("bars and tone") => Generator::BarsAndTone,
n => {
if let Some(d) = DemoScene::ALL.iter().find(|d| d.file_name().eq_ignore_ascii_case(n)) {
return Generator::Demo(*d);
}
report.warn(format!("generator \"{name}\" is not supported; imported as Black Video"));
Generator::BlackVideo
}
}
}
fn read_rate(n: Node) -> Option<FrameRate> {
let r = child(n, "rate")?;
let tb = child_i64(r, "timebase")?;
Some(rate_from_timebase(tb, child_bool(r, "ntsc").unwrap_or(false)))
}
fn write_rate(w: &mut XmlWriter, rate: FrameRate) {
let (tb, ntsc) = timebase(rate);
w.open("rate", &[]);
w.text("timebase", tb);
w.text("ntsc", bool_str(ntsc));
w.close();
}
// ---------------------------------------------------------------------------------------------
// Import
// ---------------------------------------------------------------------------------------------
/// Most times a truncated nested sequence is imported again at a shallower depth.
const MAX_REIMPORTS: usize = 4096;
struct PendingLink {
seq: ItemId,
kind: TrackKind,
track: usize,
clip: ClipId,
refs: Vec<String>,
}
/// Deepest `bin`/`children`/`project` nesting a hostile file may walk. XML containers can nest
/// without limit in the file, and the walk 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,
files: HashMap<String, Node<'a, 'i>>,
seq_defs: HashMap<String, Node<'a, 'i>>,
file_items: HashMap<String, ItemId>,
seq_items: HashMap<String, ItemId>,
in_progress: HashSet<String>,
/// Nested sequences left out because the chain was too deep, counted so a sequence whose
/// subtree lost one is known to be incomplete.
depth_hits: usize,
/// Sequences imported incomplete (a nested sequence below them was left out), by key: the
/// nesting depth they were imported at. Reached again at a shallower depth they are imported again.
truncated_at: HashMap<String, usize>,
/// Re-imports of truncated sequences still allowed.
reimports_left: usize,
links: Vec<PendingLink>,
xml_clip_ids: HashMap<(ItemId, String), ClipId>,
/// `(sequence key, file key)` pairs where some audio clip item of that file uses `sourcetrack/trackindex` > 1,
/// i.e. the file's channels are split onto mono tracks in that sequence (#463).
split_files: HashSet<(String, String)>,
/// Current container nesting, checked against [`MAX_XML_DEPTH`].
depth: usize,
}
/// The `(sequence key, file key)` an audio clip item belongs to, if it references a file.
fn clip_seq_file(c: Node) -> Option<(String, String)> {
let seq = c.ancestors().skip(1).find(|a| a.has_tag_name("sequence"))?;
Some((node_key(seq), node_key(child(c, "file")?)))
}
/// The 1-based `sourcetrack/trackindex` of an audio clip item.
fn audio_track_index(c: Node) -> Option<i64> {
let st = child(c, "sourcetrack")?;
if child_text(st, "mediatype").is_some_and(|m| m != "audio") {
return None;
}
child_i64(st, "trackindex")
}
fn node_key(n: Node) -> String {
match n.attribute("id") {
Some(id) => id.to_string(),
None => format!("#node{}", n.id().get()),
}
}
pub(crate) fn import(text_in: &str, opts: &ImportOptions, report: &mut Report) -> Result<Imported> {
let doc = crate::xml::parse(text_in).map_err(|e| Error::parse(Format::Fcp7Xml, e))?;
let root = doc.root_element();
if root.tag_name().name() != "xmeml" {
return Err(Error::parse(Format::Fcp7Xml, "root element is not <xmeml>"));
}
if root.descendants().any(|n| n.has_tag_name("timebase") && n.text().and_then(|t| t.trim().parse::<f64>().ok()).is_some_and(|tb| tb > MAX_RATE as f64)) {
report.warn(format!("a timebase above {MAX_RATE} per second is not a frame rate; it was limited to {MAX_RATE}"));
}
let mut imp = Imp {
b: Builder::new(root.descendants().find(|n| n.has_tag_name("project")).and_then(|p| child_text(p, "name")).unwrap_or("Imported XML")),
opts,
report,
files: HashMap::new(),
seq_defs: HashMap::new(),
file_items: HashMap::new(),
seq_items: HashMap::new(),
in_progress: HashSet::new(),
depth_hits: 0,
truncated_at: HashMap::new(),
reimports_left: MAX_REIMPORTS,
links: Vec::new(),
xml_clip_ids: HashMap::new(),
split_files: HashSet::new(),
depth: 0,
};
for n in root.descendants().filter(|n| n.is_element()) {
match n.tag_name().name() {
"clipitem" if audio_track_index(n).is_some_and(|i| i > 1) => {
if let Some(key) = clip_seq_file(n) {
imp.split_files.insert(key);
}
}
"file" if elements(n).next().is_some() => {
imp.files.entry(node_key(n)).or_insert(n);
}
"sequence" if child(n, "media").is_some() => {
imp.seq_defs.entry(node_key(n)).or_insert(n);
}
_ => {}
}
}
imp.walk_container(root, None, true);
imp.resolve_links();
if imp.b.p.items.is_empty() {
return Err(Error::Empty);
}
Ok(imp.b.finish())
}
impl<'a, 'i> Imp<'a, 'i, '_> {
/// Walk `xmeml`, `project`, `bin` and `children` containers.
fn walk_container(&mut self, n: Node<'a, 'i>, bin: Option<BinId>, top: bool) {
if self.depth >= MAX_XML_DEPTH {
self.report.warn(format!("XML containers are nested more than {MAX_XML_DEPTH} deep; deeper bins and clips were skipped"));
return;
}
self.depth += 1;
for c in elements(n) {
match c.tag_name().name() {
"project" => {
let target = c.children().find(|x| x.has_tag_name("children")).unwrap_or(c);
self.walk_container(target, bin, top);
}
"children" => self.walk_container(c, bin, top),
"bin" => {
let name = child_text(c, "name").unwrap_or("Bin");
let b = self.b.bin(name, bin);
let target = child(c, "children").unwrap_or(c);
self.walk_container(target, Some(b), top);
}
"sequence" => {
if let Some(id) = self.sequence(c, bin)
&& top
&& !self.b.top.contains(&id)
{
self.b.top.push(id);
}
}
"clip" => self.master_clip(c, bin),
_ => {}
}
}
self.depth -= 1;
}
/// A master clip in a bin: its file(s) become media items.
fn master_clip(&mut self, n: Node<'a, 'i>, bin: Option<BinId>) {
let file = n.descendants().find(|d| d.has_tag_name("file"));
match file {
Some(f) => {
let id = self.file(f, child_text(n, "name"), bin);
// A sequence's clip items file their media at the top level, so a sequence earlier in the
// document that used this file first left it there; the master clip's bin is its home.
if let (Some(item), Some(b)) = (id, bin)
&& self.b.p.root.parent_of(item) == Some(self.b.p.root.id)
{
self.b.p.move_to_bin(&[item], Some(b));
}
if let Some(item) = id.and_then(|i| self.b.p.item_mut(i))
&& let Some(l) = path_text(n, &["labels", "label2"]).and_then(label_from)
{
item.label = l;
}
if let (Some(item), Some(rate)) = (id, read_rate(n)) {
let markers = read_markers(n, rate, &mut self.b);
if let Some(m) = self.b.p.item_mut(item).and_then(|i| i.as_media_mut())
&& m.markers.is_empty()
{
m.markers = markers;
}
}
}
None => {
if let Some(s) = n.descendants().find(|d| d.has_tag_name("sequence")) {
self.sequence(s, bin);
}
}
}
}
/// Media item for a `<file>` element (definition or reference by id).
fn file(&mut self, n: Node<'a, 'i>, fallback_name: Option<&str>, bin: Option<BinId>) -> Option<ItemId> {
let key = node_key(n);
if let Some(id) = self.file_items.get(&key) {
return Some(*id);
}
let def = if elements(n).next().is_some() { n } else { *self.files.get(&key)? };
let name = child_text(def, "name").filter(|s| !s.is_empty()).or(fallback_name).unwrap_or("Untitled").to_string();
let rate = read_rate(def);
let video = child(def, "media").and_then(|m| child(m, "video"));
let audio = child(def, "media").and_then(|m| child(m, "audio"));
let dims = video.map(|v| {
let sc = child(v, "samplecharacteristics").unwrap_or(v);
(child_i64(sc, "width").unwrap_or(1920) as u32, child_i64(sc, "height").unwrap_or(1080) as u32)
});
let aud = audio.map(|a| {
let sc = child(a, "samplecharacteristics").unwrap_or(a);
(child_i64(sc, "samplerate").unwrap_or(48_000) as u32, child_i64(a, "channelcount").unwrap_or(2) as u32)
});
let r = rate.unwrap_or_default();
let path = child_text(def, "pathurl").filter(|s| !s.is_empty());
let mut spec = MediaSpec {
duration: child_i64(def, "duration").filter(|d| *d > 0).map(|d| r.tick_of(d)),
video: dims.map(|(w, h)| (w, h, r)),
audio: aud,
start_tc: child(def, "timecode").and_then(|t| child_i64(t, "frame")),
kind: None,
};
if spec.video.is_none() && spec.audio.is_none() {
// No media characteristics: guess from the extension.
match kind_from_ext(path.unwrap_or(&name)) {
MediaKind::AudioOnly => spec.audio = Some((48_000, 2)),
k => {
spec.video = Some((1920, 1080, r));
spec.kind = Some(k);
}
}
}
let id = match path {
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!("file \"{name}\" has no pathurl; imported offline"));
let p = resolve_path(&name, self.opts.base_dir.as_deref());
let id = self.b.file_media(&format!("fileid:{key}"), &name, &p, &spec, bin);
if let Some(m) = self.b.p.item_mut(id).and_then(|i| i.as_media_mut()) {
m.offline = true;
}
id
}
};
self.file_items.insert(key, id);
Some(id)
}
/// Sequence item for a `<sequence>` element (definition or reference).
fn sequence(&mut self, n: Node<'a, 'i>, bin: Option<BinId>) -> Option<ItemId> {
let key = node_key(n);
let depth = self.in_progress.len();
// A sequence imported with a nested sequence cut off is imported again (into the same
// item) when it is reached higher up the chain, where its nested sequence now fits.
let mut again = None;
if let Some(id) = self.seq_items.get(&key) {
let shallower = self.truncated_at.get(&key).is_some_and(|d| depth < *d) && !self.in_progress.contains(&key);
if !shallower {
return Some(*id);
}
if self.reimports_left == 0 {
self.report.warn("truncated nested sequence kept incomplete after the re-import limit was reached");
return Some(*id);
}
self.reimports_left -= 1;
again = Some(*id);
}
let def = if child(n, "media").is_some() { n } else { *self.seq_defs.get(&key)? };
if depth >= crate::MAX_NESTING_DEPTH {
self.depth_hits += 1;
self.report.warn("nested sequence is nested too deeply; imported as a gap");
return None;
}
let hits_before = self.depth_hits;
if !self.in_progress.insert(key.clone()) {
self.report.warn("recursive nested sequence ignored");
return None;
}
let name = child_text(def, "name").unwrap_or("Sequence").to_string();
let rate = read_rate(def).unwrap_or_default();
let tc = child(def, "timecode");
let df = tc.and_then(|t| child_text(t, "displayformat")).is_some_and(|d| d.eq_ignore_ascii_case("DF"));
let vfmt = child(def, "media").and_then(|m| child(m, "video")).and_then(|v| child(v, "format")).and_then(|f| child(f, "samplecharacteristics"));
let (w, h) = vfmt.map(|s| (child_i64(s, "width").unwrap_or(1920) as u32, child_i64(s, "height").unwrap_or(1080) as u32)).unwrap_or((1920, 1080));
let mut settings = settings_for(rate, w, h, df);
if let Some(sr) = child(def, "media")
.and_then(|m| child(m, "audio"))
.and_then(|a| child(a, "format"))
.and_then(|f| child(f, "samplecharacteristics"))
.and_then(|s| child_i64(s, "samplerate"))
{
settings.sample_rate = sr as u32;
}
let id = match again {
Some(id) => id,
None => {
let id = self.b.reserve_sequence(&name, settings.clone(), bin);
if let Some(l) = path_text(def, &["labels", "label2"]).and_then(label_from)
&& let Some(it) = self.b.p.item_mut(id)
{
it.label = l;
}
id
}
};
self.seq_items.insert(key.clone(), id);
let mut seq = empty_sequence(settings);
seq.start_timecode = tc.and_then(|t| child_i64(t, "frame")).unwrap_or(0);
seq.markers = read_markers(def, rate, &mut self.b);
let media = child(def, "media");
for (kind, tag) in [(TrackKind::Video, "video"), (TrackKind::Audio, "audio")] {
let Some(m) = media.and_then(|m| child(m, tag)) else { continue };
for (ti, tn) in children(m, "track").enumerate() {
if !self.b.ensure_tracks(&mut seq, kind, ti + 1) {
self.report.warn(format!("FCP7 {kind:?} tracks beyond {MAX_IMPORTED_TRACKS} were skipped"));
break;
}
self.track(&mut seq, id, kind, ti, tn, TrackFormat { rate, frame: (w, h) });
}
}
if seq.video_tracks.is_empty() {
self.b.ensure_tracks(&mut seq, TrackKind::Video, 1);
}
if seq.audio_tracks.is_empty() {
self.b.ensure_tracks(&mut seq, TrackKind::Audio, 1);
}
self.b.put_sequence(id, seq);
self.in_progress.remove(&key);
if self.depth_hits > hits_before {
self.truncated_at.insert(key, depth);
} else {
self.truncated_at.remove(&key);
}
Some(id)
}
fn track(&mut self, seq: &mut Sequence, seq_id: ItemId, kind: TrackKind, ti: usize, tn: Node<'a, 'i>, fmt: TrackFormat) {
let TrackFormat { rate, frame } = fmt;
{
let t = &mut seq.tracks_mut(kind)[ti];
t.enabled = child_bool(tn, "enabled").unwrap_or(true);
t.locked = child_bool(tn, "locked").unwrap_or(false);
}
let mut trans_nodes = Vec::new();
for c in elements(tn) {
match c.tag_name().name() {
"clipitem" | "generatoritem" => {
if let Some((ti_item, refs)) = self.clip_item(c, kind, rate, frame) {
let xml_id = node_key(c);
self.xml_clip_ids.insert((seq_id, xml_id), ti_item.id);
if !refs.is_empty() {
self.links.push(PendingLink { seq: seq_id, kind, track: ti, clip: ti_item.id, refs });
}
let t = &mut seq.tracks_mut(kind)[ti];
if t.items.iter().any(|o| o.start < ti_item.end() && ti_item.start < o.end()) {
self.report.warn("overlapping clip items on one track; the later one was moved to a new track");
if self.b.place(seq, kind, ti + 1, ti_item).is_none() {
self.report.warn(format!("FCP7 {kind:?} track exceeds the {MAX_IMPORTED_TRACKS}-track import limit; clip was skipped"));
}
} else {
t.items.push(ti_item);
}
}
}
"transitionitem" => trans_nodes.push(c),
_ => {}
}
}
seq.tracks_mut(kind)[ti].sort();
for c in trans_nodes {
self.transition(seq, kind, ti, c, rate);
}
}
fn clip_item(&mut self, c: Node<'a, 'i>, kind: TrackKind, seq_rate: FrameRate, frame: (u32, u32)) -> Option<(TrackItem, Vec<String>)> {
let name = child_text(c, "name").unwrap_or("").to_string();
let rate = read_rate(c).unwrap_or(seq_rate);
let item = self.clip_media(c, kind, seq_rate, frame, &name)?;
let start = child_i64(c, "start").unwrap_or(-1);
let end = child_i64(c, "end").unwrap_or(-1);
let in_f = child_i64(c, "in").unwrap_or(0);
let out_f = child_i64(c, "out").unwrap_or(in_f);
let src_in = child_i64(c, "pproTicksIn").map(Tick).unwrap_or_else(|| rate.tick_of(in_f));
let src_out = child_i64(c, "pproTicksOut").map(Tick).unwrap_or_else(|| rate.tick_of(out_f));
let remap = self.time_remap(c);
let (mut speed, reverse, hold) = (remap.speed, remap.reverse, remap.hold);
let src_len = (src_out - src_in).abs();
let (start_t, dur) = match (start >= 0, end >= 0) {
(true, true) => (seq_rate.tick_of(start), seq_rate.tick_of(end) - seq_rate.tick_of(start)),
(true, false) => {
let d = if hold { rate.tick_of(out_f - in_f) } else { unscaled(src_len, speed) };
(seq_rate.tick_of(start), d)
}
(false, true) => {
let d = if hold { rate.tick_of(out_f - in_f) } else { unscaled(src_len, speed) };
(seq_rate.tick_of(end) - d, d)
}
(false, false) => {
self.report.warn(format!("clip \"{name}\" has neither start nor end; skipped"));
return None;
}
};
if dur <= Tick::ZERO {
return None;
}
if !remap.has_remap && !hold && src_len != dur && src_len > Tick::ZERO {
speed = (src_len.0 as f64 / dur.0 as f64 * 10_000.0).round() / 10_000.0;
}
let mut ti = self.b.clip(item, kind, if name.is_empty() { "Clip" } else { &name }, start_t, dur, src_in.min(src_out));
ti.speed = speed;
ti.reverse = reverse;
if hold {
ti.frame_hold = Some(src_in);
}
ti.enabled = child_bool(c, "enabled").unwrap_or(true);
if let Some(l) = path_text(c, &["labels", "label2"]).and_then(label_from) {
ti.label = l;
}
self.apply_clip_channels(&mut ti, c, item, kind);
if let Some(mode) = child_text(c, "compositemode") {
match BLEND_XML.iter().find(|(n, _)| n.eq_ignore_ascii_case(mode)) {
Some((_, v)) if *v != 0 => set_param(&mut ti, "opacity", "blend", Param::new(ParamValue::Choice(*v))),
Some(_) => {}
None => self.report.warn(format!("composite mode \"{mode}\" is not supported")),
}
}
ti.markers = read_markers(c, rate, &mut self.b);
let src_frame = self.source_frame(item).unwrap_or(frame);
for f in c.children().filter(|x| x.has_tag_name("filter")) {
self.filter(&mut ti, f, rate, frame, src_frame);
}
let refs: Vec<String> = children(c, "link").filter_map(|l| child_text(l, "linkclipref")).map(str::to_string).collect();
Some((ti, refs))
}
fn clip_media(&mut self, c: Node<'a, 'i>, kind: TrackKind, seq_rate: FrameRate, frame: (u32, u32), name: &str) -> Option<ItemId> {
if c.has_tag_name("generatoritem") {
let eff = child(c, "effect");
let gname = eff.and_then(|e| child_text(e, "name")).unwrap_or(name).to_string();
let gid = eff.and_then(|e| child_text(e, "effectid")).unwrap_or("").to_string();
let mut g = generator_from(&gname, &gid, self.report);
if let (Generator::ColorMatte { color }, Some(e)) = (&mut g, eff)
&& let Some(v) = e.descendants().find(|d| d.has_tag_name("value") && child(*d, "red").is_some())
{
*color = read_color(v);
}
let spec = MediaSpec { video: Some((frame.0, frame.1, seq_rate)), ..Default::default() };
let key = format!("gen:{}", serde_json::to_string(&g).unwrap_or_default());
let label = if name.is_empty() { g.label() } else { name.to_string() };
Some(self.b.generator_media(&key, &label, g, &spec, None))
} else if let Some(f) = child(c, "file") {
match self.file(f, Some(name), None) {
Some(item) => Some(item),
None => {
self.report.warn(format!("clip \"{name}\" refers to a file the document does not define; skipped"));
None
}
}
} else if let Some(s) = child(c, "sequence") {
// A nested sequence left out (nested too deeply, or recursive) stays in the timeline as an offline
// clip, so the clip keeps its place and length instead of shortening the sequence.
match self.sequence(s, None) {
Some(id) => Some(id),
None => {
self.report.warn(format!("clip \"{name}\" refers to a nested sequence that was left out; imported offline"));
Some(self.offline_media(kind, seq_rate, frame, name))
}
}
} else {
self.report.warn(format!("clip \"{name}\" has no media reference; imported offline"));
Some(self.offline_media(kind, seq_rate, frame, name))
}
}
fn offline_media(&mut self, kind: TrackKind, seq_rate: FrameRate, frame: (u32, u32), name: &str) -> ItemId {
{
let spec = MediaSpec {
video: (kind == TrackKind::Video).then_some((frame.0, frame.1, seq_rate)),
audio: (kind == TrackKind::Audio).then_some((48_000, 2)),
..Default::default()
};
let key = format!("offline:{name}");
let p = resolve_path(name, self.opts.base_dir.as_deref());
let id = self.b.file_media(&key, name, &p, &spec, None);
if let Some(m) = self.b.p.item_mut(id).and_then(|i| i.as_media_mut()) {
m.offline = true;
}
id
}
}
fn time_remap(&mut self, c: Node<'a, 'i>) -> ClipRemap {
let mut remap = ClipRemap::default();
for eff in c.children().filter(|x| x.has_tag_name("filter")).filter_map(|f| child(f, "effect")) {
if child_text(eff, "effectid") == Some("timeremap") {
remap.has_remap = true;
for p in children(eff, "parameter") {
match child_text(p, "parameterid") {
Some("speed") => {
let v = child_f64(p, "value").unwrap_or(100.0);
if v == 0.0 {
remap.hold = true;
} else {
remap.speed = v.abs() / 100.0;
remap.reverse |= v < 0.0;
}
if child(p, "keyframe").is_some() {
self.report.warn("variable speed (time remap keyframes) is not supported; a constant speed was used");
}
}
Some("reverse") => remap.reverse |= child_bool(p, "value").unwrap_or(false),
Some("variablespeed") if child_bool(p, "value") == Some(true) || child_f64(p, "value").is_some_and(|v| v != 0.0) => {
self.report.warn("variable speed (time remap keyframes) is not supported; a constant speed was used");
}
_ => {}
}
}
}
}
remap
}
fn apply_clip_channels(&self, ti: &mut TrackItem, c: Node<'a, 'i>, item: ItemId, kind: TrackKind) {
// `sourcetrack/trackindex` (1-based) picks the source channel of a mono track split off a multichannel file (#463).
// Index 1 is also what a stereo clip on a stereo track carries, so it means channel 0 only when another clip
// item of the same file in this sequence uses a higher index (the file is split); otherwise it keeps the
// default (empty) channel mapping.
if kind == TrackKind::Audio
&& let Some(idx) = audio_track_index(c)
&& (idx > 1 || (idx == 1 && clip_seq_file(c).is_some_and(|k| self.split_files.contains(&k))))
&& let Ok(ch) = u16::try_from(idx - 1)
{
ti.source_channels = vec![ch];
// The two halves of a split stereo file play on their own side, as the stereo clip did (#371):
// a mono clip is centred (both sides at unity), so the halves would otherwise sum on both
// sides, +3 dB for uncorrelated channels, +6 dB for dual mono. An `audiopan` filter
// (read below) still overrides this.
let stereo = matches!(&self.b.p.item(item).map(|i| &i.kind), Some(ItemKind::Media(m)) if m.info.audio().is_some_and(|a| a.channels == 2));
if stereo && ch <= 1 {
set_param(ti, "panner", "balance", Param::new(ParamValue::Float(if ch == 0 { -100.0 } else { 100.0 })));
}
}
}
fn source_frame(&self, item: ItemId) -> Option<(u32, u32)> {
match &self.b.p.item(item)?.kind {
ItemKind::Media(m) => m.info.video.as_ref().map(|v| (v.width, v.height)),
ItemKind::Sequence(s) => Some((s.settings.width, s.settings.height)),
_ => None,
}
}
fn filter(&mut self, ti: &mut TrackItem, f: Node, rate: FrameRate, frame: (u32, u32), src: (u32, u32)) {
let Some(e) = child(f, "effect") else { return };
let enabled = child_bool(f, "enabled").unwrap_or(true);
let id = child_text(e, "effectid").unwrap_or("");
let name = child_text(e, "name").unwrap_or(id);
let params: Vec<Node> = children(e, "parameter").collect();
let find = |pid: &str| {
params.iter().copied().find(|p| child_text(*p, "parameterid") == Some(pid) || child_text(*p, "name").is_some_and(|n| n.eq_ignore_ascii_case(pid)))
};
let (fw, fh) = (frame.0 as f64, frame.1 as f64);
let (sw, sh) = (src.0 as f64, src.1 as f64);
match id {
"timeremap" => {}
"basic" => {
if let Some(p) = find("scale") {
set_param(ti, "motion", "scale", read_param(p, rate, |v| v));
}
if let Some(p) = find("rotation") {
set_param(ti, "motion", "rotation", read_param(p, rate, |v| v));
}
if let Some(p) = find("center") {
let pr = read_point_param(p, rate, |x, y| Vec2::new(fw / 2.0 + x * fw, fh / 2.0 + y * fh));
if pr.is_animated() || pr.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", pr);
}
}
if let Some(p) = find("centerOffset") {
let pr = read_point_param(p, rate, |x, y| Vec2::new(sw / 2.0 + x * sw, sh / 2.0 + y * sh));
if pr.is_animated() || pr.value.as_vec2().is_some_and(|v| (v.x - sw / 2.0).abs() > 1e-9 || (v.y - sh / 2.0).abs() > 1e-9) {
set_param(ti, "motion", "anchor", pr);
}
}
if let Some(p) = find("antiflicker") {
set_param(ti, "motion", "anti_flicker", read_param(p, rate, |v| v));
}
if let Some(m) = ti.effect_mut("motion") {
m.enabled = enabled;
}
}
"opacity" => {
if let Some(p) = find("opacity") {
set_param(ti, "opacity", "opacity", read_param(p, rate, |v| v));
}
}
"audiolevels" => {
if let Some(p) = find("level") {
set_param(ti, "volume", "level", read_param(p, rate, gain_to_db));
}
}
"audiopan" => {
if let Some(p) = find("pan") {
set_param(ti, "panner", "balance", read_param(p, rate, |v| v * 100.0));
}
}
_ => {
let def = filmcraft_project::find_effect(id).filter(|d| !d.intrinsic).or_else(|| find_effect_by_name(name).filter(|d| !d.intrinsic));
let Some(def) = def else {
self.report.warn(format!("effect \"{name}\" is not supported and was skipped"));
return;
};
let mut inst = def.instance();
inst.enabled = enabled;
for pd in &def.params {
let Some(p) = find(pd.id).or_else(|| find(pd.label)) else { continue };
let pr = match &pd.default {
ParamValue::Float(_) => read_param(p, rate, |v| v),
ParamValue::Vec2(_) => read_point_param(p, rate, Vec2::new),
ParamValue::Bool(_) => Param::new(ParamValue::Bool(child_bool(p, "value").unwrap_or(false))),
ParamValue::Choice(_) => Param::new(ParamValue::Choice(child_i64(p, "value").unwrap_or(0).max(0) as u32)),
ParamValue::Color(_) => Param::new(ParamValue::Color(child(p, "value").map(read_color).unwrap_or([0.0, 0.0, 0.0, 1.0]))),
ParamValue::Text(_) => Param::new(ParamValue::Text(child_text(p, "value").unwrap_or("").to_string())),
ParamValue::Curve(_) | ParamValue::Path(_) => continue,
};
inst.params.insert(pd.id.to_string(), pr);
}
ti.effects.push(inst);
}
}
}
fn transition(&mut self, seq: &mut Sequence, kind: TrackKind, ti: usize, c: Node, rate: FrameRate) {
let start = child_i64(c, "start").unwrap_or(0);
let end = child_i64(c, "end").unwrap_or(start);
let (s, e) = (rate.tick_of(start), rate.tick_of(end));
if e <= s {
return;
}
let eff = child(c, "effect");
let name = eff.and_then(|x| child_text(x, "name")).or_else(|| eff.and_then(|x| child_text(x, "effectid"))).unwrap_or("Cross Dissolve");
let effect = transition_effect(name, kind == TrackKind::Audio, self.report);
let align_s = child_text(c, "alignment").unwrap_or("").to_ascii_lowercase();
let track = &mut seq.tracks_mut(kind)[ti];
let (mut from, mut to) = (None, None);
if align_s != "start-black" {
from = track.items.iter().filter(|i| i.end() >= s && i.end() <= e).max_by_key(|i| i.end()).map(|i| (i.id, i.end()));
}
if align_s != "end-black" {
to = track.items.iter().filter(|i| i.start >= s && i.start <= e).min_by_key(|i| i.start).map(|i| (i.id, i.start));
}
// A cut needs both sides to meet.
if let (Some((_, fe)), Some((_, ts))) = (from, to)
&& fe != ts
{
if align_s == "start-black" || (align_s.is_empty() && ts == s) {
from = None;
} else {
to = None;
}
}
if from.is_none() && to.is_none() {
self.report.warn(format!("transition \"{name}\" at frame {start} has no adjacent clip; skipped"));
return;
}
let cut = from.map(|f| f.1).or(to.map(|t| t.1)).unwrap_or(s);
let align = match align_s.as_str() {
"center" => TransitionAlign::CenterAtCut,
"start" | "start-black" => TransitionAlign::StartAtCut,
"end" | "end-black" => TransitionAlign::EndAtCut,
_ if cut == s => TransitionAlign::StartAtCut,
_ if cut == e => TransitionAlign::EndAtCut,
_ => TransitionAlign::CenterAtCut,
};
let id = TransitionId(self.b.alloc());
track.transitions.push(Transition { id, effect, start: s, duration: e - s, from: from.map(|f| f.0), to: to.map(|t| t.0), align, reverse: false });
track.sort();
}
fn resolve_links(&mut self) {
// Union clip items that reference each other.
let mut group_of: HashMap<(ItemId, ClipId), u64> = HashMap::new();
let pending = std::mem::take(&mut self.links);
for pl in &pending {
let mut members: Vec<ClipId> = pl.refs.iter().filter_map(|r| self.xml_clip_ids.get(&(pl.seq, r.clone())).copied()).collect();
members.push(pl.clip);
members.sort();
members.dedup();
if members.len() < 2 {
continue;
}
let existing = members.iter().find_map(|m| group_of.get(&(pl.seq, *m)).copied());
let g = existing.unwrap_or_else(|| self.b.link_id());
for m in members {
group_of.insert((pl.seq, m), g);
}
let _ = (pl.kind, pl.track);
}
for ((seq, clip), g) in group_of {
if let Some(s) = self.b.p.sequence_mut(seq)
&& let Some((_, it)) = s.find_item_mut(clip)
{
it.link = Some(g);
}
}
}
}
fn read_color(v: Node) -> [f32; 4] {
let c = |n: &str, d: f64| (child_f64(v, n).unwrap_or(d) / 255.0) as f32;
[c("red", 0.0), c("green", 0.0), c("blue", 0.0), c("alpha", 255.0)]
}
fn read_param(p: Node, rate: FrameRate, map: impl Fn(f64) -> f64) -> Param {
let v = child_f64(p, "value").unwrap_or(0.0);
let mut pr = Param::new(ParamValue::Float(map(v)));
for k in children(p, "keyframe") {
let when = child_i64(k, "when").unwrap_or(0);
let kv = child_f64(k, "value").unwrap_or(v);
let mut kf = Keyframe::new(rate.tick_of(when), ParamValue::Float(map(kv)));
kf.interp = keyframe_interp(k);
pr.keyframes.push(kf);
}
pr.keyframes.sort_by_key(|k| k.time);
if let Some(k) = pr.keyframes.first() {
pr.value = k.value.clone();
}
pr
}
fn keyframe_interp(k: Node) -> Interpolation {
match path_text(k, &["interpolation", "name"]).map(str::to_ascii_lowercase).as_deref() {
Some("hold") => Interpolation::Hold,
Some("bezier") | Some("fcpcurve") => Interpolation::Bezier,
_ => Interpolation::Linear,
}
}
fn read_xy(v: Node) -> (f64, f64) {
(child_f64(v, "horiz").unwrap_or(0.0), child_f64(v, "vert").unwrap_or(0.0))
}
fn read_point_param(p: Node, rate: FrameRate, map: impl Fn(f64, f64) -> Vec2) -> Param {
let (x, y) = child(p, "value").map(read_xy).unwrap_or((0.0, 0.0));
let mut pr = Param::new(ParamValue::Vec2(map(x, y)));
for k in children(p, "keyframe") {
let when = child_i64(k, "when").unwrap_or(0);
let (kx, ky) = child(k, "value").map(read_xy).unwrap_or((x, y));
let mut kf = Keyframe::new(rate.tick_of(when), ParamValue::Vec2(map(kx, ky)));
kf.interp = keyframe_interp(k);
pr.keyframes.push(kf);
}
pr.keyframes.sort_by_key(|k| k.time);
if let Some(k) = pr.keyframes.first() {
pr.value = k.value.clone();
}
pr
}
fn read_markers(n: Node, rate: FrameRate, b: &mut Builder) -> Vec<Marker> {
let mut out = Vec::new();
for m in children(n, "marker") {
let in_f = child_i64(m, "in").unwrap_or(0);
let out_f = child_i64(m, "out").unwrap_or(-1);
let start = rate.tick_of(in_f);
let duration = if out_f > in_f { rate.tick_of(out_f) - start } else { Tick::ZERO };
let color = child_text(m, "color").and_then(label_from).unwrap_or(Label::Green);
out.push(Marker {
url: String::new(),
author: String::new(),
custom_color: None,
id: MarkerId(b.alloc()),
start,
duration,
name: child_text(m, "name").unwrap_or("").to_string(),
comment: child_text(m, "comment").unwrap_or("").to_string(),
kind: MarkerKind::Comment,
color,
});
}
out.sort_by_key(|m| m.start);
out
}
// ---------------------------------------------------------------------------------------------
// Export
// ---------------------------------------------------------------------------------------------
struct Exp<'a, 'r> {
p: &'a Project,
opts: &'a ExportOptions,
report: &'r mut Report,
w: XmlWriter,
file_ids: HashMap<ItemId, String>,
seq_ids: HashMap<ItemId, String>,
master_ids: HashMap<ItemId, String>,
writing: HashSet<ItemId>,
written_seqs: HashSet<ItemId>,
next_clip: usize,
}
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);
p.sequence(seq_id).ok_or(Error::NoSequence(seq_id))?;
let mut x = Exp {
p,
opts,
report,
w: XmlWriter::new(Some("xmeml")),
file_ids: HashMap::new(),
seq_ids: HashMap::new(),
master_ids: HashMap::new(),
writing: HashSet::new(),
written_seqs: HashSet::new(),
next_clip: 1,
};
let v = if opts.xmeml_version == 5 { "5" } else { "4" };
x.w.open("xmeml", &[("version", v)]);
x.write_master_clips(seq_id);
x.write_sequence(seq_id, true);
x.w.close();
Ok(x.w.finish())
}
impl Exp<'_, '_> {
fn seq_id(&mut self, id: ItemId) -> String {
let n = self.seq_ids.len() + 1;
self.seq_ids.entry(id).or_insert_with(|| format!("sequence-{n}")).clone()
}
fn write_timecode(&mut self, frame: i64, rate: FrameRate, df: bool) {
self.w.open("timecode", &[]);
write_rate(&mut self.w, rate);
self.w.text("string", format_timecode_frames(frame, rate, df));
self.w.text("frame", frame);
self.w.text("displayformat", if df { "DF" } else { "NDF" });
self.w.close();
}
fn write_sequence(&mut self, id: ItemId, top: bool) {
let sid = self.seq_id(id);
if self.written_seqs.contains(&id) || self.writing.contains(&id) {
self.w.empty("sequence", &[("id", &sid)]);
return;
}
let Some((it, seq)) = self.p.item(id).and_then(|it| Some((it, it.as_sequence()?))) else {
self.w.empty("sequence", &[("id", &sid)]);
return;
};
self.writing.insert(id);
let rate = seq.settings.frame_rate;
let df = seq.settings.drop_frame && rate.supports_drop_frame();
self.w.open("sequence", &[("id", &sid)]);
self.w.text("name", self.opts.name.clone().filter(|_| top).unwrap_or_else(|| it.name.clone()));
self.w.text("duration", frames_round(rate, seq.duration()));
write_rate(&mut self.w, rate);
self.write_timecode(seq.start_timecode, rate, df);
self.w.open("labels", &[]);
self.w.text("label2", it.label.name());
self.w.close();
self.w.open("media", &[]);
// Link table: ClipId -> (xml id, kind, track index, clip index).
let mut clip_xml: HashMap<ClipId, (String, TrackKind, usize, usize)> = HashMap::new();
for kind in [TrackKind::Video, TrackKind::Audio] {
for (ti, t) in seq.tracks(kind).iter().enumerate() {
for (ci, c) in t.items.iter().enumerate() {
let xid = format!("clipitem-{}", self.next_clip);
self.next_clip += 1;
clip_xml.insert(c.id, (xid, kind, ti + 1, ci + 1));
}
}
}
let mut link_members: HashMap<u64, Vec<ClipId>> = HashMap::new();
for t in seq.all_tracks() {
for c in &t.items {
if let Some(l) = c.link {
link_members.entry(l).or_default().push(c.id);
}
}
}
// Each clip lists every member of its group, so a group of n clips writes n * n links.
if let Some(n) = link_members.values().map(Vec::len).filter(|&n| n > MAX_LINK_MEMBERS).max() {
self.report.warn(format!("a link group of {n} clips was exported with its first {MAX_LINK_MEMBERS} members"));
link_members.values_mut().for_each(|m| m.truncate(MAX_LINK_MEMBERS));
}
if seq.all_tracks().any(|t| t.items.iter().any(|i| i.group.is_some())) {
self.report.info("clip groups have no FCP7 XML equivalent and were not exported");
}
for kind in [TrackKind::Video, TrackKind::Audio] {
let tag = if kind == TrackKind::Video { "video" } else { "audio" };
self.w.open(tag, &[]);
self.w.open("format", &[]);
self.w.open("samplecharacteristics", &[]);
if kind == TrackKind::Video {
write_rate(&mut self.w, rate);
self.w.text("width", seq.settings.width);
self.w.text("height", seq.settings.height);
self.w.text("anamorphic", "FALSE");
self.w.text("pixelaspectratio", if seq.settings.par == (1, 1) { "square" } else { "custom" });
self.w.text("fielddominance", "none");
} else {
self.w.text("depth", 16);
self.w.text("samplerate", seq.settings.sample_rate);
}
self.w.close();
self.w.close();
for t in seq.tracks(kind) {
self.w.open("track", &[]);
// Clip and transition items in time order.
let mut order: Vec<(Tick, u8, usize)> = t.items.iter().enumerate().map(|(i, c)| (c.start, 1, i)).collect();
order.extend(t.transitions.iter().enumerate().map(|(i, tr)| (tr.start, 0, i)));
order.sort();
for (_, k, i) in order {
if k == 1 {
let c = &t.items[i];
let links: Vec<(String, TrackKind, usize, usize)> = c
.link
.and_then(|l| link_members.get(&l))
// a clip cut from an over-large group stays unlinked, or its links would restore a larger group on import
.filter(|m| m.contains(&c.id))
.map(|m| m.iter().filter_map(|id| clip_xml.get(id).cloned()).collect())
.unwrap_or_default();
let xid = clip_xml[&c.id].0.clone();
self.write_clip(c, kind, seq, &xid, &links);
} else {
self.write_transition(&t.transitions[i], kind, rate, t);
}
}
self.w.text("enabled", bool_str(t.enabled));
self.w.text("locked", bool_str(t.locked));
self.w.close();
}
self.w.close();
}
self.w.close(); // media
write_markers(&mut self.w, &seq.markers, rate);
self.w.close(); // sequence
self.writing.remove(&id);
self.written_seqs.insert(id);
}
fn write_transition(&mut self, tr: &Transition, kind: TrackKind, rate: FrameRate, t: &filmcraft_project::Track) {
if !on_frame(rate, tr.start) || !on_frame(rate, tr.duration) {
self.report.warn("sub-frame transition positions were rounded to frames");
}
let align = match (tr.from, tr.to, tr.align) {
(None, Some(_), _) => "start-black",
(Some(_), None, _) => "end-black",
(_, _, TransitionAlign::CenterAtCut) => "center",
(_, _, TransitionAlign::StartAtCut) => "start",
(_, _, TransitionAlign::EndAtCut) => "end",
};
let _ = t;
self.w.open("transitionitem", &[]);
write_rate(&mut self.w, rate);
self.w.text("start", frames_round(rate, tr.start));
self.w.text("end", frames_round(rate, tr.end()));
self.w.text("alignment", align);
self.w.open("effect", &[]);
let name = transition_name(&tr.effect);
self.w.text("name", &name);
self.w.text("effectid", &name);
self.w.text("effectcategory", tr.effect.def().and_then(|d| d.category.get(1).copied()).unwrap_or("Dissolve"));
self.w.text("effecttype", "transition");
self.w.text("mediatype", if kind == TrackKind::Video { "video" } else { "audio" });
self.w.close();
self.w.close();
}
fn master_id(&mut self, item: ItemId) -> String {
let n = self.master_ids.len() + 1;
self.master_ids.entry(item).or_insert_with(|| format!("masterclip-{n}")).clone()
}
/// Source-media (master clip) markers live on `<clip>`, not on timeline `<clipitem>`s.
fn write_master_clips(&mut self, seq_id: ItemId) {
let mut seen = HashSet::new();
let mut items = Vec::new();
self.collect_file_media(seq_id, &mut seen, &mut items);
for item in items {
let Some(m) = item_media(self.p, item) else { continue };
if m.markers.is_empty() {
continue;
}
let rate = m
.info
.video
.as_ref()
.map(|v| m.interpret.frame_rate.unwrap_or(v.frame_rate))
.unwrap_or_else(|| self.p.sequence(seq_id).map(|s| s.settings.frame_rate).unwrap_or_default());
let name = self.p.item(item).map(|i| i.name.clone()).unwrap_or_default();
let label = self.p.item(item).map(|i| i.label).unwrap_or(Label::Iris);
let duration = m.info.duration;
let markers = m.markers.clone();
let mid = self.master_id(item);
self.w.open("clip", &[("id", &mid)]);
self.w.text("name", name);
self.w.text("duration", frames_round(rate, duration));
write_rate(&mut self.w, rate);
self.w.open("labels", &[]);
self.w.text("label2", label.name());
self.w.close();
self.write_file(item, rate);
write_markers(&mut self.w, &markers, rate);
self.w.close();
}
}
fn collect_file_media(&self, seq: ItemId, seen: &mut HashSet<ItemId>, out: &mut Vec<ItemId>) {
if !seen.insert(seq) {
return;
}
let Some(s) = self.p.sequence(seq) else { return };
for t in s.all_tracks() {
for c in &t.items {
let base = base_item(self.p, c.item);
match self.p.item(base).map(|i| &i.kind) {
Some(ItemKind::Sequence(_)) => self.collect_file_media(base, seen, out),
Some(ItemKind::Media(_)) if crate::common::generator_of(self.p, base).is_none() && !out.contains(&base) => out.push(base),
_ => {}
}
}
}
}
fn write_clip(&mut self, c: &TrackItem, kind: TrackKind, seq: &Sequence, xid: &str, links: &[(String, TrackKind, usize, usize)]) {
let rate = seq.settings.frame_rate;
if !on_frame(rate, c.start) || !on_frame(rate, c.duration) {
self.report.warn("sub-frame clip positions were rounded to frames");
}
if let Some(clip) = crate::common::uncarried_clip(self.p, c, rate) {
self.report
.warn(format!("{clip} has no Final Cut Pro 7 XML equivalent: it is written as a clip item without media and is not read back on import"));
}
let base = base_item(self.p, c.item);
let generator = crate::common::generator_of(self.p, base).cloned();
let is_seq = matches!(self.p.item(base).map(|i| &i.kind), Some(ItemKind::Sequence(_)));
let tag = if generator.is_some() { "generatoritem" } else { "clipitem" };
let hold = c.frame_hold;
let src_in = hold.unwrap_or(c.source_in);
let src_out = if hold.is_some() { src_in + c.duration } else { c.source_out() };
let (start_f, end_f, in_f) = (frames_round(rate, c.start), frames_round(rate, c.end()), frames_round(rate, src_in));
// At normal speed (and on a freeze frame) the source span is the record span. Rounded on its own
// it can come out a frame shorter or longer than `end - start` (#340), so derive it from them.
let out_f = if hold.is_some() || c.speed.abs() == 1.0 { in_f.saturating_add(end_f.saturating_sub(start_f)) } else { frames_round(rate, src_out) };
self.w.open(tag, &[("id", xid)]);
if generator.is_none() && !is_seq {
let mid = self.master_id(base);
self.w.text("masterclipid", mid);
}
self.w.text("name", &c.name);
self.w.text("enabled", bool_str(c.enabled));
let media_dur = self.p.item(base).map(|i| i.duration()).unwrap_or(Tick::ZERO).max(src_out);
self.w.text("duration", frames_round(rate, media_dur).max(out_f));
write_rate(&mut self.w, rate);
self.w.text("start", start_f);
self.w.text("end", end_f);
self.w.text("in", in_f);
self.w.text("out", out_f);
self.w.text("pproTicksIn", src_in.0);
self.w.text("pproTicksOut", src_out.0);
if let Some(g) = &generator {
self.write_generator(g);
} else if is_seq {
self.write_sequence(base, false);
} else {
self.write_file(base, rate);
}
if kind == TrackKind::Audio {
self.w.open("sourcetrack", &[]);
self.w.text("mediatype", "audio");
self.w.text("trackindex", c.source_channels.first().map_or(1, |ch| u32::from(*ch).saturating_add(1)));
self.w.close();
}
if let Some(blend) = param(c, "opacity", "blend").and_then(|p| p.value.as_f64()).map(|v| v as u32).filter(|v| *v != 0) {
match BLEND_XML.iter().find(|(_, v)| *v == blend) {
Some((n, _)) => self.w.text("compositemode", n),
None => self.report.warn("blend mode not representable in FCP7 XML; Normal used"),
}
}
self.write_filters(c, kind, seq, base);
for (lid, lkind, ti, ci) in links {
self.w.open("link", &[]);
self.w.text("linkclipref", lid);
self.w.text("mediatype", if *lkind == TrackKind::Video { "video" } else { "audio" });
self.w.text("trackindex", ti);
self.w.text("clipindex", ci);
self.w.close();
}
self.w.open("labels", &[]);
self.w.text("label2", c.label.name());
self.w.close();
write_markers(&mut self.w, &c.markers, rate);
self.w.close();
}
fn write_generator(&mut self, g: &Generator) {
self.w.open("effect", &[]);
match g {
Generator::BlackVideo => {
self.w.text("name", "Slug");
self.w.text("effectid", "slug");
}
Generator::ColorMatte { color } => {
self.w.text("name", "Color");
self.w.text("effectid", "Color");
self.w.text("effectcategory", "Matte");
self.w.text("effecttype", "generator");
self.w.text("mediatype", "video");
self.w.open("parameter", &[]);
self.w.text("parameterid", "fillcolor");
self.w.text("name", "Color");
write_color(&mut self.w, *color);
self.w.close();
self.w.close();
return;
}
other => {
self.report.info(format!("generator \"{}\" is written with a FilmCraft effect id", other.label()));
self.w.text("name", other.label());
self.w.text("effectid", format!("filmcraft:{}", serde_json::to_string(other).unwrap_or_default()));
}
}
self.w.text("effectcategory", "Matte");
self.w.text("effecttype", "generator");
self.w.text("mediatype", "video");
self.w.close();
}
fn write_file(&mut self, item: ItemId, seq_rate: FrameRate) {
if let Some(fid) = self.file_ids.get(&item) {
let fid = fid.clone();
self.w.empty("file", &[("id", &fid)]);
return;
}
let fid = format!("file-{}", self.file_ids.len() + 1);
self.file_ids.insert(item, fid.clone());
let Some(m) = item_media(self.p, item) else {
self.w.empty("file", &[("id", &fid)]);
return;
};
let name = self.p.item(item).map(|i| i.name.clone()).unwrap_or_default();
let frate = m.info.video.as_ref().map(|v| m.interpret.frame_rate.unwrap_or(v.frame_rate)).unwrap_or(seq_rate);
self.w.open("file", &[("id", &fid)]);
let path = item_path(self.p, item).unwrap_or("");
self.w.text("name", if name.is_empty() { file_name(path).to_string() } else { name });
if crate::common::is_absolute(path) {
self.w.text("pathurl", path_to_file_url(path, true));
} else {
self.w.text("pathurl", path);
}
write_rate(&mut self.w, frate);
self.w.text("duration", frames_round(frate, m.info.duration));
let tc = m.info.start_timecode.unwrap_or(0);
self.write_timecode(tc, frate, false);
self.w.open("media", &[]);
if let Some(v) = &m.info.video {
self.w.open("video", &[]);
self.w.open("samplecharacteristics", &[]);
write_rate(&mut self.w, frate);
self.w.text("width", v.width);
self.w.text("height", v.height);
self.w.text("anamorphic", "FALSE");
self.w.text("pixelaspectratio", if v.par == (1, 1) { "square" } else { "custom" });
self.w.text("fielddominance", "none");
self.w.close();
self.w.close();
}
if let Some(a) = m.info.audio() {
self.w.open("audio", &[]);
self.w.open("samplecharacteristics", &[]);
self.w.text("depth", a.bits_per_sample.unwrap_or(16));
self.w.text("samplerate", a.sample_rate);
self.w.close();
self.w.text("channelcount", a.channels);
self.w.close();
}
self.w.close();
self.w.close();
}
fn write_filters(&mut self, c: &TrackItem, kind: TrackKind, seq: &Sequence, base: ItemId) {
let rate = seq.settings.frame_rate;
let (fw, fh) = (seq.settings.width as f64, seq.settings.height as f64);
let (sw, sh) = match self.p.item(base).map(|i| &i.kind) {
Some(ItemKind::Media(m)) => m.info.video.as_ref().map(|v| (v.width as f64, v.height as f64)).unwrap_or((fw, fh)),
Some(ItemKind::Sequence(s)) => (s.settings.width as f64, s.settings.height as f64),
_ => (fw, fh),
};
if kind == TrackKind::Video {
let motion_changed = ["position", "scale", "scale_width", "rotation", "anchor", "anti_flicker"].iter().any(|p| param_modified(c, "motion", p));
if motion_changed {
if param_modified(c, "motion", "scale_width") || param(c, "motion", "uniform_scale").and_then(|p| p.value.as_bool()) == Some(false) {
self.report.warn("non-uniform scale is not supported by FCP7 Basic Motion; uniform scale written");
}
let enabled = c.effect("motion").is_none_or(|e| e.enabled);
self.open_effect("Basic Motion", "basic", "motion", "motion", "video", enabled);
self.float_param(c, FloatParam { effect: "motion", pid: "scale", label: "Scale", min: 0.0, max: 1000.0, xml_id: "scale" }, rate, |v| v);
self.float_param(
c,
FloatParam { effect: "motion", pid: "rotation", label: "Rotation", min: -8640.0, max: 8640.0, xml_id: "rotation" },
rate,
|v| v,
);
self.point_param(c, PointParam { effect: "motion", pid: "position", label: "Center", xml_id: "center", size: (fw, fh) }, rate, |v| {
((v.x - fw / 2.0) / fw, (v.y - fh / 2.0) / fh)
});
self.point_param(c, PointParam { effect: "motion", pid: "anchor", label: "Anchor Point", xml_id: "centerOffset", size: (sw, sh) }, rate, |v| {
((v.x - sw / 2.0) / sw, (v.y - sh / 2.0) / sh)
});
if param_modified(c, "motion", "anti_flicker") {
self.float_param(
c,
FloatParam { effect: "motion", pid: "anti_flicker", label: "Anti-flicker Filter", min: 0.0, max: 1.0, xml_id: "antiflicker" },
rate,
|v| v,
);
}
self.close_effect();
}
if param_modified(c, "opacity", "opacity") {
self.open_effect("Opacity", "opacity", "motion", "motion", "video", true);
self.float_param(c, FloatParam { effect: "opacity", pid: "opacity", label: "opacity", min: 0.0, max: 100.0, xml_id: "opacity" }, rate, |v| v);
self.close_effect();
}
if c.speed != 1.0 || c.reverse || c.frame_hold.is_some() {
if param(c, "time_remap", "speed").is_some_and(|p| p.is_animated()) {
self.report.warn("speed ramps (time remapping keyframes) are not exported to FCP7 XML");
}
self.open_effect("Time Remap", "timeremap", "motion", "motion", "video", true);
let sp = if c.frame_hold.is_some() { 0.0 } else { c.speed * 100.0 };
self.simple_param("variablespeed", "variablespeed", "0");
self.simple_param("speed", "speed", &num(sp));
self.simple_param("reverse", "reverse", bool_str(c.reverse));
self.simple_param("frameblending", "frameblending", "FALSE");
self.close_effect();
}
} else {
if c.gain_db != 0.0 {
self.report.info("clip gain was folded into Audio Levels");
}
if param_modified(c, "volume", "level") || c.gain_db != 0.0 {
let g = c.gain_db;
self.open_effect("Audio Levels", "audiolevels", "audiolevels", "audiolevels", "audio", true);
self.float_param(c, FloatParam { effect: "volume", pid: "level", label: "Level", min: 0.0, max: 3.98109, xml_id: "level" }, rate, move |v| {
db_to_gain(v + g)
});
self.close_effect();
}
// A one-channel clip says where it is panned even when centred: without Audio Pan the
// importer pans the halves of a split stereo file to their sides (#371).
if param_modified(c, "panner", "balance") || c.source_channels.len() == 1 {
self.open_effect("Audio Pan", "audiopan", "audiopan", "audiopan", "audio", true);
self.float_param(c, FloatParam { effect: "panner", pid: "balance", label: "Pan", min: -1.0, max: 1.0, xml_id: "pan" }, rate, |v| v / 100.0);
self.close_effect();
}
if param_modified(c, "channel_volume", "left") || param_modified(c, "channel_volume", "right") {
self.report.warn("Channel Volume is not supported by FCP7 XML and was not exported");
}
}
for e in standard_effects(c) {
self.generic_effect(e, kind, rate);
}
}
fn open_effect(&mut self, name: &str, id: &str, category: &str, etype: &str, media: &str, enabled: bool) {
self.w.open("filter", &[]);
if !enabled {
self.w.text("enabled", "FALSE");
}
self.w.open("effect", &[]);
self.w.text("name", name);
self.w.text("effectid", id);
self.w.text("effectcategory", category);
self.w.text("effecttype", etype);
self.w.text("mediatype", media);
}
fn close_effect(&mut self) {
self.w.close();
self.w.close();
}
fn simple_param(&mut self, id: &str, name: &str, value: &str) {
self.w.open("parameter", &[]);
self.w.text("parameterid", id);
self.w.text("name", name);
self.w.text("value", value);
self.w.close();
}
fn float_param(&mut self, c: &TrackItem, spec: FloatParam, rate: FrameRate, map: impl Fn(f64) -> f64) {
let FloatParam { effect, pid, label, min, max, xml_id } = spec;
let default = find_effect(effect).and_then(|d| d.param(pid)).and_then(|p| p.default.as_f64()).unwrap_or(0.0);
let p = param(c, effect, pid).cloned().unwrap_or_else(|| Param::new(ParamValue::Float(default)));
self.w.open("parameter", &[]);
self.w.text("parameterid", xml_id);
self.w.text("name", label);
self.w.text("valuemin", num(min));
self.w.text("valuemax", num(max));
self.w.text("value", num(map(p.value.as_f64().unwrap_or(default))));
self.keyframes(&p, rate, |v| v.as_f64().map(|x| num(map(x))), None::<fn(&mut XmlWriter, &ParamValue)>);
self.w.close();
}
fn point_param(&mut self, c: &TrackItem, spec: PointParam, rate: FrameRate, map: impl Fn(Vec2) -> (f64, f64)) {
let PointParam { effect, pid, label, xml_id, size } = spec;
let centre = Vec2::new(size.0 / 2.0, size.1 / 2.0);
let fix = |v: Vec2| Vec2::new(if v.x.is_nan() { centre.x } else { v.x }, if v.y.is_nan() { centre.y } else { v.y });
let p = param(c, effect, pid).cloned().unwrap_or_else(|| Param::new(ParamValue::Vec2(centre)));
self.w.open("parameter", &[]);
self.w.text("parameterid", xml_id);
self.w.text("name", label);
let (x, y) = map(fix(p.value.as_vec2().unwrap_or(centre)));
self.w.open("value", &[]);
self.w.text("horiz", num(x));
self.w.text("vert", num(y));
self.w.close();
for k in &p.keyframes {
let (kx, ky) = map(fix(k.value.as_vec2().unwrap_or(centre)));
self.w.open("keyframe", &[]);
self.w.text("when", frames_round(rate, k.time));
self.w.open("value", &[]);
self.w.text("horiz", num(kx));
self.w.text("vert", num(ky));
self.w.close();
self.write_interp(k.interp);
self.w.close();
}
self.w.close();
}
fn write_interp(&mut self, i: Interpolation) {
match i {
Interpolation::Linear => {}
Interpolation::Hold => {
self.w.open("interpolation", &[]);
self.w.text("name", "hold");
self.w.close();
}
_ => {
self.report.info("Bezier keyframe easing is written as FCP curve keyframes (handles not preserved)");
self.w.open("interpolation", &[]);
self.w.text("name", "FCPCurve");
self.w.close();
}
}
}
fn keyframes(&mut self, p: &Param, rate: FrameRate, val: impl Fn(&ParamValue) -> Option<String>, _custom: Option<fn(&mut XmlWriter, &ParamValue)>) {
for k in &p.keyframes {
let Some(v) = val(&k.value) else { continue };
if !on_frame(rate, k.time) {
self.report.info("sub-frame keyframes were rounded to frames");
}
self.w.open("keyframe", &[]);
self.w.text("when", frames_round(rate, k.time));
self.w.text("value", v);
self.write_interp(k.interp);
self.w.close();
}
}
fn generic_effect(&mut self, e: &EffectInstance, kind: TrackKind, rate: FrameRate) {
let Some(def) = e.def() else {
self.report.warn(format!("unknown effect \"{}\" was not exported", e.effect));
return;
};
let media = if kind == TrackKind::Video { "video" } else { "audio" };
// the name an export has always written, so a UI rename does not change the file
self.open_effect(filmcraft_project::interchange_name(def), def.id, def.category.get(1).copied().unwrap_or("Filter"), "filter", media, e.enabled);
for pd in &def.params {
let Some(p) = e.params.get(pd.id) else { continue };
match &p.value {
ParamValue::Float(v) => {
self.w.open("parameter", &[]);
self.w.text("parameterid", pd.id);
self.w.text("name", pd.label);
self.w.text("value", num(*v));
self.keyframes(p, rate, |v| v.as_f64().map(num), None::<fn(&mut XmlWriter, &ParamValue)>);
self.w.close();
}
ParamValue::Vec2(v) => {
self.w.open("parameter", &[]);
self.w.text("parameterid", pd.id);
self.w.text("name", pd.label);
self.w.open("value", &[]);
self.w.text("horiz", num(if v.x.is_nan() { 0.0 } else { v.x }));
self.w.text("vert", num(if v.y.is_nan() { 0.0 } else { v.y }));
self.w.close();
self.w.close();
if p.is_animated() {
self.report.warn(format!("point keyframes of \"{}\" were not exported", def.name));
}
}
ParamValue::Bool(b) => self.simple_param(pd.id, pd.label, bool_str(*b)),
ParamValue::Choice(c) => self.simple_param(pd.id, pd.label, &c.to_string()),
ParamValue::Text(t) => self.simple_param(pd.id, pd.label, t),
ParamValue::Color(c) => {
self.w.open("parameter", &[]);
self.w.text("parameterid", pd.id);
self.w.text("name", pd.label);
write_color(&mut self.w, *c);
self.w.close();
}
ParamValue::Curve(_) | ParamValue::Path(_) => {
self.report.warn(format!("curve parameters of \"{}\" are not supported by FCP7 XML", def.name));
}
}
}
self.close_effect();
}
}
fn write_color(w: &mut XmlWriter, c: [f32; 4]) {
let b = |v: f32| ((v.clamp(0.0, 1.0) * 255.0).round() as i64).to_string();
w.open("value", &[]);
w.text("alpha", b(c[3]));
w.text("red", b(c[0]));
w.text("green", b(c[1]));
w.text("blue", b(c[2]));
w.close();
}
fn write_markers(w: &mut XmlWriter, markers: &[Marker], rate: FrameRate) {
for m in markers {
w.open("marker", &[]);
w.text("comment", &m.comment);
w.text("name", &m.name);
let i = frames_round(rate, m.start);
w.text("in", i);
w.text("out", if m.duration > Tick::ZERO { frames_round(rate, m.start + m.duration) } else { -1 });
w.text("color", m.color.name());
w.close();
}
}
/// Frame rate and frame size an imported track's clips are read against.
#[derive(Clone, Copy)]
struct TrackFormat {
rate: FrameRate,
frame: (u32, u32),
}
/// Identity, label and range of a float effect parameter in the exported XML.
struct FloatParam<'a> {
effect: &'a str,
pid: &'a str,
label: &'a str,
min: f64,
max: f64,
xml_id: &'a str,
}
/// Identity, label and frame size of a point effect parameter in the exported XML.
struct PointParam<'a> {
effect: &'a str,
pid: &'a str,
label: &'a str,
xml_id: &'a str,
size: (f64, f64),
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.