Skip to content

EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust

Merge remote-tracking branch 'origin/main' into HEAD

bflatastic2a72f0387277
diff --cc apps/effectcraft-cli/tests/it/cli.rs
index 12a9bf4a3,5f78ec2c1..c9d601ee9
--- a/apps/effectcraft-cli/tests/it/cli.rs
+++ b/apps/effectcraft-cli/tests/it/cli.rs
@@@ -419,35 -419,38 +419,67 @@@ fn render_out_is_relative_to_the_workin
let _ = std::fs::remove_dir_all(&root);
}
+/// #1743: `render-frame --out` writes a PNG to the path it is given, and never over footage or
+/// the project file.
+#[test]
+fn render_frame_never_writes_over_footage_or_the_project() {
+ let root = tmp("render-frame-overwrite");
+ let _ = std::fs::remove_dir_all(&root);
+ std::fs::create_dir_all(&root).unwrap();
+ let (clip, project) = (root.join("clip.png"), root.join("p.ecproj"));
+ let (c, p) = (clip.to_str().unwrap(), project.to_str().unwrap());
+ // A real PNG to import: a frame of the demo project.
+ ok_json(&["render-frame", "--max-side", "64", "--out", c]);
+ let imported = json!({"paths": [c]}).to_string();
+ ok_json(&["run", "file.import", &imported, "comp.new", r#"{"name":"T","width":64,"height":36,"duration":1}"#, "--empty", "--save-as", p]);
+ let (footage, saved) = (std::fs::read(&clip).unwrap(), std::fs::read(&project).unwrap());
+ for (out, what) in [(c, "footage"), (p, "project")] {
+ let (code, v) = run_json(&["render-frame", "--project", p, "--out", out]);
+ assert_eq!(code, 1, "{what}: {v}");
+ let error = v["error"].as_str().unwrap();
+ assert!(error.contains(out) && error.contains(what), "{what}: {v}");
+ }
+ assert_eq!(std::fs::read(&clip).unwrap(), footage, "the footage is as it was");
+ assert_eq!(std::fs::read(&project).unwrap(), saved, "the project file is as it was");
+ // Anywhere else it writes.
+ let free = root.join("frame.png");
+ ok_json(&["render-frame", "--project", p, "--out", free.to_str().unwrap()]);
+ assert_eq!(&std::fs::read(&free).unwrap()[..8], b"\x89PNG\r\n\x1a\n");
+ let _ = std::fs::remove_dir_all(&root);
+}
+
+ /// Two queue items on one file are refused by the render before anything is written, with the
+ /// file as it was.
+ #[test]
+ fn render_refuses_two_items_on_one_file() {
+ let root = tmp("render-clash");
+ let _ = std::fs::remove_dir_all(&root);
+ std::fs::create_dir_all(&root).unwrap();
+ let out = root.join("clash.mp4");
+ std::fs::write(&out, b"EARLIER").unwrap();
+ let project = root.join("p.ecproj");
+ let p = project.to_str().unwrap();
+ let add = json!({"output": out.to_str().unwrap()}).to_string();
+ ok_json(&[
+ "run",
+ "comp.new",
+ r#"{"name":"T","width":64,"height":36,"duration":1}"#,
+ "renderQueue.add",
+ &add,
+ "renderQueue.add",
+ &add,
+ "--empty",
+ "--save-as",
+ p,
+ ]);
+ let (code, v) = run_json(&["render", "--queue", "--project", p]);
+ assert_eq!(code, 1, "{v}");
+ let error = v["error"].as_str().unwrap();
+ assert!(error.contains("#1") && error.contains("#2") && error.contains("clash.mp4"), "{v}");
+ assert_eq!(std::fs::read(&out).unwrap(), b"EARLIER");
+ let _ = std::fs::remove_dir_all(&root);
+ }
+
/// A real stdio client: each edit's reply is read before disconnecting or killing the server.
struct McpChild {
child: std::process::Child,
diff --cc crates/engine/src/output_guard.rs
index ca667cd99,654569558..46c4356ed
--- a/crates/engine/src/output_guard.rs
+++ b/crates/engine/src/output_guard.rs
@@@ -6,10 -6,15 +6,20 @@@
//! Missing sources remain protected by their normalized path. Checks happen before dispatch;
//! filesystem changes between the check and the write require exporter-side revalidation.
//!
+//! The commands that write to a path they are given (Save Frame As, Export Lottie, Save a Copy,
+//! Collect Files, Export Timeline…) never replace one of those files either, with no flag:
+//! they write through [`Session::write_output`], the one place that checks. Save and Save As
+//! write the project's own file and do not.
++//!
+ //! Nor does a render write one file twice. When two outputs of one job name the same file (two
+ //! items with one Output To, a duplicated item, output modules or segments that meet), the one
+ //! rendered later replaces what the earlier one just wrote, and nothing is on disk to say so when
+ //! the job starts. [`Session::duplicate_outputs`] lists them and the whole render is refused before
+ //! anything is written: no answer makes a render replacing its own output right. A numbered sequence is compared by the frames
+ //! it writes: two items of one pattern clash only where their frames do, and an item that skips
+ //! existing frames leaves the earlier one's alone. A new item's default output name steps aside
+ //! the same way it does for footage ([`Session::avoid_sources`]).
+ //!
use std::collections::{HashMap, HashSet};
#[cfg(not(target_arch = "wasm32"))]
@@@ -17,9 -22,8 +27,9 @@@ use std::path::Component
use std::path::{Path, PathBuf};
use std::sync::Arc;
- use effectcraft_project::render_queue::{RenderQueueItem, log_path, numbered_template, sequence_frame, sequence_path};
+ use effectcraft_project::render_queue::{RenderQueueItem, log_path, numbered_template, sequence_frame, sequence_parts, sequence_path};
use effectcraft_project::{Footage, ItemKind};
+use serde_json::{Value, json};
use crate::Session;
@@@ -34,15 -38,10 +44,19 @@@ const PROBE_LIMIT: u64 = 100_000
/// render time.
const MAX_NUMBER: u32 = 1_000;
+/// What a file is written for, which words a refusal.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum Use {
+ /// A Render Queue output (or a preview render): the fix is Output To.
+ Render,
+ /// Anything else written to a path: a frame, an export, a copy.
+ Export,
+}
+
+ /// Stands for the frame number in the name a numbered sequence is compared by: a character no
+ /// file is named with.
+ const FRAME: char = '\u{e000}';
+
/// What reads a file the project depends on.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum Source {
@@@ -368,20 -598,21 +668,21 @@@ impl Session
.map(PathBuf::as_path)
.chain(movie)
.chain(Some(Path::new(&log)))
- .find_map(|path| protected.find(path).map(|source| source.refusal(&path.to_string_lossy()))))
+ .find_map(|path| protected.find(path).map(|source| source.refusal(&path.to_string_lossy(), Use::Render))))
}
- /// A new item's default output must not be a file the project reads: `[compName]_1`,
- /// `[compName]_2`… take its place (and avoid the queue's other outputs), as After Effects
- /// numbers a second item of the same composition. An output nothing is in the way of keeps
- /// the composition's own name, and one the caller chose is not touched: rendering it is
- /// refused instead.
+ /// A new item's default output must not be a file the project reads, nor one another item of
+ /// the queue writes (any of its output modules, whether or not it is ticked): `[compName]_1`,
+ /// `[compName]_2`… take its place, as After Effects numbers a second item of the same
+ /// composition. An output nothing is in the way of keeps the composition's own name; the name
+ /// is stored in the item, so it stays as it is when the item it avoided goes away. One the
+ /// caller chose is not touched: rendering it is refused instead ([`Session::duplicate_outputs`]).
pub(crate) fn avoid_sources(&self, item: &mut RenderQueueItem) {
- if cfg!(target_arch = "wasm32") {
- return;
- }
- let protected = self.protected_files();
- if protected.is_empty() {
+ // Native source protection stays with its filesystem guard; virtual web outputs still
+ // need distinct queue names because the browser stores completed files by path.
+ let protected = if cfg!(target_arch = "wasm32") { Protected::default() } else { self.protected_files() };
+ let Ok(queue) = self.queue_writes() else { return };
+ if protected.is_empty() && queue.is_empty() {
return;
}
let template = item.output.output.clone();
diff --cc docs/agents.md
index c23c20ec5,8d411add4..f5197378f
--- a/docs/agents.md
+++ b/docs/agents.md
@@@ -319,18 -319,16 +319,28 @@@ build real projects through these inter
proresProfile: 4444, output}` then `renderQueue.render {"wait": true}`. Check a render by
importing it (`file.import`, `file.newCompFromSelection`) and `render_frame {transparent: true}`
for its alpha (ProRes 4444 and WebM VP9 alpha both read back as straight alpha).
+ **A render never writes one file twice either:** when two outputs of the job (two items, a
+ `renderQueue.duplicate` copy, output modules, segments) name the same file, the whole render is
+ refused before anything is written, naming both items. Sequences clash only on frames both
+ write. A later item with Skip Existing Files leaves the earlier one's frames alone only when
+ the exporter can check the final destination. Browser/memory sinks and storage-overflow renders still report collisions.
+ Preflight compares every configured overflow destination, since available space can change during a render. Default
+ names are numbered like footage collisions when another queue item writes them
+ (`renderQueue.add`, `render.preRender`, `comp.saveFrameAs {queue}`, `file.createProxy`: a second
+ `Main` renders to `Main_1.mp4`); a name you give is kept, and `renderQueue.duplicate` copies the
+ output as it is, so change one with `renderQueue.setOutput` or turn it off.
+* **Other files written to a path you give** follow the same footage rule, with no flag and no
+ prompt: `comp.saveFrameAs` (also `…Psd`, `…Exr`), `file.exportLottie`, `file.saveCopy`,
+ `file.saveCopyAsXml`, `file.collectFiles` (every copy and the collected project; nothing is
+ written if one would land on a file the project reads), `file.exportTimeline` (and the movies it
+ pre-renders), `essential.exportTemplate`, `anim.savePreset`, `view.exportGuides`,
+ `shortcuts.export`, the control channel's `render.frame` / `ui.screenshot` with a `path`, the
+ MCP `render_frame` tool and `effectcraft-cli render-frame --out`. Footage (every frame of a
+ sequence), a proxy and the project file are refused with the reason and left untouched.
+ `file.checkOutput {path}` says beforehand (`{blocked, source, reason}`). Not covered: Save /
+ Save As / Increment and Save / auto-save (they write the project's own file), script `File`
+ writes (a script may rewrite a data file it also imports), and files the app extracts for
+ itself (template media, vector images).
* **Essential Graphics**: controls can be addressed by name (`essential.set {"layer":"#1",
"control":"Title","value":"John Smith"}`); a command that targets an explicit `comp` runs even
when the active comp would disable it (`essential.exportTemplate {"comp":"Lower Third", …}`).