f67d38b35cc5
aaf_omf.rs
//! File ▸ Export ▸ AAF… / OMF… and File ▸ Import of AAF / OMF documents.
//!
//! The interchange crate writes the documents; this module prepares their audio essence the way
//! Premiere's AAF and OMF export dialogs offer it: embedded in the document or written as separate
//! WAV / AIFF files next to it, at a chosen sample rate and bit depth, trimmed to the used ranges
//! plus handles (or whole), with clip effects rendered in, broken out to mono; and for AAF an
//! optional video mixdown rendered to one file.
//!
//! `file.exportAaf {path, sequence?, mixdownVideo?, breakoutToMono?, audio?: "embedded"|"separate"|
//! "linked", audioFormat?: "wav"|"aiff"|"mxf" (OP-Atom, AAF only), sampleRate?, bitDepth?, trimAudio?, handles? (frames),
//! renderAudioEffects?, smallSectors?}`
//!
//! `file.exportOmf {path, sequence?, audio?: "embedded"|"separate", audioFormat?, sampleRate?,
//! bitDepth?, trimAudio? (default on), handles?, renderAudioEffects?, breakoutToMono?}`
//!
//! `file.importAaf {path, bin?}` (also `file.import` of `.aaf` / `.omf` files).
use std::sync::{Arc, Mutex};
use serde_json::{Value, json};
use filmcraft_interchange::essence::{AudioEssence, AudioNeed, EssenceData, EssenceKey, MediaOptions, MixdownVideo, NeedOptions, NestNeeds, audio_needs};
use filmcraft_project::{ClipId, ItemId, Project, Sequence, SequenceSettings, Track, TrackItem, TrackKind};
use filmcraft_time::{Tick, TimeRange};
use crate::commands::{bad, bool_p, str_p, u64_p};
use crate::{EngineError, Result, Session};
/// Where exported audio goes.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum AudioMode {
/// Inside the document.
Embedded,
/// Separate WAV / AIFF files next to the document.
Separate,
/// The original media files (AAF only; untrimmed, unrendered).
Linked,
}
/// The audio settings of the AAF / OMF export dialogs.
#[derive(Clone, Debug)]
pub struct AudioPlan {
pub mode: AudioMode,
pub aiff: bool,
/// Separate files as OP-Atom MXF (AAF only; Avid-style consolidated media).
pub mxf: bool,
pub sample_rate: u32,
pub bits: u16,
pub trim: bool,
pub handles: Tick,
pub render_effects: bool,
pub breakout: bool,
/// Nested sequences on the audio tracks. OMF: their sound is rendered into the export, as
/// Premiere Pro does. AAF: they are written as compositions, so the media of the clips inside
/// them is prepared like the rest.
pub nests: NestNeeds,
}
fn plan_from(s: &Session, p: &Value, seq: ItemId, cmd: &str, omf: bool) -> Result<AudioPlan> {
let q = s.project.sequence(seq).ok_or(EngineError::NoSequence)?;
let mode = match str_p(p, "audio").unwrap_or("embedded") {
"embedded" | "embed" | "encapsulate" => AudioMode::Embedded,
"separate" | "separateAudio" => AudioMode::Separate,
"linked" | "link" if !omf => AudioMode::Linked,
other => return Err(bad(cmd, format!("unknown audio mode {other:?} (embedded, separate{})", if omf { "" } else { " or linked" }))),
};
let (aiff, mxf) = match str_p(p, "audioFormat").unwrap_or("wav") {
"wav" | "bwf" | "broadcastWave" => (false, false),
"aiff" | "aif" => (true, false),
"mxf" | "opatom" if !omf => (false, true),
other => return Err(bad(cmd, format!("unknown audio format {other:?} (wav, aiff{})", if omf { "" } else { " or mxf" }))),
};
let sample_rate = u64_p(p, "sampleRate").map(|r| r as u32).unwrap_or(q.settings.sample_rate.max(1));
if !(8_000..=192_000).contains(&sample_rate) {
return Err(bad(cmd, "sampleRate must be 8000–192000"));
}
// A number, or the string the params list it as ("16|24"); anything else is refused rather
// than read as 16 (#4019).
let bits: u16 = match p.get("bitDepth").filter(|v| !v.is_null()) {
None => 16,
Some(v) => match v
.as_u64()
.or_else(|| v.as_f64().filter(|f| f.fract() == 0.0 && *f >= 0.0).map(|f| f as u64))
.or_else(|| v.as_str().and_then(|s| s.trim().parse().ok()))
{
Some(16) => 16,
Some(24) => 24,
_ => return Err(bad(cmd, format!("bitDepth must be 16 or 24, not {v}"))),
},
};
let frames = u64_p(p, "handles").unwrap_or(if omf { 30 } else { 0 }) as i64;
Ok(AudioPlan {
mode,
aiff,
mxf,
sample_rate,
bits,
trim: bool_p(p, "trimAudio").unwrap_or(omf),
handles: q.settings.frame_rate.tick_of(frames),
render_effects: bool_p(p, "renderAudioEffects").unwrap_or(false),
breakout: bool_p(p, "breakoutToMono").unwrap_or(false),
nests: if omf { NestNeeds::Render } else { NestNeeds::Inside },
})
}
fn quantize(planar: &[&Vec<f32>], bits: u16) -> Vec<u8> {
let n = planar.first().map_or(0, |c| c.len());
let bps = if bits >= 24 { 3 } else { 2 };
let mut out = Vec::with_capacity(n * planar.len() * bps);
for i in 0..n {
for c in planar {
let x = c[i].clamp(-1.0, 1.0);
if bps == 3 {
out.extend_from_slice(&((x * 8_388_607.0).round() as i32).to_le_bytes()[..3]);
} else {
out.extend_from_slice(&((x * 32_767.0).round() as i16).to_le_bytes());
}
}
}
out
}
fn dequantize(pcm: &[u8], channels: usize, bits: u16) -> Vec<Vec<f32>> {
let bps = bits.div_ceil(8) as usize;
let ch = channels.max(1);
let n = pcm.len() / (bps * ch).max(1);
let mut out = vec![Vec::with_capacity(n); ch];
for i in 0..n {
for (c, o) in out.iter_mut().enumerate() {
let s = &pcm[(i * ch + c) * bps..(i * ch + c + 1) * bps];
let v = match bps {
1 => (s[0] as f32 - 128.0) / 128.0,
2 => i16::from_le_bytes([s[0], s[1]]) as f32 / 32_768.0,
3 => (i32::from_le_bytes([0, s[0], s[1], s[2]]) >> 8) as f32 / 8_388_608.0,
_ => i32::from_le_bytes([s[0], s[1], s[2], s[3]]) as f32 / 2_147_483_648.0,
};
o.push(v);
}
}
out
}
const MAX_EXPORT_AUDIO_CHANNELS: usize = 64;
const MAX_EXPORT_AUDIO_SAMPLES: usize = 64 * 1024 * 1024;
/// Decode a media range at `sample_rate` (planar).
fn decode(s: &Session, need: &AudioNeed, sample_rate: u32) -> Result<Vec<Vec<f32>>> {
let src = s
.media
.full_res_source(&s.project, need.item, &*s.services)
.ok_or_else(|| EngineError::Other(format!("media {} is offline", need.path.as_deref().unwrap_or("?"))))?;
let start = need.start.to_units_floor(sample_rate as i64);
let frames = (need.end.to_units_floor(sample_rate as i64) - start).max(0) as usize;
let ch = (need.channels.max(1) as usize).min(MAX_EXPORT_AUDIO_CHANNELS);
let total_samples = ch.checked_mul(frames).ok_or_else(|| EngineError::Other("audio export buffer size overflow".into()))?;
if total_samples > MAX_EXPORT_AUDIO_SAMPLES {
return Err(EngineError::Other(format!("audio export buffer size {total_samples} samples exceeds maximum allowed ({MAX_EXPORT_AUDIO_SAMPLES})")));
}
let mut out: Vec<Vec<f32>> = vec![Vec::with_capacity(frames); ch];
let chunk = sample_rate as usize * 10;
let mut done = 0usize;
while done < frames {
let n = chunk.min(frames - done);
let b = src.audio_stream(need.audio_stream, start + done as i64, n, sample_rate).map_err(|e| EngineError::Other(e.to_string()))?;
for (c, o) in out.iter_mut().enumerate() {
match b.channels.get(c).or(b.channels.first()) {
Some(x) => o.extend(x.iter().copied().chain(std::iter::repeat(0.0)).take(n)),
None => o.extend(std::iter::repeat_n(0.0, n)),
}
}
done += n;
}
Ok(out)
}
/// Render one clip (with its effects, gain and volume) over a media range, through the export
/// pipeline's audio mixer.
fn render_clip(s: &Session, seq: ItemId, need: &AudioNeed, sample_rate: u32, bits: u16) -> Result<Vec<Vec<f32>>> {
let EssenceKey::Clip(clip_id) = need.key else { return decode(s, need, sample_rate) };
let (q, track, c) = audio_clip(&s.project, seq, clip_id).ok_or_else(|| EngineError::Other("clip not found".into()))?;
let c = c.clone();
let mut p: Project = (*s.project).clone();
let settings = SequenceSettings { sample_rate, ..q.settings.clone() };
let rs = p.new_sequence("AAF audio render", settings, 0, 1, None);
let dur = need.end - need.start;
let mut c = c;
c.start = Tick::ZERO;
c.source_in = need.start;
c.duration = dur;
c.speed = 1.0;
c.reverse = false;
c.link = None;
let channels = match track.channels {
filmcraft_project::AudioChannels::Mono => 1,
filmcraft_project::AudioChannels::Surround51 => 6,
_ => 2,
};
if let Some(t) = p.sequence_mut(rs).and_then(|r| r.audio_tracks.first_mut()) {
t.channels = track.channels;
t.items = vec![c];
}
let buf: Arc<Mutex<Vec<u8>>> = Arc::default();
let sink_buf = buf.clone();
let mut settings = filmcraft_export::ExportSettings {
format: filmcraft_export::Format::Wav,
path: "render.wav".into(),
range: Some(TimeRange::new(Tick::ZERO, dur)),
part_of_batch: true,
sink: Some(filmcraft_export::OutputSink(Arc::new(move |_: &str, d: Vec<u8>| {
*sink_buf.lock().unwrap_or_else(|e| e.into_inner()) = d;
Ok(())
}))),
..Default::default()
};
settings.audio.sample_rate = Some(sample_rate);
settings.audio.channels = channels;
settings.audio.bits = bits;
let project = Arc::new(p);
let provider = s.media.full_res_provider(project.clone(), s.services.clone());
filmcraft_export::export(&project, rs, &settings, &provider, &Default::default()).map_err(|e| EngineError::Other(e.to_string()))?;
let wav = std::mem::take(&mut *buf.lock().unwrap_or_else(|e| e.into_inner()));
let (pcm, ch, _, b) = filmcraft_interchange::wav::parse_wav(&wav).ok_or_else(|| EngineError::Other("audio render produced no WAVE data".into()))?;
Ok(dequantize(&pcm, ch as usize, b))
}
/// The audio clip `clip` with its track and sequence: in `seq`, or in a sequence nested in it
/// (clip ids are unique in a project).
fn audio_clip(p: &Project, seq: ItemId, clip: ClipId) -> Option<(&Sequence, &Track, &TrackItem)> {
let first = p.sequence(seq).into_iter();
let others = p.sequences().filter(|i| i.id != seq).filter_map(|i| p.sequence(i.id));
for q in first.chain(others) {
if let Some((t, c)) = q.tracks(TrackKind::Audio).iter().find_map(|t| t.items.iter().find(|c| c.id == clip).map(|c| (t, c))) {
return Some((q, t, c));
}
}
None
}
fn safe_name(s: &str) -> String {
let n: String = s.chars().map(|c| if c.is_alphanumeric() || " -_.".contains(c) { c } else { '_' }).collect();
let n = n.trim().trim_matches('.').to_string();
if n.is_empty() { "audio".into() } else { n }
}
fn ensure_dir(s: &Session, dir: &str) {
if !s.services.export_in_memory() && !dir.is_empty() {
let _ = std::fs::create_dir_all(dir);
}
}
fn check_linked_streams(s: &Session, seq: ItemId, plan: &AudioPlan) -> Result<()> {
if plan.mode == AudioMode::Linked && !plan.trim && !plan.render_effects {
let needs = audio_needs(&s.project, seq, &NeedOptions { nests: plan.nests, ..Default::default() });
if needs.iter().any(|need| need.audio_stream > 0) {
return Err(EngineError::Other("linked AAF media cannot select container audio streams; choose embedded or separate audio".into()));
}
}
Ok(())
}
/// Prepare the audio essence of an export; returns the essence and the files written.
pub fn prepare_audio(s: &Session, seq: ItemId, plan: &AudioPlan, media_dir: &str) -> Result<(Vec<AudioEssence>, Vec<String>)> {
check_linked_streams(s, seq, plan)?;
if plan.mode == AudioMode::Linked && !plan.trim && !plan.render_effects {
return Ok((Vec::new(), Vec::new()));
}
let needs = audio_needs(
&s.project,
seq,
&NeedOptions { handles: plan.handles, per_clip: plan.render_effects, whole_media: !plan.trim && !plan.render_effects, nests: plan.nests },
);
let mut essence = Vec::new();
let mut files = Vec::new();
let mut used = std::collections::HashSet::new();
for need in &needs {
// a nested sequence has no file to read: its sound is mixed, with what is on the clip
let nest = s.project.sequence(need.item).is_some();
let planar = if plan.render_effects || nest { render_clip(s, seq, need, plan.sample_rate, plan.bits)? } else { decode(s, need, plan.sample_rate)? };
let frames = planar.first().map_or(0, Vec::len) as u64;
let groups: Vec<(Option<u32>, Vec<&Vec<f32>>)> =
if plan.breakout { planar.iter().enumerate().map(|(c, x)| (Some(c as u32), vec![x])).collect() } else { vec![(None, planar.iter().collect())] };
let base = match need.key {
EssenceKey::Clip(c) => {
let name = audio_clip(&s.project, seq, c).map(|(_, _, ti)| ti.name.clone()).unwrap_or_default();
format!("{} {}", safe_name(&name), c.0)
}
EssenceKey::Media(_) | EssenceKey::MediaStream { .. } => safe_name(
need.path
.as_deref()
.map(|p| std::path::Path::new(p).file_stem().map(|x| x.to_string_lossy().into_owned()).unwrap_or_default())
.as_deref()
.unwrap_or("audio"),
),
};
for (ch, chans) in groups {
let pcm = quantize(&chans, plan.bits);
let n = chans.len() as u32;
let data = match plan.mode {
AudioMode::Embedded => EssenceData::Embedded(pcm),
AudioMode::Separate | AudioMode::Linked => {
let ext = if plan.mxf {
"mxf"
} else if plan.aiff {
"aif"
} else {
"wav"
};
let stem = match ch {
Some(c) => format!("{base}_A{}", c + 1),
None => base.clone(),
};
let mut name = format!("{stem}.{ext}");
let mut k = 1;
while !used.insert(name.to_ascii_lowercase()) {
k += 1;
name = format!("{stem} ({k}).{ext}");
}
let path = if media_dir.is_empty() { name.clone() } else { format!("{media_dir}/{name}") };
let bytes = if plan.mxf {
let bps = plan.bits.div_ceil(8) as usize;
let samples: Vec<i32> = pcm
.chunks_exact(bps)
.map(|b| if bps == 3 { i32::from_le_bytes([0, b[0], b[1], b[2]]) >> 8 } else { i16::from_le_bytes([b[0], b[1]]) as i32 })
.collect();
let opts = craft_media::mxf::OpAtomPcm {
sample_rate: plan.sample_rate,
bits: plan.bits as u32,
channels: n,
edit_rate: None,
ids: craft_media::mxf::PackageIds::from_seed(&path, &name),
timecode: None,
};
craft_media::mxf::write_opatom_pcm_as(&opts, &samples, "FilmCraft", "FilmCraft", env!("CARGO_PKG_VERSION"))
.map_err(|e| EngineError::Other(format!("{path}: {e}")))?
} else if plan.aiff {
filmcraft_interchange::wav::aiff_file(&pcm, n as u16, plan.sample_rate, plan.bits)
} else {
filmcraft_interchange::wav::wav_file(&pcm, n as u16, plan.sample_rate, plan.bits)
};
s.services.write_file(&path, &bytes).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
files.push(path.clone());
EssenceData::File { path }
}
};
essence.push(AudioEssence {
key: need.key,
channel: ch,
start: need.start,
frames,
sample_rate: plan.sample_rate,
bits: plan.bits,
channels: n,
data,
effects_rendered: plan.render_effects || nest,
});
}
}
Ok((essence, files))
}
/// Render the video of `seq` to one file for an AAF video mixdown.
fn mixdown(s: &Session, seq: ItemId, path: &str) -> Result<MixdownVideo> {
let q = s.project.sequence(seq).ok_or(EngineError::NoSequence)?;
let dur = q.duration();
if dur <= Tick::ZERO {
return Err(EngineError::Other("the sequence is empty".into()));
}
let format = if path.to_ascii_lowercase().ends_with(".mxf") {
filmcraft_export::Format::from_name("mxf-opatom").unwrap_or(filmcraft_export::Format::DnxHr)
} else {
filmcraft_export::Format::DnxHr
};
let mut settings = filmcraft_export::ExportSettings {
format,
path: path.to_string(),
range: Some(TimeRange::new(Tick::ZERO, dur)),
include_audio: false,
part_of_batch: true,
dnx_profile: "hq".into(),
..Default::default()
};
if s.services.export_in_memory() {
let services = s.services.clone();
settings.sink = Some(filmcraft_export::OutputSink(Arc::new(move |p: &str, d: Vec<u8>| services.write_file(p, &d))));
}
let project = s.project.clone();
let provider = s.media.full_res_provider(project.clone(), s.services.clone());
filmcraft_export::export(&project, seq, &settings, &provider, &Default::default()).map_err(|e| EngineError::Other(format!("video mixdown: {e}")))?;
Ok(MixdownVideo { path: path.to_string(), start: Tick::ZERO, duration: dur, width: q.settings.width, height: q.settings.height })
}
fn report_json(r: &filmcraft_interchange::Report) -> Vec<String> {
r.entries.iter().map(|e| if e.count > 1 { format!("{} (×{})", e.message, e.count) } else { e.message.clone() }).collect()
}
fn split(path: &str) -> (String, String) {
let p = std::path::Path::new(path);
let dir = p.parent().map(|d| d.to_string_lossy().to_string()).unwrap_or_default();
let stem = p.file_stem().map(|n| n.to_string_lossy().to_string()).unwrap_or_else(|| "Export".into());
(dir, stem)
}
fn join(dir: &str, name: &str) -> String {
if dir.is_empty() { name.to_string() } else { format!("{dir}/{name}") }
}
/// `file.exportAaf`
pub fn export_aaf(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "file.exportAaf";
let path = str_p(p, "path").ok_or_else(|| bad(cmd, "need `path`"))?.to_string();
let seq = crate::export_tools::sequence_param(s, p, cmd)?;
let plan = plan_from(s, p, seq, cmd, false)?;
check_linked_streams(s, seq, &plan)?;
let (dir, stem) = split(&path);
let media_dir = join(&dir, &format!("{stem} Media"));
let mut files = Vec::new();
if plan.mode != AudioMode::Embedded || bool_p(p, "mixdownVideo").unwrap_or(false) {
ensure_dir(s, &media_dir);
}
let (essence, written) = prepare_audio(s, seq, &plan, &media_dir)?;
files.extend(written);
let mixdown_video = if bool_p(p, "mixdownVideo").unwrap_or(false) {
let ext = if str_p(p, "mixdownFormat") == Some("mxf") { "mxf" } else { "mov" };
let m = mixdown(s, seq, &join(&media_dir, &format!("{} Video Mixdown.{ext}", safe_name(&stem))))?;
files.push(m.path.clone());
Some(m)
} else {
None
};
let opts = filmcraft_interchange::aaf::AafOptions {
name: s.project.item(seq).map(|i| i.name.clone()),
media: MediaOptions { breakout_to_mono: plan.breakout, audio_only: false, essence, mixdown_video },
small_sectors: bool_p(p, "smallSectors").unwrap_or(false),
};
let (bytes, report) = filmcraft_interchange::aaf::export(&s.project, seq, &opts).map_err(|e| EngineError::Other(e.to_string()))?;
s.services.write_file(&path, &bytes).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
Ok(json!({"path": path, "bytes": bytes.len(), "mediaFiles": files, "report": report_json(&report)}))
}
/// `file.exportOmf`
pub fn export_omf(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "file.exportOmf";
let path = str_p(p, "path").ok_or_else(|| bad(cmd, "need `path`"))?.to_string();
let seq = crate::export_tools::sequence_param(s, p, cmd)?;
let plan = plan_from(s, p, seq, cmd, true)?;
let (dir, stem) = split(&path);
let media_dir = join(&dir, &format!("{stem} Audio Files"));
if plan.mode == AudioMode::Separate {
ensure_dir(s, &media_dir);
}
let (essence, files) = prepare_audio(s, seq, &plan, &media_dir)?;
let opts = filmcraft_interchange::omf::OmfOptions {
name: str_p(p, "title").map(str::to_string).or_else(|| s.project.item(seq).map(|i| i.name.clone())),
media: MediaOptions { breakout_to_mono: plan.breakout, audio_only: true, essence, mixdown_video: None },
};
let (bytes, report) = filmcraft_interchange::omf::export(&s.project, seq, &opts).map_err(|e| EngineError::Other(e.to_string()))?;
if bytes.len() as u64 > i32::MAX as u64 {
return Err(EngineError::Other("the OMF file would exceed 2 GB; use separate audio files or trim the audio".into()));
}
s.services.write_file(&path, &bytes).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
Ok(json!({"path": path, "bytes": bytes.len(), "mediaFiles": files, "report": report_json(&report)}))
}
/// `file.importAaf` (and OMF): import a document as sequences.
pub fn import_document(s: &mut Session, p: &Value, cmd: &str) -> Result<Value> {
let path = str_p(p, "path").ok_or_else(|| bad(cmd, "need `path`"))?.to_string();
let bytes = s.services.read_file(&path).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
let format = crate::interchange::detect(&path, &bytes).filter(|f| matches!(f, filmcraft_interchange::Format::Aaf | filmcraft_interchange::Format::Omf));
let format = format.ok_or_else(|| bad(cmd, format!("{path} is not an AAF or OMF file")))?;
let bin = u64_p(p, "bin").map(filmcraft_project::BinId);
crate::interchange::import(s, &path, &bytes, format, bin)
}
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.