Files
effectcraft/crates/automation/src/backend.rs
T
Andrea Zorzi a70eb03fa6 #3593: render_frame and render_preview tile times into one contact sheet (#3594)
* #3593: render_frame and render_preview tile `times` into one contact sheet

* contributors: credit andreaaazo by their GitHub profile name

* #3593: contact-sheet cells default to 320 px, sheets stay under 8000 px

With `times`, `max_side` now defaults to 320 per cell instead of 960, so
64 frames of a 16:9 comp make a 2560 x 1440 sheet instead of 7680 x 4320.
`sheet::MAX_SIDE` drops from 8192 to 7680. `labels` that isn't true or
false is a bad-arguments error, and a bridged cell keeps the time asked
for when the app's reply leaves `time` out.
2026-11-13 19:40:11 +05:30

260 lines
12 KiB
Rust

//! Where tools run: an in-process session, or the desktop app over its control channel.
use effectcraft_engine::Session;
use effectcraft_engine::time::Tick;
use serde_json::{Value, json};
use crate::confine::{ConfinedFootage, ConfinedServices, Confinement, Lookup};
use crate::{BridgeClient, Error, Result, base64, encode_png, fit, recompress_png};
pub struct Backend {
target: Target,
/// File access confined to folders (`--automation-read-root` / `--automation-write-root`).
confinement: Option<Confinement>,
}
enum Target {
/// An in-process session (no window): engine commands, inspection and rendering.
Headless(Box<Session>),
/// A running desktop app reached over its control channel: everything, plus the live UI.
Bridge(BridgeClient),
}
/// A rendered comp frame.
pub struct Frame {
pub png: Vec<u8>,
pub comp: Value,
pub time: f64,
pub width: u32,
pub height: u32,
}
/// A rendered comp frame as straight RGBA8 pixels, for callers that compose frames.
pub struct Pixels {
pub image: image::RgbaImage,
pub comp: Value,
pub time: f64,
}
impl Backend {
pub fn headless(session: Session) -> Self {
Backend { target: Target::Headless(Box::new(session)), confinement: None }
}
/// Bridge to the app's control channel at `addr` (`9877` or `127.0.0.1:9877`).
pub fn bridge(addr: &str) -> Result<Self> {
Ok(Backend { target: Target::Bridge(BridgeClient::new(addr)?), confinement: None })
}
/// Confine the files the commands run here may read and write ([`Confinement`]). In-process,
/// the session's own footage and file reads are confined too, so a project from a read root
/// can't show footage from outside it.
pub fn confine(&mut self, confinement: Confinement) {
if let Target::Headless(s) = &mut self.target {
s.footage = std::sync::Arc::new(ConfinedFootage::new(s.footage.clone(), confinement.clone()));
s.services = std::sync::Arc::new(ConfinedServices::new(s.services.clone(), confinement.clone()));
}
self.confinement = Some(confinement);
}
pub fn confinement(&self) -> Option<&Confinement> {
self.confinement.as_ref()
}
pub fn is_bridge(&self) -> bool {
matches!(self.target, Target::Bridge(_))
}
pub fn session(&mut self) -> Option<&mut Session> {
match &mut self.target {
Target::Headless(s) => Some(s),
Target::Bridge(_) => None,
}
}
/// Run an engine command by id (checked against the [`Confinement`], if any).
pub fn exec(&mut self, id: &str, params: Value) -> Result<Value> {
let params = if params.is_null() { json!({}) } else { params };
if let Some(c) = self.confinement.clone() {
for lookup in c.check_command(id, &params)? {
let found = match lookup {
Lookup::ProjectFile | Lookup::QueueDefault => self.run("project.summary", json!({}))?,
Lookup::RenderOutputs => self.run("renderQueue.list", json!({}))?,
};
c.check_lookup(&lookup, &found)?;
}
}
self.run(id, params)
}
fn run(&mut self, id: &str, params: Value) -> Result<Value> {
match &mut self.target {
Target::Headless(s) => {
let r = s.execute_checked(id, params);
s.drain_events();
Ok(r?)
}
Target::Bridge(b) => b.call("engine.execute", json!({"command": id, "params": params})),
}
}
/// Query whether the current project protects `path`. This is an advisory snapshot, not a
/// reservation: use [`Self::render_to_file`] to validate and write in the owning session.
/// Relative paths are resolved against this process's folder, because the app has its own.
pub fn check_output(&mut self, path: &str) -> Result<()> {
let absolute = std::path::absolute(path).map_err(|e| Error::BadArgs(format!("cannot resolve {path}: {e}")))?;
let found = self.exec("file.checkOutput", json!({"path": absolute.to_string_lossy()}))?;
match found.get("blocked").and_then(Value::as_bool) {
Some(false) => Ok(()),
_ => Err(Error::BadArgs(found.get("reason").and_then(Value::as_str).unwrap_or("this file is one the project reads").to_string())),
}
}
/// Call a raw control-channel method (bridge only).
pub fn control(&mut self, method: &str, params: Value) -> Result<Value> {
match &mut self.target {
Target::Bridge(b) => b.call(method, if params.is_null() { json!({}) } else { params }),
Target::Headless(_) => Err(Error::BadArgs(NEED_BRIDGE.into())),
}
}
/// Render a comp frame (comp time `time` seconds, default the CTI) as PNG, longest side at most
/// `max_side` (0 = full size).
pub fn render(&mut self, comp: Option<&Value>, time: Option<f64>, max_side: u32) -> Result<Frame> {
self.render_with(comp, time, max_side, false)
}
/// [`Backend::render`]; `transparent` keeps the frame's alpha instead of compositing it over
/// the comp's background colour.
pub fn render_with(&mut self, comp: Option<&Value>, time: Option<f64>, max_side: u32, transparent: bool) -> Result<Frame> {
self.render_output(comp, time, max_side, transparent, None)
}
/// Render and save in the owning session. In bridge mode, checking and writing are one
/// desktop operation, so another command cannot make the destination protected in between.
pub fn render_to_file(&mut self, comp: Option<&Value>, time: Option<f64>, max_side: u32, transparent: bool, path: &str) -> Result<Frame> {
if let Some(confinement) = self.confinement() {
confinement.check(path, crate::confine::Access::Write)?;
}
let absolute = std::path::absolute(path).map_err(|e| Error::BadArgs(format!("cannot resolve {path}: {e}")))?;
self.render_output(comp, time, max_side, transparent, Some(&absolute.to_string_lossy()))
}
/// [`Backend::render_with`] at comp time `time` seconds, as pixels instead of a PNG, longest
/// side at most `max_side` (0 = full size).
pub fn render_pixels(&mut self, comp: Option<&Value>, time: f64, max_side: u32, transparent: bool) -> Result<Pixels> {
match &mut self.target {
Target::Headless(s) => {
let cid = s.resolve_comp(comp).map_err(|_| no_comp(comp))?;
let t = Tick::from_seconds_f64(time);
let (w, h, rgba) = s.render_rgba8_alpha(cid, t, max_side, transparent)?;
let image = image::RgbaImage::from_raw(w, h, rgba).ok_or_else(|| Error::Other("bad image buffer".into()))?;
Ok(Pixels { image: fit(image, max_side), comp: json!(cid.0), time: t.seconds() })
}
Target::Bridge(b) => {
let r = b.call("render.frame", frame_params(comp, Some(time), max_side, transparent))?;
let raw = frame_png(&r)?;
let image = image::load_from_memory(&raw).map_err(|e| Error::Other(format!("png: {e}")))?.to_rgba8();
// The time the app rendered, or the time asked for when its reply leaves it out.
let time = r["time"].as_f64().unwrap_or(time);
Ok(Pixels { image: fit(image, max_side), comp: r["comp"].clone(), time })
}
}
}
/// Check `path` before composing an image here to save there (a contact sheet): the
/// [`Confinement`] and the open project's own files, as [`Backend::render_to_file`] checks a
/// frame. Returns the absolute path to give [`Backend::write_composed`]. The desktop app
/// only saves frames it renders itself, so this is headless only.
pub fn composed_output(&mut self, path: &str) -> Result<String> {
if let Some(confinement) = self.confinement() {
confinement.check(path, crate::confine::Access::Write)?;
}
let absolute = std::path::absolute(path).map_err(|e| Error::BadArgs(format!("cannot resolve {path}: {e}")))?;
let absolute = absolute.to_string_lossy().into_owned();
match &mut self.target {
Target::Headless(s) => {
s.refuse_export(&absolute)?;
Ok(absolute)
}
Target::Bridge(_) => Err(Error::BadArgs(NO_BRIDGED_SHEET.into())),
}
}
/// Save bytes composed here to a path from [`Backend::composed_output`], through the session,
/// which refuses the files the project reads.
pub fn write_composed(&mut self, path: &str, bytes: &[u8]) -> Result<()> {
match &mut self.target {
Target::Headless(s) => Ok(s.write_output(path, bytes)?),
Target::Bridge(_) => Err(Error::BadArgs(NO_BRIDGED_SHEET.into())),
}
}
fn render_output(&mut self, comp: Option<&Value>, time: Option<f64>, max_side: u32, transparent: bool, path: Option<&str>) -> Result<Frame> {
match &mut self.target {
Target::Headless(s) => {
if let Some(path) = path {
s.refuse_export(path)?;
}
let cid = s.resolve_comp(comp).map_err(|_| no_comp(comp))?;
let t = time.map(Tick::from_seconds_f64).unwrap_or_else(|| s.time());
let (w, h, rgba) = s.render_rgba8_alpha(cid, t, max_side, transparent)?;
let png = encode_png(w, h, rgba, max_side)?;
if let Some(path) = path {
s.write_output(path, &png)?;
}
Ok(Frame { png, comp: json!(cid.0), time: t.seconds(), width: w, height: h })
}
Target::Bridge(b) => {
let mut p = frame_params(comp, time, max_side, transparent);
if let Some(path) = path {
p["path"] = json!(path);
p["write"] = json!(true);
}
let r = b.call("render.frame", p)?;
if let Some(path) = path
&& r.get("path").and_then(Value::as_str) != Some(path)
{
return Err(Error::App("render.frame did not confirm the saved path; update the connected app before saving frames".into()));
}
let raw = frame_png(&r)?;
let (png, width, height) = recompress_png(&raw, max_side)?;
Ok(Frame { png, comp: r["comp"].clone(), time: r["time"].as_f64().unwrap_or(0.0), width, height })
}
}
}
}
/// `render.frame` parameters for an inline (base64) frame.
fn frame_params(comp: Option<&Value>, time: Option<f64>, max_side: u32, transparent: bool) -> Value {
let mut p = json!({"max_side": max_side, "base64": true});
if transparent {
p["transparent"] = json!(true);
}
if let Some(t) = time {
p["time"] = json!(t);
}
if let Some(c) = comp.filter(|c| !c.is_null()) {
p["comp"] = c.clone();
}
p
}
/// The PNG bytes of a `render.frame` reply.
fn frame_png(r: &Value) -> Result<Vec<u8>> {
let data = r.get("png").and_then(Value::as_str).ok_or_else(|| Error::App("render.frame returned no `png`".into()))?;
base64::decode(data).ok_or_else(|| Error::App("render.frame: bad base64".into()))
}
const NO_BRIDGED_SHEET: &str = "saving a contact sheet (`times` with `path`) needs the headless MCP server: the desktop app only saves frames it renders itself. Leave out `path` to get the sheet inline, or save single frames with `time`";
fn no_comp(comp: Option<&Value>) -> Error {
match comp.filter(|c| !c.is_null()) {
Some(c) => Error::BadArgs(format!("no composition {c} (see get_project)")),
None => Error::BadArgs("no active composition: create one (execute_command comp.new) or open a project".into()),
}
}
pub const NEED_BRIDGE: &str =
"this tool drives the live app: start it with `effectcraft --control 9877` and run the MCP server as `effectcraft-cli mcp --bridge 9877`";