f67d38b35cc5
gtemplate.rs
//! Graphics templates (`.fcgt`): FilmCraft's own format for reusable graphics with editable
//! properties, the counterpart of motion graphics templates in other editors.
//!
//! A template file is UTF-8 JSON ([`GraphicsTemplate`]):
//!
//! ```json
//! {
//! "format": "filmcraft.graphicsTemplate",
//! "version": 1,
//! "id": "user:my-lower-third",
//! "name": "My Lower Third",
//! "category": "Lower Thirds",
//! "description": "", "author": "", "license": "", "tags": [],
//! "canvas": [1920, 1080],
//! "duration": 1270080000000,
//! "layers": [ /* graphic_text / graphic_shape effect instances, as in a project file */ ],
//! "graphic": { /* roll, intro / outro (GraphicMeta) */ },
//! "controls": [ { "id": "name", "name": "Name", "kind": "text", "layer": 1, "param": "text" } ],
//! "resources": { "fonts": [ { "family": "…", "style": "…", "license": "OFL-1.1", "data": "<base64>" } ] }
//! }
//! ```
//!
//! - `version` is the format version; readers refuse newer versions.
//! - Layers are referenced by their [`LayerExtra::uid`](crate::graphic_design::LayerExtra); every
//! layer of a template has one.
//! - `controls` are the properties a user of the template edits (Essential Graphics ▸ Edit):
//! text, colour, slider (with `min` / `max`), checkbox, font and position, each bound to one
//! layer parameter (`enabled` = the layer's visibility).
//! - `resources.fonts` optionally embeds font files (base64) that the template needs; installing
//! the template registers them. Only embed fonts whose licence allows redistribution.
//!
//! FilmCraft never reads Adobe `.mogrt` files (or any other application's template format);
//! [`GraphicsTemplate::from_bytes`] rejects ZIP archives with a message saying so.
//!
//! The built-in templates ([`builtin_templates`]) are original designs made for FilmCraft in code
//! (no image, font or template files), under the project licence.
use std::collections::{HashMap, HashSet};
use filmcraft_geom::Vec2;
use filmcraft_time::{TICKS_PER_SECOND, Tick};
use serde::{Deserialize, Serialize};
use crate::effect::EffectInstance;
use crate::graphic::{self, new_shape_layer, new_text_layer};
use crate::graphic_design::{GraphicMeta, LayerExtra, Pin, PinTarget, Roll, RollMode};
use crate::keyframe::{Param, ParamValue};
pub const TEMPLATE_FORMAT: &str = "filmcraft.graphicsTemplate";
pub const TEMPLATE_VERSION: u32 = 1;
pub const TEMPLATE_EXTENSION: &str = "fcgt";
/// Kind of an editable template property.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ControlKind {
#[default]
Text,
Color,
Slider,
Checkbox,
Font,
Position,
}
impl ControlKind {
pub const ALL: [ControlKind; 6] =
[ControlKind::Text, ControlKind::Color, ControlKind::Slider, ControlKind::Checkbox, ControlKind::Font, ControlKind::Position];
pub fn name(self) -> &'static str {
match self {
ControlKind::Text => "text",
ControlKind::Color => "color",
ControlKind::Slider => "slider",
ControlKind::Checkbox => "checkbox",
ControlKind::Font => "font",
ControlKind::Position => "position",
}
}
pub fn from_name(s: &str) -> Option<ControlKind> {
let s = s.to_ascii_lowercase();
let s = if s == "colour" { "color".to_string() } else { s };
ControlKind::ALL.into_iter().find(|k| k.name() == s)
}
/// The kind that edits parameter `param` of a layer.
pub fn for_param(param: &str) -> ControlKind {
match param {
"text" | "name" => ControlKind::Text,
"font" | "font_style" => ControlKind::Font,
"position" | "anchor" => ControlKind::Position,
"enabled" => ControlKind::Checkbox,
p if p.ends_with("_color") => ControlKind::Color,
p => match crate::find_effect(graphic::TEXT_LAYER)
.and_then(|d| d.param(p))
.or_else(|| crate::find_effect(graphic::SHAPE_LAYER).and_then(|d| d.param(p)))
{
Some(d) => match &d.default {
ParamValue::Bool(_) => ControlKind::Checkbox,
ParamValue::Color(_) => ControlKind::Color,
ParamValue::Vec2(_) => ControlKind::Position,
ParamValue::Text(_) => ControlKind::Text,
_ => ControlKind::Slider,
},
None => ControlKind::Slider,
},
}
}
}
/// One editable property of a template (Essential Graphics ▸ Edit).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct TemplateControl {
/// Stable id (`[a-z0-9_-]`), unique in the template.
pub id: String,
/// Label shown to the user.
pub name: String,
pub kind: ControlKind,
/// The layer (by uid) and parameter id it edits (`enabled` = layer visibility).
pub layer: u64,
pub param: String,
/// Slider range.
#[serde(skip_serializing_if = "Option::is_none")]
pub min: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub max: Option<f64>,
}
/// The template a placed graphic came from (kept on the clip, `GraphicMeta::template`).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct TemplateLink {
pub id: String,
pub name: String,
pub controls: Vec<TemplateControl>,
}
/// A font embedded in a template.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct FontResource {
pub family: String,
pub style: String,
/// SPDX id of the font's licence (must allow redistribution).
pub license: String,
/// Original file name (informational).
pub file: String,
/// The font file, base64.
pub data: String,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Resources {
#[serde(skip_serializing_if = "Vec::is_empty")]
pub fonts: Vec<FontResource>,
}
impl Resources {
pub fn is_empty(&self) -> bool {
self.fonts.is_empty()
}
}
/// A graphics template (`.fcgt`).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct GraphicsTemplate {
pub format: String,
pub version: u32,
pub id: String,
pub name: String,
pub category: String,
pub description: String,
pub author: String,
pub license: String,
pub tags: Vec<String>,
/// Frame size the template was designed for.
pub canvas: [u32; 2],
/// Default clip duration.
pub duration: Tick,
pub layers: Vec<EffectInstance>,
/// Roll / responsive time settings (`template` is not stored here).
pub graphic: GraphicMeta,
pub controls: Vec<TemplateControl>,
#[serde(skip_serializing_if = "Resources::is_empty")]
pub resources: Resources,
}
impl Default for GraphicsTemplate {
fn default() -> Self {
GraphicsTemplate {
format: TEMPLATE_FORMAT.into(),
version: TEMPLATE_VERSION,
id: String::new(),
name: String::new(),
category: "My Templates".into(),
description: String::new(),
author: String::new(),
license: String::new(),
tags: Vec::new(),
canvas: [1920, 1080],
duration: Tick(5 * TICKS_PER_SECOND),
layers: Vec::new(),
graphic: GraphicMeta::default(),
controls: Vec::new(),
resources: Resources::default(),
}
}
}
/// Problems reading or validating a template.
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum TemplateError {
#[error(
"this file is a ZIP archive (an Adobe .mogrt or another application's package?): FilmCraft does not read motion graphics templates from other applications, only its own .fcgt graphics templates"
)]
ForeignPackage,
#[error("not a FilmCraft graphics template: {0}")]
NotTemplate(String),
#[error("this graphics template was made by a newer FilmCraft (format version {0}; this build reads up to {TEMPLATE_VERSION})")]
TooNew(u32),
#[error("invalid graphics template: {0}")]
Invalid(String),
}
/// Lower-case slug of a name (`My Lower Third` → `my-lower-third`), retaining Unicode letters and digits.
pub fn slug(name: &str) -> String {
let mut s = String::new();
for c in name.chars() {
if c.is_alphanumeric() {
s.extend(c.to_lowercase());
} else if !s.ends_with('-') && !s.is_empty() {
s.push('-');
}
}
let s = s.trim_end_matches('-').to_string();
if s.is_empty() { "template".into() } else { s }
}
impl GraphicsTemplate {
/// Serialize (pretty JSON).
pub fn to_json(&self) -> String {
serde_json::to_string_pretty(self).unwrap_or_default()
}
/// Read a template file. ZIP archives (such as `.mogrt` packages) are refused without being
/// inspected.
pub fn from_bytes(bytes: &[u8]) -> Result<GraphicsTemplate, TemplateError> {
if bytes.starts_with(b"PK\x03\x04") || bytes.starts_with(b"PK\x05\x06") {
return Err(TemplateError::ForeignPackage);
}
let text =
std::str::from_utf8(bytes.strip_prefix(b"\xef\xbb\xbf").unwrap_or(bytes)).map_err(|_| TemplateError::NotTemplate("not UTF-8 text".into()))?;
let v: serde_json::Value = serde_json::from_str(text).map_err(|e| TemplateError::NotTemplate(e.to_string()))?;
if v.get("format").and_then(|f| f.as_str()) != Some(TEMPLATE_FORMAT) {
return Err(TemplateError::NotTemplate(format!("`format` is not \"{TEMPLATE_FORMAT}\"")));
}
let ver = v.get("version").and_then(|x| x.as_u64()).unwrap_or(0) as u32;
if ver > TEMPLATE_VERSION {
return Err(TemplateError::TooNew(ver));
}
if ver == 0 {
return Err(TemplateError::Invalid("missing `version`".into()));
}
let t: GraphicsTemplate = serde_json::from_value(v).map_err(|e| TemplateError::Invalid(e.to_string()))?;
t.validate()?;
Ok(t)
}
/// Check the template's structure: layers are graphic layers with unique uids, controls
/// point at existing layers and parameters, ids are unique.
pub fn validate(&self) -> Result<(), TemplateError> {
let bad = |m: String| Err(TemplateError::Invalid(m));
if self.name.trim().is_empty() {
return bad("the template has no name".into());
}
if self.layers.is_empty() {
return bad("the template has no layers".into());
}
if self.canvas[0] == 0 || self.canvas[1] == 0 || self.canvas[0] > 16384 || self.canvas[1] > 16384 {
return bad(format!("bad canvas size {:?}", self.canvas));
}
let mut layers = HashMap::with_capacity(self.layers.len());
for (i, l) in self.layers.iter().enumerate() {
if !graphic::is_layer(l) {
return bad(format!("layer {i} is `{}`, not a graphic layer", l.effect));
}
let uid = layer_uid(l);
if uid == 0 || layers.insert(uid, l).is_some() {
return bad(format!("layer {i} has no unique uid"));
}
}
let mut ids = HashSet::with_capacity(self.controls.len());
for c in &self.controls {
if c.id.is_empty() || !ids.insert(c.id.as_str()) {
return bad(format!("control `{}` has no unique id", c.name));
}
let Some(l) = layers.get(&c.layer) else {
return bad(format!("control `{}` points at a missing layer", c.name));
};
if c.param != "enabled" && !l.params.contains_key(&c.param) {
return bad(format!("control `{}`: the layer has no parameter `{}`", c.name, c.param));
}
}
for f in &self.resources.fonts {
if base64_decode(&f.data).is_none() {
return bad(format!("font `{}` is not valid base64", f.family));
}
}
Ok(())
}
/// The layers and settings for a graphic clip on a `canvas`-sized frame. When the frame size
/// differs from the template's, the layers are scaled uniformly (fit) and centred, and pin
/// distances scale with them. Both scale axes, including keyframes, are fitted even when
/// Uniform Scale is off. The result links back to the template.
pub fn instantiate(&self, canvas: (u32, u32)) -> (Vec<EffectInstance>, GraphicMeta) {
let (w, h) = (canvas.0 as f64, canvas.1 as f64);
let (tw, th) = (self.canvas[0] as f64, self.canvas[1] as f64);
let s = (w / tw).min(h / th);
let off = Vec2::new((w - tw * s) / 2.0, (h - th * s) / 2.0);
let mut layers = self.layers.clone();
if (s - 1.0).abs() > 1e-9 || off.x.abs() > 1e-9 || off.y.abs() > 1e-9 {
for l in &mut layers {
// Imported layers can omit parameters and rely on definition defaults. Make
// both scale axes explicit before fitting so those defaults are scaled too.
if let Some(def) = l.def() {
for key in ["scale", "scale_width"] {
if let Some(param) = def.param(key) {
l.params.entry(key.to_string()).or_insert_with(|| Param::new(param.default.clone()));
}
}
}
if let Some(p) = l.params.get_mut("position") {
p.map_values(|v| match v {
ParamValue::Vec2(q) if !q.x.is_nan() => ParamValue::Vec2(Vec2::new(q.x * s + off.x, q.y * s + off.y)),
o => o,
});
}
for key in ["scale", "scale_width"] {
if let Some(p) = l.params.get_mut(key) {
p.map_values(|v| match v {
ParamValue::Float(x) => ParamValue::Float(x * s),
o => o,
});
}
}
if let Some(pin) = l.layer.as_mut().and_then(|x| x.pin.as_mut()) {
pin.offsets.iter_mut().for_each(|o| *o *= s);
}
}
}
let mut meta = self.graphic.clone();
meta.template = Some(TemplateLink { id: self.id.clone(), name: self.name.clone(), controls: self.controls.clone() });
(layers, meta)
}
}
/// A layer's uid (0 = none).
pub fn layer_uid(e: &EffectInstance) -> u64 {
e.layer.as_ref().map_or(0, |x| x.uid)
}
/// Give every layer without a uid a fresh one (unique among `layers`).
pub fn ensure_uids(layers: &mut [EffectInstance]) -> bool {
graphic::ensure_layer_uids(layers)
}
// ------------------------------------------------------------------------------------------------
// base64 (RFC 4648, standard alphabet, padded)
// ------------------------------------------------------------------------------------------------
const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
pub fn base64_encode(data: &[u8]) -> String {
let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
for c in data.chunks(3) {
let n = (c[0] as u32) << 16 | (*c.get(1).unwrap_or(&0) as u32) << 8 | *c.get(2).unwrap_or(&0) as u32;
for k in 0..4 {
if k <= c.len() {
out.push(B64[(n >> (18 - 6 * k) & 63) as usize] as char);
} else {
out.push('=');
}
}
}
out
}
pub fn base64_decode(s: &str) -> Option<Vec<u8>> {
let mut out = Vec::with_capacity(s.len() / 4 * 3);
let mut acc = 0u32;
let mut bits = 0;
for b in s.bytes().filter(|b| !b.is_ascii_whitespace()) {
if b == b'=' {
break;
}
let v = B64.iter().position(|&x| x == b)? as u32;
acc = acc << 6 | v;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
acc &= (1 << bits) - 1;
}
}
Some(out)
}
// ------------------------------------------------------------------------------------------------
// Built-in templates (original designs)
// ------------------------------------------------------------------------------------------------
fn set(e: &mut EffectInstance, id: &str, v: ParamValue) {
e.params.insert(id.to_string(), Param::new(v));
}
fn rgb(hex: u32) -> ParamValue {
let c = |s: u32| ((hex >> s) & 0xff) as f32 / 255.0;
ParamValue::Color([c(16), c(8), c(0), 1.0])
}
fn text(uid: u64, name: &str, s: &str, pos: (f64, f64), size: f64, style: &str) -> EffectInstance {
let mut e = new_text_layer(s, Vec2::new(pos.0, pos.1), size);
set(&mut e, "name", ParamValue::Text(name.into()));
set(&mut e, "font", ParamValue::Text("Inter".into()));
set(&mut e, "font_style", ParamValue::Text(style.into()));
e.layer = Some(Box::new(LayerExtra { uid, ..Default::default() }));
e
}
fn shape(uid: u64, name: &str, kind: u32, pos: (f64, f64), size: (f64, f64), color: u32) -> EffectInstance {
let mut e = new_shape_layer(kind, Vec2::new(pos.0, pos.1), Vec2::new(size.0, size.1), vec![]);
set(&mut e, "name", ParamValue::Text(name.into()));
set(&mut e, "fill_color", rgb(color));
e.layer = Some(Box::new(LayerExtra { uid, ..Default::default() }));
e
}
fn pin(e: &mut EffectInstance, to: u64, edges: [bool; 4], offsets: [f64; 4]) {
let p =
Pin { to: if to == 0 { PinTarget::Frame } else { PinTarget::Layer(to) }, left: edges[0], top: edges[1], right: edges[2], bottom: edges[3], offsets };
e.layer.get_or_insert_with(Default::default).pin = Some(p);
}
fn ctl(id: &str, name: &str, layer: u64, param: &str) -> TemplateControl {
TemplateControl { id: id.into(), name: name.into(), kind: ControlKind::for_param(param), layer, param: param.into(), min: None, max: None }
}
fn slider(id: &str, name: &str, layer: u64, param: &str, min: f64, max: f64) -> TemplateControl {
TemplateControl { min: Some(min), max: Some(max), ..ctl(id, name, layer, param) }
}
fn builtin(
id: &str,
name: &str,
category: &str,
description: &str,
seconds: i64,
layers: Vec<EffectInstance>,
controls: Vec<TemplateControl>,
) -> GraphicsTemplate {
GraphicsTemplate {
id: format!("builtin:{id}"),
name: name.into(),
category: category.into(),
description: description.into(),
author: "FilmCraft contributors".into(),
license: "MIT OR Apache-2.0".into(),
tags: vec![category.to_ascii_lowercase()],
duration: Tick(seconds * TICKS_PER_SECOND),
layers,
controls,
..Default::default()
}
}
/// The built-in templates: original FilmCraft designs (lower thirds, titles, end credits,
/// callouts, a ticker), defined here in code. Designed at 1920×1080 with the bundled Inter font.
pub fn builtin_templates() -> Vec<GraphicsTemplate> {
let mut v = Vec::new();
// Lower third: a slab that grows with the name, a small accent square and a role line.
{
let mut slab = shape(1, "Slab", 0, (400.0, 900.0), (560.0, 150.0), 0x1d4ed8);
set(&mut slab, "opacity", ParamValue::Float(92.0));
pin(&mut slab, 2, [true, false, true, false], [-40.0, 0.0, 48.0, 0.0]);
let mut accent = shape(4, "Accent", 0, (130.0, 900.0), (12.0, 150.0), 0xfacc15);
pin(&mut accent, 1, [true, false, false, false], [-12.0, 0.0, 0.0, 0.0]);
let mut name = text(2, "Name", "Alex Morgan", (160.0, 895.0), 62.0, "SemiBold");
set(&mut name, "fill_color", rgb(0xffffff));
let mut role = text(3, "Role", "Field Producer", (162.0, 950.0), 36.0, "Regular");
set(&mut role, "fill_color", rgb(0xdbeafe));
v.push(builtin(
"lower-third-slab",
"Lower Third – Slab",
"Lower Thirds",
"Name and role on a coloured slab that widens with the name.",
6,
vec![slab, accent, name, role],
vec![
ctl("name", "Name", 2, "text"),
ctl("role", "Role", 3, "text"),
ctl("slab_color", "Slab Color", 1, "fill_color"),
ctl("accent_color", "Accent Color", 4, "fill_color"),
ctl("text_color", "Name Color", 2, "fill_color"),
ctl("show_role", "Show Role", 3, "enabled"),
ctl("font", "Font", 2, "font"),
],
));
}
// Lower third: name with a rule underneath that stretches to the name's width.
{
let mut name = text(1, "Name", "Sam Rivera", (140.0, 900.0), 58.0, "Bold");
let shadow = |e: &mut EffectInstance| {
set(e, "shadow", ParamValue::Bool(true));
set(e, "shadow_distance", ParamValue::Float(3.0));
set(e, "shadow_blur", ParamValue::Float(12.0));
set(e, "shadow_opacity", ParamValue::Float(60.0));
};
shadow(&mut name);
let mut rule = shape(2, "Rule", 0, (300.0, 920.0), (320.0, 5.0), 0x22d3ee);
pin(&mut rule, 1, [true, false, true, false], [0.0, 0.0, 0.0, 0.0]);
let mut role = text(3, "Role", "Lead Engineer", (140.0, 966.0), 34.0, "Medium");
set(&mut role, "tracking", ParamValue::Float(40.0));
shadow(&mut role);
v.push(builtin(
"lower-third-rule",
"Lower Third – Rule",
"Lower Thirds",
"Name over a thin rule that always matches the name's width.",
6,
vec![name, rule, role],
vec![
ctl("name", "Name", 1, "text"),
ctl("role", "Role", 3, "text"),
ctl("rule_color", "Rule Color", 2, "fill_color"),
ctl("font", "Font", 1, "font"),
slider("name_size", "Name Size", 1, "size", 24.0, 140.0),
],
));
}
// Centred title with a subtitle and a short rule between them.
{
let mut title = text(1, "Title", "THE LONG WAY HOME", (960.0, 520.0), 112.0, "Bold");
set(&mut title, "align", ParamValue::Choice(1));
set(&mut title, "tracking", ParamValue::Float(60.0));
let mut rule = shape(2, "Rule", 0, (960.0, 556.0), (220.0, 4.0), 0xf97316);
set(&mut rule, "opacity", ParamValue::Float(90.0));
let mut sub = text(3, "Subtitle", "a story in three parts", (960.0, 628.0), 44.0, "Italic");
set(&mut sub, "align", ParamValue::Choice(1));
set(&mut sub, "fill_color", rgb(0xe5e7eb));
v.push(builtin(
"title-centered",
"Title – Centered",
"Titles",
"Large centred title, accent rule and subtitle.",
5,
vec![title, rule, sub],
vec![
ctl("title", "Title", 1, "text"),
ctl("subtitle", "Subtitle", 3, "text"),
slider("title_size", "Title Size", 1, "size", 40.0, 240.0),
ctl("title_color", "Title Color", 1, "fill_color"),
ctl("accent", "Accent Color", 2, "fill_color"),
ctl("font", "Font", 1, "font"),
],
));
}
// Title in a box (text background) with a soft shadow.
{
let mut title = text(1, "Title", "Chapter One", (960.0, 560.0), 96.0, "SemiBold");
set(&mut title, "align", ParamValue::Choice(1));
set(&mut title, "fill_color", rgb(0x111827));
set(&mut title, "background", ParamValue::Bool(true));
set(&mut title, "background_color", rgb(0xfef3c7));
set(&mut title, "background_opacity", ParamValue::Float(100.0));
set(&mut title, "background_size", ParamValue::Float(36.0));
set(&mut title, "background_radius", ParamValue::Float(10.0));
set(&mut title, "shadow", ParamValue::Bool(true));
set(&mut title, "shadow_distance", ParamValue::Float(8.0));
set(&mut title, "shadow_blur", ParamValue::Float(30.0));
set(&mut title, "shadow_opacity", ParamValue::Float(45.0));
v.push(builtin(
"title-boxed",
"Title – Boxed",
"Titles",
"A title on a rounded card with a soft shadow.",
5,
vec![title],
vec![
ctl("title", "Title", 1, "text"),
ctl("text_color", "Text Color", 1, "fill_color"),
ctl("box_color", "Box Color", 1, "background_color"),
slider("box_opacity", "Box Opacity", 1, "background_opacity", 0.0, 100.0),
ctl("position", "Position", 1, "position"),
],
));
}
// End credits that roll from below the frame to above it.
{
let mut heading = text(1, "Heading", "CREDITS", (960.0, 160.0), 72.0, "Bold");
set(&mut heading, "align", ParamValue::Choice(1));
set(&mut heading, "tracking", ParamValue::Float(120.0));
let body = "Directed by\nJordan Lee\n\nWritten by\nPriya Natarajan\n\nEdited by\nMarco Bianchi\n\nMusic by\nHana Kobayashi\n\nMade with FilmCraft";
let mut credits = text(2, "Credits", body, (960.0, 300.0), 46.0, "Regular");
set(&mut credits, "align", ParamValue::Choice(1));
set(&mut credits, "leading", ParamValue::Float(10.0));
let mut t = builtin(
"end-credits-roll",
"End Credits – Roll",
"End Credits",
"Centred credits that roll up from below the frame and leave at the top.",
12,
vec![heading, credits],
vec![
ctl("heading", "Heading", 1, "text"),
ctl("credits", "Credits", 2, "text"),
ctl("font", "Font", 2, "font"),
ctl("color", "Text Color", 2, "fill_color"),
],
);
t.graphic.roll = Roll { mode: RollMode::Roll, start_off_screen: true, end_off_screen: true, ..Default::default() };
v.push(t);
}
// Callout: a label on a box with a pointer that follows it.
{
let mut label = text(1, "Label", "Look here", (1260.0, 380.0), 48.0, "SemiBold");
set(&mut label, "fill_color", rgb(0xffffff));
set(&mut label, "background", ParamValue::Bool(true));
set(&mut label, "background_color", rgb(0xdc2626));
set(&mut label, "background_opacity", ParamValue::Float(100.0));
set(&mut label, "background_size", ParamValue::Float(18.0));
set(&mut label, "background_radius", ParamValue::Float(6.0));
let mut dot = shape(2, "Pointer", 1, (1200.0, 470.0), (34.0, 34.0), 0xdc2626);
set(&mut dot, "stroke", ParamValue::Bool(true));
set(&mut dot, "stroke_color", rgb(0xffffff));
set(&mut dot, "stroke_width", ParamValue::Float(5.0));
pin(&mut dot, 1, [true, true, false, false], [-60.0, 55.0, 0.0, 0.0]);
v.push(builtin(
"callout-pointer",
"Callout – Pointer",
"Callouts",
"A boxed label with a round pointer; move the label and the pointer follows.",
4,
vec![dot, label],
vec![
ctl("label", "Label", 1, "text"),
ctl("color", "Color", 1, "background_color"),
ctl("pointer", "Pointer Color", 2, "fill_color"),
ctl("position", "Position", 1, "position"),
],
));
}
// Callout: a pill-shaped tag around its text, with a status dot.
{
let mut tag = shape(1, "Tag", 0, (300.0, 140.0), (300.0, 70.0), 0x0f172a);
set(&mut tag, "corner_radius", ParamValue::Float(35.0));
set(&mut tag, "opacity", ParamValue::Float(88.0));
pin(&mut tag, 2, [true; 4], [-70.0, -18.0, 30.0, 18.0]);
let mut dot = shape(3, "Dot", 1, (190.0, 140.0), (22.0, 22.0), 0x22c55e);
pin(&mut dot, 2, [true, false, false, false], [-44.0, 0.0, 0.0, 0.0]);
let mut label = text(2, "Text", "LIVE", (220.0, 155.0), 40.0, "Bold");
set(&mut label, "tracking", ParamValue::Float(80.0));
v.push(builtin(
"callout-tag",
"Callout – Tag",
"Callouts",
"A rounded tag that fits its text, with a status dot.",
4,
vec![tag, dot, label],
vec![
ctl("text", "Text", 2, "text"),
ctl("tag_color", "Tag Color", 1, "fill_color"),
ctl("dot_color", "Dot Color", 3, "fill_color"),
ctl("show_dot", "Show Dot", 3, "enabled"),
],
));
}
// Ticker: a crawl from right to left.
{
let mut line = text(
1,
"Ticker",
"Breaking: the river festival moves to Saturday • Roads close at 6 pm • Shuttle buses run every 15 minutes",
(40.0, 1010.0),
44.0,
"Medium",
);
set(&mut line, "background", ParamValue::Bool(true));
set(&mut line, "background_color", rgb(0x111827));
set(&mut line, "background_opacity", ParamValue::Float(85.0));
set(&mut line, "background_size", ParamValue::Float(14.0));
let mut t = builtin(
"ticker-crawl",
"Ticker – Crawl",
"Lower Thirds",
"A news-style line that crawls in from the right and leaves at the left.",
15,
vec![line],
vec![ctl("text", "Text", 1, "text"), ctl("text_color", "Text Color", 1, "fill_color"), ctl("bar_color", "Bar Color", 1, "background_color")],
);
t.graphic.roll = Roll { mode: RollMode::CrawlLeft, start_off_screen: true, end_off_screen: true, ..Default::default() };
v.push(t);
}
v
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn base64_round_trip() {
for n in 0..20 {
let data: Vec<u8> = (0..n).map(|i| (i * 37 + 11) as u8).collect();
assert_eq!(base64_decode(&base64_encode(&data)).unwrap(), data);
}
assert_eq!(base64_encode(b"Man"), "TWFu");
assert_eq!(base64_encode(b"Ma"), "TWE=");
assert!(base64_decode("@@@").is_none());
}
#[test]
fn builtins_are_valid_and_round_trip() {
let all = builtin_templates();
assert!(all.len() >= 8);
let mut ids: Vec<&str> = all.iter().map(|t| t.id.as_str()).collect();
ids.dedup();
assert_eq!(ids.len(), all.len());
for cat in ["Lower Thirds", "Titles", "End Credits", "Callouts"] {
assert!(all.iter().any(|t| t.category == cat), "{cat}");
}
for t in all {
t.validate().unwrap_or_else(|e| panic!("{}: {e}", t.name));
let back = GraphicsTemplate::from_bytes(t.to_json().as_bytes()).unwrap();
assert_eq!(back, t);
}
}
#[test]
fn refuses_foreign_and_newer_files() {
assert_eq!(GraphicsTemplate::from_bytes(b"PK\x03\x04rest"), Err(TemplateError::ForeignPackage));
assert!(matches!(GraphicsTemplate::from_bytes(b"{\"format\":\"x\"}"), Err(TemplateError::NotTemplate(_))));
let mut t = builtin_templates().remove(0);
t.version = 99;
assert_eq!(GraphicsTemplate::from_bytes(t.to_json().as_bytes()), Err(TemplateError::TooNew(99)));
let mut t = builtin_templates().remove(0);
t.controls[0].layer = 999;
assert!(matches!(t.validate(), Err(TemplateError::Invalid(_))));
}
#[test]
fn template_slugs_preserve_non_ascii_names() {
assert_eq!(slug("片头"), "片头");
assert_eq!(slug("片尾"), "片尾");
assert_eq!(slug("Écran Été"), "écran-été");
assert_eq!(slug("My Lower Third!"), "my-lower-third");
assert_eq!(slug(" ../片头\\片尾! "), "片头-片尾");
assert_eq!(slug("---"), "template");
}
#[test]
fn instantiates_on_other_frame_sizes() {
let t = builtin_templates().into_iter().find(|t| t.id == "builtin:title-centered").unwrap();
let (same, meta) = t.instantiate((1920, 1080));
assert_eq!(same, t.layers);
assert_eq!(meta.template.as_ref().unwrap().id, t.id);
let (half, _) = t.instantiate((960, 540));
assert_eq!(half[0].params["position"].value, ParamValue::Vec2(Vec2::new(480.0, 260.0)));
assert_eq!(half[0].params["scale"].value, ParamValue::Float(50.0));
// a vertical frame: fit to width, centred vertically
let (tall, _) = t.instantiate((1080, 1920));
let ParamValue::Vec2(p) = tall[0].params["position"].value else { panic!() };
assert!((p.x - 540.0).abs() < 1e-9 && (p.y - (520.0 * 0.5625 + (1920.0 - 1080.0 * 0.5625) / 2.0)).abs() < 1e-9);
assert_eq!(slug("My Lower Third!"), "my-lower-third");
assert_eq!(ControlKind::for_param("background_opacity"), ControlKind::Slider);
assert_eq!(ControlKind::for_param("shadow"), ControlKind::Checkbox);
}
#[test]
fn instantiates_nonuniform_layers_with_both_axes_fitted() {
let position = Vec2::new(1920.0, 1080.0);
let mut t = GraphicsTemplate {
canvas: [3840, 2160],
layers: vec![new_text_layer("Lower third", position, 100.0), new_shape_layer(0, position, Vec2::new(400.0, 100.0), Vec::new())],
..Default::default()
};
for uniform in [false, true] {
for layer in &mut t.layers {
set(layer, "uniform_scale", ParamValue::Bool(uniform));
set(layer, "scale", ParamValue::Float(50.0));
set(layer, "scale_width", ParamValue::Float(150.0));
}
let original = t.clone();
for (canvas, fit) in [((3840, 2160), 1.0), ((1920, 1080), 0.5), ((1080, 1920), 0.28125), ((7680, 4320), 2.0)] {
let (layers, _) = t.instantiate(canvas);
for layer in &layers {
let spec = graphic::eval_layer(layer, Tick::ZERO, canvas).unwrap();
let width = if uniform { 0.5 } else { 1.5 };
assert_eq!(spec.transform.scale, Vec2::new(width * fit, 0.5 * fit));
assert_eq!(spec.transform.position, Vec2::new(canvas.0 as f64 / 2.0, canvas.1 as f64 / 2.0));
// Keep the independent width fitted even while Uniform Scale hides it.
assert_eq!(layer.params["scale_width"].value, ParamValue::Float(150.0 * fit));
}
}
assert_eq!(t, original);
}
}
#[test]
fn instantiates_imported_layers_with_omitted_scale_defaults() {
for omitted in [&["scale"][..], &["scale_width"][..], &["scale", "scale_width"][..]] {
for uniform in [false, true] {
let position = Vec2::new(1920.0, 1080.0);
let mut t = GraphicsTemplate {
name: "Imported defaults".into(),
canvas: [3840, 2160],
layers: vec![new_text_layer("Reveal", position, 100.0), new_shape_layer(0, position, Vec2::new(400.0, 100.0), Vec::new())],
..Default::default()
};
ensure_uids(&mut t.layers);
for layer in &mut t.layers {
set(layer, "uniform_scale", ParamValue::Bool(uniform));
for (key, start, end) in [("scale", 50.0, 100.0), ("scale_width", 150.0, 200.0)] {
if omitted.contains(&key) {
layer.params.remove(key);
} else {
let mut param = Param::new(ParamValue::Float(start));
param.put_keyframe(Tick::ZERO, ParamValue::Float(start));
param.put_keyframe(Tick(TICKS_PER_SECOND), ParamValue::Float(end));
layer.params.insert(key.into(), param);
}
}
}
let imported = GraphicsTemplate::from_bytes(t.to_json().as_bytes()).unwrap();
assert_eq!(imported, t);
for (canvas, fit) in [((1920, 1080), 0.5), ((1080, 1920), 0.28125), ((7680, 4320), 2.0)] {
let (layers, _) = imported.instantiate(canvas);
for (placed, original) in layers.iter().zip(&imported.layers) {
for key in omitted {
assert!(!original.params.contains_key(*key));
assert_eq!(placed.params[*key].value, ParamValue::Float(100.0 * fit));
assert!(placed.params[*key].keyframes.is_empty());
}
for time in [Tick::ZERO, Tick(TICKS_PER_SECOND / 2), Tick(TICKS_PER_SECOND)] {
let before = graphic::eval_layer(original, time, (3840, 2160)).unwrap();
let after = graphic::eval_layer(placed, time, canvas).unwrap();
assert_eq!(after.transform.scale, Vec2::new(before.transform.scale.x * fit, before.transform.scale.y * fit));
}
}
}
assert_eq!(imported, t);
}
}
}
#[test]
fn instantiates_animated_width_with_timing_and_interpolation_preserved() {
use crate::keyframe::{Interpolation, Keyframe};
let mut layer = new_text_layer("Reveal", Vec2::new(1920.0, 1080.0), 100.0);
set(&mut layer, "uniform_scale", ParamValue::Bool(false));
let end = Tick(TICKS_PER_SECOND);
for interp in [Interpolation::Linear, Interpolation::Hold] {
let mut first = Keyframe::new(Tick::ZERO, ParamValue::Float(0.0));
first.interp = interp;
let last = Keyframe::new(end, ParamValue::Float(200.0));
let width = Param { value: ParamValue::Float(100.0), keyframes: vec![first, last] };
layer.params.insert("scale_width".into(), width.clone());
let t = GraphicsTemplate { canvas: [3840, 2160], layers: vec![layer.clone()], ..Default::default() };
for (canvas, fit) in [((1920, 1080), 0.5), ((1080, 1920), 0.28125), ((7680, 4320), 2.0)] {
let (layers, _) = t.instantiate(canvas);
let placed = &layers[0];
let scaled = &placed.params["scale_width"];
assert_eq!(scaled.value, ParamValue::Float(100.0 * fit));
assert_eq!(scaled.keyframes.len(), width.keyframes.len());
for (key, original) in scaled.keyframes.iter().zip(&width.keyframes) {
let mut restored = key.clone();
restored.value = original.value.clone();
assert_eq!(&restored, original);
}
let midpoint = if interp == Interpolation::Hold { 0.0 } else { fit };
for (time, expected_width) in [(Tick::ZERO, 0.0), (Tick(TICKS_PER_SECOND / 2), midpoint), (end, 2.0 * fit)] {
let spec = graphic::eval_layer(placed, time, canvas).unwrap();
assert_eq!(spec.transform.scale, Vec2::new(expected_width, fit));
}
}
assert_eq!(t.layers[0].params["scale_width"], width);
}
}
}
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.