Skip to main content

alpha2_compose/
spec.rs

1//! The compose spec: a video described by intent, which [`crate::compile`] turns into a
2//! project document.
3//!
4//! Times are seconds, rounded to the nearest tick (1/120 000 s). Lengths are canvas pixels.
5//! Colors are CSS hex strings or the project's `{red, green, blue, alpha}` object. Nodes are
6//! tagged by `type`, and a node with an `id` can be named by another (a music bed ducks under
7//! it).
8
9use std::collections::BTreeMap;
10
11use alpha2_model::{
12    Animated, Composition, Easing, EffectValue, LayoutNode, MediaSource, Rgba, TextShadow,
13    TextStroke, Track,
14};
15use serde::{Deserialize, Serialize};
16
17/// The newest compose spec version this build reads.
18pub const COMPOSE_VERSION: u32 = 1;
19
20/// A whole video: a body, what is drawn over it, and what plays under it.
21#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
22#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
23#[serde(deny_unknown_fields)]
24pub struct VideoSpec {
25    /// The schema the spec follows (`https://alpha2.sh/schema/compose.v1.json`), for editors and
26    /// validators. The compiler does not read it.
27    #[serde(rename = "$schema", default, skip_serializing_if = "Option::is_none")]
28    pub schema: Option<String>,
29    /// Spec version. This build reads only [`COMPOSE_VERSION`].
30    #[serde(default = "compose_version")]
31    #[cfg_attr(feature = "schema", schemars(extend("const" = COMPOSE_VERSION)))]
32    pub compose_version: u32,
33    /// The project's name. Default `video`.
34    #[serde(default, skip_serializing_if = "Option::is_none")]
35    pub name: Option<String>,
36    /// Size, rate and background. Default `youtube-1080p`.
37    #[serde(default)]
38    pub canvas: Canvas,
39    /// Fonts, colors, sizes and default timings. Default `clean-dark`.
40    #[serde(default)]
41    pub theme: ThemeChoice,
42    /// The main picture, from time zero. Its length is the video's unless `duration` says
43    /// otherwise.
44    pub body: Node,
45    /// Nodes drawn over the body in order, placed by their own `at` (default 0) and lasting to
46    /// the end unless they say otherwise.
47    #[serde(default, skip_serializing_if = "Vec::is_empty")]
48    pub overlays: Vec<Node>,
49    /// Sound beside the body's: `audio` and `music_bed` nodes, placed as overlays are.
50    #[serde(default, skip_serializing_if = "Vec::is_empty")]
51    pub audio: Vec<Node>,
52    /// The video's length in seconds. Default: the body's.
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub duration: Option<f64>,
55    /// The loudness an export normalizes the mix to. Returned as an export option, not stored
56    /// in the project.
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    pub loudness: Option<Loudness>,
59}
60
61const fn compose_version() -> u32 {
62    COMPOSE_VERSION
63}
64
65/// The canvas: a preset name, or its parts.
66#[derive(Clone, Debug, PartialEq, Serialize)]
67#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
68#[serde(untagged)]
69pub enum Canvas {
70    /// A preset at 30 fps: `youtube-1080p` (1920x1080), `youtube-4k` (3840x2160), `youtube-720p`
71    /// (1280x720), `shorts` (1080x1920), `square` (1080x1080) or `portrait` (1080x1350).
72    Preset(String),
73    /// A preset with some parts replaced, or every part given.
74    Custom(CustomCanvas),
75}
76
77impl Default for Canvas {
78    fn default() -> Self {
79        Self::Preset("youtube-1080p".to_owned())
80    }
81}
82
83/// A canvas by its parts.
84#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
85#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
86#[serde(deny_unknown_fields)]
87pub struct CustomCanvas {
88    /// The preset the other parts replace parts of. Default `youtube-1080p`.
89    #[serde(default, skip_serializing_if = "Option::is_none")]
90    pub preset: Option<String>,
91    /// Width in pixels.
92    #[serde(default, skip_serializing_if = "Option::is_none")]
93    pub width: Option<u32>,
94    /// Height in pixels.
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub height: Option<u32>,
97    /// Frames per second: an integer, 23.976, 29.97 or 59.94, or the project's exact
98    /// `{num, den}`.
99    #[serde(default, skip_serializing_if = "Option::is_none")]
100    pub frame_rate: Option<FrameRateChoice>,
101    /// The opaque color under everything. Default: the theme's.
102    #[serde(default, skip_serializing_if = "Option::is_none")]
103    pub background: Option<Rgba>,
104}
105
106/// A frame rate, as a number or exactly.
107#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
108#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
109#[serde(untagged)]
110pub enum FrameRateChoice {
111    /// Frames per second: an integer, or 23.976, 29.97 or 59.94 for the NTSC rates.
112    Number(f64),
113    /// The project's exact rate.
114    Exact(alpha2_time::FrameRate),
115}
116
117/// A theme by name, or one built on a named theme.
118#[derive(Clone, Debug, PartialEq, Serialize)]
119#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
120#[serde(untagged)]
121pub enum ThemeChoice {
122    /// A built-in theme: `clean-dark` or `clean-light`.
123    Named(String),
124    /// A theme of its own.
125    Custom(Box<Theme>),
126}
127
128impl Default for ThemeChoice {
129    fn default() -> Self {
130        Self::Named("clean-dark".to_owned())
131    }
132}
133
134/// How text, panels and timings look. Parts left out come from the base theme. Sizes are
135/// fractions of the canvas's shorter side, so a theme looks the same on wide and tall canvases.
136#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
137#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
138#[serde(deny_unknown_fields)]
139pub struct Theme {
140    /// The built-in theme this one changes. Default `clean-dark`.
141    #[serde(default, skip_serializing_if = "Option::is_none")]
142    pub base: Option<String>,
143    /// Font family, as the font names it. Unset, text draws in the first font an export
144    /// registers.
145    #[serde(default, skip_serializing_if = "Option::is_none")]
146    pub font_family: Option<String>,
147    /// Text color.
148    #[serde(default, skip_serializing_if = "Option::is_none")]
149    pub text: Option<Rgba>,
150    /// The canvas background.
151    #[serde(default, skip_serializing_if = "Option::is_none")]
152    pub background: Option<Rgba>,
153    /// What title and end cards are drawn on.
154    #[serde(default, skip_serializing_if = "Option::is_none")]
155    pub surface: Option<Rgba>,
156    /// The boxes behind labels, lower thirds and boxed captions.
157    #[serde(default, skip_serializing_if = "Option::is_none")]
158    pub panel: Option<Rgba>,
159    /// A highlight: a lower third's bar.
160    #[serde(default, skip_serializing_if = "Option::is_none")]
161    pub accent: Option<Rgba>,
162    /// Title size.
163    #[serde(default, skip_serializing_if = "Option::is_none")]
164    pub title_size: Option<f32>,
165    /// Subtitle size.
166    #[serde(default, skip_serializing_if = "Option::is_none")]
167    pub subtitle_size: Option<f32>,
168    /// Body text size.
169    #[serde(default, skip_serializing_if = "Option::is_none")]
170    pub body_size: Option<f32>,
171    /// Caption size.
172    #[serde(default, skip_serializing_if = "Option::is_none")]
173    pub caption_size: Option<f32>,
174    /// Label size: a grid cell's.
175    #[serde(default, skip_serializing_if = "Option::is_none")]
176    pub label_size: Option<f32>,
177    /// The space kept clear at the canvas's edges.
178    #[serde(default, skip_serializing_if = "Option::is_none")]
179    pub margin: Option<f32>,
180    /// The transition a slideshow, or a sequence asking for `theme`, puts between children.
181    #[serde(default, skip_serializing_if = "Option::is_none")]
182    pub transition: Option<Transition>,
183    /// How long a still shows when nothing says, in seconds.
184    #[serde(default, skip_serializing_if = "Option::is_none")]
185    pub still_seconds: Option<f64>,
186    /// How long a card or text shows when nothing says, in seconds.
187    #[serde(default, skip_serializing_if = "Option::is_none")]
188    pub text_seconds: Option<f64>,
189    /// How long text and cards fade in and out, in seconds.
190    #[serde(default, skip_serializing_if = "Option::is_none")]
191    pub fade_seconds: Option<f64>,
192}
193
194/// The loudness an export normalizes to: a target, or a target and a ceiling.
195#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
196#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
197#[serde(untagged)]
198pub enum Loudness {
199    /// Integrated loudness in LUFS, under a -1 dBTP ceiling.
200    Lufs(f64),
201    /// Integrated loudness and a true-peak ceiling.
202    Target(crate::LoudnessTarget),
203}
204
205/// The transition between two neighbours of a sequence.
206#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
207#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
208#[serde(deny_unknown_fields)]
209pub struct Transition {
210    /// `crossfade`, a built-in transition's short name (`wipe-left`, `circle-open`, ...), or a
211    /// full effect id (`alpha2.transition.fade`).
212    #[serde(rename = "type")]
213    pub kind: String,
214    /// How long the neighbours overlap, in seconds.
215    pub duration: f64,
216    /// The timing curve. Default linear.
217    #[serde(default, skip_serializing_if = "Option::is_none")]
218    pub easing: Option<Easing>,
219    /// The effect's parameters by name.
220    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
221    pub params: BTreeMap<String, Animated<EffectValue>>,
222    /// The effect definition's version. Default 1.
223    #[serde(default, skip_serializing_if = "Option::is_none")]
224    pub version: Option<u32>,
225}
226
227/// A sequence's transitions: none, the theme's, or one given.
228#[derive(Clone, Debug, PartialEq, Serialize)]
229#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
230#[serde(untagged)]
231pub enum TransitionChoice {
232    /// `none` for cuts, `theme` for the theme's transition, or a transition name at the theme's
233    /// duration.
234    Named(String),
235    /// A transition.
236    Given(Transition),
237}
238
239/// Space kept clear inside an area.
240#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
241#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
242#[serde(untagged)]
243pub enum Inset {
244    /// The same on every side.
245    Uniform(f32),
246    /// `[top, right, bottom, left]`.
247    Sides([f32; 4]),
248}
249
250/// How a picture fills its area.
251#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
252#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
253#[serde(rename_all = "snake_case")]
254pub enum Fit {
255    /// All of it, as large as fits; the rest of the area stays empty.
256    #[default]
257    Contain,
258    /// All of the area, cropped to it.
259    Cover,
260    /// Stretched to the area.
261    Fill,
262    /// At its own size in pixels, cropped to the area.
263    None,
264}
265
266/// A point of an area: its center, an edge's middle or a corner.
267#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
268#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
269#[serde(rename_all = "kebab-case")]
270pub enum Align {
271    /// The center.
272    #[default]
273    Center,
274    /// The top edge's middle.
275    Top,
276    /// The bottom edge's middle.
277    Bottom,
278    /// The left edge's middle.
279    Left,
280    /// The right edge's middle.
281    Right,
282    /// The top-left corner.
283    TopLeft,
284    /// The top-right corner.
285    TopRight,
286    /// The bottom-left corner.
287    BottomLeft,
288    /// The bottom-right corner.
289    BottomRight,
290}
291
292/// What a media file holds, when its extension does not say.
293#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
294#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
295#[serde(rename_all = "snake_case")]
296pub enum FileKind {
297    /// Moving pictures, perhaps with sound.
298    Video,
299    /// A still picture.
300    Image,
301    /// Sound alone.
302    Audio,
303}
304
305/// What a video shorter than its node does once it ends.
306#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
307#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
308#[serde(rename_all = "snake_case")]
309pub enum WhenShort {
310    /// Holds its last frame.
311    Freeze,
312    /// Plays again from its start.
313    Loop,
314    /// Slows to fill the node.
315    Stretch,
316    /// Shows nothing.
317    Blank,
318    /// The spec does not compile.
319    Error,
320}
321
322/// What a video longer than its node does.
323#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
324#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
325#[serde(rename_all = "snake_case")]
326pub enum WhenLong {
327    /// Ends with the node.
328    Trim,
329    /// Speeds up to fit the node.
330    Stretch,
331    /// The spec does not compile.
332    Error,
333}
334
335/// One part of a video.
336#[derive(Clone, Debug, PartialEq, Serialize)]
337#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
338#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
339pub enum Node {
340    /// Children one after another, with transitions between them.
341    Sequence(Sequence),
342    /// Children over each other, each over the ones before.
343    Stack(Stack),
344    /// Children in the cells of a grid, row by row.
345    Grid(Grid),
346    /// A video or still file.
347    Media(Media),
348    /// Text.
349    Text(Text),
350    /// An area painted one color.
351    Color(ColorFill),
352    /// Timed text from cues, a SubRip or WebVTT file, or word timestamps.
353    Captions(Captions),
354    /// A layout generator: boxes, text and shapes laid out by CSS flexbox and grid.
355    Layout(Layout),
356    /// A sound file.
357    Audio(Audio),
358    /// Part of a project (sources, tracks, compositions) at its own times. Overlays only.
359    Raw(Raw),
360    /// Stills or clips in turn, with transitions and slow zooms.
361    Slideshow(Slideshow),
362    /// A video under its captions.
363    CaptionedVideo(CaptionedVideo),
364    /// Music under the video, faded in and out and ducked under speech.
365    MusicBed(MusicBed),
366    /// A number counting from one value to another, as text.
367    Counter(Counter),
368    /// Children drawn together into one picture, which then takes an opacity, a blend mode,
369    /// effects and a transform as one layer.
370    Group(Group),
371    /// Shapes drawn with one fill and one stroke: bars, frames, dividers, badges, icons.
372    Shape(Shape),
373    /// A node shown only where another node's picture is.
374    Matte(Matte),
375    /// A node shown only inside outlines.
376    Mask(Mask),
377    /// Boxes laid out by CSS flexbox or grid around text, shapes and any other node.
378    Box(BoxNode),
379}
380
381/// Children drawn together as one layer. Unlike a stack, whose children each meet what is under
382/// them, a group composites its children first: its opacity, blend mode, effects and transform
383/// apply to that one picture.
384///
385/// A group's children share its time as one picture does: a video or animated picture in it
386/// starts with the group and plays at its own speed, and it holds no sequences, captions or
387/// sound nodes. A child's sound still plays, outside the picture.
388#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
389#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
390#[serde(deny_unknown_fields)]
391pub struct Group {
392    /// The node's name, for other nodes to refer to.
393    #[serde(default, skip_serializing_if = "Option::is_none")]
394    pub id: Option<String>,
395    /// The children, each over the ones before, placed in the group's area.
396    pub children: Vec<Node>,
397    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
398    #[serde(default, skip_serializing_if = "Option::is_none")]
399    pub at: Option<f64>,
400    /// Length in seconds. Default: the longest child's.
401    #[serde(default, skip_serializing_if = "Option::is_none")]
402    pub duration: Option<f64>,
403    /// Pixels kept clear inside the parent's area: the group's area.
404    #[serde(default, skip_serializing_if = "Option::is_none")]
405    pub inset: Option<Inset>,
406    /// Opacity of the whole, 0..=1. Default 1.
407    #[serde(default, skip_serializing_if = "Option::is_none")]
408    pub opacity: Option<Anim<f32>>,
409    /// How the whole meets what is under it. Default `normal`.
410    #[serde(default, skip_serializing_if = "Option::is_none")]
411    pub blend: Option<alpha2_model::ClipBlendMode>,
412    /// Effects on the whole, in order, before its transform.
413    #[serde(default, skip_serializing_if = "Vec::is_empty")]
414    pub effects: Vec<EffectUse>,
415    /// Moves, scales or turns the whole.
416    #[serde(default, skip_serializing_if = "Option::is_none")]
417    pub transform: Option<GroupTransform>,
418    /// How it comes in at its start.
419    #[serde(default, skip_serializing_if = "Option::is_none")]
420    pub enter: Option<Motion>,
421    /// How it goes out, ending at its end.
422    #[serde(default, skip_serializing_if = "Option::is_none")]
423    pub exit: Option<Motion>,
424}
425
426/// One effect: a built-in by its short name (`gaussian-blur`) or any effect by its full id, with
427/// its parameters by name. A parameter is a constant, a ramp or keys; a named image input is a
428/// node.
429#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
430#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
431pub struct EffectUse {
432    /// The effect: a built-in's short name or a full id with its dots.
433    pub effect: String,
434    /// The version a full id names. Default: the built-in's, else 1.
435    #[serde(default, skip_serializing_if = "Option::is_none")]
436    pub version: Option<u32>,
437    /// Parameters and named inputs, as `schema/effects.v1.json` lists them.
438    #[serde(flatten)]
439    pub params: BTreeMap<String, serde_json::Value>,
440}
441
442/// A group's movement, about `anchor`.
443#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
444#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
445#[serde(deny_unknown_fields)]
446pub struct GroupTransform {
447    /// Offset in pixels, `[x, y]`. Default `[0, 0]`.
448    #[serde(default, skip_serializing_if = "Option::is_none")]
449    pub position: Option<Anim<[f32; 2]>>,
450    /// Size multiple. Default 1.
451    #[serde(default, skip_serializing_if = "Option::is_none")]
452    pub scale: Option<Anim<f32>>,
453    /// Clockwise turn in degrees. Default 0.
454    #[serde(default, skip_serializing_if = "Option::is_none")]
455    pub rotation: Option<Anim<f32>>,
456    /// The point it scales and turns about, `[0, 0]` the area's top left to `[1, 1]` its bottom
457    /// right. Default `[0.5, 0.5]`.
458    #[serde(default, skip_serializing_if = "Option::is_none")]
459    pub anchor: Option<[f32; 2]>,
460}
461
462/// Children one after another.
463#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
464#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
465#[serde(deny_unknown_fields)]
466pub struct Sequence {
467    /// The node's name, for other nodes to refer to.
468    #[serde(default, skip_serializing_if = "Option::is_none")]
469    pub id: Option<String>,
470    /// The children, in play order.
471    pub children: Vec<Node>,
472    /// What joins neighbours: a transition overlaps them by its duration, and their sound
473    /// crosses over it. Default `none`. Only single pictures (media, text, color, layout) can
474    /// transition into each other; anything else, or a part shorter than the transition,
475    /// joins by crossfade.
476    #[serde(default, skip_serializing_if = "Option::is_none")]
477    pub transition: Option<TransitionChoice>,
478    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
479    #[serde(default, skip_serializing_if = "Option::is_none")]
480    pub at: Option<f64>,
481    /// Length in seconds. Default: the node's own length, else what its parent gives it.
482    #[serde(default, skip_serializing_if = "Option::is_none")]
483    pub duration: Option<f64>,
484    /// How it comes in at its start.
485    #[serde(default, skip_serializing_if = "Option::is_none")]
486    pub enter: Option<Motion>,
487    /// How it goes out, ending at its end.
488    #[serde(default, skip_serializing_if = "Option::is_none")]
489    pub exit: Option<Motion>,
490}
491
492/// Children over each other.
493#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
494#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
495#[serde(deny_unknown_fields)]
496pub struct Stack {
497    /// The node's name, for other nodes to refer to.
498    #[serde(default, skip_serializing_if = "Option::is_none")]
499    pub id: Option<String>,
500    /// The children, each drawn over the ones before and starting at its own `at`.
501    pub children: Vec<Node>,
502    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
503    #[serde(default, skip_serializing_if = "Option::is_none")]
504    pub at: Option<f64>,
505    /// Length in seconds. Default: the node's own length, else what its parent gives it.
506    #[serde(default, skip_serializing_if = "Option::is_none")]
507    pub duration: Option<f64>,
508    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
509    #[serde(default, skip_serializing_if = "Option::is_none")]
510    pub inset: Option<Inset>,
511    /// How it comes in at its start.
512    #[serde(default, skip_serializing_if = "Option::is_none")]
513    pub enter: Option<Motion>,
514    /// How it goes out, ending at its end.
515    #[serde(default, skip_serializing_if = "Option::is_none")]
516    pub exit: Option<Motion>,
517    /// Seconds between the children's entrances. With it, the node's `enter` and `exit` move
518    /// each child rather than the whole, and child `i`'s entrance (its own `enter` too) starts
519    /// `i * stagger` after the child does.
520    #[serde(default, skip_serializing_if = "Option::is_none")]
521    pub stagger: Option<f64>,
522}
523
524/// Children in grid cells.
525#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
526#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
527#[serde(deny_unknown_fields)]
528pub struct Grid {
529    /// The node's name, for other nodes to refer to.
530    #[serde(default, skip_serializing_if = "Option::is_none")]
531    pub id: Option<String>,
532    /// The cells' contents, row by row.
533    pub children: Vec<Node>,
534    /// Columns. Default: as square a grid as the children make.
535    #[serde(default, skip_serializing_if = "Option::is_none")]
536    pub columns: Option<u32>,
537    /// Pixels between cells.
538    #[serde(default)]
539    pub gap: f32,
540    /// How long the grid lasts when its cells differ, and what a cell that ends early shows.
541    /// Default `shortest`.
542    #[serde(default)]
543    pub length: GridLength,
544    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
545    #[serde(default, skip_serializing_if = "Option::is_none")]
546    pub at: Option<f64>,
547    /// Length in seconds. Default: the node's own length, else what its parent gives it.
548    #[serde(default, skip_serializing_if = "Option::is_none")]
549    pub duration: Option<f64>,
550    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
551    #[serde(default, skip_serializing_if = "Option::is_none")]
552    pub inset: Option<Inset>,
553    /// How it comes in at its start.
554    #[serde(default, skip_serializing_if = "Option::is_none")]
555    pub enter: Option<Motion>,
556    /// How it goes out, ending at its end.
557    #[serde(default, skip_serializing_if = "Option::is_none")]
558    pub exit: Option<Motion>,
559    /// Seconds between the children's entrances. With it, the node's `enter` and `exit` move
560    /// each child rather than the whole, and child `i`'s entrance (its own `enter` too) starts
561    /// `i * stagger` after the child does.
562    #[serde(default, skip_serializing_if = "Option::is_none")]
563    pub stagger: Option<f64>,
564}
565
566/// How long a grid of clips of different lengths lasts.
567#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
568#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
569#[serde(rename_all = "snake_case")]
570pub enum GridLength {
571    /// As long as its shortest cell.
572    #[default]
573    Shortest,
574    /// As long as its longest; shorter clips hold their last frame.
575    LongestFreeze,
576    /// As long as its longest; shorter clips play again from their start.
577    LongestLoop,
578}
579
580/// A video or still file.
581#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
582#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
583#[serde(deny_unknown_fields)]
584pub struct Media {
585    /// The node's name, for other nodes to refer to.
586    #[serde(default, skip_serializing_if = "Option::is_none")]
587    pub id: Option<String>,
588    /// The file. It becomes the source's locator and the export's asset.
589    pub path: String,
590    /// What the file holds. Default: by its extension.
591    #[serde(default, skip_serializing_if = "Option::is_none")]
592    pub kind: Option<FileKind>,
593    /// Where in the file a video starts, in seconds.
594    #[serde(default, skip_serializing_if = "Option::is_none")]
595    pub trim_start: Option<f64>,
596    /// Where in the file a video ends, in seconds. Default: its end.
597    #[serde(default, skip_serializing_if = "Option::is_none")]
598    pub trim_end: Option<f64>,
599    /// Playback speed of a video: 2 plays it twice as fast. Default 1. A video that loops takes
600    /// only speed 1.
601    #[serde(default, skip_serializing_if = "Option::is_none")]
602    pub speed: Option<f64>,
603    /// Keeps a video's sound at its pitch when `speed` is not 1 (time-stretched instead of
604    /// resampled). Default true.
605    #[serde(default, skip_serializing_if = "Option::is_none")]
606    pub preserve_pitch: Option<bool>,
607    /// Plays a video again from its start while the node lasts. Its `speed` must be 1.
608    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
609    pub r#loop: bool,
610    /// What a video does when the node outlasts it. Default: what its parent asks (a grid's
611    /// length rule), else `freeze`.
612    #[serde(default, skip_serializing_if = "Option::is_none")]
613    pub when_short: Option<WhenShort>,
614    /// What a video does when it outlasts the node. Default `trim`.
615    #[serde(default, skip_serializing_if = "Option::is_none")]
616    pub when_long: Option<WhenLong>,
617    /// Linear gain of a video's sound. Default 1.
618    #[serde(default, skip_serializing_if = "Option::is_none")]
619    pub volume: Option<f32>,
620    /// Silences a video's sound.
621    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
622    pub muted: bool,
623    /// Opacity, 0..=1. Default 1.
624    #[serde(default, skip_serializing_if = "Option::is_none")]
625    pub opacity: Option<f32>,
626    /// Seconds of fade in from transparent.
627    #[serde(default, skip_serializing_if = "Option::is_none")]
628    pub fade_in: Option<f64>,
629    /// Seconds of fade out to transparent.
630    #[serde(default, skip_serializing_if = "Option::is_none")]
631    pub fade_out: Option<f64>,
632    /// How large it shows, as a multiple of its fitted size: a constant, a ramp
633    /// (`{"from": 1, "to": 1.2}` is a slow zoom over the node), or keys. Default 1.
634    #[serde(default, skip_serializing_if = "Option::is_none")]
635    pub zoom: Option<Anim<f32>>,
636    /// A Gaussian blur's radius, as a fraction of the picture's shorter side.
637    #[serde(default, skip_serializing_if = "Option::is_none")]
638    pub blur: Option<f32>,
639    /// A label a comparison grid shows on the cell.
640    #[serde(default, skip_serializing_if = "Option::is_none")]
641    pub label: Option<String>,
642    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
643    #[serde(default, skip_serializing_if = "Option::is_none")]
644    pub at: Option<f64>,
645    /// Length in seconds. Default: the node's own length, else what its parent gives it.
646    #[serde(default, skip_serializing_if = "Option::is_none")]
647    pub duration: Option<f64>,
648    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
649    #[serde(default, skip_serializing_if = "Option::is_none")]
650    pub inset: Option<Inset>,
651    /// How a picture fills its area. Default `contain`.
652    #[serde(default, skip_serializing_if = "Option::is_none")]
653    pub fit: Option<Fit>,
654    /// Where in its area the picture or text lies. Default `center`.
655    #[serde(default, skip_serializing_if = "Option::is_none")]
656    pub align: Option<Align>,
657    /// How it comes in at its start.
658    #[serde(default, skip_serializing_if = "Option::is_none")]
659    pub enter: Option<Motion>,
660    /// How it goes out, ending at its end.
661    #[serde(default, skip_serializing_if = "Option::is_none")]
662    pub exit: Option<Motion>,
663}
664
665impl Media {
666    /// A node of the file at `path`, everything else by default.
667    #[must_use]
668    pub fn new(path: impl Into<String>) -> Self {
669        Self {
670            id: None,
671            path: path.into(),
672            kind: None,
673            trim_start: None,
674            trim_end: None,
675            speed: None,
676            preserve_pitch: None,
677            r#loop: false,
678            volume: None,
679            muted: false,
680            opacity: None,
681            fade_in: None,
682            fade_out: None,
683            zoom: None,
684            when_short: None,
685            when_long: None,
686            blur: None,
687            label: None,
688            at: None,
689            duration: None,
690            inset: None,
691            fit: None,
692            align: None,
693            enter: None,
694            exit: None,
695        }
696    }
697}
698
699/// A file given by its path alone, or a media node.
700#[derive(Clone, Debug, PartialEq, Serialize)]
701#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
702#[serde(untagged)]
703pub enum MediaItem {
704    /// The file, everything else by default.
705    Path(String),
706    /// A `media` node.
707    Node(Box<Node>),
708}
709
710/// Text in one of the theme's styles.
711#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
712#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
713#[serde(deny_unknown_fields)]
714pub struct Text {
715    /// The node's name, for other nodes to refer to.
716    #[serde(default, skip_serializing_if = "Option::is_none")]
717    pub id: Option<String>,
718    /// The text; `\n` starts a line.
719    pub text: String,
720    /// The theme style it starts from. Default `body`.
721    #[serde(default)]
722    pub style: TextRole,
723    /// Font size in pixels, or a theme length. Default: the style's.
724    #[serde(default, skip_serializing_if = "Option::is_none")]
725    pub font_size: Option<Size>,
726    /// Family. Default: the theme's.
727    #[serde(default, skip_serializing_if = "Option::is_none")]
728    pub font_family: Option<String>,
729    /// Color. Default: the theme's text color.
730    #[serde(default, skip_serializing_if = "Option::is_none")]
731    pub color: Option<SolidColor>,
732    /// A box of this color behind each line.
733    #[serde(default, skip_serializing_if = "Option::is_none")]
734    pub background: Option<SolidColor>,
735    /// Bands around the glyphs, innermost first, widths as fractions of the font size (as a
736    /// text style's `strokes`).
737    #[serde(default, skip_serializing_if = "Vec::is_empty")]
738    pub strokes: Vec<TextStroke>,
739    /// Shadows of the glyphs, the first on top, lengths as fractions of the font size (as a
740    /// text style's `shadows`).
741    #[serde(default, skip_serializing_if = "Vec::is_empty")]
742    pub shadows: Vec<TextShadow>,
743    /// The most lines it may take. It first shrinks within `fit`; text still longer is cut after
744    /// its last line, ended by `ellipsis`. Default: no limit.
745    #[serde(default, skip_serializing_if = "Option::is_none")]
746    pub max_lines: Option<u32>,
747    /// The font sizes in pixels it is fitted between, the largest at which it fits its area and
748    /// `max_lines`. Default with `max_lines`: 0.3 times its font size up to its font size;
749    /// otherwise its font size alone.
750    #[serde(default, skip_serializing_if = "Option::is_none")]
751    pub fit: Option<TextFit>,
752    /// What ends a line `max_lines` cuts: `true` an ellipsis, `false` nothing, or this text.
753    /// Default `true`.
754    #[serde(default, skip_serializing_if = "Option::is_none")]
755    pub ellipsis: Option<Ellipsis>,
756    /// Opacity, 0..=1. Default 1.
757    #[serde(default, skip_serializing_if = "Option::is_none")]
758    pub opacity: Option<f32>,
759    /// Seconds of fade in and out. Default none.
760    #[serde(default, skip_serializing_if = "Option::is_none")]
761    pub fade: Option<f64>,
762    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
763    #[serde(default, skip_serializing_if = "Option::is_none")]
764    pub at: Option<f64>,
765    /// Length in seconds. Default: the node's own length, else what its parent gives it.
766    #[serde(default, skip_serializing_if = "Option::is_none")]
767    pub duration: Option<f64>,
768    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
769    #[serde(default, skip_serializing_if = "Option::is_none")]
770    pub inset: Option<Inset>,
771    /// Where in its area the picture or text lies. Default `center`.
772    #[serde(default, skip_serializing_if = "Option::is_none")]
773    pub align: Option<Align>,
774    /// How it comes in at its start.
775    #[serde(default, skip_serializing_if = "Option::is_none")]
776    pub enter: Option<Motion>,
777    /// How it goes out, ending at its end.
778    #[serde(default, skip_serializing_if = "Option::is_none")]
779    pub exit: Option<Motion>,
780    /// Reveals the text a word or a line at a time.
781    #[serde(default, skip_serializing_if = "Option::is_none")]
782    pub reveal: Option<Reveal>,
783}
784
785/// The font sizes a text is fitted between, in pixels.
786#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
787#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
788#[serde(deny_unknown_fields)]
789pub struct TextFit {
790    /// Smallest font size; when nothing larger fits, the text draws at this size.
791    pub min: f32,
792    /// Largest font size. Default: the text's font size, so it only shrinks.
793    #[serde(default, skip_serializing_if = "Option::is_none")]
794    pub max: Option<f32>,
795}
796
797/// What ends a cut line: an ellipsis or nothing (`true`, `false`), or a text.
798#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
799#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
800#[serde(untagged)]
801pub enum Ellipsis {
802    /// An ellipsis, or nothing.
803    Shown(bool),
804    /// This text, 1 to 64 bytes without line breaks or control characters.
805    Text(String),
806}
807
808/// A theme text style.
809#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
810#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
811#[serde(rename_all = "snake_case")]
812pub enum TextRole {
813    /// The largest.
814    Title,
815    /// Under a title.
816    Subtitle,
817    /// Running text.
818    #[default]
819    Body,
820    /// A cell's label.
821    Label,
822}
823
824/// Shapes in the node's area, filled and stroked as one compound path. Coordinates are fractions
825/// of the area, `[0, 0]` its top left to `[1, 1]` its bottom right; lengths are fractions of its
826/// shorter side.
827#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
828#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
829#[serde(deny_unknown_fields)]
830pub struct Shape {
831    /// The node's name, for other nodes to refer to.
832    #[serde(default, skip_serializing_if = "Option::is_none")]
833    pub id: Option<String>,
834    /// The outlines, at least one.
835    pub shapes: Vec<Geometry>,
836    /// What covers their inside. Default: nothing, unless there is no stroke, then the theme's
837    /// accent.
838    #[serde(default, skip_serializing_if = "Option::is_none")]
839    pub fill: Option<PaintChoice>,
840    /// A line along the outlines.
841    #[serde(default, skip_serializing_if = "Option::is_none")]
842    pub stroke: Option<Stroke>,
843    /// Keeps part of the outlines' length. A line that draws itself has
844    /// `{"end": {"from": 0, "to": 1}}`.
845    #[serde(default, skip_serializing_if = "Option::is_none")]
846    pub trim: Option<Trim>,
847    /// Opacity, 0..=1. Default 1.
848    #[serde(default, skip_serializing_if = "Option::is_none")]
849    pub opacity: Option<f32>,
850    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
851    #[serde(default, skip_serializing_if = "Option::is_none")]
852    pub at: Option<f64>,
853    /// Length in seconds. Default: what its parent gives it.
854    #[serde(default, skip_serializing_if = "Option::is_none")]
855    pub duration: Option<f64>,
856    /// Pixels kept clear inside the parent's area: the shapes' area.
857    #[serde(default, skip_serializing_if = "Option::is_none")]
858    pub inset: Option<Inset>,
859    /// How it comes in at its start.
860    #[serde(default, skip_serializing_if = "Option::is_none")]
861    pub enter: Option<Motion>,
862    /// How it goes out, ending at its end.
863    #[serde(default, skip_serializing_if = "Option::is_none")]
864    pub exit: Option<Motion>,
865}
866
867/// `content` shown where `by`'s picture is: by its alpha (text as a window onto video) or its
868/// luminance. `by` is never drawn itself. Both are placed in the node's area.
869#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
870#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
871#[serde(deny_unknown_fields)]
872pub struct Matte {
873    /// The node's name, for other nodes to refer to.
874    #[serde(default, skip_serializing_if = "Option::is_none")]
875    pub id: Option<String>,
876    /// What is shown.
877    pub content: Box<Node>,
878    /// Where it is shown. One picture: not a sequence.
879    pub by: Box<Node>,
880    /// What of `by` counts: `alpha` (default) or `luma`.
881    #[serde(rename = "use", default, skip_serializing_if = "Option::is_none")]
882    pub uses: Option<MatteUse>,
883    /// Shows `content` where `by` is not instead.
884    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
885    pub invert: bool,
886    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
887    #[serde(default, skip_serializing_if = "Option::is_none")]
888    pub at: Option<f64>,
889    /// Length in seconds. Default: the content's.
890    #[serde(default, skip_serializing_if = "Option::is_none")]
891    pub duration: Option<f64>,
892    /// Pixels kept clear inside the parent's area.
893    #[serde(default, skip_serializing_if = "Option::is_none")]
894    pub inset: Option<Inset>,
895}
896
897/// What of a matte's picture is coverage.
898#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
899#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
900#[serde(rename_all = "snake_case")]
901pub enum MatteUse {
902    /// Its opacity.
903    #[default]
904    Alpha,
905    /// Its brightness.
906    Luma,
907}
908
909/// `content` shown only inside outlines, combined in order. Outlines are in the node's area as a
910/// shape's are, and stay put while the content moves.
911#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
912#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
913#[serde(deny_unknown_fields)]
914pub struct Mask {
915    /// The node's name, for other nodes to refer to.
916    #[serde(default, skip_serializing_if = "Option::is_none")]
917    pub id: Option<String>,
918    /// What is shown.
919    pub content: Box<Node>,
920    /// The outlines, at least one.
921    pub shapes: Vec<MaskShape>,
922    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
923    #[serde(default, skip_serializing_if = "Option::is_none")]
924    pub at: Option<f64>,
925    /// Length in seconds. Default: the content's.
926    #[serde(default, skip_serializing_if = "Option::is_none")]
927    pub duration: Option<f64>,
928    /// Pixels kept clear inside the parent's area.
929    #[serde(default, skip_serializing_if = "Option::is_none")]
930    pub inset: Option<Inset>,
931}
932
933/// One mask outline and how it combines with those before it.
934#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
935#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
936pub struct MaskShape {
937    /// The outline.
938    #[serde(flatten)]
939    pub geometry: Geometry,
940    /// `add` (default; the first adds to nothing), `subtract` or `intersect`.
941    #[serde(default, skip_serializing_if = "Option::is_none")]
942    pub mode: Option<alpha2_model::MaskMode>,
943    /// Edge softness, as a fraction of the area's shorter side. Default 0.
944    #[serde(default, skip_serializing_if = "Option::is_none")]
945    pub feather: Option<Anim<f32>>,
946    /// Keeps the outside of the outline instead.
947    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
948    pub invert: bool,
949}
950
951/// A box laid out by CSS flexbox (the default) or grid, filling the node's area. Its fields are
952/// the engine layout's container fields as CSS writes them (`flex_direction`, `gap`,
953/// `"8px 16px"` paddings, `"repeat(3, 1fr)"` tracks); `background` and `border` take theme
954/// colors.
955///
956/// Text, shapes, colors and boxes among its children are drawn by the layout itself. Any other
957/// child (a video, a group, a sequence) gets a place in the layout and is drawn there, clipped to
958/// its rounded corners; such a place keeps still.
959#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
960#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
961pub struct BoxNode {
962    /// The node's name, for other nodes to refer to.
963    #[serde(default, skip_serializing_if = "Option::is_none")]
964    pub id: Option<String>,
965    /// The children, in paint order.
966    #[serde(default, skip_serializing_if = "Vec::is_empty")]
967    pub children: Vec<BoxChild>,
968    /// What covers the box, rounded by `border_radius`.
969    #[serde(default, skip_serializing_if = "Option::is_none")]
970    pub background: Option<PaintChoice>,
971    /// A border inside the box.
972    #[serde(default, skip_serializing_if = "Option::is_none")]
973    pub border: Option<BoxBorder>,
974    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
975    #[serde(default, skip_serializing_if = "Option::is_none")]
976    pub at: Option<f64>,
977    /// Length in seconds. Default: the longest picture child's, else what its parent gives it.
978    #[serde(default, skip_serializing_if = "Option::is_none")]
979    pub duration: Option<f64>,
980    /// Pixels kept clear inside the parent's area. A nested box places itself by its item fields.
981    #[serde(default, skip_serializing_if = "Option::is_none")]
982    pub inset: Option<Inset>,
983    /// The other container fields of an engine layout box, by name. A length may be a theme
984    /// length, `{"$theme": "margin", "scale": 2}`: `margin`, `title_size`, `subtitle_size`,
985    /// `body_size`, `caption_size` or `label_size`, times `scale` (default 1).
986    #[serde(flatten)]
987    pub css: BTreeMap<String, serde_json::Value>,
988}
989
990/// A box border.
991#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
992#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
993#[serde(deny_unknown_fields)]
994pub struct BoxBorder {
995    /// Width, as a layout size: a fraction of the picture's shorter side or `"<n>px"`.
996    pub width: LayoutSize,
997    /// What covers it.
998    pub paint: PaintChoice,
999}
1000
1001/// A layout size: a number is a fraction of the picture's shorter side, `"<n>px"` canvas pixels.
1002#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1003#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1004#[serde(untagged)]
1005pub enum LayoutSize {
1006    /// A fraction of the picture's shorter side.
1007    Fraction(f32),
1008    /// Pixels, `"<n>px"`.
1009    Pixels(String),
1010}
1011
1012/// A box's child: a node, or `{"box": item fields, "node": node}` when it has item fields (size,
1013/// flex or grid placement, `aspect_ratio`, `border_radius`, `margin`).
1014#[derive(Clone, Debug, PartialEq, Serialize)]
1015#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1016#[serde(untagged)]
1017pub enum BoxChild {
1018    /// A node with its item fields.
1019    Placed(PlacedChild),
1020    /// A node.
1021    Plain(Node),
1022}
1023
1024/// A box child with item fields.
1025#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1026#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1027#[serde(deny_unknown_fields)]
1028pub struct PlacedChild {
1029    /// Item fields of an engine layout box, as it writes them; lengths may be theme lengths.
1030    #[serde(rename = "box")]
1031    pub item: BTreeMap<String, serde_json::Value>,
1032    /// The node.
1033    pub node: Node,
1034}
1035
1036impl BoxChild {
1037    /// The node.
1038    #[must_use]
1039    pub const fn node(&self) -> &Node {
1040        match self {
1041            Self::Placed(placed) => &placed.node,
1042            Self::Plain(node) => node,
1043        }
1044    }
1045
1046    /// Its item fields; none for a plain node.
1047    #[must_use]
1048    pub fn item(&self) -> BTreeMap<String, serde_json::Value> {
1049        match self {
1050            Self::Placed(placed) => placed.item.clone(),
1051            Self::Plain(_) => BTreeMap::new(),
1052        }
1053    }
1054}
1055
1056impl<'de> Deserialize<'de> for BoxChild {
1057    // An object with `node` is a placed child; anything else is a node, so a node's own errors
1058    // are reported as they are.
1059    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1060        use serde::de::Error as _;
1061        let value = serde_json::Value::deserialize(deserializer)?;
1062        if value
1063            .as_object()
1064            .is_some_and(|object| object.contains_key("node"))
1065        {
1066            serde_json::from_value(value)
1067                .map(Self::Placed)
1068                .map_err(D::Error::custom)
1069        } else {
1070            Node::deserialize(value)
1071                .map(Self::Plain)
1072                .map_err(D::Error::custom)
1073        }
1074    }
1075}
1076
1077/// One outline, in its area's unit square. Masks take the same outlines.
1078#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1079#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1080#[serde(tag = "shape", rename_all = "snake_case", deny_unknown_fields)]
1081pub enum Geometry {
1082    /// A rectangle, optionally with rounded corners.
1083    Rect {
1084        /// Centre. Default `[0.5, 0.5]`.
1085        #[serde(default, skip_serializing_if = "Option::is_none")]
1086        center: Option<Anim<[f32; 2]>>,
1087        /// Width and height. Default `[1, 1]`.
1088        #[serde(default, skip_serializing_if = "Option::is_none")]
1089        size: Option<Anim<[f32; 2]>>,
1090        /// Corner radius. Default 0.
1091        #[serde(default, skip_serializing_if = "Option::is_none")]
1092        corner_radius: Option<Anim<f32>>,
1093        /// Clockwise turn in degrees. Default 0.
1094        #[serde(default, skip_serializing_if = "Option::is_none")]
1095        rotation: Option<Anim<f32>>,
1096    },
1097    /// An ellipse.
1098    Ellipse {
1099        /// Centre. Default `[0.5, 0.5]`.
1100        #[serde(default, skip_serializing_if = "Option::is_none")]
1101        center: Option<Anim<[f32; 2]>>,
1102        /// Width and height. Default `[1, 1]`.
1103        #[serde(default, skip_serializing_if = "Option::is_none")]
1104        size: Option<Anim<[f32; 2]>>,
1105        /// Clockwise turn in degrees. Default 0.
1106        #[serde(default, skip_serializing_if = "Option::is_none")]
1107        rotation: Option<Anim<f32>>,
1108    },
1109    /// A regular polygon.
1110    Polygon {
1111        /// Centre. Default `[0.5, 0.5]`.
1112        #[serde(default, skip_serializing_if = "Option::is_none")]
1113        center: Option<Anim<[f32; 2]>>,
1114        /// Corners, 3 or more.
1115        points: u32,
1116        /// Distance of the corners from the centre. Default 0.5.
1117        #[serde(default, skip_serializing_if = "Option::is_none")]
1118        radius: Option<Anim<f32>>,
1119        /// How round the corners are, 0..=1. Default 0.
1120        #[serde(default, skip_serializing_if = "Option::is_none")]
1121        roundness: Option<Anim<f32>>,
1122        /// Clockwise turn in degrees. Default 0.
1123        #[serde(default, skip_serializing_if = "Option::is_none")]
1124        rotation: Option<Anim<f32>>,
1125    },
1126    /// A star.
1127    Star {
1128        /// Centre. Default `[0.5, 0.5]`.
1129        #[serde(default, skip_serializing_if = "Option::is_none")]
1130        center: Option<Anim<[f32; 2]>>,
1131        /// Tips, 3 or more.
1132        points: u32,
1133        /// Distance of the tips from the centre. Default 0.5.
1134        #[serde(default, skip_serializing_if = "Option::is_none")]
1135        outer_radius: Option<Anim<f32>>,
1136        /// Distance of the inner corners from the centre. Default 0.25.
1137        #[serde(default, skip_serializing_if = "Option::is_none")]
1138        inner_radius: Option<Anim<f32>>,
1139        /// Clockwise turn in degrees. Default 0.
1140        #[serde(default, skip_serializing_if = "Option::is_none")]
1141        rotation: Option<Anim<f32>>,
1142    },
1143    /// An outline as SVG path data (`d`), in the area's unit square.
1144    Path {
1145        /// The path data: `M`, `L`, `H`, `V`, `C`, `S`, `Q`, `T`, `A` and `Z`, absolute or
1146        /// relative.
1147        d: String,
1148    },
1149}
1150
1151/// A color, a theme color, or a gradient.
1152#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1153#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1154#[serde(untagged)]
1155pub enum PaintChoice {
1156    /// A theme color by name.
1157    Theme(ThemeColor),
1158    /// Colors along a line across the area.
1159    Linear(LinearPaint),
1160    /// Colors out from a point.
1161    Radial(RadialPaint),
1162    /// Colors around a point.
1163    Conic(ConicPaint),
1164    /// One color: CSS hex or the project's color object.
1165    Color(Rgba),
1166}
1167
1168/// `{"linear": gradient}`.
1169#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1170#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1171#[serde(deny_unknown_fields)]
1172pub struct LinearPaint {
1173    /// The gradient.
1174    pub linear: Gradient,
1175}
1176
1177/// `{"radial": gradient}`.
1178#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1179#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1180#[serde(deny_unknown_fields)]
1181pub struct RadialPaint {
1182    /// The gradient.
1183    pub radial: Gradient,
1184}
1185
1186/// `{"conic": gradient}`.
1187#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1188#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1189#[serde(deny_unknown_fields)]
1190pub struct ConicPaint {
1191    /// The gradient.
1192    pub conic: Gradient,
1193}
1194
1195/// Where the compose schema is published.
1196pub const COMPOSE_SCHEMA_ID: &str = "https://alpha2.sh/schema/compose.v1.json";
1197
1198/// A size in pixels, or one of the theme's lengths.
1199#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
1200#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1201#[serde(untagged)]
1202pub enum Size {
1203    /// Pixels of the canvas.
1204    Pixels(f32),
1205    /// A theme length.
1206    Theme(ThemeLength),
1207}
1208
1209/// One of the theme's lengths times `scale`, as a fraction of the picture's shorter side.
1210#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
1211#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1212#[serde(deny_unknown_fields)]
1213pub struct ThemeLength {
1214    /// Which of the theme's lengths.
1215    #[serde(rename = "$theme")]
1216    pub token: LengthToken,
1217    /// What it is multiplied by. Default 1.
1218    #[serde(default, skip_serializing_if = "Option::is_none")]
1219    pub scale: Option<f32>,
1220}
1221
1222/// A theme's named lengths.
1223#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1224#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1225#[serde(rename_all = "snake_case")]
1226pub enum LengthToken {
1227    /// Space kept from the edges.
1228    Margin,
1229    /// The title style's font size.
1230    TitleSize,
1231    /// The subtitle style's font size.
1232    SubtitleSize,
1233    /// The body style's font size.
1234    BodySize,
1235    /// Captions' font size.
1236    CaptionSize,
1237    /// The label style's font size.
1238    LabelSize,
1239}
1240
1241/// A theme color, so a design follows whatever theme it is drawn with.
1242#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
1243#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1244#[serde(deny_unknown_fields)]
1245pub struct ThemeColor {
1246    /// Which of the theme's colors.
1247    #[serde(rename = "$theme")]
1248    pub token: ThemeToken,
1249    /// Opacity multiplied into it, 0..=1. Default 1.
1250    #[serde(default, skip_serializing_if = "Option::is_none")]
1251    pub alpha: Option<f32>,
1252}
1253
1254/// A theme's named colors.
1255#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1256#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1257#[serde(rename_all = "snake_case")]
1258pub enum ThemeToken {
1259    /// Text.
1260    Text,
1261    /// The canvas behind everything.
1262    Background,
1263    /// Cards and title cards.
1264    Surface,
1265    /// Bars behind text.
1266    Panel,
1267    /// Highlights.
1268    Accent,
1269}
1270
1271/// Colors spread over a gradient.
1272#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1273#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1274#[serde(deny_unknown_fields)]
1275pub struct Gradient {
1276    /// Two or more colors, evenly spaced unless each says its `offset` in 0..=1.
1277    pub stops: Vec<Stop>,
1278    /// A linear gradient's direction in degrees, as CSS: 0 upward, 90 rightward. A conic one's
1279    /// start. Default 180 for linear (downward), 0 for conic.
1280    #[serde(default, skip_serializing_if = "Option::is_none")]
1281    pub angle: Option<f32>,
1282    /// A radial or conic gradient's centre. Default `[0.5, 0.5]`.
1283    #[serde(default, skip_serializing_if = "Option::is_none")]
1284    pub center: Option<[f32; 2]>,
1285    /// A radial gradient's radius. Default 0.5.
1286    #[serde(default, skip_serializing_if = "Option::is_none")]
1287    pub radius: Option<f32>,
1288}
1289
1290/// One gradient color.
1291#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1292#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1293#[serde(untagged)]
1294pub enum Stop {
1295    /// A color at a set position.
1296    At(OffsetStop),
1297    /// A color, spaced evenly with the others.
1298    Even(SolidColor),
1299}
1300
1301/// A gradient color at a set position.
1302#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1303#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1304#[serde(deny_unknown_fields)]
1305pub struct OffsetStop {
1306    /// The color.
1307    pub color: SolidColor,
1308    /// Where along the gradient, 0..=1.
1309    pub offset: f32,
1310}
1311
1312/// One color: a theme color, CSS hex, or the project's color object.
1313#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
1314#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1315#[serde(untagged)]
1316pub enum SolidColor {
1317    /// A theme color by name.
1318    Theme(ThemeColor),
1319    /// CSS hex or the color object.
1320    Color(Rgba),
1321}
1322
1323/// A line along outlines.
1324#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1325#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1326#[serde(deny_unknown_fields)]
1327pub struct Stroke {
1328    /// What covers it. Default: the theme's text color.
1329    #[serde(default, skip_serializing_if = "Option::is_none")]
1330    pub paint: Option<PaintChoice>,
1331    /// Width, as a fraction of the area's shorter side.
1332    pub width: Anim<f32>,
1333    /// Dash and gap lengths, as fractions of the area's shorter side. Default: solid.
1334    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1335    pub dash: Vec<f32>,
1336    /// How open ends look. Default `butt`.
1337    #[serde(default, skip_serializing_if = "Option::is_none")]
1338    pub cap: Option<alpha2_model::LineCap>,
1339    /// How segments meet. Default `miter`.
1340    #[serde(default, skip_serializing_if = "Option::is_none")]
1341    pub join: Option<alpha2_model::LineJoin>,
1342}
1343
1344/// The part of outlines' length that is kept, from `start` to `end`, shifted by `offset` turns.
1345#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
1346#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1347#[serde(deny_unknown_fields)]
1348pub struct Trim {
1349    /// Default 0.
1350    #[serde(default, skip_serializing_if = "Option::is_none")]
1351    pub start: Option<Anim<f32>>,
1352    /// Default 1.
1353    #[serde(default, skip_serializing_if = "Option::is_none")]
1354    pub end: Option<Anim<f32>>,
1355    /// Default 0.
1356    #[serde(default, skip_serializing_if = "Option::is_none")]
1357    pub offset: Option<Anim<f32>>,
1358}
1359
1360/// An area painted one color.
1361#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1362#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1363#[serde(deny_unknown_fields)]
1364pub struct ColorFill {
1365    /// The node's name, for other nodes to refer to.
1366    #[serde(default, skip_serializing_if = "Option::is_none")]
1367    pub id: Option<String>,
1368    /// The color. Default: the theme's surface.
1369    #[serde(default, skip_serializing_if = "Option::is_none")]
1370    pub color: Option<SolidColor>,
1371    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1372    #[serde(default, skip_serializing_if = "Option::is_none")]
1373    pub at: Option<f64>,
1374    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1375    #[serde(default, skip_serializing_if = "Option::is_none")]
1376    pub duration: Option<f64>,
1377    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
1378    #[serde(default, skip_serializing_if = "Option::is_none")]
1379    pub inset: Option<Inset>,
1380    /// How it comes in at its start.
1381    #[serde(default, skip_serializing_if = "Option::is_none")]
1382    pub enter: Option<Motion>,
1383    /// How it goes out, ending at its end.
1384    #[serde(default, skip_serializing_if = "Option::is_none")]
1385    pub exit: Option<Motion>,
1386}
1387
1388/// Timed text.
1389#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1390#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1391#[cfg_attr(feature = "schema", schemars(rename = "CaptionsNode"))]
1392#[serde(deny_unknown_fields)]
1393pub struct Captions {
1394    /// The node's name, for other nodes to refer to.
1395    #[serde(default, skip_serializing_if = "Option::is_none")]
1396    pub id: Option<String>,
1397    /// Cues as given, in seconds from the node's start.
1398    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1399    pub cues: Vec<Cue>,
1400    /// Words with their times, as speech recognition gives them, grouped into cues of up to
1401    /// `max_chars` characters.
1402    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1403    pub words: Vec<Cue>,
1404    /// A SubRip (`.srt`) or WebVTT (`.vtt`) file, read by the binding.
1405    #[serde(default, skip_serializing_if = "Option::is_none")]
1406    pub file: Option<String>,
1407    /// SubRip text.
1408    #[serde(default, skip_serializing_if = "Option::is_none")]
1409    pub srt: Option<String>,
1410    /// WebVTT text.
1411    #[serde(default, skip_serializing_if = "Option::is_none")]
1412    pub vtt: Option<String>,
1413    /// How the captions look. Default `outline`.
1414    #[serde(default)]
1415    pub style: CaptionStyle,
1416    /// The longest cue words are grouped into, in characters. Default 32 on a tall canvas, 42
1417    /// on a wide one.
1418    #[serde(default, skip_serializing_if = "Option::is_none")]
1419    pub max_chars: Option<u32>,
1420    /// Font size in pixels. Default: the theme's caption size.
1421    #[serde(default, skip_serializing_if = "Option::is_none")]
1422    pub font_size: Option<Size>,
1423    /// Text color. Default: the theme's.
1424    #[serde(default, skip_serializing_if = "Option::is_none")]
1425    pub color: Option<SolidColor>,
1426    /// The color `karaoke` and `pop` give the word being said. Default: the theme's accent.
1427    #[serde(default, skip_serializing_if = "Option::is_none")]
1428    pub highlight: Option<SolidColor>,
1429    /// Each speaker's look, keyed by a WebVTT voice or a cue's `speaker`; it overrides the
1430    /// style.
1431    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
1432    pub speakers: BTreeMap<String, SpeakerLook>,
1433    /// Where the text's middle lies, as a fraction of the canvas height. Default depends on the
1434    /// style and the canvas's shape.
1435    #[serde(default, skip_serializing_if = "Option::is_none")]
1436    pub position: Option<f32>,
1437    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1438    #[serde(default, skip_serializing_if = "Option::is_none")]
1439    pub at: Option<f64>,
1440    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1441    #[serde(default, skip_serializing_if = "Option::is_none")]
1442    pub duration: Option<f64>,
1443}
1444
1445/// Text over an interval.
1446#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1447#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1448#[serde(deny_unknown_fields)]
1449pub struct Cue {
1450    /// Start in seconds.
1451    pub start: f64,
1452    /// End in seconds.
1453    pub end: f64,
1454    /// The text.
1455    pub text: String,
1456    /// Who says it: a key of the captions' `speakers` gives the cue its look.
1457    #[serde(default, skip_serializing_if = "Option::is_none")]
1458    pub speaker: Option<String>,
1459}
1460
1461/// How one speaker's captions look.
1462#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
1463#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1464#[serde(deny_unknown_fields)]
1465pub struct SpeakerLook {
1466    /// Their text color.
1467    #[serde(default, skip_serializing_if = "Option::is_none")]
1468    pub color: Option<SolidColor>,
1469    /// Where their text's middle lies, as fractions of the canvas, `(0, 0)` top-left.
1470    #[serde(default, skip_serializing_if = "Option::is_none")]
1471    pub position: Option<alpha2_model::Vec2>,
1472}
1473
1474/// How captions look.
1475#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
1476#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1477#[serde(rename_all = "kebab-case")]
1478pub enum CaptionStyle {
1479    /// Text with a dark band around the glyphs, near the bottom.
1480    #[default]
1481    Outline,
1482    /// Text on a panel behind each line, near the bottom.
1483    Boxed,
1484    /// Text centered on a translucent bar across the canvas near the bottom, shown as long as
1485    /// the captions.
1486    BarBottom,
1487    /// Larger outlined text a little below the middle, as short-form video draws it.
1488    BoldCenter,
1489    /// White text with a black stroke and a soft shadow, near the bottom.
1490    Bold,
1491    /// `bold`, each word turning the highlight color as it is said. Needs word times (`words`
1492    /// or WebVTT inline timestamps), else draws as `bold`.
1493    Karaoke,
1494    /// `bold`, the word being said growing a little in the highlight color. Needs word times.
1495    Pop,
1496}
1497
1498/// A layout generator.
1499#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1500#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1501#[serde(deny_unknown_fields)]
1502pub struct Layout {
1503    /// The node's name, for other nodes to refer to.
1504    #[serde(default, skip_serializing_if = "Option::is_none")]
1505    pub id: Option<String>,
1506    /// The root box, as a project's layout generator writes it.
1507    pub root: Box<LayoutNode>,
1508    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1509    #[serde(default, skip_serializing_if = "Option::is_none")]
1510    pub at: Option<f64>,
1511    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1512    #[serde(default, skip_serializing_if = "Option::is_none")]
1513    pub duration: Option<f64>,
1514    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
1515    #[serde(default, skip_serializing_if = "Option::is_none")]
1516    pub inset: Option<Inset>,
1517    /// Where in its area the picture or text lies. Default `center`.
1518    #[serde(default, skip_serializing_if = "Option::is_none")]
1519    pub align: Option<Align>,
1520    /// How it comes in at its start.
1521    #[serde(default, skip_serializing_if = "Option::is_none")]
1522    pub enter: Option<Motion>,
1523    /// How it goes out, ending at its end.
1524    #[serde(default, skip_serializing_if = "Option::is_none")]
1525    pub exit: Option<Motion>,
1526}
1527
1528/// A sound file.
1529#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1530#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1531#[serde(deny_unknown_fields)]
1532pub struct Audio {
1533    /// The node's name, for other nodes to refer to.
1534    #[serde(default, skip_serializing_if = "Option::is_none")]
1535    pub id: Option<String>,
1536    /// The file.
1537    pub path: String,
1538    /// Where in the file it starts, in seconds.
1539    #[serde(default, skip_serializing_if = "Option::is_none")]
1540    pub trim_start: Option<f64>,
1541    /// Where in the file it ends, in seconds. Default: its end.
1542    #[serde(default, skip_serializing_if = "Option::is_none")]
1543    pub trim_end: Option<f64>,
1544    /// Plays the file again from its start while the node lasts.
1545    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1546    pub r#loop: bool,
1547    /// Linear gain. Default 1.
1548    #[serde(default, skip_serializing_if = "Option::is_none")]
1549    pub volume: Option<f32>,
1550    /// Seconds of fade in.
1551    #[serde(default, skip_serializing_if = "Option::is_none")]
1552    pub fade_in: Option<f64>,
1553    /// Seconds of fade out.
1554    #[serde(default, skip_serializing_if = "Option::is_none")]
1555    pub fade_out: Option<f64>,
1556    /// The `id` of a node (or `body`) whose sound this ducks under.
1557    #[serde(default, skip_serializing_if = "Option::is_none")]
1558    pub duck_under: Option<String>,
1559    /// How far ducking lowers it, in dB (negative). Default -12.
1560    #[serde(default, skip_serializing_if = "Option::is_none")]
1561    pub duck_depth_db: Option<f32>,
1562    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1563    #[serde(default, skip_serializing_if = "Option::is_none")]
1564    pub at: Option<f64>,
1565    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1566    #[serde(default, skip_serializing_if = "Option::is_none")]
1567    pub duration: Option<f64>,
1568}
1569
1570/// Part of a project at its own times.
1571#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1572#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1573#[serde(deny_unknown_fields)]
1574pub struct Raw {
1575    /// Sources its tracks read. Ids must not collide with the compiler's (`s1`, `s2`, ...); a
1576    /// `src-` prefix keeps them apart.
1577    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1578    pub sources: Vec<MediaSource>,
1579    /// Tracks drawn over what comes before, at timeline times.
1580    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1581    pub tracks: Vec<Track>,
1582    /// Compositions its clips show.
1583    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1584    pub compositions: Vec<Composition>,
1585    /// Each file a media source of the fragment reads, by source id: the export's assets.
1586    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
1587    pub assets: BTreeMap<String, String>,
1588}
1589
1590/// Stills or clips in turn.
1591#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1592#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1593#[serde(deny_unknown_fields)]
1594pub struct Slideshow {
1595    /// The node's name, for other nodes to refer to.
1596    #[serde(default, skip_serializing_if = "Option::is_none")]
1597    pub id: Option<String>,
1598    /// The slides.
1599    pub items: Vec<MediaItem>,
1600    /// How long each slide shows, transitions included, in seconds. Default: `fit_to`'s length
1601    /// shared out, else the theme's still length.
1602    #[serde(default, skip_serializing_if = "Option::is_none")]
1603    pub seconds: Option<f64>,
1604    /// A sound file whose length the slides share out. It is not played; add it as a music bed.
1605    #[serde(default, skip_serializing_if = "Option::is_none")]
1606    pub fit_to: Option<String>,
1607    /// What joins slides. Default `theme`.
1608    #[serde(default, skip_serializing_if = "Option::is_none")]
1609    pub transition: Option<TransitionChoice>,
1610    /// How far each slide zooms in over its time, as a multiple (1.15 ends 15% larger). Default
1611    /// none.
1612    #[serde(default, skip_serializing_if = "Option::is_none")]
1613    pub ken_burns: Option<f32>,
1614    /// How slides fill the canvas. Default `cover`.
1615    #[serde(default, skip_serializing_if = "Option::is_none")]
1616    pub fit: Option<Fit>,
1617    /// When it starts in its parent; its length is the slides'.
1618    #[serde(default, skip_serializing_if = "Option::is_none")]
1619    pub at: Option<f64>,
1620}
1621
1622/// A video under its captions.
1623#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1624#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1625#[serde(deny_unknown_fields)]
1626pub struct CaptionedVideo {
1627    /// The node's name, for other nodes to refer to. Its sound is the video's.
1628    #[serde(default, skip_serializing_if = "Option::is_none")]
1629    pub id: Option<String>,
1630    /// The video.
1631    pub video: MediaItem,
1632    /// The captions, timed from the video's start.
1633    pub captions: Box<Captions>,
1634    /// How the video fills the canvas. Default `cover`.
1635    #[serde(default, skip_serializing_if = "Option::is_none")]
1636    pub fit: Option<Fit>,
1637    /// When it starts in its parent; its length is the video's.
1638    #[serde(default, skip_serializing_if = "Option::is_none")]
1639    pub at: Option<f64>,
1640}
1641
1642/// Music under the video.
1643#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1644#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1645#[serde(deny_unknown_fields)]
1646pub struct MusicBed {
1647    /// The node's name, for other nodes to refer to.
1648    #[serde(default, skip_serializing_if = "Option::is_none")]
1649    pub id: Option<String>,
1650    /// The file.
1651    pub path: String,
1652    /// Linear gain. Default 1.
1653    #[serde(default, skip_serializing_if = "Option::is_none")]
1654    pub volume: Option<f32>,
1655    /// Seconds of fade in. Default 1.
1656    #[serde(default, skip_serializing_if = "Option::is_none")]
1657    pub fade_in: Option<f64>,
1658    /// Seconds of fade out at the end. Default 2.
1659    #[serde(default, skip_serializing_if = "Option::is_none")]
1660    pub fade_out: Option<f64>,
1661    /// The `id` of a node (or `body`) whose sound it ducks under.
1662    #[serde(default, skip_serializing_if = "Option::is_none")]
1663    pub duck_under: Option<String>,
1664    /// How far ducking lowers it, in dB (negative). Default -12.
1665    #[serde(default, skip_serializing_if = "Option::is_none")]
1666    pub duck_depth_db: Option<f32>,
1667    /// Plays the file again from its start while the video lasts. Default true.
1668    #[serde(default = "yes")]
1669    pub r#loop: bool,
1670    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1671    #[serde(default, skip_serializing_if = "Option::is_none")]
1672    pub at: Option<f64>,
1673    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1674    #[serde(default, skip_serializing_if = "Option::is_none")]
1675    pub duration: Option<f64>,
1676}
1677
1678const fn yes() -> bool {
1679    true
1680}
1681
1682/// A timing curve: `linear`, a CSS name (`ease`, `ease-in`, `ease-out`, `ease-in-out`) or a
1683/// project easing object.
1684#[derive(Clone, Debug, PartialEq, Serialize)]
1685#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1686#[serde(untagged)]
1687pub enum EasingChoice {
1688    /// `linear`, `ease`, `ease-in`, `ease-out` or `ease-in-out`, with the CSS curves.
1689    Named(String),
1690    /// A project easing.
1691    Curve(Easing),
1692}
1693
1694/// A value over a node's time: a constant, a ramp from one value to another, or keys. Times are
1695/// seconds from the node's start.
1696#[derive(Clone, Debug, PartialEq, Serialize)]
1697#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1698#[serde(untagged)]
1699pub enum Anim<T> {
1700    /// From `from` to `to`.
1701    Ramp(Ramp<T>),
1702    /// Through keyed values.
1703    Keys(Keys<T>),
1704    /// One value throughout.
1705    Value(T),
1706}
1707
1708impl<'de, T: serde::de::DeserializeOwned> Deserialize<'de> for Anim<T> {
1709    // An object with `keys` is keys and one with `from` a ramp; anything else is a value. Ramps
1710    // and keys are objects only, as the schema says, though serde reads a struct from an array.
1711    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1712        use serde::de::Error as _;
1713        let value = serde_json::Value::deserialize(deserializer)?;
1714        let object = value.as_object();
1715        if object.is_some_and(|object| object.contains_key("keys")) {
1716            serde_json::from_value(value).map(Anim::Keys)
1717        } else if object.is_some_and(|object| object.contains_key("from")) {
1718            serde_json::from_value(value).map(Anim::Ramp)
1719        } else if value.is_array() && !accepts_array::<T>() {
1720            return Err(D::Error::custom(
1721                "expected a value, `{from, to}` or `{keys}`, not an array",
1722            ));
1723        } else {
1724            serde_json::from_value(value).map(Anim::Value)
1725        }
1726        .map_err(D::Error::custom)
1727    }
1728}
1729
1730/// Whether `T` itself is written as an array, as a vector value is.
1731fn accepts_array<T: serde::de::DeserializeOwned>() -> bool {
1732    serde_json::from_value::<T>(serde_json::json!([0, 0])).is_ok()
1733        || serde_json::from_value::<T>(serde_json::json!([0, 0, 0, 0])).is_ok()
1734}
1735
1736/// A change from one value to another; before it the value is `from`, after it `to`.
1737#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1738#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1739#[serde(deny_unknown_fields)]
1740pub struct Ramp<T> {
1741    /// The value at the start.
1742    pub from: T,
1743    /// The value at the end.
1744    pub to: T,
1745    /// The timing curve. Default linear.
1746    #[serde(default, skip_serializing_if = "Option::is_none")]
1747    pub ease: Option<EasingChoice>,
1748    /// When it starts. Default 0.
1749    #[serde(default, skip_serializing_if = "Option::is_none")]
1750    pub at: Option<f64>,
1751    /// How long it lasts. Default: to the node's end.
1752    #[serde(default, skip_serializing_if = "Option::is_none")]
1753    pub duration: Option<f64>,
1754}
1755
1756/// Values at times; the value holds before the first and after the last.
1757#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1758#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1759#[serde(deny_unknown_fields)]
1760pub struct Keys<T> {
1761    /// The keys, in increasing time; at least one.
1762    pub keys: Vec<Key<T>>,
1763}
1764
1765/// One keyed value.
1766#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1767#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1768#[serde(deny_unknown_fields)]
1769pub struct Key<T> {
1770    /// Seconds from the node's start.
1771    pub t: f64,
1772    /// The value.
1773    pub v: T,
1774    /// The timing curve to the next key. Default linear.
1775    #[serde(default, skip_serializing_if = "Option::is_none")]
1776    pub ease: Option<EasingChoice>,
1777}
1778
1779/// An entrance or exit, timed from the node's own start or back from its own end.
1780#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1781#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1782#[serde(deny_unknown_fields)]
1783pub struct Motion {
1784    /// What moves: `fade` (opacity alone), `rise` (a slide up), `slide` (toward `direction`) or
1785    /// `scale` (from `size` times its size). `rise`, `slide` and `scale` fade too unless `fade`
1786    /// is false.
1787    #[serde(rename = "type")]
1788    pub kind: MotionKind,
1789    /// Length in seconds; 0 is no motion. Default: the theme's fade length.
1790    #[serde(default, skip_serializing_if = "Option::is_none")]
1791    pub duration: Option<f64>,
1792    /// The timing curve. Default linear.
1793    #[serde(default, skip_serializing_if = "Option::is_none")]
1794    pub easing: Option<EasingChoice>,
1795    /// Which way a `slide` travels, entering into place and leaving out of it. Default `up`.
1796    #[serde(default, skip_serializing_if = "Option::is_none")]
1797    pub direction: Option<Direction>,
1798    /// How far a `rise` or `slide` travels, in pixels. Default: the theme's margin.
1799    #[serde(default, skip_serializing_if = "Option::is_none")]
1800    pub distance: Option<f32>,
1801    /// The size a `scale` enters from or exits to, as a multiple of its own. Default 0.
1802    #[serde(default, skip_serializing_if = "Option::is_none")]
1803    pub size: Option<f32>,
1804    /// Whether a `rise`, `slide` or `scale` also fades. Default true.
1805    #[serde(default, skip_serializing_if = "Option::is_none")]
1806    pub fade: Option<bool>,
1807}
1808
1809/// What an entrance or exit moves.
1810#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1811#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1812#[serde(rename_all = "snake_case")]
1813pub enum MotionKind {
1814    /// Opacity alone.
1815    Fade,
1816    /// A slide up.
1817    Rise,
1818    /// A slide toward `direction`.
1819    Slide,
1820    /// A change of size about the node's own anchor.
1821    Scale,
1822}
1823
1824/// A direction of travel on the canvas.
1825#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
1826#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1827#[serde(rename_all = "snake_case")]
1828pub enum Direction {
1829    /// Toward the top.
1830    #[default]
1831    Up,
1832    /// Toward the bottom.
1833    Down,
1834    /// Toward the left.
1835    Left,
1836    /// Toward the right.
1837    Right,
1838}
1839
1840/// A text revealed a unit at a time. Each unit moves at a constant rate over `duration`.
1841#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1842#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1843#[serde(deny_unknown_fields)]
1844pub struct Reveal {
1845    /// The unit: `word` (words holding a letter or digit) or `line` (laid-out lines).
1846    pub by: RevealUnit,
1847    /// How each unit appears: `fade`, or `rise` (fading in while moving up). Default `fade`.
1848    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
1849    pub kind: Option<RevealKind>,
1850    /// Seconds between one unit's start and the next's. Default half the duration.
1851    #[serde(default, skip_serializing_if = "Option::is_none")]
1852    pub stagger: Option<f64>,
1853    /// Seconds each unit takes. Default: the theme's fade length.
1854    #[serde(default, skip_serializing_if = "Option::is_none")]
1855    pub duration: Option<f64>,
1856    /// How far a `rise` moves, in pixels. Default half the font size.
1857    #[serde(default, skip_serializing_if = "Option::is_none")]
1858    pub distance: Option<f32>,
1859}
1860
1861/// The unit a text is revealed by.
1862#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1863#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1864#[serde(rename_all = "snake_case")]
1865pub enum RevealUnit {
1866    /// Words that hold a letter or digit; other characters show throughout.
1867    Word,
1868    /// Laid-out lines.
1869    Line,
1870}
1871
1872/// How a revealed unit appears.
1873#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1874#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1875#[serde(rename_all = "snake_case")]
1876pub enum RevealKind {
1877    /// Opacity alone.
1878    Fade,
1879    /// Fading in while moving up.
1880    Rise,
1881}
1882
1883/// A number counting from `start` to `end`, shown as text that changes on the frame grid.
1884#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1885#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1886#[serde(deny_unknown_fields)]
1887pub struct Counter {
1888    /// The node's name, for other nodes to refer to.
1889    #[serde(default, skip_serializing_if = "Option::is_none")]
1890    pub id: Option<String>,
1891    /// The value it counts from.
1892    pub start: f64,
1893    /// The value it counts to.
1894    pub end: f64,
1895    /// Seconds the count takes from the node's start, at most 100,000 frames; it then holds
1896    /// `end`. Default: the node's whole length.
1897    #[serde(default, skip_serializing_if = "Option::is_none")]
1898    pub count_duration: Option<f64>,
1899    /// The timing curve of the count. Default linear.
1900    #[serde(default, skip_serializing_if = "Option::is_none")]
1901    pub easing: Option<EasingChoice>,
1902    /// How the number is written.
1903    #[serde(default, skip_serializing_if = "Option::is_none")]
1904    pub format: Option<NumberFormat>,
1905    /// The theme style it starts from. Default `title`.
1906    #[serde(default, skip_serializing_if = "Option::is_none")]
1907    pub style: Option<TextRole>,
1908    /// Font size in pixels, or a theme length. Default: the style's.
1909    #[serde(default, skip_serializing_if = "Option::is_none")]
1910    pub font_size: Option<Size>,
1911    /// Family. Default: the theme's.
1912    #[serde(default, skip_serializing_if = "Option::is_none")]
1913    pub font_family: Option<String>,
1914    /// Color. Default: the theme's text color.
1915    #[serde(default, skip_serializing_if = "Option::is_none")]
1916    pub color: Option<SolidColor>,
1917    /// Bands around the glyphs, as a text node's `strokes`.
1918    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1919    pub strokes: Vec<TextStroke>,
1920    /// Shadows of the glyphs, as a text node's `shadows`.
1921    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1922    pub shadows: Vec<TextShadow>,
1923    /// Opacity, 0..=1. Default 1.
1924    #[serde(default, skip_serializing_if = "Option::is_none")]
1925    pub opacity: Option<f32>,
1926    /// Seconds from the parent's start (an overlay's: the video's). Ignored in a sequence.
1927    #[serde(default, skip_serializing_if = "Option::is_none")]
1928    pub at: Option<f64>,
1929    /// Length in seconds. Default: the node's own length, else what its parent gives it.
1930    #[serde(default, skip_serializing_if = "Option::is_none")]
1931    pub duration: Option<f64>,
1932    /// Pixels kept clear inside the parent's area: one number, or `[top, right, bottom, left]`.
1933    #[serde(default, skip_serializing_if = "Option::is_none")]
1934    pub inset: Option<Inset>,
1935    /// Where in its area the number lies. Default `center`.
1936    #[serde(default, skip_serializing_if = "Option::is_none")]
1937    pub align: Option<Align>,
1938    /// How it comes in at its start.
1939    #[serde(default, skip_serializing_if = "Option::is_none")]
1940    pub enter: Option<Motion>,
1941    /// How it goes out, ending at its end.
1942    #[serde(default, skip_serializing_if = "Option::is_none")]
1943    pub exit: Option<Motion>,
1944}
1945
1946/// How a counter writes its number.
1947#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
1948#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1949#[serde(deny_unknown_fields)]
1950pub struct NumberFormat {
1951    /// Digits after the decimal point, at most 6. Default 0.
1952    #[serde(default, skip_serializing_if = "Option::is_none")]
1953    pub decimals: Option<u32>,
1954    /// Put between each group of three integer digits, as `,`. Default none.
1955    #[serde(default, skip_serializing_if = "Option::is_none")]
1956    pub thousands: Option<String>,
1957    /// The decimal point. Default `.`.
1958    #[serde(default, skip_serializing_if = "Option::is_none")]
1959    pub point: Option<String>,
1960    /// Text before the number.
1961    #[serde(default, skip_serializing_if = "Option::is_none")]
1962    pub prefix: Option<String>,
1963    /// Text after the number.
1964    #[serde(default, skip_serializing_if = "Option::is_none")]
1965    pub suffix: Option<String>,
1966}