f67d38b35cc5
graphic_templates.rs
//! Graphics templates, responsive design, per-character styles, source graphics and font
//! replacement (M10.7).
//!
//! - **Templates** (`graphics.template.*`): FilmCraft's own `.fcgt` format
//! ([`filmcraft_project::gtemplate`]). Built-in templates are original designs in code; user
//! templates live in `<data dir>/Graphics Templates/*.fcgt`. Export As Motion Graphics Template
//! makes one from a graphic clip with chosen editable properties; Install copies a `.fcgt` into
//! the user folder (Adobe `.mogrt` files are refused without being opened); Apply places a new
//! graphic clip; `graphics.template.set` edits a placed template's properties.
//! - **Responsive design:** `graphics.setRoll` (roll / crawl options), `graphics.setResponsiveTime`
//! (protected intro / outro), `graphics.pin` (pin a layer's edges to another layer or the frame).
//! - **Per-character styles:** `graphics.setCharStyle` styles a range of characters.
//! - **Upgrade Caption to Graphic**, **Upgrade to Source Graphic** (one set of layers shared by
//! every clip of a project item; editing one instance updates the others) and **Replace Fonts
//! in Projects**.
use std::collections::HashSet;
use std::sync::{Arc, Mutex, OnceLock};
use filmcraft_geom::{Affine, Vec2};
use filmcraft_project::graphic::{self, layer_display_name, layer_indices};
use filmcraft_project::graphic_design::{CharStyle, GraphicMeta, LayerExtra, Pin, PinTarget, RollMode, SourceGraphic, apply_char_style, clear_char_style};
use filmcraft_project::gtemplate::{
self, ControlKind, FontResource, GraphicsTemplate, TEMPLATE_EXTENSION, TemplateControl, base64_decode, base64_encode, builtin_templates, ensure_uids,
layer_uid,
};
use filmcraft_project::{ClipId, EffectInstance, ItemId, ItemKind, Label, ParamValue, Project, TrackItem};
use filmcraft_render::graphic_clip::{item_layer_specs, layer_bounds};
use filmcraft_time::Tick;
use serde_json::{Value, json};
use crate::commands::{CommandSpec, always, bad, bool_p, f64_p, has_seq, str_p, u64_p};
use crate::graphics::{layer_effect_index, place_video_clip, set_props, target_clip};
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], params: &'static str, enabled: Enabled, run: Run) -> CommandSpec {
CommandSpec { id, label, menu, shortcut: None, params, enabled, run, journal: true, named: crate::commands::NamedKeys::NONE }
}
fn query(id: &'static str, label: &'static str, params: &'static str, run: Run) -> CommandSpec {
CommandSpec { id, label, menu: &[], shortcut: None, params, enabled: always, run, journal: false, named: crate::commands::NamedKeys::NONE }
}
const G: &[&str] = &["Graphics and Titles"];
const MAX_THUMBNAIL_DIMENSION: u32 = 1920;
fn has_graphic(s: &Session) -> std::result::Result<(), String> {
has_seq(s)?;
target_clip(s, &Value::Null).map(|_| ()).ok_or_else(|| "select a graphic clip".into())
}
fn has_captions(s: &Session) -> std::result::Result<(), String> {
has_seq(s)?;
if s.active_sequence().is_some_and(|q| q.caption_tracks.iter().any(|t| !t.captions.is_empty())) { Ok(()) } else { Err("there are no captions".into()) }
}
// ------------------------------------------------------------------------------------------------
// Template library
// ------------------------------------------------------------------------------------------------
/// Where user graphics templates live: `<data dir>/Graphics Templates` (None without a data
/// directory).
pub fn user_templates_dir(s: &Session) -> Option<std::path::PathBuf> {
s.prefs_path.as_ref().and_then(|p| p.parent()).map(|d| d.join("Graphics Templates"))
}
/// A template from the library: built in, or a user file.
#[derive(Clone, Debug)]
pub struct LibraryEntry {
pub template: GraphicsTemplate,
/// None for built-in templates.
pub path: Option<String>,
}
/// Built-in and user templates (user files that fail to read are skipped).
pub fn library(s: &Session) -> Vec<LibraryEntry> {
let mut v: Vec<LibraryEntry> = builtin_templates().into_iter().map(|t| LibraryEntry { template: t, path: None }).collect();
if let Some(dir) = user_templates_dir(s)
&& let Some(Ok(mut names)) = s.services.list_dir(&dir.to_string_lossy())
{
names.sort();
for n in names.into_iter().filter(|n| n.to_ascii_lowercase().ends_with(&format!(".{TEMPLATE_EXTENSION}"))) {
let path = dir.join(&n).to_string_lossy().to_string();
if let Ok(b) = s.services.read_file(&path)
&& let Ok(t) = GraphicsTemplate::from_bytes(&b)
{
v.push(LibraryEntry { template: t, path: Some(path) });
}
}
}
v
}
fn is_mogrt(path: &str) -> bool {
path.to_ascii_lowercase().ends_with(".mogrt")
}
const MOGRT: &str = "FilmCraft does not open Adobe .mogrt files (or other applications' template packages); it reads only its own .fcgt graphics templates";
/// Find a template by id, name (case-insensitive) or `.fcgt` path.
pub fn find_template(s: &Session, key: &str) -> Result<LibraryEntry> {
if is_mogrt(key) {
return Err(EngineError::Other(MOGRT.into()));
}
if key.to_ascii_lowercase().ends_with(&format!(".{TEMPLATE_EXTENSION}")) || key.contains('/') || key.contains('\\') {
let b = s.services.read_file(key).map_err(|e| EngineError::Other(format!("{key}: {e}")))?;
let t = GraphicsTemplate::from_bytes(&b).map_err(|e| EngineError::Other(format!("{key}: {e}")))?;
return Ok(LibraryEntry { template: t, path: Some(key.to_string()) });
}
let lib = library(s);
lib.iter()
.find(|e| e.template.id == key)
.or_else(|| lib.iter().find(|e| e.template.name.eq_ignore_ascii_case(key)))
.cloned()
.ok_or_else(|| bad("graphics.template", format!("no graphics template `{key}`")))
}
/// Register the fonts a template embeds (once per font file).
fn register_fonts(t: &GraphicsTemplate) -> usize {
static SEEN: OnceLock<Mutex<HashSet<u64>>> = OnceLock::new();
let mut n = 0;
for f in &t.resources.fonts {
let Some(data) = base64_decode(&f.data) else { continue };
let h = data.iter().fold(0xcbf2_9ce4_8422_2325u64, |h, b| (h ^ *b as u64).wrapping_mul(0x100_0000_01b3));
let mut seen = SEEN.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner());
if seen.insert(h) {
n += filmcraft_text::fonts::add_font_data(data).len();
}
}
n
}
fn control_json(c: &TemplateControl) -> Value {
json!({"id": c.id, "name": c.name, "kind": c.kind.name(), "layer": c.layer, "param": c.param, "min": c.min, "max": c.max})
}
fn entry_json(e: &LibraryEntry) -> Value {
let t = &e.template;
json!({
"id": t.id, "name": t.name, "category": t.category, "description": t.description, "author": t.author,
"license": t.license, "tags": t.tags, "source": if e.path.is_some() { "user" } else { "builtin" }, "path": e.path,
"canvas": t.canvas, "duration": t.duration.0, "seconds": t.duration.seconds(), "layers": t.layers.len(),
"roll": t.graphic.roll.mode.label(), "controls": t.controls.iter().map(control_json).collect::<Vec<_>>(),
"fonts": t.resources.fonts.iter().map(|f| json!({"family": f.family, "style": f.style, "license": f.license})).collect::<Vec<_>>(),
})
}
/// Render a template's thumbnail (static: rolls are shown at rest) as straight sRGB RGBA8,
/// `w` pixels wide with the template's aspect ratio. Returns (width, height, pixels).
pub fn thumbnail(t: &GraphicsTemplate, w: u32) -> (u32, u32, Vec<u8>) {
let (w, h) = thumbnail_dimensions(t.canvas, w);
register_fonts(t);
let mut meta = t.graphic.clone();
meta.roll.mode = RollMode::Off;
let mut p = Project::new("thumb");
let rate = filmcraft_time::FrameRate::FPS_30;
let g = p.add_item("G", Label::Rose, ItemKind::Graphic { width: t.canvas[0], height: t.canvas[1], rate }, None);
let Some(mut it) = p.make_track_item(
g,
filmcraft_project::TrackKind::Video,
Tick::ZERO,
filmcraft_time::TimeRange::new(Tick::ZERO, t.duration.max(rate.frame_duration())),
rate,
) else {
return (w, h, vec![0; w as usize * h as usize * 4]);
};
it.effects.extend(t.layers.iter().cloned());
it.graphic = Some(Box::new(meta));
// a moment into the clip, so intro animations have settled a little
let at = Tick((t.duration.0 / 2).min(filmcraft_time::TICKS_PER_SECOND));
let mut img = filmcraft_render::image::Image::new(w as usize, h as usize);
// fit both sides: a capped height leaves `w / canvas width` too large for a tall canvas
let k = (w as f64 / t.canvas[0].max(1) as f64).min(h as f64 / t.canvas[1].max(1) as f64);
filmcraft_render::graphic_clip::render_graphic(&it, at, (t.canvas[0], t.canvas[1]), &Affine::scale(k, k), &mut img);
(w, h, img.to_rgba8())
}
/// Fit a requested thumbnail width within a bounded rectangle without trusting the template's
/// aspect ratio to derive an unbounded second dimension.
fn thumbnail_dimensions(canvas: [u32; 2], requested_width: u32) -> (u32, u32) {
let mut w = requested_width.clamp(16, MAX_THUMBNAIL_DIMENSION);
let aspect = canvas[0].max(1) as f64 / canvas[1].max(1) as f64;
let mut h = (w as f64 / aspect).round().clamp(1.0, u32::MAX as f64) as u32;
if h > MAX_THUMBNAIL_DIMENSION {
h = MAX_THUMBNAIL_DIMENSION;
w = (h as f64 * aspect).round().clamp(1.0, MAX_THUMBNAIL_DIMENSION as f64) as u32;
}
(w, h)
}
/// Cached thumbnails by template id + content + width (the UI asks every frame).
pub fn thumbnail_cached(t: &GraphicsTemplate, w: u32) -> Arc<(u32, u32, Vec<u8>)> {
static CACHE: OnceLock<Mutex<std::collections::HashMap<(String, u64, u32), Arc<(u32, u32, Vec<u8>)>>>> = OnceLock::new();
let json = t.to_json();
let h = json.bytes().fold(0xcbf2_9ce4_8422_2325u64, |h, b| (h ^ b as u64).wrapping_mul(0x100_0000_01b3));
let key = (t.id.clone(), h, w);
if let Some(v) = CACHE.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner()).get(&key) {
return v.clone();
}
let v = Arc::new(thumbnail(t, w));
let mut c = CACHE.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner());
if c.len() > 256 {
c.clear();
}
c.insert(key, v.clone());
v
}
fn list_templates(s: &mut Session, p: &Value) -> Result<Value> {
let q = str_p(p, "query").unwrap_or("").to_ascii_lowercase();
let cat = str_p(p, "category").map(str::to_ascii_lowercase);
let src = str_p(p, "source");
let v: Vec<Value> = library(s)
.iter()
.filter(|e| {
let t = &e.template;
(q.is_empty()
|| t.name.to_ascii_lowercase().contains(&q)
|| t.category.to_ascii_lowercase().contains(&q)
|| t.description.to_ascii_lowercase().contains(&q)
|| t.tags.iter().any(|x| x.to_ascii_lowercase().contains(&q)))
&& cat.as_ref().is_none_or(|c| t.category.to_ascii_lowercase() == *c)
&& src.is_none_or(|x| (x == "user") == e.path.is_some())
})
.map(entry_json)
.collect();
Ok(Value::Array(v))
}
/// Value of a control on a placed graphic, as JSON.
fn control_value(it: &TrackItem, c: &TemplateControl, mt: Tick) -> Value {
let Some(e) = it.effects.iter().find(|e| graphic::is_layer(e) && layer_uid(e) == c.layer) else { return Value::Null };
if c.param == "enabled" {
return json!(e.enabled);
}
let Some(prm) = e.params.get(&c.param) else { return Value::Null };
match prm.value_at(mt) {
ParamValue::Text(t) if c.kind == ControlKind::Font => {
let style = match e.params.get("font_style").map(|p| p.value_at(mt)) {
Some(ParamValue::Text(s)) => s,
_ => String::new(),
};
json!({"family": t, "style": style})
}
ParamValue::Text(t) => json!(t),
ParamValue::Color(c) => json!(format!(
"#{:02x}{:02x}{:02x}",
(c[0].clamp(0.0, 1.0) * 255.0).round() as u8,
(c[1].clamp(0.0, 1.0) * 255.0).round() as u8,
(c[2].clamp(0.0, 1.0) * 255.0).round() as u8
)),
ParamValue::Vec2(v) => json!([v.x, v.y]),
ParamValue::Bool(b) => json!(b),
ParamValue::Float(f) => json!(f),
ParamValue::Choice(c) => json!(c),
_ => Value::Null,
}
}
fn clip_item(s: &Session, clip: ClipId) -> Result<TrackItem> {
let q = s.active_sequence().ok_or(EngineError::NoSequence)?;
q.find_item(clip).map(|(_, it)| it.clone()).ok_or_else(|| bad("graphics", "no such clip"))
}
fn mt_at_playhead(s: &Session, it: &TrackItem) -> Tick {
it.source_time_at(s.playhead().clamp(it.start, it.end() - Tick(1)))
}
/// Set template controls `values` ({control id or name: value}) on `clip`, each as its own
/// property change (callers fold the undo steps).
fn set_controls(s: &mut Session, clip: ClipId, values: &serde_json::Map<String, Value>) -> Result<usize> {
let it = clip_item(s, clip)?;
let link = it.graphic.as_ref().and_then(|m| m.template.clone()).ok_or_else(|| bad("graphics.template.set", "the graphic was not made from a template"))?;
let tl = s.playhead().clamp(it.start, it.end() - Tick(1));
let mut n = 0;
for (k, v) in values {
let c = link
.controls
.iter()
.find(|c| c.id == *k)
.or_else(|| link.controls.iter().find(|c| c.name.eq_ignore_ascii_case(k)))
.ok_or_else(|| bad("graphics.template.set", format!("the template has no property `{k}`")))?;
let ei = it
.effects
.iter()
.position(|e| graphic::is_layer(e) && layer_uid(e) == c.layer)
.ok_or_else(|| bad("graphics.template.set", "the property's layer is gone"))?;
let mut props = serde_json::Map::new();
match (c.kind, v) {
(ControlKind::Font, Value::Object(o)) => {
if let Some(f) = o.get("family") {
props.insert("font".into(), f.clone());
}
if let Some(st) = o.get("style") {
props.insert("font_style".into(), st.clone());
}
}
(ControlKind::Slider, Value::Number(x)) => {
let x = x.as_f64().unwrap_or(0.0).clamp(c.min.unwrap_or(f64::MIN), c.max.unwrap_or(f64::MAX));
props.insert(c.param.clone(), json!(x));
}
_ => {
props.insert(c.param.clone(), v.clone());
}
}
set_props(s, clip, ei, &props, tl, "Change Template Property", None)?;
n += 1;
}
Ok(n)
}
/// Keep only the first of the undo steps made since `before`, under `label`.
fn fold_undo(s: &mut Session, before: usize, label: &str) {
if s.history.undo.len() > before + 1 {
s.history.undo.truncate(before + 1);
}
if let Some(e) = s.history.undo.get_mut(before) {
e.0 = label.to_string();
}
}
fn apply_template(s: &mut Session, p: &Value) -> Result<Value> {
let key = str_p(p, "template").or_else(|| str_p(p, "id")).or_else(|| str_p(p, "name")).ok_or_else(|| bad("graphics.template.apply", "need `template`"))?;
let entry = find_template(s, key)?;
let t = entry.template;
register_fonts(&t);
let (w, h) = s.active_sequence().map(|q| (q.settings.width, q.settings.height)).ok_or(EngineError::NoSequence)?;
let (layers, meta) = t.instantiate((w, h));
let before = s.history.undo.len();
let dur = t.duration;
let clip = place_video_clip(s, "graphics.template.apply", &t.name, p, "Apply Graphics Template", layers, move |pr, (w, h, rate)| {
let src = crate::graphics::graphic_source(pr, w, h, rate);
(src, rate.snap_nearest(dur))
})?;
let meta2 = meta.clone();
s.edit_sequence("Apply Graphics Template", move |q, _, _| {
let (_, it) = q.find_item_mut(clip).ok_or(filmcraft_edit::EditError::NoItem(clip))?;
it.graphic = Some(Box::new(meta2));
Ok(())
})?;
if let Some(vals) = p.get("values").and_then(Value::as_object) {
let vals = vals.clone();
if let Err(e) = set_controls(s, clip, &vals) {
// undo the whole apply
fold_undo(s, before, "Apply Graphics Template");
let _ = s.execute("edit.undo", json!({}));
return Err(e);
}
}
fold_undo(s, before, "Apply Graphics Template");
s.state.graphic_layers.clear();
Ok(json!({"clip": clip.0, "template": t.id, "name": t.name, "controls": t.controls.iter().map(control_json).collect::<Vec<_>>()}))
}
fn template_controls(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.template.controls", "no graphic clip"))?;
let it = clip_item(s, clip)?;
let mt = mt_at_playhead(s, &it);
let Some(link) = it.graphic.as_ref().and_then(|m| m.template.as_ref()) else {
return Ok(json!({"clip": clip.0, "template": Value::Null, "controls": []}));
};
let controls: Vec<Value> = link
.controls
.iter()
.map(|c| {
let mut j = control_json(c);
j["value"] = control_value(&it, c, mt);
j
})
.collect();
Ok(json!({"clip": clip.0, "template": link.id, "name": link.name, "controls": controls}))
}
/// Parse export `controls`: `[{layer: n|name, param, name?, kind?, min?, max?, id?}]`.
fn export_controls(it: &TrackItem, layers: &[EffectInstance], p: &Value) -> Result<Vec<TemplateControl>> {
let idx = layer_indices(&it.effects);
let mut out: Vec<TemplateControl> = Vec::new();
let Some(arr) = p.get("controls").and_then(Value::as_array) else {
// default: every text layer's text
for (i, &ei) in idx.iter().enumerate() {
let e = &it.effects[ei];
if e.effect == graphic::TEXT_LAYER {
let name = layer_display_name(e, i);
out.push(TemplateControl {
id: format!("text{}", out.len() + 1),
name,
kind: ControlKind::Text,
layer: layer_uid(&layers[i]),
param: "text".into(),
min: None,
max: None,
});
}
}
return Ok(out);
};
for (n, c) in arr.iter().enumerate() {
let li = match c.get("layer") {
Some(Value::Number(x)) => x.as_u64().unwrap_or(0) as usize,
Some(Value::String(name)) => (0..idx.len())
.find(|&i| layer_display_name(&it.effects[idx[i]], i).eq_ignore_ascii_case(name))
.ok_or_else(|| bad("graphics.template.export", format!("no layer named `{name}`")))?,
_ => return Err(bad("graphics.template.export", "each control needs `layer`")),
};
let layer = layers.get(li).ok_or_else(|| bad("graphics.template.export", format!("no layer {li}")))?;
let param = str_p(c, "param").unwrap_or("text").to_string();
let param = match param.as_str() {
"color" | "fillColor" => "fill_color".to_string(),
"fontSize" => "size".to_string(),
"visible" | "show" => "enabled".to_string(),
_ => param,
};
if param != "enabled" && !layer.params.contains_key(¶m) {
return Err(bad("graphics.template.export", format!("layer {li} has no property `{param}`")));
}
let kind = str_p(c, "kind").and_then(ControlKind::from_name).unwrap_or_else(|| ControlKind::for_param(¶m));
let name =
str_p(c, "name").map(str::to_string).unwrap_or_else(|| format!("{} {}", layer_display_name(&it.effects[idx[li]], li), param.replace('_', " ")));
let id = str_p(c, "id").map(str::to_string).unwrap_or_else(|| {
let base = gtemplate::slug(&name).replace('-', "_");
if out.iter().any(|o| o.id == base) { format!("{base}_{n}") } else { base }
});
let (mut min, mut max) = (f64_p(c, "min"), f64_p(c, "max"));
if kind == ControlKind::Slider && (min.is_none() || max.is_none()) {
let d = filmcraft_project::find_effect(&layer.effect).and_then(|d| d.param(¶m)).map(|d| d.kind.clone());
if let Some(filmcraft_project::ParamKind::Float { soft_min, soft_max, .. }) = d {
min = min.or(Some(soft_min));
max = max.or(Some(soft_max));
}
}
out.push(TemplateControl { id, name, kind, layer: layer_uid(layer), param, min, max });
}
Ok(out)
}
fn export_template(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.template.export", "select a graphic clip"))?;
let it = clip_item(s, clip)?;
let size = match s.project.item(it.item).map(|x| &x.kind) {
Some(ItemKind::Graphic { width, height, .. }) => [*width, *height],
_ => [1920, 1080],
};
let name = str_p(p, "name").map(str::to_string).unwrap_or_else(|| it.name.clone());
if name.trim().is_empty() {
return Err(bad("graphics.template.export", "need a `name`"));
}
let idx = layer_indices(&it.effects);
if idx.is_empty() {
return Err(bad("graphics.template.export", "the graphic has no layers"));
}
// layers with uids, keyframes made relative to the clip start
let mut layers: Vec<EffectInstance> = idx.iter().map(|&i| it.effects[i].clone()).collect();
let base_uids: Vec<u64> = layers.iter().map(layer_uid).collect();
ensure_uids(&mut layers);
if it.source_in != Tick::ZERO {
for l in &mut layers {
for prm in l.params.values_mut() {
prm.keyframes.iter_mut().for_each(|k| k.time -= it.source_in);
}
}
}
let controls = export_controls(&it, &layers, p)?;
let mut meta = it.graphic.as_deref().cloned().unwrap_or_default();
meta.template = None;
if meta.has_responsive_time() {
meta.design_in -= it.source_in;
}
let mut fonts = Vec::new();
if bool_p(p, "embedFonts").unwrap_or(false) {
let license = str_p(p, "fontLicense").unwrap_or("UNKNOWN").to_string();
let mut seen = HashSet::new();
for l in &layers {
let fam = match l.params.get("font").map(|x| &x.value) {
Some(ParamValue::Text(f)) => f.clone(),
_ => continue,
};
let st = match l.params.get("font_style").map(|x| &x.value) {
Some(ParamValue::Text(f)) => f.clone(),
_ => "Regular".into(),
};
let r = filmcraft_text::resolve(&fam, &st);
let face = filmcraft_text::fonts::face(r.face);
if r.missing || face.info.origin == "bundled" || !seen.insert(r.face) {
continue;
}
if let Some(data) = face.data() {
fonts.push(FontResource {
family: face.info.family.clone(),
style: face.info.style.clone(),
license: license.clone(),
file: String::new(),
data: base64_encode(&data),
});
}
}
}
let t = GraphicsTemplate {
id: format!("user:{}", gtemplate::slug(&name)),
name: name.clone(),
category: str_p(p, "category").unwrap_or("My Templates").to_string(),
description: str_p(p, "description").unwrap_or("").to_string(),
author: str_p(p, "author").unwrap_or("").to_string(),
license: str_p(p, "license").unwrap_or("").to_string(),
tags: p.get("tags").and_then(Value::as_array).map(|a| a.iter().filter_map(Value::as_str).map(str::to_string).collect()).unwrap_or_default(),
canvas: size,
duration: it.duration,
layers,
graphic: meta,
controls,
resources: gtemplate::Resources { fonts },
..Default::default()
};
t.validate().map_err(|e| EngineError::Other(e.to_string()))?;
let path = match str_p(p, "path") {
Some(x) => {
if is_mogrt(x) {
return Err(bad("graphics.template.export", "graphics templates are saved as .fcgt"));
}
x.to_string()
}
None => {
let dir = user_templates_dir(s).ok_or_else(|| bad("graphics.template.export", "need `path` (no data directory for templates)"))?;
let _ = std::fs::create_dir_all(&dir);
dir.join(format!("{}.{TEMPLATE_EXTENSION}", gtemplate::slug(&name))).to_string_lossy().to_string()
}
};
s.services.write_file(&path, t.to_json().as_bytes()).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
// the clip's layers keep the uids the template refers to
if base_uids.contains(&0) {
let uids: Vec<u64> = t.layers.iter().map(layer_uid).collect();
let before = s.history.undo.len();
let _ = s.edit_sequence("Export Graphics Template", move |q, _, _| {
let (_, it) = q.find_item_mut(clip).ok_or(filmcraft_edit::EditError::NoItem(clip))?;
for (ei, uid) in layer_indices(&it.effects).into_iter().zip(uids) {
it.effects[ei].layer.get_or_insert_with(Default::default).uid = uid;
}
Ok(())
});
// bookkeeping, not an edit the user undoes
if s.history.undo.len() > before {
s.history.undo.pop();
}
}
Ok(json!({"path": path, "id": t.id, "name": t.name, "controls": t.controls.iter().map(control_json).collect::<Vec<_>>(), "fonts": t.resources.fonts.len()}))
}
fn install_template(s: &mut Session, p: &Value) -> Result<Value> {
let path = str_p(p, "path").ok_or_else(|| bad("graphics.template.install", "need `path`"))?.to_string();
if is_mogrt(&path) {
return Err(EngineError::Other(MOGRT.into()));
}
let b = s.services.read_file(&path).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
let mut t = GraphicsTemplate::from_bytes(&b).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
if !t.id.starts_with("user:") {
t.id = format!("user:{}", gtemplate::slug(&t.name));
}
let dir = user_templates_dir(s).ok_or_else(|| bad("graphics.template.install", "no data directory for templates"))?;
let _ = std::fs::create_dir_all(&dir);
let dest = dir.join(format!("{}.{TEMPLATE_EXTENSION}", gtemplate::slug(&t.name))).to_string_lossy().to_string();
s.services.write_file(&dest, t.to_json().as_bytes()).map_err(|e| EngineError::Other(format!("{dest}: {e}")))?;
let fonts = register_fonts(&t);
s.toast(format!("Installed graphics template \"{}\"", t.name));
Ok(json!({"id": t.id, "name": t.name, "path": dest, "fontsRegistered": fonts}))
}
fn remove_template(s: &mut Session, p: &Value) -> Result<Value> {
let key = str_p(p, "template").ok_or_else(|| bad("graphics.template.remove", "need `template`"))?;
// Only an entry of the library is removed, and only when the key names exactly one: a template's
// id is its document's own claim, so a duplicate or path-shaped id must not pick another file.
let lib = library(s);
let mut hits: Vec<&LibraryEntry> = lib.iter().filter(|e| e.path.as_deref() == Some(key)).collect();
if hits.is_empty() {
hits = lib.iter().filter(|e| e.template.id == key).collect();
}
if hits.is_empty() {
hits = lib.iter().filter(|e| e.template.name.eq_ignore_ascii_case(key)).collect();
}
let e = match hits.as_slice() {
[e] => (*e).clone(),
[] => return Err(bad("graphics.template.remove", format!("no graphics template `{key}` in the library"))),
_ => return Err(bad("graphics.template.remove", format!("more than one library template is named `{key}`: remove it by its file path"))),
};
let path = e.path.ok_or_else(|| bad("graphics.template.remove", "built-in templates cannot be removed"))?;
std::fs::remove_file(&path).map_err(|x| EngineError::Other(format!("{path}: {x}")))?;
Ok(json!({"removed": e.template.id}))
}
fn template_thumbnail(s: &mut Session, p: &Value) -> Result<Value> {
let key = str_p(p, "template").ok_or_else(|| bad("graphics.template.thumbnail", "need `template`"))?;
let e = find_template(s, key)?;
let (w, h, rgba) = thumbnail(&e.template, u64_p(p, "width").unwrap_or(320) as u32);
let png = filmcraft_export::encode_png(rgba, w, h).map_err(|x| EngineError::Other(x.to_string()))?;
if let Some(path) = str_p(p, "path") {
s.services.write_file(path, &png).map_err(|x| EngineError::Other(format!("{path}: {x}")))?;
return Ok(json!({"width": w, "height": h, "path": path}));
}
Ok(json!({"width": w, "height": h, "pngBase64": base64_encode(&png)}))
}
// ------------------------------------------------------------------------------------------------
// Responsive design
// ------------------------------------------------------------------------------------------------
/// Duration parameter: `<key>Frames` (sequence frames), `<key>Seconds`, or `<key>` in ticks.
fn dur_p(s: &Session, p: &Value, key: &str) -> Option<Tick> {
let rate = s.sequence_rate();
if let Some(f) = f64_p(p, &format!("{key}Frames")) {
return Some(rate.tick_of(f.round() as i64));
}
if let Some(sec) = f64_p(p, &format!("{key}Seconds")) {
return Some(Tick::from_seconds_f64(sec.max(0.0)));
}
p.get(key).and_then(Value::as_i64).map(Tick)
}
fn edit_meta(s: &mut Session, clip: ClipId, label: &str, f: impl FnOnce(&mut GraphicMeta, &TrackItem) -> Result<()>) -> Result<GraphicMeta> {
s.edit_sequence(label, |q, _, _| {
let (_, it) = q.find_item_mut(clip).ok_or(filmcraft_edit::EditError::NoItem(clip))?;
let mut m = it.graphic.as_deref().cloned().unwrap_or_default();
f(&mut m, it)?;
it.graphic = (!m.is_empty()).then(|| Box::new(m.clone()));
Ok(m)
})
}
fn set_roll(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.setRoll", "no graphic clip"))?;
let mode = match str_p(p, "mode") {
Some(m) => Some(RollMode::from_name(m).ok_or_else(|| bad("graphics.setRoll", format!("unknown mode `{m}` (off, roll, crawlLeft, crawlRight)")))?),
None => None,
};
let (pre, ei, eo, post) = (dur_p(s, p, "preroll"), dur_p(s, p, "easeIn"), dur_p(s, p, "easeOut"), dur_p(s, p, "postroll"));
let (so, eoff) = (bool_p(p, "startOffScreen"), bool_p(p, "endOffScreen"));
let m = edit_meta(s, clip, "Roll/Crawl Options", |m, _| {
if let Some(x) = mode {
m.roll.mode = x;
}
if let Some(x) = so {
m.roll.start_off_screen = x;
}
if let Some(x) = eoff {
m.roll.end_off_screen = x;
}
for (dst, v) in [(&mut m.roll.preroll, pre), (&mut m.roll.ease_in, ei), (&mut m.roll.ease_out, eo), (&mut m.roll.postroll, post)] {
if let Some(v) = v {
*dst = v.max(Tick::ZERO);
}
}
Ok(())
})?;
Ok(json!({"clip": clip.0, "roll": serde_json::to_value(&m.roll).unwrap_or_default()}))
}
fn set_responsive_time(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.setResponsiveTime", "no graphic clip"))?;
let (intro, outro) = (dur_p(s, p, "intro"), dur_p(s, p, "outro"));
if intro.is_none() && outro.is_none() {
return Err(bad("graphics.setResponsiveTime", "need `introFrames` / `outroFrames` (or seconds / ticks)"));
}
let m = edit_meta(s, clip, "Responsive Design - Time", |m, it| {
if !m.has_responsive_time() {
m.design_in = it.source_in;
m.design_duration = Tick((it.duration.0 as f64 * it.speed.abs()).round() as i64);
}
if let Some(x) = intro {
m.intro = x.max(Tick::ZERO);
}
if let Some(x) = outro {
m.outro = x.max(Tick::ZERO);
}
if m.intro + m.outro > m.design_duration {
return Err(bad("graphics.setResponsiveTime", "the intro and outro are longer than the graphic"));
}
if m.intro == Tick::ZERO && m.outro == Tick::ZERO {
m.design_in = Tick::ZERO;
m.design_duration = Tick::ZERO;
}
Ok(())
})?;
Ok(json!({"clip": clip.0, "intro": m.intro.0, "outro": m.outro.0, "designDuration": m.design_duration.0}))
}
fn edges_p(p: &Value) -> [bool; 4] {
match p.get("edges") {
Some(Value::Array(a)) => {
let has = |n: &str| a.iter().any(|v| v.as_str().is_some_and(|x| x.eq_ignore_ascii_case(n)));
[has("left"), has("top"), has("right"), has("bottom")]
}
Some(Value::String(x)) if x != "all" => {
let has = |n: &str| x.split([',', ' ']).any(|v| v.eq_ignore_ascii_case(n));
[has("left"), has("top"), has("right"), has("bottom")]
}
_ => [true; 4],
}
}
fn pin_layer(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.pin", "no graphic clip"))?;
let (l, ei) = layer_effect_index(s, clip, p)?;
let it = clip_item(s, clip)?;
let size = match s.project.item(it.item).map(|x| &x.kind) {
Some(ItemKind::Graphic { width, height, .. }) => (*width, *height),
_ => (1920, 1080),
};
let idx = layer_indices(&it.effects);
let to = p.get("to").cloned().unwrap_or(json!("frame"));
let target: Option<Option<usize>> = match &to {
Value::String(x) if x == "none" || x.is_empty() => None,
Value::String(x) if x == "frame" || x.eq_ignore_ascii_case("video frame") => Some(None),
Value::Number(n) => Some(Some(n.as_u64().unwrap_or(0) as usize)),
Value::String(name) => Some(Some(
(0..idx.len())
.find(|&i| layer_display_name(&it.effects[idx[i]], i).eq_ignore_ascii_case(name))
.ok_or_else(|| bad("graphics.pin", format!("no layer named `{name}`")))?,
)),
_ => return Err(bad("graphics.pin", "`to`: \"frame\", \"none\", a layer index or name")),
};
if let Some(Some(t)) = target
&& (t >= idx.len() || t == l)
{
return Err(bad("graphics.pin", "pin to another layer of the same graphic"));
}
let edges = edges_p(p);
let mt = mt_at_playhead(s, &it);
// pins are measured at rest (without the roll / crawl offset)
let mut rest = it.clone();
if let Some(m) = rest.graphic.as_mut() {
m.roll.mode = RollMode::Off;
}
let shown = item_layer_specs(&rest, mt, size);
let bounds_of = |e: usize| shown.iter().find(|(x, _)| *x == e).map(|(_, sp)| layer_bounds(sp));
let own = bounds_of(ei).ok_or_else(|| bad("graphics.pin", "bad layer"))?;
let pin = match target {
None => None,
Some(None) => Some((PinTarget::Frame, [0.0, 0.0, size.0 as f64, size.1 as f64], None)),
Some(Some(t)) => Some((PinTarget::Layer(0), bounds_of(idx[t]).ok_or_else(|| bad("graphics.pin", "bad target"))?, Some(idx[t]))),
};
let r = s.edit_sequence("Responsive Design - Position", move |q, _, _| {
let (_, it) = q.find_item_mut(clip).ok_or(filmcraft_edit::EditError::NoItem(clip))?;
let li = layer_indices(&it.effects);
let mut layers: Vec<EffectInstance> = li.iter().map(|&i| it.effects[i].clone()).collect();
ensure_uids(&mut layers);
for (k, &i) in li.iter().enumerate() {
it.effects[i].layer = layers[k].layer.clone();
}
let new_pin = pin.map(|(to, tb, teff)| {
let to = match (to, teff) {
(PinTarget::Layer(_), Some(te)) => PinTarget::Layer(layer_uid(&it.effects[te])),
_ => PinTarget::Frame,
};
Pin::new(to, edges, own, tb)
});
it.effects[ei].layer.get_or_insert_with(Default::default).pin = new_pin;
let uid = it.effects[ei].layer.as_ref().map_or(0, |x| x.uid);
Ok(json!({"clip": clip.0, "layer": l, "uid": uid, "pin": it.effects[ei].layer.as_ref().and_then(|x| x.pin.as_ref()).map(|p| serde_json::to_value(p).unwrap_or_default())}))
})?;
Ok(r)
}
/// Stroke widths use the same finite pixel range as the layer controls.
fn char_stroke_width(k: &str, v: &Value) -> Result<f32> {
v.as_f64()
.filter(|n| n.is_finite() && (0.0..=1000.0).contains(n))
.map(|n| n as f32)
.ok_or_else(|| bad("graphics.setCharStyle", format!("`{k}` must be a number from 0 to 1000")))
}
fn char_stroke_kind(k: &str, v: &Value) -> Result<u32> {
let kind = match v {
Value::Number(n) => n.as_u64().filter(|n| *n <= 2).map(|n| n as u32),
Value::String(s) => graphic::STROKE_OPTS.iter().position(|o| o.eq_ignore_ascii_case(s)).map(|n| n as u32),
_ => None,
};
kind.ok_or_else(|| bad("graphics.setCharStyle", format!("`{k}` must be outer, center, inner, or 0..2")))
}
fn char_style_p(v: &Value) -> Result<CharStyle> {
let o = v.as_object().ok_or_else(|| bad("graphics.setCharStyle", "`style` must be an object"))?;
let mut c = CharStyle::default();
for (k, x) in o {
match k.as_str() {
"font" | "family" => c.font = x.as_str().map(str::to_string),
"fontStyle" | "font_style" | "style" => c.font_style = x.as_str().map(str::to_string),
"size" | "fontSize" => c.size = x.as_f64().map(|v| v as f32),
"stroke" => c.stroke = Some(x.as_bool().ok_or_else(|| bad("graphics.setCharStyle", "`stroke` must be a boolean"))?),
"stroke2" => c.stroke2 = Some(x.as_bool().ok_or_else(|| bad("graphics.setCharStyle", "`stroke2` must be a boolean"))?),
"strokeWidth" | "stroke_width" => c.stroke_width = Some(char_stroke_width(k, x)?),
"stroke2Width" | "stroke2_width" => c.stroke2_width = Some(char_stroke_width(k, x)?),
"strokeType" | "stroke_type" => c.stroke_type = Some(char_stroke_kind(k, x)?),
"stroke2Type" | "stroke2_type" => c.stroke2_type = Some(char_stroke_kind(k, x)?),
"fill" | "color" | "fillColor" | "fill_color" | "strokeColor" | "stroke_color" | "stroke2Color" | "stroke2_color" => {
let color = Some(match crate::commands::json_to_param(&ParamValue::Color([0.0; 4]), x) {
Some(ParamValue::Color(col)) => col,
_ => return Err(bad("graphics.setCharStyle", format!("`{k}`: \"#rrggbb\" or [r,g,b,a]"))),
});
match k.as_str() {
"strokeColor" | "stroke_color" => c.stroke_color = color,
"stroke2Color" | "stroke2_color" => c.stroke2_color = color,
_ => c.fill = color,
}
}
"bold" | "fauxBold" | "faux_bold" => c.faux_bold = x.as_bool(),
"italic" | "fauxItalic" | "faux_italic" => c.faux_italic = x.as_bool(),
"underline" => c.underline = x.as_bool(),
"strikethrough" | "strike" => c.strikethrough = x.as_bool(),
"tracking" => c.tracking = x.as_f64().map(|v| v as f32),
"baselineShift" | "baseline_shift" => c.baseline_shift = x.as_f64().map(|v| v as f32),
"caps" => {
c.caps = match x {
Value::Number(n) => n.as_u64().map(|v| v.min(2) as u32),
Value::String(s) => graphic::CAPS_OPTS.iter().position(|o| o.eq_ignore_ascii_case(s.replace('_', " ").as_str())).map(|i| i as u32),
_ => None,
}
}
other => return Err(bad("graphics.setCharStyle", format!("unknown style property `{other}`"))),
}
}
Ok(c)
}
fn set_char_style(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.setCharStyle", "no graphic clip"))?;
let (l, ei) = layer_effect_index(s, clip, p)?;
let clear = bool_p(p, "clear").unwrap_or(false);
let style = match p.get("style") {
Some(v) => char_style_p(v)?,
None if clear => CharStyle::default(),
None => return Err(bad("graphics.setCharStyle", "need `style` (or `clear`)")),
};
let tl = s.playhead();
let (start, end) = (u64_p(p, "start").map(|v| v as usize), u64_p(p, "end").map(|v| v as usize));
// A pointer gesture shares one undo step only within the same clip, layer and range.
let merge = bool_p(p, "merge").unwrap_or(false).then(|| format!("graphics.setCharStyle:{}:{ei}:{start:?}:{end:?}", clip.0));
if bool_p(p, "begin").unwrap_or(false) {
s.history.merge_key = None;
}
let runs = s.edit_sequence_as("Character Style", merge.as_deref(), move |q, _, _| {
let (_, it) = q.find_item_mut(clip).ok_or(filmcraft_edit::EditError::NoItem(clip))?;
let mt = it.source_time_at(tl.clamp(it.start, it.end() - Tick(1)));
let e = &mut it.effects[ei];
if e.effect != graphic::TEXT_LAYER {
return Err(bad("graphics.setCharStyle", "the layer is not a text layer"));
}
let n = graphic::text_chars(e, mt);
let (a, b) = (start.unwrap_or(0).min(n), end.unwrap_or(n).min(n));
if a >= b {
return Err(bad("graphics.setCharStyle", "empty character range"));
}
let x = e.layer.get_or_insert_with(Default::default);
x.runs = if clear { clear_char_style(&x.runs, n, a, b) } else { apply_char_style(&x.runs, n, a, b, &style) };
let runs = serde_json::to_value(&x.runs).unwrap_or_default();
if x.is_empty() {
e.layer = None;
}
Ok(runs)
})?;
Ok(json!({"clip": clip.0, "layer": l, "styles": runs}))
}
// ------------------------------------------------------------------------------------------------
// Upgrade Caption to Graphic / Upgrade to Source Graphic
// ------------------------------------------------------------------------------------------------
/// Caption text with `<i>`/`<b>`/`<u>` → plain text and character style runs.
fn caption_runs(text: &str) -> (String, Vec<filmcraft_project::StyleRun>) {
let mut out = String::new();
let mut runs: Vec<filmcraft_project::StyleRun> = Vec::new();
let (mut it, mut bo, mut ul) = (false, false, false);
let mut rest = text;
let mut n = 0usize;
while let Some(ch) = rest.chars().next() {
if ch == '<'
&& let Some(end) = rest.find('>')
{
match rest[1..end].trim().to_ascii_lowercase().as_str() {
"i" => it = true,
"/i" => it = false,
"b" => bo = true,
"/b" => bo = false,
"u" => ul = true,
"/u" => ul = false,
_ => {}
}
rest = &rest[end + 1..];
continue;
}
let decoded = match ch {
'&' if rest.starts_with("&") => ('&', 5),
'&' if rest.starts_with("<") => ('<', 4),
'&' if rest.starts_with(">") => ('>', 4),
c => (c, c.len_utf8()),
};
out.push(decoded.0);
if it || bo || ul {
let st = CharStyle { faux_italic: it.then_some(true), faux_bold: bo.then_some(true), underline: ul.then_some(true), ..Default::default() };
runs = apply_char_style(&runs, n + 1, n, n + 1, &st);
}
n += 1;
rest = &rest[decoded.1..];
}
(out, runs)
}
fn upgrade_caption(s: &mut Session, p: &Value) -> Result<Value> {
let seq = s.active_sequence().ok_or(EngineError::NoSequence)?;
let (w, h) = (seq.settings.width, seq.settings.height);
let ids: Vec<ClipId> = match p.get("captions").and_then(Value::as_array) {
Some(a) => a.iter().filter_map(Value::as_u64).map(ClipId).collect(),
None if !s.state.caption_selection.is_empty() => s.state.caption_selection.clone(),
None => {
let t = s.playhead();
seq.caption_tracks.iter().find_map(|tr| tr.caption_at(t).map(|c| c.id)).into_iter().collect()
}
};
if ids.is_empty() {
return Err(bad("graphics.upgradeCaption", "select captions to upgrade"));
}
let mut jobs = Vec::new();
for tr in &seq.caption_tracks {
for c in tr.captions.iter().filter(|c| ids.contains(&c.id)) {
jobs.push((c.clone(), tr.style.clone()));
}
}
if jobs.is_empty() {
return Err(bad("graphics.upgradeCaption", "no such captions"));
}
let before = s.history.undo.len();
let mut clips = Vec::new();
for (c, st) in &jobs {
let k = h as f64 / 1080.0;
let size = st.size as f64 * k;
let (text, runs) = caption_runs(&c.text);
let lines = text.lines().count().max(1) as f64;
let line_h = size * st.line_spacing as f64;
let x = match st.align {
filmcraft_project::CaptionAlign::Left => w as f64 * 0.1,
filmcraft_project::CaptionAlign::Center => w as f64 / 2.0,
filmcraft_project::CaptionAlign::Right => w as f64 * 0.9,
};
let margin = st.margin as f64 * h as f64;
let first_baseline = match st.anchor {
filmcraft_project::CaptionAnchor::Bottom => h as f64 - margin - (lines - 1.0) * line_h - size * 0.25,
filmcraft_project::CaptionAnchor::Top => margin + size,
filmcraft_project::CaptionAnchor::Middle => h as f64 / 2.0 - (lines - 1.0) * line_h / 2.0 + size * 0.35,
};
let mut layer = graphic::new_text_layer(&text, Vec2::new(x, first_baseline), size);
let set = |e: &mut EffectInstance, k: &str, v: ParamValue| {
e.params.insert(k.into(), filmcraft_project::Param::new(v));
};
let col = |c: [u8; 4]| [c[0] as f32 / 255.0, c[1] as f32 / 255.0, c[2] as f32 / 255.0, 1.0];
set(&mut layer, "font", ParamValue::Text(st.font.clone()));
let font_style = if st.font_style.trim().is_empty() { "SemiBold" } else { st.font_style.trim() };
set(&mut layer, "font_style", ParamValue::Text(font_style.into()));
set(&mut layer, "align", ParamValue::Choice(st.align as u32));
set(&mut layer, "fill_color", ParamValue::Color(col(st.color)));
set(&mut layer, "leading", ParamValue::Float(line_h - size * 1.21));
if st.background {
set(&mut layer, "background", ParamValue::Bool(true));
set(&mut layer, "background_color", ParamValue::Color(col(st.background_color)));
set(&mut layer, "background_opacity", ParamValue::Float(st.background_color[3] as f64 / 2.55));
set(&mut layer, "background_size", ParamValue::Float(size * 0.2));
}
if st.outline > 0.0 {
set(&mut layer, "stroke", ParamValue::Bool(true));
set(&mut layer, "stroke_color", ParamValue::Color(col(st.outline_color)));
set(&mut layer, "stroke_width", ParamValue::Float(st.outline as f64 * k));
}
if !runs.is_empty() {
layer.layer = Some(Box::new(LayerExtra { runs, ..Default::default() }));
}
let name = text.lines().next().unwrap_or("Caption").chars().take(40).collect::<String>();
let dur = c.duration;
let q = json!({"time": c.start.0});
let clip = place_video_clip(s, "graphics.upgradeCaption", &name, &q, "Upgrade Caption to Graphic", vec![layer], move |pr, (w, h, rate)| {
(crate::graphics::graphic_source(pr, w, h, rate), dur)
})?;
clips.push(clip.0);
}
let del: Vec<ClipId> = jobs.iter().map(|j| j.0.id).collect();
s.edit_sequence("Upgrade Caption to Graphic", move |q, _, st| {
filmcraft_edit::captions::delete_captions(q, &del, false)?;
st.caption_selection.clear();
Ok(())
})?;
fold_undo(s, before, "Upgrade Caption to Graphic");
Ok(json!({"clips": clips, "upgraded": jobs.len()}))
}
fn upgrade_to_source(s: &mut Session, p: &Value) -> Result<Value> {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.upgradeToSourceGraphic", "select a graphic clip"))?;
let it = clip_item(s, clip)?;
if s.project.source_graphics.contains_key(&it.item) {
return Err(bad("graphics.upgradeToSourceGraphic", "the graphic already is a source graphic"));
}
let kind = s.project.item(it.item).map(|x| x.kind.clone()).ok_or_else(|| bad("graphics.upgradeToSourceGraphic", "no item"))?;
let seq = s.state.active_sequence.ok_or(EngineError::NoSequence)?;
let name = it.name.clone();
let item = s.edit("Upgrade to Source Graphic", move |pr, st| {
let item = pr.add_item(&name, Label::Rose, kind, None);
let q = pr.sequence_mut(seq).ok_or(EngineError::NoSequence)?;
let (_, ti) = q.find_item_mut(clip).ok_or_else(|| bad("graphics.upgradeToSourceGraphic", "no such clip"))?;
ti.item = item;
let layers: Vec<EffectInstance> = ti.effects.iter().filter(|e| graphic::is_layer(e)).cloned().collect();
let meta = ti.graphic.as_deref().cloned();
pr.source_graphics.insert(item, SourceGraphic { layers, meta });
st.project_selection = vec![item];
Ok(item)
})?;
Ok(json!({"clip": clip.0, "item": item.0}))
}
/// After a `graphics.*` command: copy an edited instance of a source graphic to the shared
/// layers and every other instance (in the same undo step).
pub fn sync_source_graphics(s: &mut Session) {
if s.project.source_graphics.is_empty() {
return;
}
let p = Arc::make_mut(&mut s.project);
let items: Vec<ItemId> = p.source_graphics.keys().copied().collect();
for item in items {
let master = p.source_graphics[&item].clone();
let layers_of = |t: &TrackItem| t.effects.iter().filter(|e| graphic::is_layer(e)).cloned().collect::<Vec<_>>();
// the first instance that differs from the master is the edited one
let mut changed: Option<SourceGraphic> = None;
for q in p.sequences() {
if let ItemKind::Sequence(sq) = &q.kind {
for tr in &sq.video_tracks {
for t in tr.items.iter().filter(|t| t.item == item) {
let l = layers_of(t);
let m = t.graphic.as_deref().cloned();
if l != master.layers || m != master.meta {
changed = Some(SourceGraphic { layers: l, meta: m });
}
}
}
}
if changed.is_some() {
break;
}
}
let Some(new) = changed else { continue };
let ids: Vec<ItemId> = p.sequences().map(|q| q.id).collect();
for id in ids {
if let Some(sq) = p.sequence_mut(id) {
for tr in &mut sq.video_tracks {
for t in tr.items.iter_mut().filter(|t| t.item == item) {
let mut fx: Vec<EffectInstance> = t.effects.iter().filter(|e| !graphic::is_layer(e)).cloned().collect();
let at = fx.iter().position(|e| !e.def().is_some_and(|d| d.intrinsic)).unwrap_or(fx.len());
for (k, l) in new.layers.iter().enumerate() {
fx.insert(at + k, l.clone());
}
t.effects = fx;
t.graphic = new.meta.clone().map(Box::new);
}
}
}
}
p.source_graphics.insert(item, new);
}
}
// ------------------------------------------------------------------------------------------------
// Fonts
// ------------------------------------------------------------------------------------------------
/// Every graphic layer (all sequences and source graphics), mutably.
fn for_each_layer(p: &mut Project, mut f: impl FnMut(&mut EffectInstance)) {
let ids: Vec<ItemId> = p.sequences().map(|q| q.id).collect();
for id in ids {
if let Some(sq) = p.sequence_mut(id) {
for tr in &mut sq.video_tracks {
for t in &mut tr.items {
t.effects.iter_mut().filter(|e| e.effect == graphic::TEXT_LAYER).for_each(&mut f);
}
}
}
}
for sg in p.source_graphics.values_mut() {
sg.layers.iter_mut().filter(|e| e.effect == graphic::TEXT_LAYER).for_each(&mut f);
}
}
fn text_of(e: &EffectInstance, k: &str) -> String {
match e.params.get(k).map(|x| &x.value) {
Some(ParamValue::Text(t)) => t.clone(),
_ => String::new(),
}
}
/// Fonts used by graphics (layers and character styles) and caption tracks.
pub fn fonts_used(s: &Session) -> Vec<(String, String, usize)> {
let mut v: Vec<(String, String, usize)> = Vec::new();
let mut add = |fam: String, st: String| match v.iter_mut().find(|x| x.0.eq_ignore_ascii_case(&fam) && x.1.eq_ignore_ascii_case(&st)) {
Some(x) => x.2 += 1,
None => v.push((fam, st, 1)),
};
let mut p = (*s.project).clone();
for_each_layer(&mut p, |e| {
let (fam, st) = (text_of(e, "font"), text_of(e, "font_style"));
add(if fam.is_empty() { "Inter".into() } else { fam.clone() }, if st.is_empty() { "Regular".into() } else { st.clone() });
for r in e.layer.as_ref().map(|x| x.runs.clone()).unwrap_or_default() {
if r.style.font.is_some() || r.style.font_style.is_some() {
add(r.style.font.clone().unwrap_or_else(|| fam.clone()), r.style.font_style.clone().unwrap_or_else(|| st.clone()));
}
}
});
for q in s.project.sequences() {
if let ItemKind::Sequence(sq) = &q.kind {
for t in &sq.caption_tracks {
let st = if t.style.font_style.trim().is_empty() { "SemiBold" } else { t.style.font_style.trim() };
add(t.style.font.clone(), st.into());
}
}
}
v.sort();
v
}
fn replace_fonts(s: &mut Session, p: &Value) -> Result<Value> {
let (from, from_style) = match p.get("from") {
Some(Value::String(f)) => (f.clone(), None),
Some(Value::Object(o)) => {
(o.get("family").and_then(Value::as_str).unwrap_or("").to_string(), o.get("style").and_then(Value::as_str).map(str::to_string))
}
_ => return Err(bad("file.replaceFonts", "need `from` (a family, or {family, style})")),
};
let (to, to_style) = match p.get("to") {
Some(Value::String(f)) => (f.clone(), str_p(p, "toStyle").map(str::to_string)),
Some(Value::Object(o)) => {
(o.get("family").and_then(Value::as_str).unwrap_or("").to_string(), o.get("style").and_then(Value::as_str).map(str::to_string))
}
_ => return Err(bad("file.replaceFonts", "need `to` (a family, or {family, style})")),
};
if from.is_empty() || to.is_empty() {
return Err(bad("file.replaceFonts", "font families cannot be empty"));
}
let n = s.edit("Replace Fonts", move |pr, _| {
let mut n = 0usize;
let matches = |fam: &str, st: &str| fam.eq_ignore_ascii_case(&from) && from_style.as_ref().is_none_or(|x| x.eq_ignore_ascii_case(st));
for_each_layer(pr, |e| {
let (fam, st) = (text_of(e, "font"), text_of(e, "font_style"));
if matches(&fam, &st) {
e.params.insert("font".into(), filmcraft_project::Param::new(ParamValue::Text(to.clone())));
if let Some(ts) = &to_style {
e.params.insert("font_style".into(), filmcraft_project::Param::new(ParamValue::Text(ts.clone())));
}
n += 1;
}
if let Some(x) = e.layer.as_mut() {
for r in &mut x.runs {
let rf = r.style.font.clone().unwrap_or_else(|| fam.clone());
let rs = r.style.font_style.clone().unwrap_or_else(|| st.clone());
if r.style.font.is_some() && matches(&rf, &rs) {
r.style.font = Some(to.clone());
if let Some(ts) = &to_style {
r.style.font_style = Some(ts.clone());
}
n += 1;
}
}
}
});
let ids: Vec<ItemId> = pr.sequences().map(|q| q.id).collect();
for id in ids {
if let Some(sq) = pr.sequence_mut(id) {
for t in &mut sq.caption_tracks {
let st = if t.style.font_style.trim().is_empty() { "SemiBold" } else { t.style.font_style.trim() };
if matches(&t.style.font, st) {
t.style.font = to.clone();
if let Some(ts) = &to_style {
t.style.font_style = ts.clone();
}
n += 1;
}
}
}
}
Ok(n)
})?;
Ok(json!({"replaced": n}))
}
fn list_fonts_used(s: &mut Session, _: &Value) -> Result<Value> {
Ok(Value::Array(
fonts_used(s)
.into_iter()
.map(|(f, st, n)| {
let missing = filmcraft_text::resolve(&f, &st).missing;
json!({"family": f, "style": st, "uses": n, "missing": missing})
})
.collect(),
))
}
pub fn commands() -> Vec<CommandSpec> {
vec![
query(
"graphics.template.list",
"List Graphics Templates",
r#"{"query":str? (search names, categories, descriptions, tags),"category":str?,"source":"builtin|user"?}"#,
list_templates,
),
spec(
"graphics.template.apply",
"Apply Graphics Template",
&[],
r#"{"template":id|name|path,"values":{control id or name: value}?,"time":ticks?,"track":index?}"#,
has_seq,
apply_template,
),
spec(
"graphics.template.export",
"Export As Motion Graphics Template…",
G,
r#"{"clip":id?,"name":str,"category":str="My Templates","description":str?,"controls":[{"layer":n|name,"param":"text|fill_color|size|font|position|enabled|…","name":str?,"kind":"text|color|slider|checkbox|font|position"?,"min":f64?,"max":f64?,"id":str?}]? (default: each text layer's text),"path":str? (default: the user templates folder),"embedFonts":bool=false,"fontLicense":str?}"#,
has_graphic,
export_template,
),
spec("file.exportGraphicsTemplate", "Motion Graphics Template…", &["File", "Export"], r#"as graphics.template.export"#, has_graphic, export_template),
spec(
"graphics.template.install",
"Install Motion Graphics Template…",
G,
r#"{"path":str (a .fcgt file; Adobe .mogrt files are refused)}"#,
always,
install_template,
),
spec("graphics.template.remove", "Remove Graphics Template", &[], r#"{"template":id|name (a user template)}"#, always, remove_template),
spec(
"graphics.template.set",
"Set Template Property",
&[],
r#"{"clip":id?,"control":id|name,"value":any} or {"clip":id?,"values":{control: value}}"#,
has_graphic,
|s, p| {
let clip = target_clip(s, p).ok_or_else(|| bad("graphics.template.set", "no graphic clip"))?;
let mut vals = p.get("values").and_then(Value::as_object).cloned().unwrap_or_default();
if let Some(c) = str_p(p, "control") {
vals.insert(c.to_string(), p.get("value").cloned().unwrap_or(Value::Null));
}
if vals.is_empty() {
return Err(bad("graphics.template.set", "need `control` and `value`, or `values`"));
}
let before = s.history.undo.len();
let n = set_controls(s, clip, &vals);
fold_undo(s, before, "Change Template Property");
Ok(json!({"clip": clip.0, "set": n?}))
},
),
query("graphics.template.controls", "List Template Properties", r#"{"clip":id?}"#, template_controls),
query(
"graphics.template.thumbnail",
"Graphics Template Thumbnail",
r#"{"template":id|name|path,"width":px=320,"path":str? (write a PNG there; else returned as pngBase64)}"#,
template_thumbnail,
),
spec(
"graphics.setRoll",
"Roll/Crawl Options",
&[],
r#"{"clip":id?,"mode":"off|roll|crawlLeft|crawlRight"?,"startOffScreen":bool?,"endOffScreen":bool?,"prerollFrames":n?,"easeInFrames":n?,"easeOutFrames":n?,"postrollFrames":n? (or …Seconds, or ticks as preroll/easeIn/easeOut/postroll)}"#,
has_graphic,
set_roll,
),
spec(
"graphics.setResponsiveTime",
"Responsive Design - Time",
&[],
r#"{"clip":id?,"introFrames":n?,"outroFrames":n? (or introSeconds / outroSeconds, or ticks as intro / outro)}"#,
has_graphic,
set_responsive_time,
),
spec(
"graphics.pin",
"Responsive Design - Position",
&[],
r#"{"clip":id?,"layer":n|name?,"to":"frame"|"none"|layer index|layer name,"edges":["left","top","right","bottom"]|"all"="all"}"#,
has_graphic,
pin_layer,
),
spec(
"graphics.setCharStyle",
"Character Style",
&[],
r##"{"clip":id?,"layer":n|name?,"start":char=0,"end":char=len,"style":{"font":str,"fontStyle":str,"size":px,"color":"#rrggbb","stroke":bool,"strokeColor":"#rrggbb","strokeWidth":px,"strokeType":"outer|center|inner","stroke2":bool,"stroke2Color":"#rrggbb","stroke2Width":px,"stroke2Type":"outer|center|inner","bold":bool,"italic":bool,"underline":bool,"strikethrough":bool,"tracking":n,"baselineShift":px,"caps":"normal|all caps|small caps"},"clear":bool? (remove styles from the range),"merge":bool?,"begin":bool? (start a new undo gesture)}"##,
has_graphic,
set_char_style,
),
spec(
"graphics.upgradeCaption",
"Upgrade Caption to Graphic",
G,
r#"{"captions":[id]? (default: the selected captions, else the one under the playhead)}"#,
has_captions,
upgrade_caption,
),
spec("graphics.upgradeToSourceGraphic", "Upgrade to Source Graphic", G, r#"{"clip":id?}"#, has_graphic, upgrade_to_source),
spec(
"file.replaceFonts",
"Replace Fonts in Projects…",
G,
r#"{"from":family|{"family","style"?},"to":family|{"family","style"?},"toStyle":str?}"#,
always,
replace_fonts,
),
query("graphics.fonts.used", "List Fonts Used", "{}", list_fonts_used),
]
}
#[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.