f67d38b35cc5
comp.rs
//! A format-neutral mob-style composition model shared by AAF and OMF.
//!
//! Both formats describe a timeline as a composition of slots (tracks) whose segments are
//! sequences of fillers, source clips and transitions, where a transition *overlaps* the end of
//! the segment before it and the start of the segment after it (the sequence's length is the sum of
//! its segment lengths minus its transition lengths). Source clips reference media through master
//! mobs and file source mobs. [`from_project`] turns a FilmCraft sequence into that shape;
//! [`to_project`] builds FilmCraft sequences and media from it. All times are ticks; the format
//! serialisers convert to and from edit units.
use std::collections::HashMap;
use filmcraft_media::MediaKind;
use filmcraft_project::{
AudioChannels, ClipId, Interpolation, ItemId, ItemKind, Keyframe, Label, Marker, MarkerId, MarkerKind, MediaRef, Param, ParamValue, Project, Sequence,
Track, TrackItem, TrackKind, Transition, TransitionAlign, TransitionId, find_effect,
};
use filmcraft_time::{FrameRate, Tick};
use crate::common::{Builder, MediaSpec, base_item, db_to_gain, file_name, file_stem, gain_to_db, param, set_param, settings_for, transition_effect};
use crate::essence::{EssenceData, EssenceKey, MediaOptions};
use crate::{ImportOptions, Imported, Report};
/// Picture or sound.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) enum CKind {
Picture,
Sound,
}
/// A whole document: compositions and the media they reference.
#[derive(Clone, Debug, Default, PartialEq)]
pub(crate) struct Document {
/// The top-level compositions.
pub compositions: Vec<Composition>,
pub sources: Vec<Source>,
/// Compositions that are only used inside others (nested sequences); a [`Source`] refers to
/// one by its index here. They may nest further.
pub nested: Vec<Composition>,
}
/// How a nested sequence is written. Premiere Pro writes one as a composition of its own in AAF
/// (clips refer to it the way they refer to media) and renders its sound in OMF, which has no
/// picture and whose readers do not follow compositions.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Nests {
Compositions,
Rendered,
}
/// Nested sequences deeper than this are left as gaps (a sequence cannot be inside itself, but a
/// damaged project may claim so).
const MAX_NESTING: usize = 16;
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct Composition {
pub name: String,
pub rate: FrameRate,
pub sample_rate: u32,
pub width: u32,
pub height: u32,
pub start_tc: i64,
pub drop: bool,
pub tracks: Vec<CTrack>,
pub markers: Vec<CMarker>,
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CTrack {
pub kind: CKind,
pub name: String,
/// Physical track number (1-based, per kind).
pub number: u32,
/// Sound: channels of the track (1 mono, 2 stereo, 6 5.1).
pub channels: u32,
pub items: Vec<CItem>,
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum CItem {
Filler(Tick),
Clip(CClip),
Transition(CTransition),
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CClip {
pub len: Tick,
/// Index into [`Document::sources`].
pub source: usize,
/// Source (file) time of the segment's first frame.
pub start: Tick,
pub gain: Option<Gain>,
pub name: String,
}
/// Clip gain (linear amplitude).
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum Gain {
Constant(f64),
/// Points at offsets from the segment start; `linear` false = hold (step) interpolation.
Varying {
linear: bool,
points: Vec<(Tick, f64)>,
},
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CTransition {
pub len: Tick,
/// Where the cut lies, from the transition start.
pub cut: Tick,
/// FilmCraft effect id.
pub effect: String,
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CMarker {
pub start: Tick,
pub duration: Tick,
pub name: String,
pub comment: String,
pub color: Option<String>,
}
/// One essence: a file (or embedded data) carrying the picture, or some channels of sound, of a
/// media item.
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct Source {
/// Groups the sources of one media item (one master mob).
pub key: String,
pub name: String,
pub kind: CKind,
pub path: Option<String>,
/// Sound: the (0-based) channel of the file this source exposes (broken out to mono), or
/// `None` for all of them.
pub channel: Option<u32>,
/// Sound: channels this source exposes (1 when `channel` is set, else `file_channels`).
pub channels: u32,
/// Sound: channels of the file / embedded data.
pub file_channels: u32,
pub width: u32,
pub height: u32,
/// Picture: the frame rate of the media.
pub frame_rate: FrameRate,
pub sample_rate: u32,
pub bits: u16,
pub length: Tick,
/// Media time of the essence's time 0 (trimmed / consolidated essence).
pub offset: Tick,
/// Start timecode in frames at `tc_rate`.
pub start_tc: Option<i64>,
pub tc_rate: FrameRate,
pub embedded: Option<Vec<u8>>,
pub markers: Vec<CMarker>,
/// Not media but a nested composition: its index in [`Document::nested`]. `start` of a clip
/// that uses it is a time in that composition.
pub nested: Option<usize>,
}
impl Source {
pub fn is_still(&self) -> bool {
self.kind == CKind::Picture && self.length == Tick::ZERO
}
}
// ---------------------------------------------------------------------------------------------
// FilmCraft → composition
// ---------------------------------------------------------------------------------------------
/// How a transition sits on a clip.
#[derive(Clone, Copy, Debug)]
enum Side {
/// Shared with the adjacent clip: the transition's timeline range.
TwoSided(Tick, Tick),
/// Fade from / to nothing: the transition's length, anchored at the clip edge.
OneSided(Tick),
}
struct Exporter<'a> {
p: &'a Project,
media: &'a MediaOptions,
doc: Document,
memo: HashMap<(String, CKind, usize, Option<u32>), usize>,
report: &'a mut Report,
seq_rate: FrameRate,
nests: Nests,
/// Nested sequences already written: their index in `doc.nested`.
nested: HashMap<ItemId, usize>,
/// The sequences being written, outermost first.
open: Vec<ItemId>,
}
pub(crate) fn from_project(p: &Project, seq_id: ItemId, name: &str, media: &MediaOptions, nests: Nests, report: &mut Report) -> crate::Result<Document> {
let seq = p.sequence(seq_id).ok_or(crate::Error::NoSequence(seq_id))?;
let rate = seq.settings.frame_rate;
let mut ex =
Exporter { p, media, doc: Document::default(), memo: HashMap::new(), report, seq_rate: rate, nests, nested: HashMap::new(), open: vec![seq_id] };
let comp = ex.composition(seq, name, true);
ex.doc.compositions.push(comp);
Ok(ex.doc)
}
impl Exporter<'_> {
/// `seq` as a composition. `top`: the exported sequence itself (a video mixdown replaces its
/// video tracks; a nested sequence under a mixdown has no video tracks left to show).
fn composition(&mut self, seq: &Sequence, name: &str, top: bool) -> Composition {
let rate = seq.settings.frame_rate;
let outer_rate = std::mem::replace(&mut self.seq_rate, rate);
let media = self.media;
let mut comp = Composition {
name: name.to_string(),
rate,
sample_rate: seq.settings.sample_rate.max(1),
width: seq.settings.width,
height: seq.settings.height,
start_tc: seq.start_timecode,
drop: seq.settings.drop_frame,
tracks: Vec::new(),
markers: seq
.markers
.iter()
.map(|m| CMarker {
start: m.start,
duration: m.duration,
name: m.name.clone(),
comment: m.comment.clone(),
color: Some(m.color.name().to_string()),
})
.collect(),
};
if !media.audio_only {
if let Some(mix) = media.mixdown_video.as_ref().filter(|_| top) {
let src = self.doc.sources.len();
self.doc.sources.push(Source {
key: "mixdown".into(),
name: format!("{name} (video mixdown)"),
kind: CKind::Picture,
path: Some(mix.path.clone()),
channel: None,
channels: 0,
file_channels: 0,
width: mix.width,
height: mix.height,
frame_rate: rate,
sample_rate: 0,
bits: 0,
length: mix.duration,
offset: Tick::ZERO,
start_tc: Some(seq.start_timecode + rate.frame_at(mix.start)),
tc_rate: rate,
embedded: None,
markers: Vec::new(),
nested: None,
});
let mut items = Vec::new();
if mix.start > Tick::ZERO {
items.push(CItem::Filler(mix.start));
}
items.push(CItem::Clip(CClip { len: mix.duration, source: src, start: Tick::ZERO, gain: None, name: format!("{name} (video mixdown)") }));
comp.tracks.push(CTrack { kind: CKind::Picture, name: "V1".into(), number: 1, channels: 0, items });
} else if media.mixdown_video.is_none() {
for (i, t) in seq.video_tracks.iter().enumerate() {
let items = self.track(t, TrackKind::Video, None);
comp.tracks.push(CTrack { kind: CKind::Picture, name: format!("V{}", i + 1), number: i as u32 + 1, channels: 0, items });
}
}
}
let mut n = 0;
for t in &seq.audio_tracks {
let ch = match t.channels {
AudioChannels::Mono => 1,
AudioChannels::Surround51 => 6,
AudioChannels::Stereo | AudioChannels::Adaptive => 2,
};
if media.breakout_to_mono {
for c in 0..ch {
n += 1;
let items = self.track(t, TrackKind::Audio, Some(c));
comp.tracks.push(CTrack { kind: CKind::Sound, name: audio_track_name(&t.name, n, ch, Some(c)), number: n, channels: 1, items });
}
} else {
n += 1;
let items = self.track(t, TrackKind::Audio, None);
comp.tracks.push(CTrack { kind: CKind::Sound, name: audio_track_name(&t.name, n, ch, None), number: n, channels: ch, items });
}
}
self.seq_rate = outer_rate;
comp
}
/// The source behind a clip of the nested sequence `nested` (project item `item`): the
/// sequence's sound as the caller rendered it for this clip, or the sequence as a composition
/// of its own.
fn nest_source(&mut self, c: &TrackItem, item: ItemId, name: &str, nested: &Sequence, ckind: CKind, channel: Option<u32>) -> Option<usize> {
let clip_key = EssenceKey::Clip(c.id);
if ckind == CKind::Sound
&& let Some(e) = self.media.essence_for(clip_key, channel).cloned()
{
let memo_key = (format!("clip:{}", c.id.0), ckind, 0, channel);
if let Some(&i) = self.memo.get(&memo_key) {
return Some(i);
}
let (path, embedded) = match e.data {
EssenceData::Embedded(d) => (None, Some(d)),
EssenceData::File { path } => (Some(path), None),
};
let s = Source {
key: memo_key.0.clone(),
// (Premiere names the rendered clip after the nested sequence)
name: name.to_string(),
kind: ckind,
path,
channel: None,
channels: e.channels.max(1),
file_channels: e.channels.max(1),
width: 0,
height: 0,
frame_rate: self.seq_rate,
sample_rate: e.sample_rate.max(1),
bits: e.bits,
length: Tick::from_units(e.frames as i64, e.sample_rate.max(1) as i64),
offset: e.start,
start_tc: None,
tc_rate: self.seq_rate,
embedded,
markers: c.markers.iter().map(marker_out).collect(),
nested: None,
};
let i = self.doc.sources.len();
self.doc.sources.push(s);
self.memo.insert(memo_key, i);
return Some(i);
}
if self.nests == Nests::Rendered {
self.report.warn(format!("the sound of the nested sequence \"{name}\" was not rendered (left as a gap)"));
return None;
}
let memo_key = (format!("seq:{}", item.0), ckind, 0, channel);
if let Some(&i) = self.memo.get(&memo_key) {
return Some(i);
}
let index = match self.nested.get(&item) {
Some(&i) => i,
None => {
if self.open.contains(&item) || self.open.len() >= MAX_NESTING {
self.report.warn(format!("the nested sequence \"{name}\" is inside itself or nested too deeply (left as a gap)"));
return None;
}
self.open.push(item);
let comp = self.composition(nested, name, false);
self.open.pop();
let i = self.doc.nested.len();
self.doc.nested.push(comp);
self.nested.insert(item, i);
i
}
};
// nothing to show or play on this kind of track: a gap (as in the sequence itself)
let comp = self.doc.nested.get(index)?;
if !comp.tracks.iter().any(|t| t.kind == ckind) {
return None;
}
let channels = if ckind == CKind::Sound { 2 } else { 0 };
let s = Source {
key: memo_key.0.clone(),
name: name.to_string(),
kind: ckind,
path: None,
channel: if ckind == CKind::Sound { channel } else { None },
channels: if channel.is_some() { 1 } else { channels },
file_channels: channels,
width: comp.width,
height: comp.height,
frame_rate: comp.rate,
sample_rate: comp.sample_rate.max(1),
bits: 16,
length: nested.duration(),
offset: Tick::ZERO,
start_tc: None,
tc_rate: comp.rate,
embedded: None,
markers: Vec::new(),
nested: Some(index),
};
let i = self.doc.sources.len();
self.doc.sources.push(s);
self.memo.insert(memo_key, i);
Some(i)
}
/// The source behind `c` on a track of `kind` (`sub`: broken-out channel slot), if exportable.
fn source_of(&mut self, c: &TrackItem, kind: TrackKind, sub: Option<u32>) -> Option<usize> {
let item = base_item(self.p, c.item);
let it = self.p.item(item)?;
let m = match &it.kind {
ItemKind::Media(m) => m,
ItemKind::Sequence(nested) => {
let ckind = if kind == TrackKind::Video { CKind::Picture } else { CKind::Sound };
let channel = sub.map(|s| c.source_channels.get(s as usize).map(|&x| x as u32).unwrap_or(s));
return self.nest_source(c, item, &it.name, nested, ckind, channel);
}
_ => {
match crate::common::uncarried_clip(self.p, c, self.seq_rate) {
Some(clip) => self.report.warn(format!("{clip} is not exported (left as a gap)")),
None => self.report.warn("graphics, titles and adjustment layers are not exported (left as gaps)"),
}
return None;
}
};
let path = match &m.media {
MediaRef::File { path } => path.clone(),
MediaRef::Generator(_) => {
self.report.warn("synthetic media (bars, colour mattes, …) is not exported (left as gaps)");
return None;
}
};
let ckind = if kind == TrackKind::Video { CKind::Picture } else { CKind::Sound };
// the source channel this slot plays when broken out to mono
let channel = sub.map(|s| c.source_channels.get(s as usize).map(|&x| x as u32).unwrap_or(s));
let clip_key = EssenceKey::Clip(c.id);
let media_key = EssenceKey::media(item, c.audio_stream);
let ess = (ckind == CKind::Sound)
.then(|| self.media.essence_for(clip_key, channel).or_else(|| self.media.essence_for(media_key, channel)))
.flatten()
.cloned();
let key = match &ess {
Some(e) if e.key == clip_key => format!("clip:{}", c.id.0),
_ if ckind == CKind::Sound && c.audio_stream > 0 => format!("item:{}:stream:{}", item.0, c.audio_stream),
_ => format!("item:{}", item.0),
};
// Original linked file locators cannot name a container stream. Leave an explicit
// unsupported-feature report rather than reference its first audio stream.
if ckind == CKind::Sound && c.audio_stream > 0 && ess.is_none() {
self.report.warn("selected container audio streams require separate or embedded audio essence (left as gaps)");
return None;
}
let stream = if ckind == CKind::Sound { c.audio_stream } else { 0 };
let memo_key = (key.clone(), ckind, stream, channel);
if let Some(&i) = self.memo.get(&memo_key) {
return Some(i);
}
let video = m.info.video.as_ref();
let audio = m.info.audio_streams.get(c.audio_stream);
let still = m.info.kind == MediaKind::Still;
match ckind {
CKind::Picture if video.is_none() && !still => return None,
CKind::Sound if audio.is_none() => return None,
_ => {}
}
let frame_rate = video.map(|v| v.frame_rate).filter(|r| r.num > 0).unwrap_or(self.seq_rate);
let mut markers: Vec<CMarker> = m.markers.iter().chain(c.markers.iter()).map(marker_out).collect();
markers.sort_by(|a, b| (a.start, &a.name).cmp(&(b.start, &b.name)));
markers.dedup();
let mut s = Source {
key,
name: it.name.clone(),
kind: ckind,
path: Some(path.clone()),
channel: None,
channels: 0,
file_channels: 0,
width: video.map_or(0, |v| v.width),
height: video.map_or(0, |v| v.height),
frame_rate,
sample_rate: audio.map_or(48_000, |a| a.sample_rate.max(1)),
bits: audio.and_then(|a| a.bits_per_sample).unwrap_or(16).clamp(8, 32) as u16,
length: if still { Tick::ZERO } else { m.info.duration },
offset: Tick::ZERO,
start_tc: m.info.start_timecode,
tc_rate: frame_rate,
embedded: None,
markers,
nested: None,
};
if ckind == CKind::Sound {
s.file_channels = audio.map_or(2, |a| a.channels.max(1));
s.channel = channel;
if let Some(e) = ess {
s.sample_rate = e.sample_rate.max(1);
s.bits = e.bits;
s.file_channels = e.channels.max(1);
// per-channel essence is a mono file: its only channel
if e.channel.is_some() {
s.channel = None;
}
s.offset = e.start;
s.length = Tick::from_units(e.frames as i64, e.sample_rate.max(1) as i64);
match e.data {
EssenceData::Embedded(d) => {
s.path = None;
s.embedded = Some(d);
}
EssenceData::File { path } => s.path = Some(path),
}
if e.key == clip_key {
s.name = format!("{} (rendered)", c.name);
}
}
}
s.channels = if s.channel.is_some() { 1 } else { s.file_channels };
let i = self.doc.sources.len();
self.doc.sources.push(s);
self.memo.insert(memo_key, i);
Some(i)
}
fn gain_of(&mut self, c: &TrackItem, source: &Source) -> Option<Gain> {
if source.key.starts_with("clip:") {
return None; // rendered: effects baked in
}
let g = c.gain_db;
match param(c, "volume", "level") {
Some(p) if p.is_animated() => {
let speed = if c.speed.abs() > 1e-9 { c.speed.abs() } else { 1.0 };
let linear = !p.keyframes.iter().all(|k| k.interp == Interpolation::Hold);
if p.keyframes.iter().any(|k| !matches!(k.interp, Interpolation::Linear | Interpolation::Hold)) {
self.report.info("Bezier volume keyframes were exported as linear");
}
let points = p
.keyframes
.iter()
.map(|k| {
let off = Tick(((k.time - c.source_in).0 as f64 / speed).round() as i64);
(off, db_to_gain(k.value.as_f64().unwrap_or(0.0) + g))
})
.collect();
Some(Gain::Varying { linear, points })
}
Some(p) => {
let db = p.value.as_f64().unwrap_or(0.0) + g;
(db.abs() > 1e-9).then(|| Gain::Constant(db_to_gain(db)))
}
None => (g.abs() > 1e-9).then(|| Gain::Constant(db_to_gain(g))),
}
}
fn track(&mut self, t: &Track, kind: TrackKind, sub: Option<u32>) -> Vec<CItem> {
// exportable clips with their sources
let clips: Vec<(&TrackItem, usize)> = t.items.iter().filter_map(|c| self.source_of(c, kind, sub).map(|s| (c, s))).collect();
let idx_of: HashMap<ClipId, usize> = clips.iter().enumerate().map(|(i, (c, _))| (c.id, i)).collect();
let mut tin: Vec<Option<(Side, &Transition)>> = vec![None; clips.len()];
let mut tout: Vec<Option<(Side, &Transition)>> = vec![None; clips.len()];
for tr in &t.transitions {
let a = tr.from.and_then(|f| idx_of.get(&f).copied());
let b = tr.to.and_then(|f| idx_of.get(&f).copied());
match (a, b) {
(Some(a), Some(b)) if b == a + 1 && clips[a].0.end() == clips[b].0.start && tr.start <= clips[b].0.start && tr.end() >= clips[a].0.end() => {
tout[a] = Some((Side::TwoSided(tr.start, tr.end()), tr));
tin[b] = Some((Side::TwoSided(tr.start, tr.end()), tr));
}
(_, Some(b)) if tr.from.is_none() || a.is_none() => {
let c = clips[b].0;
let len = (tr.end().min(c.end()) - tr.start.max(c.start)).max(Tick::ZERO);
if tr.start != c.start {
self.report.info("a fade-in transition not starting at its clip was moved to the clip start");
}
if len > Tick::ZERO {
tin[b] = Some((Side::OneSided(len), tr));
}
}
(Some(a), _) => {
let c = clips[a].0;
let len = (tr.end().min(c.end()) - tr.start.max(c.start)).max(Tick::ZERO);
if tr.end() != c.end() {
self.report.info("a fade-out transition not ending at its clip was moved to the clip end");
}
if len > Tick::ZERO {
tout[a] = Some((Side::OneSided(len), tr));
}
}
_ => self.report.warn("a transition without an exported clip was dropped"),
}
}
let mut out = Vec::new();
let mut cursor = Tick::ZERO;
let mut tail = Tick::ZERO; // the timeline must reach at least here (after a fade-out)
for (i, &(c, src)) in clips.iter().enumerate() {
let (s, e) = (c.start, c.end());
let mut seg_start = s;
match tin[i] {
Some((Side::TwoSided(ts, _), _)) => seg_start = ts,
Some((Side::OneSided(len), tr)) => {
let fill_to = s + len;
if fill_to > cursor {
out.push(CItem::Filler(fill_to - cursor));
cursor = fill_to;
}
out.push(CItem::Transition(CTransition { len, cut: Tick::ZERO, effect: tr.effect.effect.clone() }));
cursor -= len;
}
None => {
if s > cursor {
out.push(CItem::Filler(s - cursor));
}
}
}
let seg_end = match tout[i] {
Some((Side::TwoSided(_, te), _)) => te,
_ => e,
};
if c.speed != 1.0 || c.reverse || c.frame_hold.is_some() {
self.report.warn("speed changes, reverse playback and frame holds are not exported (clips play at 100%)");
}
let source = self.doc.sources[src].clone();
// clips play at 100% here, so timeline and media advance together
let start = c.source_in + (seg_start - s) - source.offset;
if start < Tick::ZERO {
self.report.warn("a clip uses media before the start of its (trimmed) essence");
}
let mut gain = if kind == TrackKind::Audio { self.gain_of(c, &source) } else { None };
if let Some(Gain::Varying { points, .. }) = &mut gain {
for p in points.iter_mut() {
p.0 += s - seg_start;
}
}
out.push(CItem::Clip(CClip { len: seg_end - seg_start, source: src, start, gain, name: c.name.clone() }));
cursor = seg_end;
match tout[i] {
Some((Side::TwoSided(ts, _), tr)) => {
out.push(CItem::Transition(CTransition { len: seg_end - ts, cut: e - ts, effect: tr.effect.effect.clone() }));
cursor = ts;
tail = tail.max(seg_end);
}
Some((Side::OneSided(len), tr)) => {
out.push(CItem::Transition(CTransition { len, cut: len, effect: tr.effect.effect.clone() }));
cursor = e - len;
tail = tail.max(e);
}
None => tail = tail.max(e),
}
}
if tail > cursor {
out.push(CItem::Filler(tail - cursor));
}
out
}
}
fn marker_out(m: &Marker) -> CMarker {
CMarker { start: m.start, duration: m.duration, name: m.name.clone(), comment: m.comment.clone(), color: Some(m.color.name().to_string()) }
}
fn marker_in(b: &mut Builder, m: &CMarker) -> Marker {
Marker {
url: String::new(),
author: String::new(),
custom_color: None,
id: MarkerId(b.alloc()),
start: m.start,
duration: m.duration,
name: m.name.clone(),
comment: m.comment.clone(),
kind: MarkerKind::Comment,
color: m.color.as_deref().and_then(Label::from_name).unwrap_or(Label::Forest),
}
}
// ---------------------------------------------------------------------------------------------
// Composition → FilmCraft
// ---------------------------------------------------------------------------------------------
/// Media a document embeds, to be written next to it by the caller (the item's path).
#[derive(Clone, Debug, PartialEq)]
pub struct ExtractedMedia {
/// The imported media item (fragment-local id) whose path is `path`.
pub item: ItemId,
pub path: String,
/// A complete WAV file.
pub wav: Vec<u8>,
}
pub(crate) fn to_project(doc: Document, opts: &ImportOptions, report: &mut Report) -> crate::Result<(Imported, Vec<ExtractedMedia>)> {
if doc.compositions.is_empty() {
return Err(crate::Error::Empty);
}
let name = opts.name.clone().unwrap_or_else(|| doc.compositions[0].name.clone());
let mut b = Builder::new(&name);
let media_bin = b.bin("Media", None);
let mut extracted = Vec::new();
// one media item per (key, path)
let mut item_of: HashMap<usize, ItemId> = HashMap::new();
let mut groups: Vec<((String, Option<String>), Vec<usize>)> = Vec::new();
for (i, s) in doc.sources.iter().enumerate() {
if s.nested.is_some() {
continue; // a nested composition, not media: a sequence (below)
}
let k = (s.key.clone(), s.path.clone().or_else(|| s.embedded.is_some().then(|| format!("embedded:{i}"))));
match groups.iter_mut().find(|(g, _)| *g == k) {
Some((_, v)) => v.push(i),
None => groups.push((k, vec![i])),
}
}
// This becomes a directory name for embedded AAF/OMF audio. `ImportOptions::name` normally
// comes from the document filename, where backslashes are ordinary Unix filename characters;
// `resolve_path` deliberately treats them as separators, so retain only one safe component.
let doc_stem = safe_path_component(opts.name.as_deref().unwrap_or("Imported"));
let mut used_paths = std::collections::HashSet::new();
for ((_, path), members) in &groups {
let srcs: Vec<&Source> = members.iter().map(|&i| &doc.sources[i]).collect();
let first = srcs[0];
let pic = srcs.iter().find(|s| s.kind == CKind::Picture);
let snd = srcs.iter().find(|s| s.kind == CKind::Sound);
let mut spec = MediaSpec {
duration: Some(srcs.iter().map(|s| s.length).max().unwrap_or(Tick::ZERO)),
video: pic.map(|p| (p.width.max(1), p.height.max(1), p.frame_rate)),
audio: snd.map(|s| {
(s.sample_rate, srcs.iter().filter(|x| x.kind == CKind::Sound).map(|x| x.file_channels.max(x.channel.map_or(0, |c| c + 1))).max().unwrap_or(1))
}),
start_tc: first.start_tc.or_else(|| srcs.iter().find_map(|s| s.start_tc)),
kind: None,
};
if pic.is_some_and(|p| p.is_still()) {
spec.kind = Some(MediaKind::Still);
}
let embedded = snd.and_then(|s| s.embedded.as_ref().map(|d| (*s, d)));
let (resolved, display) = match (path.as_deref(), embedded) {
(_, Some((s, _))) => {
let safe: String = first.name.chars().map(|c| if c.is_alphanumeric() || " -_.".contains(c) { c } else { '_' }).collect();
let base = format!("{doc_stem} Media/{}{}", safe.trim(), s.channel.map(|c| format!(" ch{}", c + 1)).unwrap_or_default());
let mut rel = format!("{base}.wav");
let mut n = 1;
while !used_paths.insert(rel.to_ascii_lowercase()) {
n += 1;
rel = format!("{base} ({n}).wav");
}
(crate::common::resolve_path(&rel, opts.base_dir.as_deref()), first.name.clone())
}
(Some(p), None) => {
(crate::common::resolve_path(p, opts.base_dir.as_deref()), if first.name.is_empty() { file_name(p).to_string() } else { first.name.clone() })
}
(None, None) => (String::new(), first.name.clone()),
};
let display = if display.is_empty() { file_stem(&resolved).to_string() } else { display };
let key = format!("{}|{}", first.key, resolved);
let id = b.file_media(&key, &display, &resolved, &spec, Some(media_bin));
if resolved.is_empty()
&& let Some(m) = b.p.item_mut(id).and_then(|i| i.as_media_mut())
{
m.offline = true;
report.warn(format!("\"{display}\" has no media location; imported offline"));
}
let mut markers: Vec<CMarker> = srcs.iter().flat_map(|s| s.markers.iter().cloned()).collect();
markers.sort_by(|a, b| (a.start, &a.name).cmp(&(b.start, &b.name)));
markers.dedup();
let mk: Vec<Marker> = markers.iter().map(|m| marker_in(&mut b, m)).collect();
if let Some(m) = b.p.item_mut(id).and_then(|i| i.as_media_mut()) {
m.markers = mk;
}
if let Some((s, data)) = embedded {
extracted.push(ExtractedMedia {
item: id,
path: resolved.clone(),
wav: crate::wav::wav_file(data, u16::try_from(s.file_channels.max(1)).unwrap_or(u16::MAX), s.sample_rate, s.bits),
});
}
for &i in members {
item_of.insert(i, id);
}
}
// nested compositions are sequences that clips use as their source: reserve them all first
// (they may use each other), then build them
let settings_of = |comp: &Composition| {
let mut settings = settings_for(comp.rate, comp.width.max(16), comp.height.max(16), comp.drop);
settings.sample_rate = comp.sample_rate.max(1);
settings
};
let nested_ids: Vec<ItemId> = doc.nested.iter().map(|comp| b.reserve_sequence(&comp.name, settings_of(comp), None)).collect();
for (i, s) in doc.sources.iter().enumerate() {
if let Some(&id) = s.nested.and_then(|n| nested_ids.get(n)) {
item_of.insert(i, id);
}
}
for (comp, &seq_id) in doc.nested.iter().zip(&nested_ids) {
let seq = build_sequence(&mut b, comp, settings_of(comp), &doc.sources, &item_of, report);
b.put_sequence(seq_id, seq);
}
for comp in &doc.compositions {
let seq_id = b.reserve_sequence(&comp.name, settings_of(comp), None);
let seq = build_sequence(&mut b, comp, settings_of(comp), &doc.sources, &item_of, report);
b.put_sequence(seq_id, seq);
b.top.push(seq_id);
}
Ok((b.finish(), extracted))
}
/// A display name used as a generated path component, never a caller-selected path fragment.
fn safe_path_component(name: &str) -> String {
let safe: String = name.chars().map(|c| if c.is_alphanumeric() || " -_.".contains(c) { c } else { '_' }).collect();
let safe = safe.trim();
if safe.is_empty() || matches!(safe, "." | "..") { "Imported".into() } else { safe.into() }
}
fn build_sequence(
b: &mut Builder,
comp: &Composition,
settings: filmcraft_project::SequenceSettings,
sources: &[Source],
item_of: &HashMap<usize, ItemId>,
report: &mut Report,
) -> Sequence {
let mut seq = crate::common::empty_sequence(settings);
seq.start_timecode = comp.start_tc;
seq.markers = comp.markers.iter().map(|m| marker_in(b, m)).collect();
for t in &comp.tracks {
let kind = if t.kind == CKind::Picture { TrackKind::Video } else { TrackKind::Audio };
let idx = seq.tracks(kind).len();
let mut track = b.track(kind, idx);
// A name of its own (not the numbered `A1` / `V1` a writer gives an unnamed track) is
// kept: a sound editor's tracks are named after what they hold.
let name = t.name.trim();
let mut chars = name.chars();
let numbered = matches!(chars.next(), Some('A' | 'V')) && !chars.as_str().is_empty() && chars.all(|c| c.is_ascii_digit());
if !name.is_empty() && !numbered {
track.name = name.to_string();
}
if kind == TrackKind::Audio {
track.channels = match t.channels {
1 => AudioChannels::Mono,
6 => AudioChannels::Surround51,
_ => AudioChannels::Stereo,
};
}
build_track(b, &mut track, kind, t, sources, item_of, report);
seq.tracks_mut(kind).push(track);
}
if seq.video_tracks.is_empty() {
let t = b.track(TrackKind::Video, 0);
seq.video_tracks.push(t);
}
if seq.audio_tracks.is_empty() {
let t = b.track(TrackKind::Audio, 0);
seq.audio_tracks.push(t);
}
link_clips(b, &mut seq);
seq
}
enum Placed {
Gap,
Clip(usize),
Tr { start: Tick, len: Tick, cut: Tick, effect: String },
}
fn build_track(b: &mut Builder, track: &mut Track, kind: TrackKind, t: &CTrack, sources: &[Source], item_of: &HashMap<usize, ItemId>, report: &mut Report) {
let mut pos = Tick::ZERO;
let mut placed: Vec<Placed> = Vec::new();
let mut clips: Vec<TrackItem> = Vec::new();
for it in &t.items {
if pos.0.abs() > 4 * MAX_TIME.0 {
report.warn("a track longer than FilmCraft supports was cut short");
break;
}
match it {
CItem::Filler(l) => {
pos += *l;
placed.push(Placed::Gap);
}
CItem::Transition(tr) => {
pos -= tr.len;
placed.push(Placed::Tr { start: pos, len: tr.len, cut: tr.cut, effect: tr.effect.clone() });
}
CItem::Clip(c) => {
let Some(&item) = item_of.get(&c.source) else {
pos += c.len;
placed.push(Placed::Gap);
continue;
};
let mut ti = b.clip(item, kind, if c.name.is_empty() { &sources[c.source].name } else { &c.name }, pos, c.len, c.start);
if kind == TrackKind::Audio {
let src = &sources[c.source];
if t.channels == 1 && src.nested.is_none() {
ti.source_channels = vec![src.channel.unwrap_or(0) as u16];
}
if let Some(g) = &c.gain {
apply_gain(&mut ti, g);
}
}
placed.push(Placed::Clip(clips.len()));
clips.push(ti);
pos += c.len;
}
}
}
// resolve transitions against their neighbours
let mut transitions = Vec::new();
for k in 0..placed.len() {
let Placed::Tr { start, len, cut, effect } = &placed[k] else { continue };
let prev = k.checked_sub(1).and_then(|i| match placed[i] {
Placed::Clip(c) => Some(c),
_ => None,
});
let next = placed.get(k + 1).and_then(|p| match p {
Placed::Clip(c) => Some(*c),
_ => None,
});
let (start, len, cut) = (*start, *len, (*cut).clamp(Tick::ZERO, *len));
let cut_at = start + cut;
match (prev, next) {
(Some(a), Some(bi)) => {
let a_end = clips[a].end();
if a_end > cut_at {
clips[a].duration = cut_at - clips[a].start;
}
let shift = cut_at - clips[bi].start;
if shift > Tick::ZERO {
// keyframes are in media time: unaffected
clips[bi].start += shift;
clips[bi].source_in += shift;
clips[bi].duration -= shift;
}
}
(None, None) => {
report.warn("a transition between two fillers was dropped");
continue;
}
_ => {}
}
let align = if cut == Tick::ZERO {
TransitionAlign::StartAtCut
} else if cut == len {
TransitionAlign::EndAtCut
} else {
TransitionAlign::CenterAtCut
};
let audio = kind == TrackKind::Audio;
let effect = match find_effect(effect) {
Some(d) if d.kind == if audio { filmcraft_project::EffectKind::AudioTransition } else { filmcraft_project::EffectKind::VideoTransition } => {
d.instance()
}
_ => transition_effect(effect, audio, report),
};
transitions.push(Transition {
id: TransitionId(b.alloc()),
effect,
start,
duration: len,
from: prev.map(|a| clips[a].id),
to: next.map(|c| clips[c].id),
align,
reverse: false,
});
}
clips.retain(|c| c.duration > Tick::ZERO);
track.items = clips;
track.transitions = transitions;
track.sort();
}
fn apply_gain(ti: &mut TrackItem, g: &Gain) {
match g {
Gain::Constant(a) => set_param(ti, "volume", "level", Param::new(ParamValue::Float(gain_to_db(*a)))),
Gain::Varying { linear, points } => {
let mut p = Param::new(ParamValue::Float(points.first().map_or(0.0, |x| gain_to_db(x.1))));
for (off, a) in points {
let off = (*off).clamp(-MAX_TIME, MAX_TIME);
let mut k = Keyframe::new(ti.source_in + off, ParamValue::Float(gain_to_db(*a)));
k.interp = if *linear { Interpolation::Linear } else { Interpolation::Hold };
p.keyframes.push(k);
}
p.keyframes.sort_by_key(|k| k.time);
set_param(ti, "volume", "level", p);
}
}
}
/// Link video and audio clips of the same media that start and end together.
fn link_clips(b: &mut Builder, seq: &mut Sequence) {
let mut groups: HashMap<(ItemId, Tick, Tick, Tick), Vec<(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() {
groups.entry((c.item, c.start, c.duration, c.source_in)).or_default().push((kind, ti, ci));
}
}
}
let mut keys: Vec<_> = groups.keys().copied().collect();
keys.sort_by_key(|k| (k.1, k.0.0, k.2, k.3));
for k in keys {
let g = &groups[&k];
if g.len() < 2 {
continue;
}
let l = b.link_id();
for &(kind, ti, ci) in g {
seq.tracks_mut(kind)[ti].items[ci].link = Some(l);
}
}
}
/// The largest time read from a document (about 3.3 days).
pub(crate) const MAX_TIME: Tick = Tick(1 << 56);
/// The name an exported audio track gets: the track's own name (what an editor called it, e.g.
/// a role such as `Dialogue.Dialogue-1`, which is what a sound editor's DAW shows), else `A<n>`;
/// a track broken out to mono gets its channel after it (`L` / `R`, the 5.1 names, or a number).
fn audio_track_name(name: &str, n: u32, channels: u32, channel: Option<u32>) -> String {
let base = if name.trim().is_empty() { format!("A{n}") } else { name.trim().to_string() };
let Some(c) = channel.filter(|_| channels > 1 && !name.trim().is_empty()) else { return base };
let label = match (channels, c) {
(2, 0) => "L".to_string(),
(2, 1) => "R".to_string(),
(6, k) => ["L", "R", "C", "LFE", "Ls", "Rs"].get(k as usize).map_or_else(|| (k + 1).to_string(), |s| (*s).to_string()),
(_, k) => (k + 1).to_string(),
};
format!("{base} {label}")
}
#[cfg(test)]
mod path_tests {
use super::safe_path_component;
#[test]
fn generated_embedded_audio_folder_is_one_safe_component() {
for (input, expected) in [(r"..\escape", ".._escape"), ("../escape", ".._escape"), ("..", "Imported"), ("", "Imported")] {
assert_eq!(safe_path_component(input), expected, "{input:?}");
}
}
}
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.