f67d38b35cc5
otio.rs
//! OpenTimelineIO JSON (`.otio`).
//!
//! Schemas read and written: `Timeline.1`, `Stack.1`, `Track.1`, `Clip.1`/`Clip.2`, `Gap.1`,
//! `Transition.1`, `Marker.1`/`Marker.2`, `ExternalReference.1`, `MissingReference.1`,
//! `GeneratorReference.1`, `LinearTimeWarp.1`, `FreezeFrame.1`, `Effect.1`, `RationalTime.1`,
//! `TimeRange.1` and `SerializableCollection.1` (several timelines).
//!
//! Times are written as frames at the sequence rate (`rate` is the exact rate as a float, e.g.
//! 23.976023976023978) and read back exactly by snapping the rate to its rational form. Fields
//! OTIO has no schema for (effects and their keyframes, labels, links, groups, clip gain, track
//! state, sequence settings, media info, generators) round-trip through `metadata.filmcraft`.
//! Nested sequences are `Stack` items inside tracks.
use std::collections::HashMap;
use filmcraft_media::{Generator, MediaInfo};
use filmcraft_project::{
ClipId, EffectInstance, ItemId, ItemKind, Label, Marker, MarkerId, MarkerKind, MediaRef, ParamValue, Project, Sequence, SequenceSettings, Track, TrackItem,
TrackKind, Transition, TransitionAlign, TransitionId,
};
use filmcraft_time::{FrameRate, TICKS_PER_SECOND, Tick};
use serde_json::{Value, json};
use crate::common::{
Builder, MAX_RATE, MediaSpec, base_item, empty_sequence, file_name, generator_of, item_media, path_to_file_url, rate_from_f64, relative_path, relative_url,
resolve_path, resolve_url, settings_for, transition_effect, transition_name,
};
use crate::{Error, ExportOptions, Format, ImportOptions, Imported, Report, Result};
// ---------------------------------------------------------------------------------------------
// Time
// ---------------------------------------------------------------------------------------------
fn rt(t: Tick, rate: FrameRate) -> Value {
let f = rate.frame_at(t);
let value = if rate.tick_of(f) == t { json!(f as f64) } else { json!(t.0 as f64 * rate.num as f64 / (rate.den as f64 * TICKS_PER_SECOND as f64)) };
json!({"OTIO_SCHEMA": "RationalTime.1", "rate": rate.as_f64(), "value": value})
}
fn tr(start: Tick, dur: Tick, rate: FrameRate) -> Value {
json!({"OTIO_SCHEMA": "TimeRange.1", "start_time": rt(start, rate), "duration": rt(dur, rate)})
}
/// RationalTime → ticks (exact for integral values at broadcast rates).
fn read_rt(v: &Value) -> Option<Tick> {
let rate = v.get("rate")?.as_f64()?;
let value = v.get("value")?.as_f64()?;
let r = rate_from_f64(rate);
if value == value.round() && value.abs() < 9e15 {
return Some(Tick::from_rational(value as i64, r.den, r.num));
}
Some(Tick((value * TICKS_PER_SECOND as f64 * r.den as f64 / r.num as f64).round() as i64))
}
/// Whether any `rate` in the document is beyond what [`rate_from_f64`] accepts.
fn has_absurd_rate(v: &Value) -> bool {
match v {
Value::Object(m) => m.iter().any(|(k, x)| if k == "rate" { x.as_f64().is_some_and(|r| r > MAX_RATE as f64) } else { has_absurd_rate(x) }),
Value::Array(a) => a.iter().any(has_absurd_rate),
_ => false,
}
}
fn read_rate(v: &Value) -> Option<FrameRate> {
v.get("rate").and_then(Value::as_f64).map(rate_from_f64)
}
fn read_tr(v: &Value) -> Option<(Tick, Tick)> {
if v.is_null() {
return None;
}
Some((read_rt(v.get("start_time")?)?, read_rt(v.get("duration")?)?))
}
fn schema(v: &Value) -> &str {
v.get("OTIO_SCHEMA").and_then(Value::as_str).unwrap_or("")
}
fn schema_name(v: &Value) -> &str {
schema(v).split('.').next().unwrap_or("")
}
fn fc(v: &Value) -> Option<&Value> {
v.get("metadata").and_then(|m| m.get("filmcraft"))
}
fn name_of(v: &Value) -> String {
v.get("name").and_then(Value::as_str).unwrap_or("").to_string()
}
fn color_name(l: Label) -> &'static str {
match l {
Label::Rose => "RED",
Label::Mango | Label::Tan => "ORANGE",
Label::Yellow => "YELLOW",
Label::Green | Label::Forest => "GREEN",
Label::Teal | Label::Caribbean => "CYAN",
Label::Blue | Label::Iris | Label::Cerulean => "BLUE",
Label::Violet | Label::Purple | Label::Lavender => "PURPLE",
Label::Magenta => "MAGENTA",
Label::Brown => "BLACK",
}
}
fn color_label(s: &str) -> Label {
match s.to_ascii_uppercase().as_str() {
"RED" => Label::Rose,
"PINK" | "MAGENTA" => Label::Magenta,
"ORANGE" => Label::Mango,
"YELLOW" => Label::Yellow,
"GREEN" => Label::Green,
"CYAN" => Label::Teal,
"BLUE" => Label::Blue,
"PURPLE" => Label::Purple,
"BLACK" => Label::Brown,
"WHITE" => Label::Lavender,
_ => Label::Green,
}
}
// ---------------------------------------------------------------------------------------------
// Export
// ---------------------------------------------------------------------------------------------
/// Most clips an export writes inside nested sequences. OTIO has no references: every use of a nested
/// sequence is written in full, so a compound clip that holds three uses of another, nested ten deep,
/// is 3^10 copies, and a 3 KB document made the export run for minutes and grow to gigabytes. Each
/// clip is about 10 KB of JSON, so this bounds the extra output near 250 MB; real projects use a
/// few thousand. Past it, further nested sequences are written as gaps, with a warning.
const MAX_NESTED_ITEMS: usize = 25_000;
struct Exp<'a, 'r> {
p: &'a Project,
opts: &'a ExportOptions,
report: &'r mut Report,
stack: Vec<ItemId>,
/// Clips written inside nested sequences so far, and the limit for it (see [`MAX_NESTED_ITEMS`]).
nested_items: usize,
nested_limit: usize,
}
pub(crate) fn export(p: &Project, seq_id: ItemId, opts: &ExportOptions, report: &mut Report) -> Result<String> {
let seq = p.sequence(seq_id).ok_or(Error::NoSequence(seq_id))?;
let rate = seq.settings.frame_rate;
let mut x = Exp { p, opts, report, stack: vec![seq_id], nested_items: 0, nested_limit: MAX_NESTED_ITEMS };
let name = opts.name.clone().unwrap_or_else(|| p.item(seq_id).map(|i| i.name.clone()).unwrap_or_default());
let stack = x.stack_json(seq_id, &name, None);
let tl = json!({
"OTIO_SCHEMA": "Timeline.1",
"name": name,
"global_start_time": rt(rate.tick_of(seq.start_timecode), rate),
"metadata": {"filmcraft": x.seq_meta(seq_id)},
"tracks": stack,
});
serde_json::to_string_pretty(&tl).map_err(|e| Error::Other(e.to_string()))
}
impl Exp<'_, '_> {
fn seq_meta(&self, id: ItemId) -> Value {
let Some((it, s)) = self.p.item(id).and_then(|it| Some((it, it.as_sequence()?))) else { return json!({}) };
json!({
"item": id.0, "custom_colors": self.p.custom_colors, "custom_color_names": self.p.custom_color_names,
"label": it.label, "custom_label_color": it.custom_label_color,
"settings": s.settings,
"start_timecode": s.start_timecode,
"master_volume_db": s.master_volume_db,
"master_effects": s.master_effects,
})
}
/// The `Stack` for a sequence; `range` = (source in, duration) when nested in a track.
fn stack_json(&mut self, id: ItemId, name: &str, range: Option<(Tick, Tick, FrameRate)>) -> Value {
let Some(seq) = self.p.sequence(id) else {
self.report.warn("missing nested sequence skipped");
return json!({"OTIO_SCHEMA": "Stack.1", "name": name, "children": [], "effects": [], "markers": [], "enabled": true, "metadata": {}});
};
let rate = seq.settings.frame_rate;
let mut tracks = Vec::new();
for kind in [TrackKind::Video, TrackKind::Audio] {
for t in seq.tracks(kind) {
tracks.push(self.track_json(t, kind, seq));
}
}
let markers: Vec<Value> = seq.markers.iter().map(|m| marker_json(m, rate)).collect();
json!({
"OTIO_SCHEMA": "Stack.1",
"name": name,
"children": tracks,
"source_range": range.map(|(s, d, r)| tr(s, d, r)).unwrap_or(Value::Null),
"effects": [],
"markers": markers,
"enabled": true,
"metadata": if range.is_some() { json!({"filmcraft": self.seq_meta(id)}) } else { json!({}) },
})
}
fn track_json(&mut self, t: &Track, kind: TrackKind, seq: &Sequence) -> Value {
let rate = seq.settings.frame_rate;
let mut children = Vec::new();
let mut pos = Tick::ZERO;
for it in &t.items {
if it.start > pos {
children.push(json!({"OTIO_SCHEMA": "Gap.1", "name": "", "source_range": tr(Tick::ZERO, it.start - pos, rate), "effects": [], "markers": [], "enabled": true, "metadata": {}}));
}
for x in t.transitions.iter().filter(|x| x.to == Some(it.id)) {
children.push(self.transition_json(x, it.start, rate));
}
children.push(self.item_json(it, kind, rate));
for x in t.transitions.iter().filter(|x| x.from == Some(it.id) && x.to.is_none()) {
children.push(self.transition_json(x, it.end(), rate));
}
pos = it.end();
}
json!({
"OTIO_SCHEMA": "Track.1",
"name": t.name,
"kind": if kind == TrackKind::Video { "Video" } else { "Audio" },
"children": children,
"source_range": null,
"effects": [],
"markers": [],
"enabled": t.enabled,
"metadata": {"filmcraft": {
"locked": t.locked, "sync_lock": t.sync_lock, "muted": t.muted, "solo": t.solo,
"channels": t.channels, "volume_db": t.volume_db, "pan": t.pan, "effects": t.effects,
}},
})
}
fn transition_json(&mut self, x: &Transition, cut: Tick, rate: FrameRate) -> Value {
let dissolve = matches!(x.effect.effect.as_str(), "cross_dissolve" | "constant_power" | "constant_gain" | "film_dissolve");
json!({
"OTIO_SCHEMA": "Transition.1",
"name": transition_name(&x.effect),
"transition_type": if dissolve { "SMPTE_Dissolve" } else { "Custom_Transition" },
"in_offset": rt(cut - x.start, rate),
"out_offset": rt(x.end() - cut, rate),
"metadata": {"filmcraft": {"effect": x.effect, "align": x.align, "reverse": x.reverse}},
})
}
fn media_ref(&mut self, item: ItemId, rate: FrameRate) -> Value {
let name = self.p.item(item).map(|i| i.name.clone()).unwrap_or_default();
let Some(m) = item_media(self.p, item) else {
return json!({"OTIO_SCHEMA": "MissingReference.1", "name": name, "available_range": null, "metadata": {}});
};
let avail = tr(m.info.start_timecode.map(|f| m.frame_rate().tick_of(f)).unwrap_or(Tick::ZERO), m.info.duration, rate);
let meta = json!({"filmcraft": {"item": item.0, "label": self.p.item(item).map(|i| i.label), "custom_label_color": self.p.item(item).and_then(|i| i.custom_label_color), "info": m.info, "offline": m.offline}});
match &m.media {
MediaRef::Generator(g) => json!({
"OTIO_SCHEMA": "GeneratorReference.1",
"name": name,
"generator_kind": match g { Generator::ColorMatte { .. } => "SolidColor", Generator::BlackVideo => "black", Generator::BarsAndTone => "SMPTEBars", _ => "FilmCraftGenerator" },
"parameters": match g { Generator::ColorMatte { color } => json!({"color": color}), _ => json!({}) },
"available_range": avail,
"metadata": {"filmcraft": {"item": item.0, "generator": g, "info": m.info, "label": self.p.item(item).map(|i| i.label), "custom_label_color": self.p.item(item).and_then(|i| i.custom_label_color)}},
}),
MediaRef::File { path } => {
let url = match &self.opts.relative_to {
Some(base) => relative_path(path, base).map(|r| relative_url(&r)).unwrap_or_else(|| abs_url(path)),
None => abs_url(path),
};
json!({"OTIO_SCHEMA": "ExternalReference.1", "name": name, "target_url": url, "available_range": avail, "available_image_bounds": null, "metadata": meta})
}
}
}
fn item_json(&mut self, it: &TrackItem, kind: TrackKind, rate: FrameRate) -> Value {
if self.stack.len() > 1 {
self.nested_items = self.nested_items.saturating_add(1);
}
let base = base_item(self.p, it.item);
let mut effects = Vec::new();
if let Some(h) = it.frame_hold {
effects.push(
json!({"OTIO_SCHEMA": "FreezeFrame.1", "name": "", "effect_name": "FreezeFrame", "time_scalar": 0.0, "metadata": {"filmcraft": {"hold": h}}}),
);
} else if it.speed != 1.0 || it.reverse {
let s = if it.reverse { -it.speed } else { it.speed };
effects.push(json!({"OTIO_SCHEMA": "LinearTimeWarp.1", "name": "", "effect_name": "LinearTimeWarp", "time_scalar": s, "metadata": {}}));
}
let meta = json!({"filmcraft": {
"label": it.label, "custom_label_color": it.custom_label_color, "link": it.link, "group": it.group, "effects": it.effects,
"gain_db": it.gain_db, "scale_to_frame": it.scale_to_frame, "source_in_ticks": it.source_in.0,
"duration_ticks": it.duration.0,
}});
let markers: Vec<Value> = it.markers.iter().map(|m| marker_json(m, rate)).collect();
let _ = kind;
if matches!(self.p.item(base).map(|i| &i.kind), Some(ItemKind::Sequence(_))) {
if self.stack.contains(&base) {
self.report.warn("recursive nested sequence skipped");
return json!({"OTIO_SCHEMA": "Gap.1", "name": "", "source_range": tr(Tick::ZERO, it.duration, rate), "effects": [], "markers": [], "enabled": true, "metadata": {}});
}
if self.nested_items >= self.nested_limit {
// once: later nested sequences hit this too, and the message would repeat
if self.nested_items < usize::MAX {
self.nested_items = usize::MAX;
self.report.warn(format!(
"more than {} clips written inside nested sequences: the rest are gaps (OTIO repeats a nested sequence for every use)",
self.nested_limit
));
}
return json!({"OTIO_SCHEMA": "Gap.1", "name": "", "source_range": tr(Tick::ZERO, it.duration, rate), "effects": [], "markers": [], "enabled": true, "metadata": {}});
}
self.stack.push(base);
let mut s = self.stack_json(base, &it.name, Some((it.source_in, it.duration, rate)));
self.stack.pop();
s["effects"] = json!(effects);
s["enabled"] = json!(it.enabled);
s["metadata"]["filmcraft"]["clip"] = meta["filmcraft"].clone();
// Nested sequence markers stay on the Stack; clip instance markers live on the clip metadata.
s["metadata"]["filmcraft"]["clip"]["markers"] = json!(markers);
return s;
}
let _ = generator_of(self.p, base);
if let Some(clip) = crate::common::uncarried_clip(self.p, it, rate) {
self.report
.warn(format!("{clip} has no OTIO equivalent: it is written as a clip with a missing media reference and is read back as offline media"));
}
let mref = self.media_ref(base, rate);
// OTIO source times are in the reference's time (which starts at its available_range start).
let origin = item_media(self.p, base).and_then(|m| m.info.start_timecode.map(|f| m.frame_rate().tick_of(f))).unwrap_or(Tick::ZERO);
let markers: Vec<Value> = it.markers.iter().map(|m| marker_json(&Marker { start: m.start + origin, ..m.clone() }, rate)).collect();
json!({
"OTIO_SCHEMA": "Clip.2",
"name": it.name,
"source_range": tr(origin + it.source_in, it.duration, rate),
"effects": effects,
"markers": markers,
"enabled": it.enabled,
"media_references": {"DEFAULT_MEDIA": mref},
"active_media_reference_key": "DEFAULT_MEDIA",
"metadata": meta,
})
}
}
fn abs_url(path: &str) -> String {
if crate::common::is_absolute(path) { path_to_file_url(path, false) } else { path.to_string() }
}
fn marker_json(m: &Marker, rate: FrameRate) -> Value {
json!({
"OTIO_SCHEMA": "Marker.2",
"name": m.name,
"comment": m.comment,
"color": color_name(m.color),
"marked_range": tr(m.start, m.duration, rate),
"metadata": {"filmcraft": {"kind": m.kind, "url": m.url, "label": m.color, "custom_color": m.custom_color, "author": m.author, "start_ticks": m.start.0, "duration_ticks": m.duration.0}},
})
}
/// JSON turns NaN (our "auto" point defaults) into `null`; restore it when reading effects back.
const NAN_SENTINEL: f64 = 1.0e308;
fn null_to_sentinel(v: &mut Value) {
match v {
Value::Object(o) => {
for (k, x) in o.iter_mut() {
if x.is_null() && (k == "x" || k == "y") {
*x = json!(NAN_SENTINEL);
} else {
null_to_sentinel(x);
}
}
}
Value::Array(a) => a.iter_mut().for_each(null_to_sentinel),
_ => {}
}
}
fn effects_from(v: Option<&Value>) -> Option<Vec<EffectInstance>> {
let mut v = v?.clone();
null_to_sentinel(&mut v);
let mut effects: Vec<EffectInstance> = serde_json::from_value(v).ok()?;
let fix = |p: &mut ParamValue| {
if let ParamValue::Vec2(v) = p {
if v.x == NAN_SENTINEL {
v.x = f64::NAN;
}
if v.y == NAN_SENTINEL {
v.y = f64::NAN;
}
}
};
for e in &mut effects {
for p in e.params.values_mut() {
fix(&mut p.value);
p.keyframes.iter_mut().for_each(|k| fix(&mut k.value));
}
}
Some(effects)
}
// ---------------------------------------------------------------------------------------------
// Import
// ---------------------------------------------------------------------------------------------
struct Imp<'a, 'r> {
b: Builder,
opts: &'a ImportOptions,
report: &'r mut Report,
links: HashMap<u64, u64>,
groups: HashMap<u64, u64>,
}
pub(crate) fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result<Imported> {
let v: Value = serde_json::from_str(text).map_err(|e| Error::parse(Format::Otio, e.to_string()))?;
let mut timelines = Vec::new();
collect_timelines(&v, &mut timelines);
if timelines.is_empty() {
return Err(Error::parse(Format::Otio, format!("no Timeline in a {} document", schema(&v))));
}
if has_absurd_rate(&v) {
report.warn(format!(
"an OTIO rate above {MAX_RATE} per second is not a frame rate; the default 24 fps was used (this includes audio sample rates above it, such as DSD)"
));
}
let mut imp = Imp { b: Builder::new(&name_of(&v)), opts, report, links: HashMap::new(), groups: HashMap::new() };
if imp.b.p.name.is_empty() {
imp.b.p.name = "Imported OTIO".into();
}
for tl in timelines {
let id = imp.timeline(tl);
imp.b.top.push(id);
}
Ok(imp.b.finish())
}
fn collect_timelines<'v>(v: &'v Value, out: &mut Vec<&'v Value>) {
match schema_name(v) {
"Timeline" | "Stack" => out.push(v),
"SerializableCollection" => {
for c in v.get("children").and_then(Value::as_array).into_iter().flatten() {
collect_timelines(c, out);
}
}
"Track" => out.push(v),
_ => {}
}
}
/// The rate of the first item a sequence can run at. Items at an audio sample rate (a gap or
/// clip at 48000 is valid OTIO) are skipped: no sequence runs at 48000 fps.
fn first_rate(v: &Value) -> Option<FrameRate> {
if let Some(sr) = v.get("source_range").filter(|s| !s.is_null()) {
return sr.get("duration").and_then(read_rate).filter(|&r| sequence_rate(r));
}
v.get("children").and_then(Value::as_array).into_iter().flatten().find_map(first_rate)
}
fn sequence_rate(rate: FrameRate) -> bool {
settings_for(rate, 1920, 1080, false).validate().is_ok()
}
impl Imp<'_, '_> {
/// Union each timeline's saved palette into the project's 64 retained colors.
/// Keep the first valid name, fill missing names even at capacity, and never keep orphan names.
fn merge_palette(&mut self, meta: Option<&Value>) {
if let Some(colors) = meta.and_then(|m| m.get("custom_colors")).and_then(Value::as_array) {
let mut overflow = false;
for color in colors.iter().filter_map(Value::as_str).filter_map(filmcraft_project::HexColor::parse) {
if self.b.p.custom_colors.contains(&color) {
continue;
}
if self.b.p.custom_colors.len() >= 64 {
overflow = true;
break;
}
self.b.p.custom_colors.push(color);
}
if overflow {
self.report.warn("OTIO saved palettes exceed the 64-color project limit; additional colors were not imported.");
}
}
if let Some(names) = meta.and_then(|m| m.get("custom_color_names")).and_then(Value::as_object) {
// Palette membership bounds retained names to 64; orphan input entries consume no slots.
for (key, value) in names {
if let (Some(color), Some(name)) = (filmcraft_project::HexColor::parse(key), value.as_str())
&& self.b.p.custom_colors.contains(&color)
&& name.len() <= 128
&& !name.chars().any(char::is_control)
{
self.b.p.custom_color_names.entry(color).or_insert_with(|| name.to_owned());
}
}
}
}
fn timeline(&mut self, tl: &Value) -> ItemId {
let name = name_of(tl);
let name = if name.is_empty() { self.opts.name.clone().unwrap_or_else(|| "Timeline".into()) } else { name };
let stack_owned;
let stack = match schema_name(tl) {
"Timeline" => tl.get("tracks").unwrap_or(&Value::Null),
"Track" => {
stack_owned = json!({"OTIO_SCHEMA": "Stack.1", "children": [tl.clone()]});
&stack_owned
}
_ => tl,
};
let meta = fc(tl).or_else(|| fc(stack));
self.merge_palette(meta);
let rate = tl.get("global_start_time").and_then(read_rate).filter(|&r| sequence_rate(r)).or_else(|| first_rate(stack)).unwrap_or_default();
let id = self.sequence(stack, &name, meta, rate);
if let Some(st) = tl.get("global_start_time").and_then(read_rt)
&& let Some(s) = self.b.p.sequence_mut(id)
{
s.start_timecode = s.settings.frame_rate.frame_at(st);
}
id
}
fn sequence(&mut self, stack: &Value, name: &str, meta: Option<&Value>, rate: FrameRate) -> ItemId {
let settings: SequenceSettings =
meta.and_then(|m| m.get("settings")).and_then(|s| serde_json::from_value(s.clone()).ok()).unwrap_or_else(|| settings_for(rate, 1920, 1080, false));
let id = self.b.reserve_sequence(name, settings.clone(), None);
if let Some(l) = meta.and_then(|m| m.get("label")).and_then(|l| serde_json::from_value::<Label>(l.clone()).ok())
&& let Some(it) = self.b.p.item_mut(id)
{
it.label = l;
}
if let Some(it) = self.b.p.item_mut(id) {
it.custom_label_color = meta.and_then(|m| m.get("custom_label_color")).and_then(Value::as_str).and_then(filmcraft_project::HexColor::parse);
}
let mut seq = empty_sequence(settings);
if let Some(m) = meta {
seq.start_timecode = m.get("start_timecode").and_then(Value::as_i64).unwrap_or(0);
seq.master_volume_db = m.get("master_volume_db").and_then(Value::as_f64).unwrap_or(0.0);
seq.master_effects = effects_from(m.get("master_effects")).unwrap_or_default();
}
seq.markers = self.markers(stack);
for t in stack.get("children").and_then(Value::as_array).into_iter().flatten() {
match schema_name(t) {
"Track" => {
let kind = if t.get("kind").and_then(Value::as_str) == Some("Audio") { TrackKind::Audio } else { TrackKind::Video };
self.track(&mut seq, t, kind);
}
other => self.report.warn(format!("OTIO {other} directly in a stack is not supported")),
}
}
self.b.ensure_tracks(&mut seq, TrackKind::Video, 1);
self.b.ensure_tracks(&mut seq, TrackKind::Audio, 1);
self.b.put_sequence(id, seq);
id
}
fn track(&mut self, seq: &mut Sequence, t: &Value, kind: TrackKind) {
let idx = seq.tracks(kind).len();
let mut track = self.b.track(kind, idx);
let n = name_of(t);
if !n.is_empty() {
track.name = n;
}
track.enabled = t.get("enabled").and_then(Value::as_bool).unwrap_or(true);
if let Some(m) = fc(t) {
let g = |k: &str| m.get(k).and_then(Value::as_bool);
track.locked = g("locked").unwrap_or(false);
track.sync_lock = g("sync_lock").unwrap_or(true);
track.muted = g("muted").unwrap_or(false);
track.solo = g("solo").unwrap_or(false);
track.volume_db = m.get("volume_db").and_then(Value::as_f64).unwrap_or(0.0);
track.pan = m.get("pan").and_then(Value::as_f64).unwrap_or(0.0);
if let Some(c) = m.get("channels").and_then(|c| serde_json::from_value(c.clone()).ok()) {
track.channels = c;
}
track.effects = effects_from(m.get("effects")).unwrap_or_default();
}
if t.get("markers").and_then(Value::as_array).is_some_and(|m| !m.is_empty()) {
let ms = self.markers(t);
seq.markers.extend(ms);
seq.markers.sort_by_key(|m| m.start);
}
// (position in children list, clip at that slot or None for gaps)
let mut slots: Vec<(Option<ClipId>, Tick, Tick)> = Vec::new();
let mut pending: Vec<(usize, &Value)> = Vec::new();
let mut pos = Tick::ZERO;
let kids = t.get("children").and_then(Value::as_array).cloned().unwrap_or_default();
for c in &kids {
match schema_name(c) {
"Transition" => {
pending.push((slots.len(), c));
continue;
}
"Gap" => {
let d = c.get("source_range").and_then(read_tr).map(|r| r.1).unwrap_or(Tick::ZERO);
slots.push((None, pos, pos + d));
pos += d;
}
"Clip" | "Stack" => {
let item = if schema_name(c) == "Clip" { self.clip(c, kind, pos) } else { self.nested(c, kind, pos) };
match item {
Some(ti) => {
let (s, e, id) = (ti.start, ti.end(), ti.id);
track.items.push(ti);
slots.push((Some(id), s, e));
pos = e;
}
None => {
let d = c.get("source_range").and_then(read_tr).map(|r| r.1).unwrap_or(Tick::ZERO);
slots.push((None, pos, pos + d));
pos += d;
}
}
}
other => {
self.report.warn(format!("OTIO {other} items are not supported and were skipped"));
}
}
}
for (slot, c) in pending {
let cut = if slot < slots.len() { slots[slot].1 } else { pos };
let from = slot.checked_sub(1).and_then(|i| slots[i].0);
let to = slots.get(slot).and_then(|s| s.0);
if from.is_none() && to.is_none() {
continue;
}
let inn = c.get("in_offset").and_then(read_rt).unwrap_or(Tick::ZERO);
let out = c.get("out_offset").and_then(read_rt).unwrap_or(Tick::ZERO);
let meta = fc(c);
let effect: EffectInstance = match meta.and_then(|m| m.get("effect")).and_then(|e| effects_from(Some(&json!([e])))).and_then(|mut v| v.pop()) {
Some(e) => e,
None => {
let n = name_of(c);
let ty = c.get("transition_type").and_then(Value::as_str).unwrap_or("SMPTE_Dissolve");
transition_effect(if n.is_empty() { ty } else { &n }, kind == TrackKind::Audio, self.report)
}
};
let align = meta.and_then(|m| m.get("align")).and_then(|a| serde_json::from_value(a.clone()).ok()).unwrap_or(if inn == Tick::ZERO {
TransitionAlign::StartAtCut
} else if out == Tick::ZERO {
TransitionAlign::EndAtCut
} else {
TransitionAlign::CenterAtCut
});
let reverse = meta.and_then(|m| m.get("reverse")).and_then(Value::as_bool).unwrap_or(false);
track.transitions.push(Transition { id: TransitionId(self.b.alloc()), effect, start: cut - inn, duration: inn + out, from, to, align, reverse });
}
track.sort();
seq.tracks_mut(kind).push(track);
}
fn apply_clip_meta(&mut self, ti: &mut TrackItem, c: &Value, meta: Option<&Value>) {
ti.enabled = c.get("enabled").and_then(Value::as_bool).unwrap_or(true);
for e in c.get("effects").and_then(Value::as_array).into_iter().flatten() {
match schema_name(e) {
"LinearTimeWarp" => {
let s = e.get("time_scalar").and_then(Value::as_f64).unwrap_or(1.0);
if s == 0.0 {
ti.frame_hold = Some(ti.source_in);
} else {
ti.speed = s.abs();
ti.reverse = s < 0.0;
}
}
"FreezeFrame" => {
ti.frame_hold = Some(fc(e).and_then(|m| m.get("hold")).and_then(|h| h.as_i64()).map(Tick).unwrap_or(ti.source_in));
}
_ => {
if meta.and_then(|m| m.get("effects")).is_none() {
let n = e.get("effect_name").and_then(Value::as_str).unwrap_or("effect");
self.report.warn(format!("OTIO effect \"{n}\" is not supported"));
}
}
}
}
let Some(m) = meta else { return };
ti.custom_label_color = m.get("custom_label_color").and_then(Value::as_str).and_then(filmcraft_project::HexColor::parse);
if let Some(l) = m.get("label").and_then(|l| serde_json::from_value::<Label>(l.clone()).ok()) {
ti.label = l;
}
if let Some(effects) = effects_from(m.get("effects")) {
ti.effects = effects;
}
if let Some(l) = m.get("link").and_then(Value::as_u64) {
let next = self.b.link_id();
ti.link = Some(*self.links.entry(l).or_insert(next));
}
if let Some(g) = m.get("group").and_then(Value::as_u64) {
let next = self.b.alloc();
ti.group = Some(*self.groups.entry(g).or_insert(next));
}
ti.gain_db = m.get("gain_db").and_then(Value::as_f64).unwrap_or(0.0);
ti.scale_to_frame = m.get("scale_to_frame").and_then(Value::as_bool).unwrap_or(false);
// Exact ticks for sub-frame values (audio) when the rational values were rounded.
if let Some(s) = m.get("source_in_ticks").and_then(Value::as_i64)
&& (Tick(s) - ti.source_in).abs() < Tick(TICKS_PER_SECOND / 1000)
{
ti.source_in = Tick(s);
if let Some(h) = &mut ti.frame_hold
&& c.get("effects").and_then(Value::as_array).is_some_and(|e| e.iter().any(|x| schema_name(x) == "LinearTimeWarp"))
{
*h = Tick(s);
}
}
if let Some(d) = m.get("duration_ticks").and_then(Value::as_i64)
&& (Tick(d) - ti.duration).abs() < Tick(TICKS_PER_SECOND / 1000)
{
ti.duration = Tick(d);
}
}
fn clip(&mut self, c: &Value, kind: TrackKind, pos: Tick) -> Option<TrackItem> {
let mref = match c.get("media_references") {
Some(refs) => {
let key = c.get("active_media_reference_key").and_then(Value::as_str).unwrap_or("DEFAULT_MEDIA");
refs.get(key).or_else(|| refs.as_object().and_then(|o| o.values().next()))
}
None => c.get("media_reference"),
}
.cloned()
.unwrap_or(Value::Null);
let name = name_of(c);
let avail = mref.get("available_range").and_then(read_tr);
let (src_in, dur) = c.get("source_range").and_then(read_tr).or(avail)?;
if dur <= Tick::ZERO {
return None;
}
let item = self.media(&mref, &name, kind, avail)?;
// Sources are media time: subtract the media's start time (available_range start).
let origin = avail.map(|a| a.0).unwrap_or(Tick::ZERO);
let mut ti = self.b.clip(item, kind, if name.is_empty() { "Clip" } else { &name }, pos, dur, src_in - origin);
ti.markers = self.markers(c);
for m in &mut ti.markers {
m.start -= origin;
}
let meta = fc(c).cloned();
self.apply_clip_meta(&mut ti, c, meta.as_ref());
Some(ti)
}
fn nested(&mut self, c: &Value, kind: TrackKind, pos: Tick) -> Option<TrackItem> {
let (src_in, dur) = c.get("source_range").and_then(read_tr)?;
let meta = fc(c);
let key = format!("stack:{}", meta.and_then(|m| m.get("item")).and_then(Value::as_u64).map(|i| i.to_string()).unwrap_or_else(|| name_of(c)));
let item = match self.b.find_media(&key) {
Some(i) => i,
None => {
let rate = first_rate(c).unwrap_or_default();
let mut inner = c.clone();
inner["source_range"] = Value::Null;
let name = name_of(c);
let id = self.sequence(&inner, if name.is_empty() { "Nested Sequence" } else { &name }, meta, rate);
self.b.register_media(&key, id);
id
}
};
let name = name_of(c);
let mut ti = self.b.clip(item, kind, if name.is_empty() { "Nested Sequence" } else { &name }, pos, dur, src_in);
let clip_meta = meta.and_then(|m| m.get("clip")).cloned();
// Stack markers belong to the nested sequence; instance markers are on filmcraft.clip.
if let Some(ref cm) = clip_meta {
ti.markers = self.markers(cm);
}
self.apply_clip_meta(&mut ti, c, clip_meta.as_ref());
Some(ti)
}
fn media(&mut self, r: &Value, clip_name: &str, kind: TrackKind, avail: Option<(Tick, Tick)>) -> Option<ItemId> {
let meta = fc(r);
let info: Option<MediaInfo> = meta.and_then(|m| m.get("info")).and_then(|i| serde_json::from_value(i.clone()).ok());
let name = {
let n = name_of(r);
if n.is_empty() { clip_name.to_string() } else { n }
};
let spec = MediaSpec {
duration: avail.map(|a| a.1),
video: (kind == TrackKind::Video).then(|| (1920, 1080, FrameRate::default())),
audio: (kind == TrackKind::Audio).then_some((48_000, 2)),
start_tc: None,
kind: None,
};
let id = match schema_name(r) {
"ExternalReference" | "ImageSequenceReference" => {
let url = r.get("target_url").and_then(Value::as_str).or_else(|| r.get("target_url_base").and_then(Value::as_str)).unwrap_or("");
let path = resolve_url(url, self.opts.base_dir.as_deref());
let display = if name.is_empty() { file_name(&path).to_string() } else { name.clone() };
let key = format!("file:{path}");
let existed = self.b.find_media(&key);
let id = self.b.file_media(&key, &display, &path, &spec, None);
if existed.is_none() {
self.fill_media(id, info, meta, kind);
}
id
}
"GeneratorReference" => {
let g: Generator = meta.and_then(|m| m.get("generator")).and_then(|g| serde_json::from_value(g.clone()).ok()).unwrap_or_else(|| {
match r.get("generator_kind").and_then(Value::as_str).unwrap_or("").to_ascii_lowercase().as_str() {
"solidcolor" | "solid_color" => {
let c = r
.get("parameters")
.and_then(|p| p.get("color"))
.and_then(|c| serde_json::from_value::<[f32; 4]>(c.clone()).ok())
.unwrap_or([0.0, 0.0, 0.0, 1.0]);
Generator::ColorMatte { color: c }
}
"smptebars" | "bars" => Generator::BarsAndTone,
"black" => Generator::BlackVideo,
other => {
self.report.warn(format!("OTIO generator \"{other}\" is not supported; imported as Black Video"));
Generator::BlackVideo
}
}
});
// Equal generator content can belong to distinct project items; repeated item IDs share media.
let key = match meta.and_then(|m| m.get("item")).and_then(Value::as_u64) {
Some(item) => format!("gen:item:{item}"),
None => format!("gen:{}", serde_json::to_string(&g).unwrap_or_default()),
};
let existed = self.b.find_media(&key);
let id = self.b.generator_media(&key, if name.is_empty() { "Generator" } else { &name }, g, &spec, None);
if existed.is_none() {
self.fill_media(id, info, meta, kind);
}
id
}
_ => {
if schema_name(r) != "MissingReference" && !r.is_null() {
self.report.warn(format!("OTIO media reference {} is not supported; imported offline", schema(r)));
}
let key = format!("missing:{name}");
let existed = self.b.find_media(&key);
let path = resolve_path(&name, self.opts.base_dir.as_deref());
let id = self.b.file_media(&key, &name, &path, &spec, None);
if existed.is_none() {
self.fill_media(id, info, meta, kind);
if let Some(m) = self.b.p.item_mut(id).and_then(|i| i.as_media_mut()) {
m.offline = true;
}
}
id
}
};
Some(id)
}
fn fill_media(&mut self, id: ItemId, info: Option<MediaInfo>, meta: Option<&Value>, kind: TrackKind) {
let label = meta.and_then(|m| m.get("label")).and_then(|l| serde_json::from_value::<Label>(l.clone()).ok());
let offline = meta.and_then(|m| m.get("offline")).and_then(Value::as_bool);
let Some(it) = self.b.p.item_mut(id) else { return };
it.custom_label_color = meta.and_then(|m| m.get("custom_label_color")).and_then(Value::as_str).and_then(filmcraft_project::HexColor::parse);
if let Some(l) = label {
it.label = l;
}
if let Some(m) = it.as_media_mut() {
match info {
Some(i) => m.info = i,
None => {
// A clip on the other kind of track proves the media has that stream too.
let _ = kind;
}
}
if let Some(o) = offline {
m.offline = o;
}
}
}
fn markers(&mut self, v: &Value) -> Vec<Marker> {
let mut out = Vec::new();
for m in v.get("markers").and_then(Value::as_array).into_iter().flatten() {
let (mut start, mut duration) = m.get("marked_range").and_then(read_tr).unwrap_or((Tick::ZERO, Tick::ZERO));
let meta = fc(m);
if let Some(s) = meta.and_then(|x| x.get("start_ticks")).and_then(Value::as_i64)
&& (Tick(s) - start).abs() < Tick(TICKS_PER_SECOND / 1000)
{
start = Tick(s);
}
if let Some(d) = meta.and_then(|x| x.get("duration_ticks")).and_then(Value::as_i64)
&& (Tick(d) - duration).abs() < Tick(TICKS_PER_SECOND / 1000)
{
duration = Tick(d);
}
let color = meta
.and_then(|x| x.get("label"))
.and_then(|l| serde_json::from_value::<Label>(l.clone()).ok())
.unwrap_or_else(|| color_label(m.get("color").and_then(Value::as_str).unwrap_or("")));
out.push(Marker {
url: meta.and_then(|x| x.get("url")).and_then(Value::as_str).unwrap_or("").to_string(),
author: meta.and_then(|x| x.get("author")).and_then(Value::as_str).unwrap_or("").to_string(),
custom_color: meta.and_then(|x| x.get("custom_color")).and_then(|c| c.as_str()).and_then(filmcraft_project::HexColor::parse),
id: MarkerId(self.b.alloc()),
start,
duration,
name: name_of(m),
comment: m.get("comment").and_then(Value::as_str).unwrap_or("").to_string(),
kind: meta.and_then(|x| x.get("kind")).and_then(|k| serde_json::from_value::<MarkerKind>(k.clone()).ok()).unwrap_or_default(),
color,
});
}
out.sort_by_key(|m| m.start);
out
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rational_time() {
for r in FrameRate::COMMON {
for f in [0i64, 1, 1799, 86_400, 10_000_001] {
let t = r.tick_of(f);
assert_eq!(read_rt(&rt(t, r)), Some(t), "{r} {f}");
}
}
// 23.976 written by other tools as a rounded float
let v = json!({"OTIO_SCHEMA": "RationalTime.1", "rate": 23.976, "value": 48.0});
assert_eq!(read_rt(&v), Some(FrameRate::FPS_23_976.tick_of(48)));
// sub-frame audio time survives
let t = Tick(TICKS_PER_SECOND / 48_000 * 12_345);
let back = read_rt(&rt(t, FrameRate::FPS_24)).unwrap();
assert!((back - t).abs() <= Tick(1));
}
/// A tree of compound clips: `uses` uses of the next level in each, `levels` media levels deep, leaf clips in the last.
fn nested_tree(levels: usize, uses: usize) -> String {
let mut xml = String::from(
r#"<?xml version="1.0"?><fcpxml version="1.10"><resources><format id="f1" frameDuration="100/2500s" 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>"#,
);
for level in 0..levels {
let inner: String = (0..uses)
.map(|i| {
if level + 1 < levels {
format!(r#"<ref-clip ref="m{}" offset="{i}s" duration="1s"/>"#, level + 1)
} else {
format!(r#"<asset-clip ref="a1" offset="{i}s" duration="1s"/>"#)
}
})
.collect();
xml.push_str(&format!(r#"<media id="m{level}" name="L{level}"><sequence format="f1" tcStart="0s"><spine>{inner}</spine></sequence></media>"#));
}
xml.push_str(r#"</resources><library><event name="E"><project name="P"><sequence format="f1" tcStart="0s"><spine><ref-clip ref="m0" offset="0s" duration="1s"/></spine></sequence></project></event></library></fcpxml>"#);
xml
}
/// OTIO repeats a nested sequence for every use, so 10 uses nested 3 deep is 111 copies and a 3 KB
/// document nested 12 deep made the export run for minutes and grow to gigabytes. Past the limit on clips
/// written inside nested sequences the rest are gaps, with one warning. The test lowers the limit so it
/// stays tiny: without the check all 112 stacks are written.
#[test]
fn nested_copies_stop_at_the_limit() {
let (imported, _) = crate::import(nested_tree(3, 10).as_bytes(), crate::Format::Fcpxml, None).expect("import succeeds");
let seq = imported.sequences[0];
let opts = ExportOptions::default();
let write = |limit: usize| {
let mut report = Report::default();
let mut x = Exp { p: &imported.project, opts: &opts, report: &mut report, stack: vec![seq], nested_items: 0, nested_limit: limit };
let stacks = x.stack_json(seq, "t", None).to_string().matches("\"Stack.1\"").count();
(stacks, report)
};
let (all, report) = write(usize::MAX - 1);
assert_eq!(all, 112);
assert!(!report.mentions("nested sequences"), "{report}");
let (capped, report) = write(200);
assert!(capped < 60, "{capped} stacks");
assert!(report.mentions("clips written inside nested sequences"), "{report}");
assert_eq!(report.warnings().filter(|w| w.message.contains("inside nested sequences")).map(|w| w.count).sum::<u32>(), 1);
}
/// An ordinary project with nested sequences is far below the real limit and exports untouched.
#[test]
fn ordinary_nesting_is_not_capped() {
let (imported, _) = crate::import(nested_tree(3, 4).as_bytes(), crate::Format::Fcpxml, None).expect("import succeeds");
let (_, report) = crate::export(&imported.project, imported.sequences[0], crate::Format::Otio, &ExportOptions::default()).expect("export succeeds");
assert!(!report.mentions("inside nested sequences"), "{report}");
}
}
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.