f67d38b35cc5
project_tools.rs
//! File / Edit / Clip menu long tail (M3.11), and [`apply_layout`], which puts these commands (and
//! those of `sequence_extras` and `scene_detect`) in Premiere's menu order.
//!
//! | Id | Menu |
//! |---|---|
//! | `file.newSearchBin` | File ▸ New ▸ Search Bin (`project.searchBinItems`, `project.editSearchBin`, `project.deleteSearchBin`) |
//! | `file.close` | File ▸ Close (⌘W): closes the active sequence |
//! | `file.closeAllProjects` / `file.closeAllOtherProjects` | File ▸ Close All Projects / Close All Other Projects |
//! | `file.saveAsTemplate` | File ▸ Save as Template… (`file.templates`, `file.newProjectFromTemplate`) |
//! | `file.importFromMediaBrowser` | File ▸ Import from Media Browser (⌥⌘I) |
//! | `file.exportSelectionProject` | File ▸ Export ▸ Selection as FilmCraft Project… |
//! | `file.exportAle` | File ▸ Export ▸ Avid Log Exchange… |
//! | `file.mediaPropertiesFile` / `file.mediaProperties` | File ▸ Get Media File Properties for ▸ File… / Selection… (⇧⌘H) |
//! | `file.projectSettings.general` / `.scratchDisks` | File ▸ Project Settings ▸ General… / Scratch Disks… |
//! | `edit.find` / `edit.findNext` | Edit ▸ Find… (⌘F) / Find Next |
//! | `edit.editOriginal` | Edit ▸ Edit Original (⌘E): the frontend opens the files (regular files with a media extension only) |
//! | `file.reveal` | Project panel ▸ Reveal in Finder / Show in Explorer: the frontend reveals the media file |
//! | `clip.editOffline` | Clip ▸ Edit Offline… |
//! | `clip.sourceSettings` | Clip ▸ Source Settings… |
//! | `clip.restoreCaptionsFromSource` | Clip ▸ Restore Captions from Source Clip (always disabled: no embedded caption reader) |
//! | `clip.updateMetadata` | Clip ▸ Update Metadata… (XMP sidecars) |
//! | `clip.generateAudioWaveform` | Clip ▸ Generate Audio Waveform (the frontend rebuilds its peaks) |
//! | `clip.automateToSequence` | Clip ▸ Automate to Sequence… |
//! | `help.systemReport` | query behind Help ▸ System Compatibility Report… |
use std::collections::{BTreeMap, BTreeSet};
use filmcraft_project::{BinEntry, FindOp, FindQuery, FindRow, ItemId, ItemKind, MarkerKind, MediaRef, Project, SearchBin, TrackKind};
use filmcraft_time::{Tick, TimeDisplay, TimeRange};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use crate::commands::{CommandSpec, always, bad, bool_p, has_project_selection, has_seq, str_p, u64_p};
use crate::{EngineError, Result, Session};
type Run = fn(&mut Session, &Value) -> Result<Value>;
type Enabled = fn(&Session) -> std::result::Result<(), String>;
fn spec(
id: &'static str,
label: &'static str,
menu: &'static [&'static str],
shortcut: Option<&'static str>,
params: &'static str,
enabled: Enabled,
run: Run,
) -> CommandSpec {
CommandSpec { id, label, menu, shortcut, params, enabled, run, journal: true, named: crate::commands::NamedKeys::NONE }
}
fn query(
id: &'static str,
label: &'static str,
menu: &'static [&'static str],
shortcut: Option<&'static str>,
params: &'static str,
enabled: Enabled,
run: Run,
) -> CommandSpec {
CommandSpec { id, label, menu, shortcut, params, enabled, run, journal: false, named: crate::commands::NamedKeys::NONE }
}
const FIND_PARAMS: &str = r#"{"scope":"project|timeline"?,"column":str?,"operator":"contains|matches|beginsWith|endsWith|doesNotContain"?,"text":str?,"rows":[{"column":str,"operator":str,"text":str}]?,"matchAll":bool=true,"caseSensitive":bool=false,"in":"all|clips|markers"?}"#;
pub(crate) fn commands() -> Vec<CommandSpec> {
vec![
// ---------------- File ----------------
spec(
"file.newSearchBin",
"Search Bin",
&["File", "New"],
None,
r#"{"name":str?,"column":str?,"operator":str?,"text":str?,"rows":[..]?,"matchAll":bool?,"caseSensitive":bool?}"#,
always,
new_search_bin,
),
query("project.searchBinItems", "Search Bin Contents", &[], None, r#"{"bin":id}"#, always, search_bin_items),
spec(
"project.editSearchBin",
"Edit Search Bin",
&[],
None,
r#"{"bin":id,"name":str?,"column":str?,"operator":str?,"text":str?,"rows":[..]?,"matchAll":bool?,"caseSensitive":bool?}"#,
always,
edit_search_bin,
),
spec("project.deleteSearchBin", "Delete Search Bin", &[], None, r#"{"bin":id}"#, always, delete_search_bin),
spec("file.close", "Close", &["File"], Some("Cmd+W"), r#"{"item":id?}"#, has_seq, |s, p| s.execute("sequence.close", p.clone())),
spec("file.closeAllProjects", "Close All Projects", &["File"], None, r#"{"force":bool?}"#, always, |s, p| s.execute("file.closeProject", p.clone())),
spec("file.closeAllOtherProjects", "Close All Other Projects", &["File"], None, "{}", only_one_project, |_, _| {
Err(EngineError::Other("only one project is open".into()))
}),
spec("file.saveAsTemplate", "Save as Template…", &["File"], None, r#"{"name":str?,"path":str?}"#, always, save_as_template),
query("file.templates", "List Project Templates", &[], None, "{}", always, list_templates),
spec("file.newProjectFromTemplate", "New Project from Template", &[], None, r#"{"template":name|path,"name":str?}"#, always, new_from_template),
spec(
"file.importFromMediaBrowser",
"Import from Media Browser",
&["File"],
Some("Cmd+Alt+I"),
r#"{"paths":[str]?,"imageSequence":bool?}"#,
always,
|s, p| {
// the Media Browser's selection unless `paths` are given
let paths = match p.get("paths").and_then(Value::as_array) {
Some(a) => a.clone(),
None => s.browser.selection.iter().map(|x| json!(x)).collect(),
};
if paths.is_empty() {
return Err(bad("file.importFromMediaBrowser", "select files in the Media Browser"));
}
let seq = p.get("imageSequence").and_then(Value::as_bool).unwrap_or(false);
s.execute("file.import", json!({"paths": paths, "imageSequence": seq}))
},
),
// File ▸ Import with "Image Sequence" checked (the UI asks for the first frame).
spec("file.importImageSequence", "Import Image Sequence…", &["File"], None, r#"{"path":str,"bin":binId?}"#, always, |s, p| {
let path = p.get("path").and_then(Value::as_str).ok_or_else(|| bad("file.importImageSequence", "need `path` (the first numbered still)"))?;
let mut q = json!({"paths": [path], "imageSequence": true});
if let Some(b) = p.get("bin") {
q["bin"] = b.clone();
}
s.execute("file.import", q)
}),
spec(
"file.exportSelectionProject",
"Selection as FilmCraft Project…",
&["File", "Export"],
None,
r#"{"path":str,"items":[id]?}"#,
has_project_selection,
export_selection,
),
spec("file.exportAle", "Avid Log Exchange…", &["File", "Export"], None, r#"{"path":str,"items":[id]?}"#, has_loggable, export_ale),
query("file.mediaPropertiesFile", "File…", &["File", "Get Media File Properties for"], None, r#"{"path":str}"#, always, media_properties_file),
query(
"file.mediaProperties",
"Selection…",
&["File", "Get Media File Properties for"],
Some("Cmd+Shift+H"),
r#"{"items":[id]?}"#,
has_media_selection,
media_properties,
),
spec(
"file.projectSettings.general",
"General…",
&["File", "Project Settings"],
None,
r#"{"renderer":"gpu|software"?,"videoDisplay":"timecode|feet35|feet16|frames"?,"audioDisplay":"samples|milliseconds"?,"captureFormat":"DV|HDV"?,"titleSafe":[h,v]?,"actionSafe":[h,v]?}"#,
always,
project_settings_general,
),
spec(
"file.projectSettings.scratchDisks",
"Scratch Disks…",
&["File", "Project Settings"],
None,
r#"{"captured":path|null?,"videoPreviews":path|null?,"audioPreviews":path|null?,"autoSave":path|null?}"#,
always,
project_settings_scratch,
),
// ---------------- Edit ----------------
spec("edit.find", "Find…", &["Edit"], Some("Cmd+F"), FIND_PARAMS, always, find),
spec("edit.findNext", "Find Next", &["Edit"], None, "{}", has_find, find_next),
spec("edit.editOriginal", "Edit Original", &["Edit"], Some("Cmd+E"), r#"{"items":[id]?}"#, has_original, edit_original),
// Project panel context menu (not in the File menu): reveal the clip's media file.
query("file.reveal", "Reveal in Finder", &[], None, r#"{"items":[id]?}"#, has_file_selection, edit_original),
// ---------------- Clip ----------------
spec(
"clip.editOffline",
"Edit Offline…",
&["Clip"],
None,
r#"{"item":id?,"mediaName":str?,"tapeName":str?,"description":str?,"scene":str?,"shot":str?,"logNote":str?}"#,
has_offline_selection,
edit_offline,
),
query("clip.sourceSettings", "Source Settings…", &["Clip"], None, r#"{"item":id?}"#, has_media_selection, source_settings),
spec("clip.restoreCaptionsFromSource", "Restore Captions from Source Clip", &["Clip"], None, "{}", no_embedded_captions, |_, _| {
Err(EngineError::Other(NO_CAPTIONS.into()))
}),
spec("clip.updateMetadata", "Update Metadata…", &["Clip"], None, r#"{"items":[id]?}"#, has_file_selection, update_metadata),
query("clip.generateAudioWaveform", "Generate Audio Waveform", &["Clip"], None, r#"{"items":[id]?}"#, has_audio_selection, generate_waveform),
spec(
"clip.automateToSequence",
"Automate to Sequence…",
&["Clip"],
None,
r#"{"items":[id]?,"ordering":"sort|selection"?,"placement":"sequentially|unnumberedMarkers"?,"method":"insert|overwrite"?,"overlapFrames":n=30,"stillFrames":n?,"videoTransition":bool=true,"audioTransition":bool=true,"ignoreAudio":bool=false,"ignoreVideo":bool=false}"#,
can_automate,
automate_to_sequence,
),
// ---------------- Help ----------------
query("help.systemReport", "System Compatibility Report", &[], None, "{}", always, |_, _| Ok(system_report())),
]
}
// ---------------------------------------------------------------------------------------------
// menu layout
// ---------------------------------------------------------------------------------------------
enum At {
After(&'static str),
Before(&'static str),
}
/// Add this module's, `sequence_extras`' and `scene_detect`'s commands and arrange them (and a few
/// existing ones) in Premiere's menu order.
pub(crate) fn apply_layout(v: &mut Vec<CommandSpec>) {
let mut pool = commands();
pool.extend(crate::sequence_extras::commands());
pool.extend(crate::scene_detect::commands());
// Apply Default Transitions to Selection works on selected clips too (⇧D), not only on
// selected edit points; the Trim Monitor button keeps using the same id.
if let Some(c) = v.iter_mut().find(|c| c.id == "trim.applyDefaultTransition")
&& let Some(i) = pool.iter().position(|c| c.id == "sequence.applyDefaultTransitionsToSelection")
{
let new = pool.remove(i);
c.enabled = new.enabled;
c.run = new.run;
c.params = new.params;
}
// Project Settings ▸ Ingest Settings…
if let Some(c) = v.iter_mut().find(|c| c.id == "project.ingestSettings") {
c.menu = &["File", "Project Settings"];
}
let layout: Vec<(At, Vec<&'static str>)> = vec![
(At::After("file.newBinFromSelection"), vec!["file.newSearchBin"]),
(At::Before("file.closeProject"), vec!["file.close"]),
(At::After("file.closeProject"), vec!["file.closeAllProjects", "file.closeAllOtherProjects"]),
(At::After("file.saveCopy"), vec!["file.saveAsTemplate"]),
(At::After("file.exportEdl"), vec!["file.exportSelectionProject", "file.exportAle", "file.exportOtio", "file.exportFcp7Xml", "file.exportFcpxml"]),
(
At::Before("file.projectManager"),
vec![
"file.mediaPropertiesFile",
"file.mediaProperties",
"file.projectSettings.general",
"file.projectSettings.scratchDisks",
"project.ingestSettings",
],
),
(At::After("edit.deselectAll"), vec!["edit.find", "edit.findNext"]),
(At::After("edit.consolidateDuplicates"), vec!["edit.editOriginal"]),
(At::After("clip.editSubclip"), vec!["clip.editOffline", "clip.sourceSettings"]),
(At::After("clip.speedDuration"), vec!["clip.sceneEditDetection"]),
(
At::After("clip.replaceFromBin"),
vec!["clip.restoreCaptionsFromSource", "clip.updateMetadata", "clip.generateAudioWaveform", "clip.automateToSequence"],
),
(At::After("sequence.applyAudioTransition"), vec!["trim.applyDefaultTransition"]),
(At::After("sequence.showThroughEdits"), vec!["sequence.normalizeMixTrack"]),
(At::After("sequence.makeSubsequence"), vec!["sequence.transcribe", "sequence.simplify"]),
(At::After("captions.showAll"), vec!["captions.showActiveOnly"]),
(At::After("markers.addChapter"), vec!["markers.addFlashCue"]),
(At::Before("file.close"), vec!["file.open"]),
(At::After("media.makeOffline"), vec!["file.importFromMediaBrowser", "file.import", "file.importImageSequence"]),
];
for (at, ids) in layout {
let mut run = Vec::new();
for id in ids {
if let Some(i) = pool.iter().position(|c| c.id == id) {
run.push(pool.remove(i));
} else if let Some(i) = v.iter().position(|c| c.id == id) {
run.push(v.remove(i));
}
}
let idx = match at {
At::After(a) => v.iter().position(|c| c.id == a).map(|i| i + 1),
At::Before(b) => v.iter().position(|c| c.id == b),
}
.unwrap_or(v.len());
v.splice(idx..idx, run);
}
v.extend(pool);
reorder(v, &SEQUENCE_MENU);
}
/// The Sequence menu in Premiere's order (submenu items where their submenu goes).
const SEQUENCE_MENU: [&str; 34] = [
"sequence.settings",
"sequence.renderEffectsInToOut",
"sequence.renderInToOut",
"sequence.renderSelection",
"sequence.renderAudio",
"sequence.deleteRenderFiles",
"sequence.deleteRenderFilesInToOut",
"sequence.matchFrame",
"sequence.reverseMatchFrame",
"sequence.addEdit",
"sequence.addEditAllTracks",
"trim.edit",
"sequence.applyVideoTransition",
"sequence.applyAudioTransition",
"trim.applyDefaultTransition",
"sequence.lift",
"sequence.extract",
"sequence.closeGap",
"sequence.goToNextGap",
"sequence.goToPrevGap",
"sequence.goToNextGapInTrack",
"sequence.goToPrevGapInTrack",
"sequence.snap",
"sequence.linkedSelection",
"sequence.selectionFollowsPlayhead",
"sequence.showThroughEdits",
"sequence.normalizeMixTrack",
"sequence.makeSubsequence",
"sequence.transcribe",
"sequence.simplify",
"sequence.addTracks",
"sequence.deleteTracks",
"sequence.colorSettings",
"mixer.addSubmix",
];
/// Put the commands `ids` (those present) in this order, at the position of the first of them.
fn reorder(v: &mut Vec<CommandSpec>, ids: &[&str]) {
let Some(at) = v.iter().position(|c| ids.contains(&c.id)) else { return };
let mut run = Vec::new();
for id in ids {
if let Some(i) = v.iter().position(|c| c.id == *id) {
run.push(v.remove(i));
}
}
let at = at.min(v.len());
v.splice(at..at, run);
}
// ---------------------------------------------------------------------------------------------
// enablement
// ---------------------------------------------------------------------------------------------
fn only_one_project(_: &Session) -> std::result::Result<(), String> {
Err("only one project is open".into())
}
const NO_CAPTIONS: &str = "the clip's media has no embedded captions FilmCraft can read (embedded CEA-608/708 caption streams are not supported yet)";
fn no_embedded_captions(_: &Session) -> std::result::Result<(), String> {
Err(NO_CAPTIONS.into())
}
fn has_find(s: &Session) -> std::result::Result<(), String> {
if s.state.find.is_some() { Ok(()) } else { Err("use Find… first".into()) }
}
/// Project items the command works on: `items`, else the Project panel selection, else the media
/// of the selected timeline clips.
fn targets(s: &Session, p: &Value) -> Vec<ItemId> {
if let Some(a) = p.get("items").and_then(Value::as_array) {
return a.iter().filter_map(|v| v.as_u64().map(ItemId)).filter(|i| s.project.items.contains_key(i)).collect();
}
if let Some(i) = u64_p(p, "item") {
return vec![ItemId(i)];
}
if !s.state.project_selection.is_empty() {
return s.state.project_selection.clone();
}
let mut out = Vec::new();
if let Some(q) = s.active_sequence() {
for c in &s.state.selection {
if let Some((_, it)) = q.find_item(*c)
&& !out.contains(&it.item)
{
out.push(it.item);
}
}
}
out
}
/// The media clip behind an item (subclips resolve to their parent).
fn media_of(p: &Project, id: ItemId) -> Option<(ItemId, &filmcraft_project::MediaClip)> {
p.resolve_media(id).map(|(root, media, _)| (root, media))
}
fn file_path(m: &filmcraft_project::MediaClip) -> Option<&str> {
match &m.media {
MediaRef::File { path } => Some(path),
MediaRef::Generator(_) => None,
}
}
fn has_media_selection(s: &Session) -> std::result::Result<(), String> {
if targets(s, &Value::Null).iter().any(|i| media_of(&s.project, *i).is_some()) { Ok(()) } else { Err("select a clip".into()) }
}
fn has_file_selection(s: &Session) -> std::result::Result<(), String> {
if targets(s, &Value::Null).iter().any(|i| media_of(&s.project, *i).is_some_and(|(_, m)| file_path(m).is_some())) {
Ok(())
} else {
Err("select a clip with a media file".into())
}
}
fn has_original(s: &Session) -> std::result::Result<(), String> {
has_file_selection(s)
}
fn has_audio_selection(s: &Session) -> std::result::Result<(), String> {
if targets(s, &Value::Null).iter().any(|i| media_of(&s.project, *i).is_some_and(|(_, m)| m.info.has_audio())) {
Ok(())
} else {
Err("select a clip with audio".into())
}
}
fn is_offline(s: &Session, id: ItemId) -> bool {
media_of(&s.project, id).is_some_and(|(mid, m)| m.offline || s.media.offline_status(mid).is_some())
}
fn has_offline_selection(s: &Session) -> std::result::Result<(), String> {
if targets(s, &Value::Null).iter().any(|i| is_offline(s, *i)) { Ok(()) } else { Err("select an offline clip".into()) }
}
fn has_loggable(s: &Session) -> std::result::Result<(), String> {
if s.project.items.keys().any(|i| media_of(&s.project, *i).is_some()) { Ok(()) } else { Err("the project has no clips to log".into()) }
}
fn can_automate(s: &Session) -> std::result::Result<(), String> {
has_seq(s)?;
has_project_selection(s)?;
if s.state.project_selection.iter().any(|i| s.project.item(*i).is_some_and(|it| !matches!(it.kind, ItemKind::Graphic { .. }))) {
Ok(())
} else {
Err("select clips in the Project panel".into())
}
}
// ---------------------------------------------------------------------------------------------
// queries (Find, search bins)
// ---------------------------------------------------------------------------------------------
/// Read a query from params: `rows`, or one `column` / `operator` / `text` row.
pub fn query_p(p: &Value, cmd: &str) -> Result<FindQuery> {
let row = |v: &Value| -> Result<FindRow> {
let op = match str_p(v, "operator").or(str_p(v, "op")) {
Some(o) => FindOp::from_name(o).ok_or_else(|| bad(cmd, format!("unknown operator `{o}`")))?,
None => FindOp::Contains,
};
Ok(FindRow { column: str_p(v, "column").unwrap_or("All").to_string(), op, text: str_p(v, "text").unwrap_or_default().to_string() })
};
let rows = match p.get("rows").and_then(Value::as_array) {
Some(a) => a.iter().map(row).collect::<Result<Vec<_>>>()?,
None => vec![row(p)?],
};
Ok(FindQuery { rows, match_all: bool_p(p, "matchAll").unwrap_or(true), case_sensitive: bool_p(p, "caseSensitive").unwrap_or(false) })
}
fn search_bin_json(p: &Project, b: &SearchBin) -> Value {
json!({"bin": b.id.0, "name": b.name, "query": b.query, "items": b.query.find(p).iter().map(|i| i.0).collect::<Vec<_>>()})
}
fn new_search_bin(s: &mut Session, p: &Value) -> Result<Value> {
let q = query_p(p, "file.newSearchBin")?;
if q.is_empty() {
return Err(bad("file.newSearchBin", "enter text to search for"));
}
let name = str_p(p, "name").map(str::to_string).unwrap_or_else(|| q.rows.iter().find(|r| !r.text.is_empty()).map(|r| r.text.clone()).unwrap_or_default());
let b = s.edit("New Search Bin", |pr, _| {
let id = filmcraft_project::BinId(pr.alloc_id());
let b = SearchBin { id, name, query: q };
pr.search_bins.push(b.clone());
Ok(b)
})?;
Ok(search_bin_json(&s.project, &b))
}
fn bin_p(s: &Session, p: &Value, cmd: &str) -> Result<SearchBin> {
let id = u64_p(p, "bin").ok_or_else(|| bad(cmd, "need `bin`"))?;
s.project.search_bins.iter().find(|b| b.id.0 == id).cloned().ok_or_else(|| bad(cmd, format!("no search bin {id}")))
}
fn search_bin_items(s: &mut Session, p: &Value) -> Result<Value> {
let b = bin_p(s, p, "project.searchBinItems")?;
Ok(search_bin_json(&s.project, &b))
}
fn edit_search_bin(s: &mut Session, p: &Value) -> Result<Value> {
let b = bin_p(s, p, "project.editSearchBin")?;
let q = if p.get("rows").is_some() || p.get("text").is_some() { Some(query_p(p, "project.editSearchBin")?) } else { None };
let name = str_p(p, "name").map(str::to_string);
let out = s.edit("Edit Search Bin", |pr, _| {
let x = pr.search_bins.iter_mut().find(|x| x.id == b.id).ok_or_else(|| bad("project.editSearchBin", "gone"))?;
if let Some(q) = q {
x.query = q;
}
if let Some(n) = name {
x.name = n;
}
Ok(x.clone())
})?;
Ok(search_bin_json(&s.project, &out))
}
fn delete_search_bin(s: &mut Session, p: &Value) -> Result<Value> {
let b = bin_p(s, p, "project.deleteSearchBin")?;
s.edit("Delete Search Bin", |pr, _| {
pr.search_bins.retain(|x| x.id != b.id);
Ok(())
})?;
Ok(Value::Null)
}
/// The last Find: Find Next walks its results.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FindState {
/// `project` or `timeline`.
pub scope: String,
pub query: FindQuery,
/// Timeline: search clip names, marker names / comments, or both (`all`).
pub within: String,
/// Index of the current result.
pub index: usize,
}
/// One timeline Find hit.
#[derive(Clone, Debug, PartialEq)]
enum Hit {
Clip(filmcraft_project::ClipId, Tick),
Marker(filmcraft_project::MarkerId, Tick),
}
fn timeline_hits(s: &Session, f: &FindState) -> Vec<Hit> {
let Some(q) = s.active_sequence() else { return Vec::new() };
let test = |text: &str| {
f.query.rows.iter().filter(|r| !r.text.is_empty()).fold(f.query.match_all, |acc, r| {
let (h, n) = if f.query.case_sensitive { (text.to_string(), r.text.clone()) } else { (text.to_lowercase(), r.text.to_lowercase()) };
let ok = match r.op {
FindOp::Contains => h.contains(&n),
FindOp::Matches => h == n,
FindOp::BeginsWith => h.starts_with(&n),
FindOp::EndsWith => h.ends_with(&n),
FindOp::DoesNotContain => !h.contains(&n),
};
if f.query.match_all { acc && ok } else { acc || ok }
})
};
if f.query.is_empty() {
return Vec::new();
}
let mut hits = Vec::new();
if f.within != "markers" {
for t in q.all_tracks() {
for it in &t.items {
let name = if it.name.is_empty() { s.project.item(it.item).map(|i| i.name.clone()).unwrap_or_default() } else { it.name.clone() };
if test(&name) {
hits.push(Hit::Clip(it.id, it.start));
}
}
}
}
if f.within != "clips" {
for m in &q.markers {
if test(&m.name) || (!m.comment.is_empty() && test(&m.comment)) {
hits.push(Hit::Marker(m.id, m.start));
}
}
}
hits.sort_by_key(|h| match h {
Hit::Clip(_, t) | Hit::Marker(_, t) => *t,
});
hits
}
/// Select / reveal result `f.index`.
fn show_result(s: &mut Session, f: &FindState) -> Result<Value> {
if f.scope == "timeline" {
let hits = timeline_hits(s, f);
let Some(h) = hits.get(f.index % hits.len().max(1)).cloned() else { return Err(EngineError::Other("no matches".into())) };
let out = match h {
Hit::Clip(c, t) => {
s.state.selection = vec![c];
s.set_playhead(t);
json!({"clip": c.0, "time": t.0})
}
Hit::Marker(m, t) => {
s.set_playhead(t);
json!({"marker": m.0, "time": t.0})
}
};
let mut out = out;
out["matches"] = json!(hits.len());
out["index"] = json!(f.index % hits.len().max(1));
return Ok(out);
}
let items = f.query.find(&s.project);
let Some(id) = items.get(f.index % items.len().max(1)).copied() else { return Err(EngineError::Other("no matches".into())) };
s.state.project_selection = vec![id];
Ok(json!({"item": id.0, "matches": items.len(), "index": f.index % items.len().max(1), "items": items.iter().map(|i| i.0).collect::<Vec<_>>()}))
}
fn find(s: &mut Session, p: &Value) -> Result<Value> {
let scope = str_p(p, "scope").unwrap_or("project").to_ascii_lowercase();
if !matches!(scope.as_str(), "project" | "timeline") {
return Err(bad("edit.find", "`scope` is project or timeline"));
}
let within = str_p(p, "in").unwrap_or("all").to_ascii_lowercase();
if scope == "timeline" {
has_seq(s).map_err(EngineError::Other)?;
}
let mut query = query_p(p, "edit.find")?;
// timeline Find searches names: an `All` / empty column is fine
if scope == "timeline" {
query.rows.iter_mut().for_each(|r| r.column = "Name".into());
}
if query.is_empty() {
return Err(bad("edit.find", "enter text to find"));
}
let f = FindState { scope, query, within, index: 0 };
s.state.find = Some(f.clone());
show_result(s, &f)
}
fn find_next(s: &mut Session, _: &Value) -> Result<Value> {
let mut f = s.state.find.clone().ok_or_else(|| EngineError::Other("use Find… first".into()))?;
f.index += 1;
let r = show_result(s, &f);
if let Ok(v) = &r {
f.index = v["index"].as_u64().unwrap_or(0) as usize;
s.state.find = Some(f);
}
r
}
// ---------------------------------------------------------------------------------------------
// templates, closing
// ---------------------------------------------------------------------------------------------
/// Where project templates live: `<data dir>/Templates` (None without a data directory).
pub fn templates_dir(s: &Session) -> Option<std::path::PathBuf> {
s.prefs_path.as_ref().and_then(|p| p.parent()).map(|d| d.join("Templates"))
}
fn save_as_template(s: &mut Session, p: &Value) -> Result<Value> {
let name = str_p(p, "name").map(str::to_string).unwrap_or_else(|| s.project.name.clone());
let path = match str_p(p, "path") {
Some(x) => x.to_string(),
None => {
let dir = templates_dir(s).ok_or_else(|| bad("file.saveAsTemplate", "need `path` (no data directory for templates)"))?;
let _ = std::fs::create_dir_all(&dir);
dir.join(format!("{}.fcproj", sanitize(&name))).to_string_lossy().to_string()
}
};
let mut proj = (*s.project).clone();
proj.name = name.clone();
proj.root.name = name.clone();
s.services.write_file(&path, &filmcraft_format::encode(&proj, false)).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
Ok(json!({"path": path, "name": name}))
}
fn sanitize(n: &str) -> String {
n.chars().map(|c| if c.is_alphanumeric() || " -_().".contains(c) { c } else { '_' }).collect::<String>().trim().to_string()
}
fn list_templates(s: &mut Session, _: &Value) -> Result<Value> {
let Some(dir) = templates_dir(s) else { return Ok(json!([])) };
let mut v: Vec<Value> = std::fs::read_dir(&dir)
.map(|rd| {
rd.flatten()
.filter(|e| e.path().extension().is_some_and(|x| x == "fcproj"))
.map(|e| json!({"name": e.path().file_stem().map(|x| x.to_string_lossy().to_string()), "path": e.path().to_string_lossy()}))
.collect()
})
.unwrap_or_default();
v.sort_by(|a, b| a["name"].as_str().cmp(&b["name"].as_str()));
Ok(Value::Array(v))
}
fn new_from_template(s: &mut Session, p: &Value) -> Result<Value> {
let t = str_p(p, "template").ok_or_else(|| bad("file.newProjectFromTemplate", "need `template`"))?;
let path = if t.ends_with(".fcproj") || t.contains('/') || t.contains('\\') {
t.to_string()
} else {
templates_dir(s).map(|d| d.join(format!("{}.fcproj", sanitize(t))).to_string_lossy().to_string()).unwrap_or_else(|| t.to_string())
};
let bytes = s.services.read_file_bounded(&path, filmcraft_format::MAX_PROJECT_BYTES).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
let mut proj = filmcraft_format::decode(&bytes).map_err(|e| EngineError::Other(e.to_string()))?.project;
if s.is_dirty() && !bool_p(p, "force").unwrap_or(false) {
return Err(EngineError::Other("the project has unsaved changes: save it first, or pass {\"force\": true} to discard them".into()));
}
let name = str_p(p, "name").unwrap_or("Untitled").to_string();
proj.name = name.clone();
proj.root.name = name;
s.project = std::sync::Arc::new(proj);
s.project_instance = std::sync::Arc::new(());
s.document_epoch = s.document_epoch.wrapping_add(1);
s.history = Default::default();
s.history.limit = 200;
s.state = Session::default().state;
s.state.active_sequence = s.project.sequences().next().map(|i| i.id);
s.state.open_sequences = s.state.active_sequence.into_iter().collect();
if s.path.take().is_some() {
s.previews.reset_temp();
}
s.media.clear();
s.media.clear_stored();
s.media.add_stored(&s.project, Some(path.as_str()));
s.revision += 1;
s.saved_revision = s.revision;
s.events.push(crate::Event::ProjectChanged { revision: s.revision });
if let Some(q) = s.state.active_sequence {
s.events.push(crate::Event::OpenSequence(q));
}
Ok(json!({"items": s.project.items.len()}))
}
// ---------------------------------------------------------------------------------------------
// exports
// ---------------------------------------------------------------------------------------------
/// The selected items plus everything they need: sequence contents (recursively), subclip
/// parents, multi-camera / merged-clip sources and graphic canvases.
///
/// Bins and items share one id space, so a named bin contributes every item it holds (and
/// everything those items need), as `project.delete` does. The project's own top bin does not,
/// since no command acts on it (#244), and only ids that name a real item end up in the result.
pub fn closure(p: &Project, roots: &[ItemId]) -> BTreeSet<ItemId> {
// Index the bin tree once. Told apart from items with a set membership test (rather than a
// full `find_bin` per queued id, which is O(n²) when exporting many items from a flat
// project) and expanded from the indexed children (rather than a second walk per bin).
let mut bins: BTreeSet<u64> = BTreeSet::new();
let mut children: BTreeMap<u64, (Vec<ItemId>, Vec<u64>)> = BTreeMap::new();
let mut bin_stack = vec![&p.root];
while let Some(b) = bin_stack.pop() {
bins.insert(b.id.0);
let mut direct = (Vec::new(), Vec::new());
for c in &b.children {
match c {
BinEntry::Item(i) => direct.0.push(*i),
BinEntry::Bin(x) => {
direct.1.push(x.id.0);
bin_stack.push(x);
}
}
}
children.insert(b.id.0, direct);
}
let mut keep: BTreeSet<ItemId> = BTreeSet::new();
let mut todo: Vec<ItemId> = roots.to_vec();
let mut seen_bins: BTreeSet<u64> = BTreeSet::new();
let mut bin_todo: Vec<u64> = Vec::new();
while let Some(id) = todo.pop() {
if bins.contains(&id.0) && id.0 != p.root.id.0 {
bin_todo.push(id.0);
while let Some(bid) = bin_todo.pop() {
if !seen_bins.insert(bid) {
continue;
}
if let Some((items, subs)) = children.get(&bid) {
todo.extend(items.iter().copied());
bin_todo.extend(subs.iter().copied());
}
}
continue;
}
let Some(it) = p.item(id) else { continue };
if !keep.insert(id) {
continue;
}
match &it.kind {
ItemKind::Subclip { parent, .. } => todo.push(*parent),
ItemKind::Sequence(q) => {
for t in q.all_tracks() {
todo.extend(t.items.iter().map(|i| i.item));
}
let mut ids = BTreeSet::new();
for v in [serde_json::to_value(&q.multicam).unwrap_or_default(), serde_json::to_value(&q.merged).unwrap_or_default()] {
crate::clip_ops::collect_ids(&v, &mut ids, p);
}
todo.extend(ids);
}
_ => {}
}
}
keep
}
/// A copy of `p` with only `keep` (bins that end up empty are dropped).
pub fn project_subset(p: &Project, keep: &BTreeSet<ItemId>) -> Project {
fn prune(b: &mut filmcraft_project::Bin, keep: &BTreeSet<ItemId>) {
b.children.retain_mut(|c| match c {
BinEntry::Item(i) => keep.contains(i),
BinEntry::Bin(x) => {
prune(x, keep);
!x.children.is_empty()
}
});
}
let mut out = p.clone();
out.items.retain(|id, _| keep.contains(id));
prune(&mut out.root, keep);
out.transcripts.retain(|id, _| keep.contains(id));
out.narrations.retain(|id, _| keep.contains(id));
// a source graphic holds its item's text and metadata: it leaves with that item only
out.source_graphics.retain(|id, _| keep.contains(id));
out.search_bins.clear();
out
}
fn export_selection(s: &mut Session, p: &Value) -> Result<Value> {
let path = str_p(p, "path").ok_or_else(|| bad("file.exportSelectionProject", "need `path`"))?.to_string();
let roots = match p.get("items").and_then(Value::as_array) {
Some(a) => a.iter().filter_map(|v| v.as_u64().map(ItemId)).collect(),
None => s.state.project_selection.clone(),
};
if roots.is_empty() {
return Err(bad("file.exportSelectionProject", "select items in the Project panel"));
}
let keep = closure(&s.project, &roots);
if keep.is_empty() {
return Err(bad("file.exportSelectionProject", "the selection has no items to export"));
}
let mut sub = project_subset(&s.project, &keep);
let name = std::path::Path::new(&path).file_stem().map(|x| x.to_string_lossy().to_string()).unwrap_or_else(|| sub.name.clone());
sub.name = name.clone();
sub.root.name = name;
s.services.write_file(&path, &filmcraft_format::encode(&sub, false)).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
Ok(json!({"path": path, "items": keep.iter().map(|i| i.0).collect::<Vec<_>>()}))
}
fn export_ale(s: &mut Session, p: &Value) -> Result<Value> {
let path = str_p(p, "path").ok_or_else(|| bad("file.exportAle", "need `path`"))?.to_string();
let mut items: Vec<ItemId> = match p.get("items").and_then(Value::as_array) {
Some(a) => a.iter().filter_map(|v| v.as_u64().map(ItemId)).collect(),
None => s.state.project_selection.clone(),
};
if items.is_empty() {
// the whole project, in Project panel order
s.project.root.all_items(&mut items);
}
let doc = filmcraft_interchange::ale::export_items(&s.project, &items);
if doc.rows.is_empty() {
return Err(EngineError::Other("none of the items is a clip that can be logged".into()));
}
s.services.write_file(&path, filmcraft_interchange::ale::write(&doc).as_bytes()).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
Ok(json!({"path": path, "clips": doc.rows.len()}))
}
// ---------------------------------------------------------------------------------------------
// media properties, settings
// ---------------------------------------------------------------------------------------------
/// File properties of a probed media file (Get Media File Properties).
pub fn info_json(name: &str, path: Option<&str>, info: &filmcraft_media::MediaInfo) -> Value {
let rate = info.frame_rate();
let secs = info.duration.seconds();
let mut v = json!({
"name": name,
"path": path,
"type": format!("{:?}", info.kind),
"container": info.container,
"fileSize": info.file_size,
"duration": {"ticks": info.duration.0, "seconds": secs, "timecode": filmcraft_time::format_timecode_frames(rate.frame_at(info.duration), rate, false)},
"startTimecode": info.start_timecode.map(|f| filmcraft_time::format_timecode_frames(f, rate, false)),
"dataRateKbps": info.file_size.filter(|_| secs > 0.0).map(|b| (b as f64 * 8.0 / secs / 1000.0).round()),
});
if let Some(vs) = &info.video {
v["video"] = json!({
"codec": vs.codec, "width": vs.width, "height": vs.height, "frameRate": vs.frame_rate.as_f64(), "frameRateLabel": vs.frame_rate.label(),
"pixelAspectRatio": format!("{}:{}", vs.par.0, vs.par.1), "pixelFormat": vs.pixel_format, "alpha": vs.has_alpha,
"bitrate": vs.bitrate, "color": format!("{:?} / {:?} / {:?}", vs.color.primaries, vs.color.transfer, vs.color.matrix),
});
}
if let Some(a) = info.audio() {
v["audio"] = json!({"codec": a.codec, "sampleRate": a.sample_rate, "channels": a.channels, "bitsPerSample": a.bits_per_sample});
}
v
}
fn media_properties(s: &mut Session, p: &Value) -> Result<Value> {
let mut out = Vec::new();
for id in targets(s, p) {
let Some((mid, m)) = media_of(&s.project, id) else { continue };
let name = s.project.item(id).map(|i| i.name.clone()).unwrap_or_default();
let mut v = info_json(&name, file_path(m), &m.info);
v["item"] = json!(id.0);
v["offline"] = json!(m.offline || s.media.offline_status(mid).is_some());
out.push(v);
}
if out.is_empty() {
return Err(EngineError::Other("select a clip".into()));
}
Ok(Value::Array(out))
}
fn media_properties_file(s: &mut Session, p: &Value) -> Result<Value> {
let path = str_p(p, "path").ok_or_else(|| bad("file.mediaPropertiesFile", "need `path`"))?;
let src = s.media.open_file(path, &*s.services)?;
let name = std::path::Path::new(path).file_name().map(|x| x.to_string_lossy().to_string()).unwrap_or_default();
Ok(info_json(&name, Some(path), src.info()))
}
fn pair_p(p: &Value, k: &str) -> Option<(f64, f64)> {
let a = p.get(k)?.as_array()?;
Some((a.first()?.as_f64()?.clamp(0.0, 50.0), a.get(1)?.as_f64()?.clamp(0.0, 50.0)))
}
pub const RENDERER_GPU: &str = "FilmCraft GPU Acceleration (wgpu)";
pub const RENDERER_SOFTWARE: &str = "FilmCraft Software Only (CPU)";
fn general_json(st: &filmcraft_project::ProjectSettings) -> Value {
json!({
"renderer": st.renderer,
"renderers": [RENDERER_GPU, RENDERER_SOFTWARE],
"videoDisplay": st.video_display.label(),
"audioDisplay": if st.audio_display_samples { "Audio Samples" } else { "Milliseconds" },
"captureFormat": st.capture_format,
"titleSafe": [st.title_safe.0, st.title_safe.1],
"actionSafe": [st.action_safe.0, st.action_safe.1],
})
}
fn project_settings_general(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "file.projectSettings.general";
let mut st = s.project.settings.clone();
if let Some(r) = str_p(p, "renderer") {
st.renderer = match r.to_ascii_lowercase().as_str() {
"gpu" => RENDERER_GPU.into(),
"software" | "cpu" => RENDERER_SOFTWARE.into(),
_ if r == RENDERER_GPU || r == RENDERER_SOFTWARE => r.into(),
_ => return Err(bad(cmd, "`renderer` is gpu or software")),
};
}
if let Some(d) = str_p(p, "videoDisplay") {
let k = d.to_ascii_lowercase().replace([' ', '-'], "");
st.video_display = TimeDisplay::ALL
.into_iter()
.find(|x| x.label().to_ascii_lowercase().replace([' ', '-'], "") == k || format!("{x:?}").to_ascii_lowercase() == k)
.ok_or_else(|| bad(cmd, format!("unknown video display format `{d}`")))?;
}
if let Some(a) = str_p(p, "audioDisplay") {
st.audio_display_samples = match a.to_ascii_lowercase().as_str() {
"samples" | "audio samples" => true,
"milliseconds" | "ms" => false,
_ => return Err(bad(cmd, "`audioDisplay` is samples or milliseconds")),
};
}
if let Some(c) = str_p(p, "captureFormat") {
if !matches!(c, "DV" | "HDV") {
return Err(bad(cmd, "`captureFormat` is DV or HDV"));
}
st.capture_format = c.into();
}
if let Some(t) = pair_p(p, "titleSafe") {
st.title_safe = t;
}
if let Some(a) = pair_p(p, "actionSafe") {
st.action_safe = a;
}
if st != s.project.settings {
s.edit("Project Settings", |pr, _| {
pr.settings = st;
Ok(())
})?;
}
Ok(general_json(&s.project.settings))
}
/// Where each scratch disk resolves to now (`Same as Project` = next to the project file, or the
/// data directory for an unsaved project).
pub fn scratch_paths(s: &Session) -> Value {
let sc = &s.project.settings.scratch;
let project_dir = s.path.as_deref().and_then(|p| std::path::Path::new(p).parent()).map(|d| d.to_string_lossy().to_string());
let same = |o: &Option<String>| o.clone().or(project_dir.clone()).unwrap_or_else(|| "(data directory until the project is saved)".into());
let auto_save = match s.path.as_deref() {
Some(p) => trusted_scratch(sc.auto_save.as_deref(), Some(p), &s.prefs.auto_save.scratch_folders)
.unwrap_or_else(|| filmcraft_format::autosave::auto_save_dir(std::path::Path::new(p)))
.to_string_lossy()
.to_string(),
None => same(&None),
};
let scratch = |o: &Option<String>| {
trusted_scratch(o.as_deref(), s.path.as_deref(), &s.prefs.auto_save.scratch_folders)
.map(|d| d.to_string_lossy().to_string())
.unwrap_or_else(|| same(&None))
};
json!({
"captured": {"setting": sc.captured, "path": scratch(&sc.captured)},
"videoPreviews": {"setting": sc.video_previews, "path": previews_dir(s).map(|d| d.to_string_lossy().to_string()).unwrap_or_else(|| same(&sc.video_previews))},
"audioPreviews": {"setting": sc.audio_previews, "path": scratch(&sc.audio_previews)},
"autoSave": {"setting": sc.auto_save, "path": auto_save},
})
}
/// Render previews folder of the open project: Scratch Disks ▸ Video Previews / `<project
/// name>`, else `FilmCraft Previews/<project name>` next to the project (None while unsaved).
pub fn previews_dir(s: &Session) -> Option<std::path::PathBuf> {
s.path.as_deref().map(|p| previews_dir_for(&s.project, p, &s.prefs.auto_save.scratch_folders))
}
/// [`previews_dir`] for `project` saved at `path`; `chosen` as in [`trusted_scratch`].
pub fn previews_dir_for(project: &Project, path: &str, chosen: &[String]) -> std::path::PathBuf {
match trusted_scratch(project.settings.scratch.video_previews.as_deref(), Some(path), chosen) {
Some(d) => {
let stem = std::path::Path::new(path).file_stem().map(|x| x.to_string_lossy().to_string()).unwrap_or_else(|| "Untitled".into());
d.join(stem)
}
None => crate::previews::dir_for_project(path),
}
}
/// The Scratch Disks folder `dir` from the settings of the project saved at `project_path`, if
/// FilmCraft may write there: a folder chosen in Project Settings ▸ Scratch Disks on this computer
/// (`chosen`, kept in the preferences), or a folder inside the project's own folder. Other folders
/// named in a project file, and paths [`crate::doc_path::resolve`] refuses (other computers,
/// devices), give None: the default location.
pub fn trusted_scratch(dir: Option<&str>, project_path: Option<&str>, chosen: &[String]) -> Option<std::path::PathBuf> {
let dir = dir.filter(|d| !d.is_empty())?;
let resolved = std::path::PathBuf::from(crate::doc_path::resolve(dir, project_path.map(std::path::Path::new)).ok()?);
if chosen.iter().any(|c| c == dir) {
return Some(resolved);
}
let project = std::path::absolute(project_path?).ok()?;
let root = project.parent().filter(|r| !r.as_os_str().is_empty())?;
inside(&resolved, root).then_some(resolved)
}
/// Whether `dir` lies inside `root`, also after following the links in the part that exists.
fn inside(dir: &std::path::Path, root: &std::path::Path) -> bool {
use std::path::Component;
if !dir.starts_with(root) || dir.components().any(|c| matches!(c, Component::ParentDir | Component::CurDir)) {
return false;
}
let mut existing = dir;
while existing.symlink_metadata().is_err() {
let Some(up) = existing.parent() else { return false };
existing = up;
}
match (std::fs::canonicalize(existing), std::fs::canonicalize(root)) {
(Ok(real), Ok(real_root)) => real.starts_with(real_root),
_ => false,
}
}
/// Remember the Scratch Disks folders chosen in this session, so projects naming them may use
/// them later (see [`trusted_scratch`]).
pub(crate) fn remember_scratch_folders(s: &mut Session, dirs: &[String]) {
const KEEP: usize = 64;
let mut prefs = s.prefs.clone();
let list = &mut prefs.auto_save.scratch_folders;
for d in dirs {
list.retain(|x| x != d);
list.push(d.clone());
}
let excess = list.len().saturating_sub(KEEP);
list.drain(..excess);
if prefs != s.prefs
&& let Err(e) = s.set_prefs(prefs)
{
log::warn!("saving preferences: {e}");
}
}
/// Log and tell the user once when the project just opened names Scratch Disks folders that
/// FilmCraft will not write to (see [`trusted_scratch`]).
pub(crate) fn warn_untrusted_scratch(s: &mut Session) {
let sc = &s.project.settings.scratch;
let ignored: Vec<String> = [&sc.auto_save, &sc.video_previews, &sc.captured, &sc.audio_previews]
.into_iter()
.filter_map(|d| d.as_deref().filter(|d| !d.is_empty()))
.filter(|d| trusted_scratch(Some(d), s.path.as_deref(), &s.prefs.auto_save.scratch_folders).is_none())
.map(str::to_string)
.collect::<BTreeSet<_>>()
.into_iter()
.collect();
if ignored.is_empty() {
return;
}
let list = ignored.join(", ");
log::warn!("project scratch disks outside the project folder not used: {list}");
s.toast(format!(
"Scratch Disks: not using {list} (outside the project folder and not chosen on this computer). Auto-saves, previews and captured media go to the default location; choose the folder in Project Settings > Scratch Disks to use it."
));
}
fn project_settings_scratch(s: &mut Session, p: &Value) -> Result<Value> {
let mut sc = s.project.settings.scratch.clone();
let mut chosen = Vec::new();
for (k, slot) in
[("captured", &mut sc.captured), ("videoPreviews", &mut sc.video_previews), ("audioPreviews", &mut sc.audio_previews), ("autoSave", &mut sc.auto_save)]
{
match p.get(k) {
None => {}
Some(Value::Null) => *slot = None,
Some(Value::String(x)) if x.is_empty() || x.eq_ignore_ascii_case("same as project") => *slot = None,
Some(Value::String(x)) => {
if let Err(crate::doc_path::NotFollowed::Refused(why)) = crate::doc_path::resolve(x, s.path.as_deref().map(std::path::Path::new)) {
return Err(bad("file.projectSettings.scratchDisks", format!("`{k}` must be a folder on this computer: {why}")));
}
chosen.push(x.clone());
*slot = Some(x.clone());
}
Some(_) => return Err(bad("file.projectSettings.scratchDisks", format!("`{k}` is a folder path or null"))),
}
}
remember_scratch_folders(s, &chosen);
if sc != s.project.settings.scratch {
s.edit("Scratch Disks", |pr, _| {
pr.settings.scratch = sc;
Ok(())
})?;
s.previews_follow_path();
}
Ok(scratch_paths(s))
}
// ---------------------------------------------------------------------------------------------
// Edit Original, clip items
// ---------------------------------------------------------------------------------------------
/// Whether Edit Original may hand `path` to the system's default app: a regular file (after
/// following links) whose name, and the name it links to, have an extension the importer takes.
/// Anything else (a folder or app bundle, a script, a shortcut, a launcher) is refused.
pub(crate) fn openable_original(path: &str) -> std::result::Result<(), String> {
let name = std::path::Path::new(path).file_name().map_or_else(|| path.to_string(), |n| n.to_string_lossy().into_owned());
let real = std::fs::canonicalize(path).map_err(|e| format!("can't open “{name}”: {e}"))?;
if !real.is_file() {
return Err(format!("“{name}” is not a file"));
}
if !filmcraft_media::is_importable(std::path::Path::new(path)) || !filmcraft_media::is_importable(&real) {
return Err(format!("Edit Original opens media files only; “{name}” is not one"));
}
Ok(())
}
fn edit_original(s: &mut Session, p: &Value) -> Result<Value> {
let mut paths = Vec::new();
for id in targets(s, p) {
if let Some(path) = media_of(&s.project, id).and_then(|(_, m)| file_path(m))
&& !paths.iter().any(|x: &String| x == path)
{
paths.push(path.to_string());
}
}
// the files as media access resolves them: a stored path it refuses is not handed to the system
let paths = paths
.iter()
.map(|path| s.media.follow(path).map_err(|why| bad("edit.editOriginal", format!("{path} is not opened: {why}"))))
.collect::<Result<Vec<String>>>()?;
if paths.is_empty() {
return Err(EngineError::Other("select a clip with a media file".into()));
}
for path in &paths {
openable_original(path).map_err(|e| bad("edit.editOriginal", e))?;
}
Ok(json!({"paths": paths}))
}
/// Metadata fields of the Edit Offline dialog: (param, metadata key).
pub const OFFLINE_FIELDS: [(&str, &str); 5] =
[("tapeName", "Tape Name"), ("description", "Description"), ("scene", "Scene"), ("shot", "Shot"), ("logNote", "Log Note")];
fn edit_offline(s: &mut Session, p: &Value) -> Result<Value> {
let id = targets(s, p).into_iter().find(|i| is_offline(s, *i)).ok_or_else(|| EngineError::Other("select an offline clip".into()))?;
let name = str_p(p, "mediaName").map(str::to_string);
let fields: Vec<(&'static str, String)> = OFFLINE_FIELDS.iter().filter_map(|(k, key)| str_p(p, k).map(|v| (*key, v.to_string()))).collect();
s.edit("Edit Offline", |pr, _| {
let it = pr.item_mut(id).ok_or_else(|| bad("clip.editOffline", "no such item"))?;
if let Some(n) = name.filter(|n| !n.is_empty()) {
it.name = n;
}
for (k, v) in fields {
if v.is_empty() {
it.metadata.remove(k);
} else {
it.metadata.insert(k.to_string(), v);
}
}
Ok(())
})?;
let it = s.project.item(id).ok_or_else(|| bad("clip.editOffline", "no such item"))?;
Ok(json!({"item": id.0, "name": it.name, "metadata": it.metadata}))
}
fn source_settings(s: &mut Session, p: &Value) -> Result<Value> {
let id = targets(s, p).into_iter().find(|i| media_of(&s.project, *i).is_some()).ok_or_else(|| EngineError::Other("select a clip".into()))?;
let (_, m) = media_of(&s.project, id).ok_or_else(|| EngineError::Other("select a clip".into()))?;
let codec = m.info.video.as_ref().map(|v| v.codec.clone()).or_else(|| m.info.audio().map(|a| a.codec.clone())).unwrap_or_default();
Ok(json!({
"item": id.0,
"codec": codec,
"container": m.info.container,
"settings": [],
"message": format!("{} has no source settings in FilmCraft. Source settings apply to camera raw formats (R3D, ARRIRAW, CinemaDNG, ProRes RAW…), which FilmCraft does not decode.", if codec.is_empty() { "This clip".to_string() } else { codec.to_uppercase() }),
}))
}
fn xml_escape(s: &str) -> String {
s.replace('&', "&").replace('<', "<").replace('>', ">").replace('"', """)
}
/// An XMP packet (ISO 16684-1) with the item's name and log metadata (Dublin Core and the XMP
/// Dynamic Media schema).
pub fn xmp_packet(it: &filmcraft_project::ProjectItem) -> String {
let meta = |k: &str| it.metadata.iter().find(|(x, _)| x.eq_ignore_ascii_case(k)).map(|(_, v)| xml_escape(v));
let mut body = format!(" <dc:title><rdf:Alt><rdf:li xml:lang=\"x-default\">{}</rdf:li></rdf:Alt></dc:title>\n", xml_escape(&it.name));
if let Some(d) = meta("Description") {
body.push_str(&format!(" <dc:description><rdf:Alt><rdf:li xml:lang=\"x-default\">{d}</rdf:li></rdf:Alt></dc:description>\n"));
}
for (k, tag) in [("Scene", "scene"), ("Shot", "shotName"), ("Log Note", "logComment"), ("Tape Name", "tapeName"), ("Comment", "comment")] {
if let Some(v) = meta(k) {
body.push_str(&format!(" <xmpDM:{tag}>{v}</xmpDM:{tag}>\n"));
}
}
format!(
"<?xpacket begin=\"\u{feff}\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>\n<x:xmpmeta xmlns:x=\"adobe:ns:meta/\">\n <rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">\n <rdf:Description rdf:about=\"\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\" xmlns:xmp=\"http://ns.adobe.com/xap/1.0/\" xmlns:xmpDM=\"http://ns.adobe.com/xmp/1.0/DynamicMedia/\" xmp:CreatorTool=\"FilmCraft\">\n{body} </rdf:Description>\n </rdf:RDF>\n</x:xmpmeta>\n<?xpacket end=\"w\"?>\n"
)
}
/// The XMP sidecar of a media file: `<dir>/<stem>.xmp`.
pub fn sidecar_path(media: &str) -> String {
std::path::Path::new(media).with_extension("xmp").to_string_lossy().to_string()
}
/// Clip ▸ Update Metadata…: write the items' metadata to XMP sidecars next to their media. An
/// existing sidecar written by another application is left alone.
fn update_metadata(s: &mut Session, p: &Value) -> Result<Value> {
let mut written = Vec::new();
let mut skipped = Vec::new();
for id in targets(s, p) {
let Some(it) = s.project.item(id) else { continue };
let Some(path) = media_of(&s.project, id).and_then(|(_, m)| file_path(m)) else { continue };
// the media file as media access resolves it: a refused stored path gets no sidecar written beside it
let file = match s.media.follow(path) {
Ok(file) => file,
Err(why) => {
skipped.push(json!({"item": id.0, "path": path, "reason": format!("{path} is not opened: {why}")}));
continue;
}
};
let side = sidecar_path(&file);
if let Ok(old) = s.services.read_file(&side)
&& !String::from_utf8_lossy(&old).contains("xmp:CreatorTool=\"FilmCraft\"")
{
skipped.push(json!({"item": id.0, "path": side, "reason": "an XMP file written by another application exists"}));
continue;
}
match s.services.write_file(&side, xmp_packet(it).as_bytes()) {
Ok(()) => written.push(json!({"item": id.0, "path": side})),
Err(e) => skipped.push(json!({"item": id.0, "path": side, "reason": e.to_string()})),
}
}
if written.is_empty() && skipped.is_empty() {
return Err(EngineError::Other("select a clip with a media file".into()));
}
Ok(json!({"written": written, "skipped": skipped}))
}
fn generate_waveform(s: &mut Session, p: &Value) -> Result<Value> {
let items: Vec<u64> = targets(s, p).into_iter().filter_map(|i| media_of(&s.project, i).filter(|(_, m)| m.info.has_audio()).map(|(mid, _)| mid.0)).collect();
if items.is_empty() {
return Err(EngineError::Other("select a clip with audio".into()));
}
Ok(json!({"items": items}))
}
// ---------------------------------------------------------------------------------------------
// Automate to Sequence
// ---------------------------------------------------------------------------------------------
/// Clip ▸ Automate to Sequence…: place the selected Project panel items in the active sequence
/// at the playhead (sequentially, or at the sequence's unnumbered — unnamed — markers), by insert
/// or overwrite, on the source-patched tracks. Consecutive clips overlap by `overlapFrames`
/// (taken from the outgoing clip's tail) and get the default transitions over the overlap. One
/// undo step.
fn automate_to_sequence(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "clip.automateToSequence";
let ordering = str_p(p, "ordering").unwrap_or("sort");
let placement = str_p(p, "placement").unwrap_or("sequentially");
let method = str_p(p, "method").unwrap_or("insert");
if !matches!(ordering, "sort" | "selection") || !matches!(placement, "sequentially" | "unnumberedMarkers") || !matches!(method, "insert" | "overwrite") {
return Err(bad(cmd, "ordering: sort|selection, placement: sequentially|unnumberedMarkers, method: insert|overwrite"));
}
let q = s.active_sequence().ok_or(EngineError::NoSequence)?;
let rate = q.settings.frame_rate;
let fd = rate.frame_duration();
let mut items: Vec<ItemId> = match p.get("items").and_then(Value::as_array) {
Some(a) => a.iter().filter_map(|v| v.as_u64().map(ItemId)).collect(),
None => s.state.project_selection.clone(),
};
let seq_id = s.state.active_sequence.ok_or(EngineError::NoSequence)?;
items.retain(|i| *i != seq_id && s.project.item(*i).is_some_and(|it| !matches!(it.kind, ItemKind::Graphic { .. })));
if ordering == "sort" {
let mut order = Vec::new();
s.project.root.all_items(&mut order);
items.sort_by_key(|i| order.iter().position(|x| x == i).unwrap_or(usize::MAX));
}
if items.is_empty() {
return Err(EngineError::Other("select clips in the Project panel".into()));
}
let tg = s.targeting();
let vdest = if bool_p(p, "ignoreVideo").unwrap_or(false) { None } else { tg.video_dest };
let adest = if bool_p(p, "ignoreAudio").unwrap_or(false) { None } else { tg.audio_dest };
if vdest.is_none() && adest.is_none() {
return Err(EngineError::Other("no destination track (check source patching, or don't ignore both audio and video)".into()));
}
let overlap = if placement == "sequentially" { rate.tick_of(u64_p(p, "overlapFrames").unwrap_or(30) as i64) } else { Tick::ZERO };
let still = u64_p(p, "stillFrames").map(|f| rate.tick_of(f as i64));
// each item's range (In/Out marks; stills: `stillFrames` or the default still duration)
let mut plan: Vec<(ItemId, TimeRange)> = Vec::new();
for id in &items {
let Some(mut r) = crate::clip_ops::item_range(&s.project, *id, s.prefs.timeline.still_duration(s.sequence_rate())) else { continue };
let is_still = s.project.item(*id).and_then(|i| i.as_media()).is_some_and(|m| matches!(m.info.kind, filmcraft_media::MediaKind::Still));
if is_still && let Some(d) = still {
r = TimeRange::new(r.start, d);
}
// snap to whole sequence frames
let d = rate.tick_of(rate.frame_at(r.duration + Tick(fd.0 / 2)).max(1));
plan.push((*id, TimeRange::new(r.start, d)));
}
// destinations. `cut_overlap[k]` is the overlap between clip k and k+1 (placement-clamped).
let mut cut_overlap: Vec<Tick> = Vec::new();
let starts: Vec<Tick> = if placement == "unnumberedMarkers" {
let mut m: Vec<Tick> = q.markers.iter().filter(|m| m.name.is_empty() && m.kind == MarkerKind::Comment).map(|m| rate.snap(m.start)).collect();
m.sort();
if m.is_empty() {
return Err(EngineError::Other("the sequence has no unnumbered markers".into()));
}
plan.truncate(m.len());
m.truncate(plan.len());
m
} else {
// the overlap can't exceed half of either clip
let mut at = s.playhead();
let mut v = Vec::new();
for (k, (_, r)) in plan.iter().enumerate() {
if k > 0 {
let prev = plan[k - 1].1.duration;
let ov = overlap.min(Tick(prev.0 / 2)).min(Tick(r.duration.0 / 2));
cut_overlap.push(ov);
at -= rate.snap(ov);
}
v.push(at);
at += r.duration;
}
v
};
let n0 = s.history.undo.len();
// insert: open room first (sync-locked / destination tracks ripple), then overwrite into it
if method == "insert" && placement == "sequentially" {
let first = starts[0];
let end = starts.iter().zip(&plan).map(|(a, (_, r))| *a + r.duration).max().unwrap_or(first);
let len = end - first;
let dests: Vec<_> = [vdest, adest].into_iter().flatten().collect();
s.edit_sequence("Automate to Sequence", |q, ctx, _| {
let mut links = std::collections::HashMap::new();
for t in q.video_tracks.iter_mut().chain(q.audio_tracks.iter_mut()) {
if !t.locked && (t.sync_lock || dests.contains(&t.id)) {
filmcraft_edit::insert_track_gap(t, first, len, ctx, &mut links);
}
}
Ok(())
})?;
}
let mut placed = Vec::new();
let mut result: Result<()> = Ok(());
for (k, ((id, r), at)) in plan.iter().zip(&starts).enumerate() {
let insert = method == "insert" && placement == "unnumberedMarkers";
match crate::commands::place_item(
s,
crate::commands::ItemPlacement { item: *id, range: *r, at: *at, vdest, adest, insert, label: "Automate to Sequence", audio_split: None },
) {
Ok(ids) => placed.push((k, ids)),
Err(e) => {
result = Err(e);
break;
}
}
}
if let Err(e) = result {
// undo everything this command did
while s.history.undo.len() > n0 {
s.undo();
}
s.history.redo.clear();
return Err(e);
}
// default transitions over the overlaps (and at the cuts when there is no overlap)
let vt = bool_p(p, "videoTransition").unwrap_or(true);
let at = bool_p(p, "audioTransition").unwrap_or(true);
let mut transitions = 0;
if placement == "sequentially" && (vt || at) {
let q = s.active_sequence().ok_or(EngineError::NoSequence)?;
let default_frames = s.project.settings.default_transition_duration_frames;
let mut edges = Vec::new();
for ((_, ids), ov) in placed.iter().skip(1).zip(cut_overlap.iter().chain(std::iter::repeat(&overlap))) {
let frames = if *ov > Tick::ZERO { rate.frame_at(*ov) } else { default_frames };
for c in ids {
let Some((tid, _)) = q.find_item(*c) else { continue };
let kind = q.track(tid).map(|t| t.kind);
let cmd = match kind {
Some(TrackKind::Video) if vt => "sequence.applyVideoTransition",
Some(TrackKind::Audio) if at => "sequence.applyAudioTransition",
_ => continue,
};
edges.push((cmd, *c, frames));
}
}
for (cmd, c, frames) in edges {
if s.execute(cmd, json!({"clip": c.0, "edge": "in", "frames": frames})).is_ok() {
transitions += 1;
}
}
}
crate::clip_ops::collapse_history(s, n0, "Automate to Sequence");
let clips: Vec<u64> = placed.iter().flat_map(|(_, ids)| ids.iter().map(|c| c.0)).collect();
s.state.selection = clips.iter().map(|c| filmcraft_project::ClipId(*c)).collect();
Ok(json!({"placed": placed.len(), "clips": clips, "transitions": transitions, "starts": starts.iter().map(|t| t.0).collect::<Vec<_>>()}))
}
// ---------------------------------------------------------------------------------------------
// System Compatibility Report
// ---------------------------------------------------------------------------------------------
/// What this build supports: OS, CPU, decoders / containers and export formats. The frontend adds
/// the GPU adapter.
pub fn system_report() -> Value {
let cpus = std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1);
let formats: Vec<Value> =
filmcraft_export::Format::ALL.iter().map(|f| json!({"format": f.label(), "available": filmcraft_export::available(*f)})).collect();
json!({
"app": format!("FilmCraft {}", env!("CARGO_PKG_VERSION")),
"os": std::env::consts::OS,
"family": std::env::consts::FAMILY,
"arch": std::env::consts::ARCH,
"cpuThreads": cpus,
"decoders": ["H.264 (AVC)", "H.265 (HEVC) Main / Main 10", "VP8", "VP9", "AV1 Main", "Apple ProRes", "Avid DNxHD / DNxHR", "Motion JPEG", "AAC-LC", "Opus", "PCM"],
"containers": ["MP4 / MOV (ISO BMFF)", "Matroska / WebM", "WAV", "PNG / JPEG stills"],
"exportFormats": formats,
"speechToText": crate::transcript::speech_available(),
"checks": [
{"name": "Operating system", "ok": true, "detail": format!("{} ({})", std::env::consts::OS, std::env::consts::ARCH)},
{"name": "CPU", "ok": cpus >= 4, "detail": format!("{cpus} hardware threads{}", if cpus < 4 { " — 4 or more recommended for 1080p playback" } else { "" })},
],
})
}
#[cfg(test)]
mod tests;
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.