> ## Documentation Index
> Fetch the complete documentation index at: https://docs.framelane.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Elements
> Every field accepted by each element type — required fields, defaults, and constraints.
This page is the field-by-field reference for the `elements[]` array in `POST /v1/renders`. For full request body examples see the **Render Examples** section.
## How to read this page
| Column | Meaning |
| ---------------- | ---------------------------------------------------- |
| **required** | The API returns `422` if the field is missing |
| **optional** | The field has a default and may be omitted |
| `→ 0` / `→ null` | Default value the API uses when the field is omitted |
`Dimension` fields accept a pixel number (`960`), a percentage string (`"50%"`), or an angle string (`"90°"` / `"90deg"`) depending on context.
***
## Common fields
These fields are present on every element type.
| Field | Type | | Default | Description |
| ---------- | ------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string (enum) | **required** | — | Element discriminator. One of: `video`, `audio`, `text`, `image`, `gradient`, `shape` |
| `id` | string | optional | `→ ""` | Unique identifier. **Required on `image` elements** — an empty ID causes the image to be silently skipped. Recommended on all elements used in transitions. |
| `time` | number ≥ 0 | optional | `→ 0` | When the element starts on the output timeline, in seconds. |
| `duration` | number > 0 | see per-type | — | How long the element is active, in seconds. **Required on `text` and `image`** — omitting it produces a zero-length window and the element will not appear. Not accepted on `video` or `audio` — use `out_point` to control clip length. |
| `visible` | boolean | optional | `→ true` | Set to `false` to exclude from the render without removing from the request. |
| `name` | string | optional | `→ null` | Human-readable label. Not used by the renderer. |
| `track` | integer 0–255 | optional | `→ null` | Timeline track index. Informational only; not used by the renderer. |
***
## Advanced transform & looks
These fields are accepted on every **visual** element (`video`, `image`, `text`, `gradient`, `shape`). They compose against the canvas backdrop and are ignored on `audio`.
| Field | Type | | Default | Description |
| ---------------- | --------------------------------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blend_mode` | BlendMode | optional | `→ "none"` | Composite against the backdrop. Separable (`multiply`, `screen`, `overlay`, `darken`, `lighten`, `color_dodge`, `color_burn`, `hard_light`, `soft_light`, `difference`, `add`, `exclusion`) + W3C non-separable (`hue`, `saturation`, `color`, `luminosity`). |
| `x_rotation` | Dimension | optional | `→ "0°"` | **Perspective tilt** about the X axis (true foreshortening, 45° fov). Device mockups, card flips. Emits `rotation:{x,y,z}` when x/y are set. Not on `text` (text tilts via animation). |
| `y_rotation` | Dimension | optional | `→ "0°"` | Perspective tilt about the Y axis. |
| `mask_shape` | `circle` \| `diamond` \| `hexagon` \| `star` \| `heart` \| `triangle` | optional | `→ null` | Analytic (SDF) shape mask clipping the element's coverage. |
| `mask` | [MaskConfig](#maskconfig) | optional | `→ null` | Feather / scale / center for the mask (iris reveals, wipes). |
| `mask_keyframes` | MaskKeyframe\[] | optional | `→ null` | Animate the mask over time (`time` + optional `feather`/`scale`/`center`/`easing`). |
| `backdrop_blur` | Dimension | optional | `→ 0` | Frosted-glass panel: the blurred canvas fills the element's footprint under its (translucent) content. Radius in px. |
| `matte` | [Matte](#matte) | optional | `→ null` | Track matte: drive this element's coverage from another layer's render (alpha/luma; text sources supported). |
`video` and `image` also accept the extended colour grade: `temperature`, `tint`, `vibrance`, `highlights`, `shadows` (in addition to `brightness`/`contrast`/etc.).
***
## video
Plays a video clip on the timeline.
### Source and trim
| Field | Type | | Default | Description |
| ------------------------- | --------------- | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_url` | URL | **required** | — | URL of the video file. Must be accessible by the renderer. |
| `in_point` | number ≥ 0 | optional | `→ 0` | Seconds into the source file to start playing from. |
| `out_point` | number > 0 | optional | `→ end of source` | Seconds into the source file to stop playing. Must be greater than `in_point` when both are set. |
| `speed` | number 0.25–4.0 | optional | `→ 1.0` | Playback speed multiplier. `2.0` = 2× speed. |
| `playback_rate_keyframes` | RateKeyframe\[] | optional | `→ null` | **Speed ramp** — piecewise-linear `{time, rate}` keyframes (absolute timeline seconds; `rate` 0 = freeze-frame). Audio keeps the static rate; mute or detach it on ramped clips. |
Video elements do not have a `duration` field. Clip length on the output timeline is determined by `out_point − in_point` (accounting for `speed`). To fix the output to a specific length, set a top-level `duration` on the request.
### Position and size
| Field | Type | | Default | Description |
| ----------------- | ------------ | -------- | ---------- | ----------------------------------------------- |
| `x` | Dimension | optional | `→ "50%"` | Horizontal center position. |
| `y` | Dimension | optional | `→ "50%"` | Vertical center position. |
| `width` | Dimension | optional | `→ "100%"` | Clip width. |
| `height` | Dimension | optional | `→ "100%"` | Clip height. |
| `z_index` | integer | optional | `→ 0` | Stacking order. Higher numbers appear in front. |
| `opacity` | number 0–100 | optional | `→ 100` | Transparency percentage. |
| `z_rotation` | Dimension | optional | `→ "0°"` | Rotation around the Z axis. |
| `flip_horizontal` | boolean | optional | `→ false` | Mirror horizontally. |
| `flip_vertical` | boolean | optional | `→ false` | Mirror vertically. |
### Audio
| Field | Type | | Default | Description |
| ------------------- | ------------ | -------- | ------- | -------------------------------------------------------------------------------- |
| `volume` | number 0–100 | optional | `→ 100` | Embedded audio volume percentage. Affects only the audio track inside this clip. |
| `fade_in_duration` | number | optional | `→ 0` | Seconds of linear audio fade-in at the clip start. |
| `fade_out_duration` | number | optional | `→ 0` | Seconds of linear audio fade-out at the clip end. |
### Color adjustments
| Field | Type | | Default | Description |
| --------------- | ------------ | -------- | -------- | ------------------------------- |
| `brightness` | number | optional | `→ 0` | Brightness offset. |
| `contrast` | number | optional | `→ 0` | Contrast offset. |
| `saturation` | number | optional | `→ 0` | Saturation offset. |
| `exposure` | number | optional | `→ 0` | Exposure offset. |
| `sharpness` | number | optional | `→ 0` | Sharpening amount. |
| `blur` | number | optional | `→ 0` | Gaussian blur radius in pixels. |
| `noise` | number | optional | `→ 0` | Film grain amount. |
| `vignette` | number | optional | `→ 0` | Vignette intensity. |
| `hue_rotate` | number | optional | `→ 0` | Hue rotation in degrees. |
| `lut_url` | URL | optional | `→ null` | URL of a `.cube` LUT file. |
| `lut_intensity` | number 0–100 | optional | `→ 100` | LUT blend percentage. |
### Cropping
| Field | Type | | Default | Description |
| ------------- | ---------- | -------- | ------- | -------------------------------------------------- |
| `crop_top` | number 0–1 | optional | `→ 0` | Fraction of the clip to crop from the top edge. |
| `crop_bottom` | number 0–1 | optional | `→ 0` | Fraction of the clip to crop from the bottom edge. |
| `crop_left` | number 0–1 | optional | `→ 0` | Fraction of the clip to crop from the left edge. |
| `crop_right` | number 0–1 | optional | `→ 0` | Fraction of the clip to crop from the right edge. |
### Border and shadow
| Field | Type | | Default | Description |
| --------------- | --------- | -------- | -------- | ------------------------------------------------------ |
| `border_radius` | Dimension | optional | `→ 0` | Corner radius in pixels. |
| `border_color` | hex color | optional | `→ null` | Border color. |
| `border_width` | Dimension | optional | `→ 0` | Border thickness in pixels. |
| `shadow_color` | hex color | optional | `→ null` | Drop shadow color. Shadow is hidden when this is null. |
| `shadow_blur` | Dimension | optional | `→ 0` | Shadow blur radius. |
| `shadow_x` | Dimension | optional | `→ 0` | Shadow horizontal offset. |
| `shadow_y` | Dimension | optional | `→ 0` | Shadow vertical offset. |
### Effects, motion
| Field | Type | | Default | Description |
| --------- | --------- | -------- | ------- | ------------------------------------------------------------------------ |
| `effects` | Effect\[] | optional | `→ []` | Visual effects (chroma key, glitch, etc.). See [Effect object](#effect). |
| `motion` | Motion\[] | optional | `→ []` | Entrance / exit / loop motion presets. See [Motion object](#motion). |
AI media operations — background removal, gaze redirect, super-resolution — are **not** inline
render fields. Run them first as standalone [Tasks](/tasks/overview) (`POST /v1/tasks/{type}`),
then reference the processed output URL as a video element's `source_url`.
***
## audio
Plays an audio clip or background music track.
| Field | Type | | Default | Description |
| ------------------- | --------------- | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `source_url` | URL | **required** | — | URL of the audio file. |
| `time` | number ≥ 0 | optional | `→ 0` | Start time on the output timeline in seconds. |
| `in_point` | number ≥ 0 | optional | `→ 0` | Seconds into the source to start from. |
| `out_point` | number > 0 | optional | `→ end of source` | Seconds into the source to stop. Controls clip length on the output timeline. Must be greater than `in_point` when both are set. |
| `speed` | number 0.25–4.0 | optional | `→ 1.0` | Playback speed multiplier. |
| `volume` | number 1–100 | optional | `→ 100` | Volume percentage. **Must be greater than `0`** — the renderer silently drops audio streams with `volume ≤ 0`. |
| `fade_in_duration` | number | optional | `→ 0` | Seconds of linear fade-in at the clip start. |
| `fade_out_duration` | number | optional | `→ 0` | Seconds of linear fade-out at the clip end. |
***
## text
Renders a text layer on screen.
`duration` is **required** on text elements. Omitting it produces a zero-length window — the text will not appear in the render.
| Field | Type | | Default | Description |
| -------------------- | ---------------------------------------------- | ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | string | **required** | — | The text content to render. |
| `duration` | number > 0 | **required** | — | How long the text is visible in seconds. |
| `time` | number ≥ 0 | optional | `→ 0` | When the text appears on the output timeline. |
| `font_family` | string | optional | `→ "Inter"` | Font family name. Must be available to the renderer. |
| `font_size` | number > 0 | optional | `→ 16` | Font size in pixels. |
| `font_weight` | integer 100–900 | optional | `→ 400` | Font weight. `400` = regular, `700` = bold. |
| `font_style` | `normal` \| `italic` \| `bold` \| `bolditalic` | optional | `→ "normal"` | Font style variant. |
| `text_color` | hex color | optional | `→ "#ffffff"` | Text fill color. |
| `text_align` | `left` \| `center` \| `right` | optional | `→ "center"` | Horizontal text alignment. |
| `text_decoration` | `none` \| `underline` \| `strikethrough` | optional | `→ "none"` | Text decoration. |
| `tracking` | number | optional | `→ 0` | Extra spacing between characters. |
| `leading` | number | optional | `→ 1.2` | Line height multiplier. |
| `stroke_color` | hex color | optional | `→ null` | Outline color. Set together with `stroke_width` to enable outlines. |
| `stroke_width` | number | optional | `→ 0` | Outline width in pixels. Has no effect unless `stroke_color` is also set. |
| `background_color` | hex color | optional | `→ null` | Color of the background box (when `background` is `true`) or the active-word highlight (when using `box` or `color` word animations). |
| `background_opacity` | number 0–100 | optional | `→ 100` | Background fill opacity. |
| `background` | boolean | optional | `→ false` | Solid color box behind the full text block. Set `background_color` to choose the color. |
| `stroke` | boolean | optional | `→ false` | Outline-only mode — draws the glyph stroke with no fill. Requires `stroke_color` and `stroke_width`. When `false`, setting `stroke_color` + `stroke_width` gives fill + stroke. |
| `shadow` | boolean | optional | `→ false` | Built-in drop shadow. |
| `text_wrap` | `wrap` \| `nowrap` | optional | `→ "wrap"` | Whether long lines wrap. |
| `motion` | Motion\[] | optional | `→ []` | Entrance / exit / loop motion presets. See [Motion object](#motion). |
| `animation_preset` | string | optional | `→ null` | Animation shorthand string (e.g. `"typewriter"`). Ignored when `word_animation` is set. |
| `word_animation` | WordAnimation | optional | `→ null` | Word-level animation with per-word timestamps. See [WordAnimation object](#wordanimation) and [word animation examples](/renders/examples/word-animation). |
| `words` | [WordSpec](#wordspec)\[] | optional | `→ null` | Per-word timing **and per-word style overrides** (`{word, start, end, style?}`). Editorial-emphasis captions = word timings + a styled keyword. Use with `motion`/`animation_preset` for the animation. |
| `counter` | [ValueCounter](#valuecounter) | optional | `→ null` | Rewrite the text from an eased numeric sweep (the animated "64%" stat hero). |
| `glow` | [TextGlow](#textglow) | optional | `→ null` | Soft glow around the glyphs (`{color, size, intensity}`). |
| `text_direction` | `ltr` \| `rtl` | optional | `→ "ltr"` | Text direction. `rtl` for right-to-left scripts. |
| `x` | Dimension | optional | `→ "50%"` | Horizontal center position. |
| `y` | Dimension | optional | `→ "50%"` | Vertical center position. |
| `width` | Dimension | optional | `→ "100%"` | Text wrap width. |
| `z_index` | integer | optional | `→ 1` | Stacking order. |
| `opacity` | number 0–100 | optional | `→ 100` | Transparency percentage. |
| `z_rotation` | Dimension | optional | `→ "0°"` | Rotation around the Z axis. |
| `border_radius` | Dimension | optional | `→ 0` | Corner radius of the fill background. |
| `shadow_color` | hex color | optional | `→ null` | Drop shadow color. |
| `shadow_blur` | Dimension | optional | `→ 0` | Shadow blur radius. |
| `shadow_x` | Dimension | optional | `→ 0` | Shadow horizontal offset. |
| `shadow_y` | Dimension | optional | `→ 0` | Shadow vertical offset. |
***
## image
Renders a static image on screen.
Both `id` and `duration` are **required** on image elements. An empty or missing `id` causes the image to be silently skipped by the renderer. A missing `duration` produces a zero-length window.
| Field | Type | | Default | Description |
| ----------------- | ------------ | ------------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| `id` | string | **required** | — | Unique identifier. Empty string causes silent skip. |
| `source_url` | URL | **required** | — | URL of the image file (PNG, JPG, WebP). |
| `duration` | number > 0 | **required** | — | How long the image is visible in seconds. |
| `time` | number ≥ 0 | optional | `→ 0` | When the image appears on the output timeline. |
| `x` | Dimension | optional | `→ "50%"` | Horizontal center position. |
| `y` | Dimension | optional | `→ "50%"` | Vertical center position. |
| `width` | Dimension | optional | `→ "100%"` | Image width. |
| `height` | Dimension | optional | `→ "100%"` | Image height. |
| `z_index` | integer | optional | `→ 0` | Stacking order. Same default as `video` — set to `1` or higher when placing an image over a video clip. |
| `opacity` | number 0–100 | optional | `→ 100` | Transparency percentage. |
| `z_rotation` | Dimension | optional | `→ "0°"` | Rotation around the Z axis. |
| `flip_horizontal` | boolean | optional | `→ false` | Mirror horizontally. |
| `flip_vertical` | boolean | optional | `→ false` | Mirror vertically. |
| `motion` | Motion\[] | optional | `→ []` | Entrance / exit / loop motion presets. |
| `effects` | Effect\[] | optional | `→ []` | Visual effects. |
| `brightness` | number | optional | `→ 0` | |
| `contrast` | number | optional | `→ 0` | |
| `saturation` | number | optional | `→ 0` | |
| `exposure` | number | optional | `→ 0` | |
| `sharpness` | number | optional | `→ 0` | |
| `blur` | number | optional | `→ 0` | Gaussian blur in pixels. |
| `noise` | number | optional | `→ 0` | Film grain. |
| `vignette` | number | optional | `→ 0` | |
| `hue_rotate` | number | optional | `→ 0` | Hue rotation in degrees. |
| `lut_url` | URL | optional | `→ null` | `.cube` LUT file URL. |
| `lut_intensity` | number 0–100 | optional | `→ 100` | LUT blend percentage. |
| `crop_top` | number 0–1 | optional | `→ 0` | |
| `crop_bottom` | number 0–1 | optional | `→ 0` | |
| `crop_left` | number 0–1 | optional | `→ 0` | |
| `crop_right` | number 0–1 | optional | `→ 0` | |
| `border_radius` | Dimension | optional | `→ 0` | Corner radius in pixels. |
| `border_color` | hex color | optional | `→ null` | |
| `border_width` | Dimension | optional | `→ 0` | |
| `shadow_color` | hex color | optional | `→ null` | |
| `shadow_blur` | Dimension | optional | `→ 0` | |
| `shadow_x` | Dimension | optional | `→ 0` | |
| `shadow_y` | Dimension | optional | `→ 0` | |
***
## gradient
A rounded gradient card / bar / pill as one element (§5e). Accepts the common transform/looks fields plus:
| Field | Type | | Default | Description |
| -------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------ | -------- | ---------------------------------------------------------------------- |
| `id` | string | **required** | — | Unique identifier. |
| `duration` | number > 0 | **required** | — | Seconds the gradient is visible. |
| `gradient` | [Gradient](#gradient-object) | **required** | — | The fill: `kind` (`linear`/`radial`), `angle_degrees`, and ≥2 `stops`. |
| `corner_radius` | number 0–1 | optional | `→ 0` | Corner radius, normalized. |
| `shadow` | [DropShadow](#dropshadow) | optional | `→ null` | Drop shadow (`{color, distance, direction, blur}`). |
| `effects` | Effect\[] | optional | `→ []` | Shader effect chain (e.g. `aurora`). |
| `x`, `y`, `width`, `height`, `opacity`, `z_index`, `motion`, `blend_mode`, `x_rotation`, `y_rotation`, … | | optional | | Common transform/looks fields. |
## shape
A first-class vector primitive: SVG path fill + stroke, morphing, trim paths (§5b).
| Field | Type | | Default | Description |
| ------------------------------------------- | ------------------------- | ------------ | ----------------- | ------------------------------------------------------------------------------- |
| `id` | string | **required** | — | Unique identifier. |
| `duration` | number > 0 | **required** | — | Seconds the shape is visible. |
| `path` | string | **required** | — | SVG path `d` (`M L H V C S Q T Z`; arcs straighten). |
| `view_box` | `[x,y,w,h]` | optional | `→ [0,0,100,100]` | Path coordinate space. |
| `fill` | hex color \| `"none"` | optional | `→ "#000000"` | Fill colour (alpha ok) or `none` for outline-only. |
| `fill_rule` | `nonzero` \| `evenodd` | optional | `→ "nonzero"` | Fill rule. |
| `stroke` | hex color | optional | `→ null` | Stroke colour. |
| `stroke_width` | number | optional | `→ null` | Stroke width in viewBox units (absent = SVG 1.0; 0 disables). |
| `stroke_dash` | `[on, off]` | optional | `→ null` | Dashed stroke lengths. |
| `corner_radius` | number 0–1 | optional | `→ 0` | Corner radius, normalized. |
| `shadow` | [DropShadow](#dropshadow) | optional | `→ null` | Drop shadow. |
| `path_keyframes` | PathKeyframe\[] | optional | `→ null` | **Morph** the path between keyframes (`{time, d, easing?}`). |
| `trim` | `{start, end}` | optional | `→ null` | Trim paths — the classic draw-on is `trim.end` animating 0→1 on a stroked path. |
| `effects`, `motion`, common transform/looks | | optional | | As above. |
***
## Composition-level features
Set on the render request itself (siblings of `elements`), not on individual elements:
| Field | Type | | Default | Description |
| --------------------- | ----------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
| `groups` | [Group](#group)\[] | optional | `→ []` | Transform groups over member elements (compose member→group→parent; optional stack layout). §5. |
| `motion_blur` | `{samples 2–32, shutter 0–1}` | optional | `→ null` | Shutter-based motion blur over the whole composition. Opt-in, N× render cost. |
| `background_gradient` | [Gradient](#gradient-object) | optional | `→ null` | Canvas-sized gradient fill behind every layer. |
| `watermark_url` | URL | optional | `→ null` | Watermark image overlaid on the output. |
| `custom_animations` | CustomAnimationRegistry | optional | `→ null` | Inline `{element, text}` custom-animation keyframe definitions, referenced by name. |
***
## Sub-objects
### Motion
Used in `motion[]` on `video`, `text`, and `image`. These are pre-built motion presets — not keyframe animations.
| Field | Type | | Default | Description |
| ---------- | ---------------------------------------------------- | ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | MotionType | **required** | — | Motion preset identifier (e.g. `fade`, `slide_up`, `zoom_in`). |
| `time` | number ≥ 0 | **required** | — | Absolute start time on the output timeline in seconds. For entrances and loops use the element's `time`. For exits use element `time + duration − motion duration`. |
| `duration` | number > 0 | **required** | — | How long the preset runs in seconds. |
| `reversed` | boolean | optional | `→ false` | `true` = exit variant; `false` = entrance variant. |
| `easing` | `ease_in_out` \| `ease_in` \| `ease_out` \| `linear` | optional | `→ "ease_in_out"` | Easing curve. |
| `scope` | `element` \| `character` | optional | `→ "element"` | Apply to the whole element (`element`) or each character individually (`character`). Character scope is only supported on `text`. |
| `loop` | boolean | optional | `→ false` | Loop the preset for its duration. |
| `delay` | number | optional | `→ 0` | Delay in seconds before starting when looping. |
| `audio` | [AudioGenerator](#audiogenerator) | optional | `→ null` | Audio-reactive offsets driven by the soundtrack FFT (beat-bounce, bass-pumped scale). Use `fade` as a no-op carrier for a pure generator. |
| `selector` | [RangeSelector](#rangeselector) | optional | `→ null` | AE-style range selector shaping the animation amount by glyph/word position (text only). |
### Effect
Used in `effects[]` on `video` and `image`.
| Field | Type | | Default | Description |
| --------------------- | ---------------------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | EffectType | **required** | — | Effect identifier (e.g. `chroma_key`, `vintage`, `add_grain`, `aurora`). |
| `intensity` | number 0–100 | optional | `→ 50` | Effect strength percentage. |
| `intensity_keyframes` | `{time, value}`\[] | optional | `→ null` | **Animate intensity** over time (absolute seconds, value 0–1). Overrides the static `intensity` — film-look ramps, chroma-key reveals, duotone fades. |
| `props` | object (string→number) | optional | `→ null` | Per-shader scalar props bound as `u_prop_` (e.g. `{"speed": 0.6}` for `aurora`). |
| `chroma_settings` | ChromaKeyProps | optional | `→ null` | Fine-tuned chroma key settings. Only used when `type` is `chroma_key`. |
### ChromaKeyProps
| Field | Type | | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------------ |
| `hue_min` | number | optional | `→ 60` | Minimum hue of the color range to key out. |
| `hue_max` | number | optional | `→ 180` | Maximum hue of the color range to key out. |
| `sat_min` | number | optional | `→ 0.3` | Minimum saturation threshold. |
| `sat_max` | number | optional | `→ 1.0` | Maximum saturation threshold. |
| `lum_min` | number | optional | `→ 0.2` | Minimum luminance threshold. |
| `lum_max` | number | optional | `→ 0.9` | Maximum luminance threshold. |
### WordAnimation
Used as `word_animation` on `text`. Drives word-by-word animated text synchronized to timestamps.
| Field | Type | | Default | Description |
| ------- | ------------------ | ------------ | ------- | ----------------------------------------------------------------------------------- |
| `style` | WordAnimationStyle | **required** | — | Animation style. One of: `glow`, `box`, `scale_pop`, `slide_up`, `fly_in`, `color`. |
| `words` | Word\[] | **required** | — | Per-word timestamps. Must be non-empty. |
### Word
Used in `word_animation.words[]`. Timestamps are **absolute timeline seconds** — the same clock as the element's `time`, motion `time`, and everything else.
| Field | Type | | Default | Description |
| ------- | ---------- | ------------ | ------- | ------------------------------------------------------------ |
| `text` | string | **required** | — | The word text. |
| `start` | number ≥ 0 | **required** | — | Seconds from the text element's start when this word begins. |
| `end` | number > 0 | **required** | — | Seconds from the text element's start when this word ends. |
### WordSpec
Used in `words[]` on `text`. Per-word timing with an optional style override (whole-word matches only).
| Field | Type | | Default | Description |
| ------- | -------------------------------------- | ------------ | -------- | ----------------------------------- |
| `word` | string | **required** | — | The word (whole-word match; UTF-8). |
| `start` | number ≥ 0 | **required** | — | Word reveal start, seconds. |
| `end` | number > 0 | **required** | — | Word reveal end, seconds. |
| `style` | `{color?, bold?, italic?, underline?}` | optional | `→ null` | Per-word style override. |
### ValueCounter
Used as `counter` on `text`. Rewrites the text from an eased numeric sweep.
| Field | Type | | Default | Description |
| ------------------- | ----------- | -------- | ------------------ | -------------------------------------------------------------------------------------- |
| `from_value` | number | optional | `→ 0` | Start value. |
| `to_value` | number | optional | `→ 100` | End value. |
| `decimals` | integer 0–6 | optional | `→ 0` | Decimal places. |
| `prefix` / `suffix` | string | optional | `→ ""` | Text around the number (e.g. `suffix: "%"`). |
| `easing` | string | optional | `→ null` | Easing curve name (`quadOut`, `spring`, …); overshooting easings overshoot the number. |
| `start_time` | number ≥ 0 | optional | `→ 0` | Seconds into the element to start. |
| `length` | number > 0 | optional | `→ remaining life` | Sweep duration. |
### TextGlow
Used as `glow` on `text`.
| Field | Type | | Default | Description |
| ----------- | --------- | ------------ | -------- | ----------------------- |
| `color` | hex color | **required** | — | Glow colour. |
| `size` | number | optional | `→ 0.15` | Glow size, em-relative. |
| `intensity` | number | optional | `→ 1.0` | Glow intensity. |
### Gradient object
Used as `gradient` on `gradient` elements and as `background_gradient` on the request.
| Field | Type | | Default | Description |
| --------------- | ------------------------ | ------------ | ------------ | ------------------------------- |
| `kind` | `linear` \| `radial` | optional | `→ "linear"` | Gradient kind. |
| `angle_degrees` | number | optional | `→ 0` | Linear angle. `0` = left→right. |
| `stops` | `{offset 0–1, color}`\[] | **required** | — | Two or more colour stops. |
### DropShadow
Used as `shadow` on `gradient` / `shape` elements.
| Field | Type | | Default | Description |
| ----------- | --------- | ------------ | ------- | ---------------------------------------- |
| `color` | hex color | **required** | — | Shadow colour (alpha ok). |
| `distance` | number | optional | `→ 0` | Offset distance in px. |
| `direction` | number | optional | `→ 90` | Direction in degrees (polar; 90 = down). |
| `blur` | number | optional | `→ 0` | Blur radius in px. |
### Matte
Used as `matte` on visual elements. Drives coverage from another layer's isolated render (the source auto-hides).
| Field | Type | | Default | Description |
| -------- | ----------------- | ------------ | ----------- | ------------------------------------------------- |
| `source` | string | **required** | — | uuid of the source layer. Text sources supported. |
| `mode` | `alpha` \| `luma` | optional | `→ "alpha"` | Matte mode. |
| `invert` | boolean | optional | `→ false` | Invert the matte. |
### MaskConfig
Used as `mask` on visual elements (layered on the analytic `mask_shape`).
| Field | Type | | Default | Description |
| --------- | ---------- | -------- | -------- | -------------------------- |
| `feather` | number | optional | `→ 0` | Soften the mask edge. |
| `scale` | number > 0 | optional | `→ 1.0` | Mask scale (iris reveals). |
| `center` | `{x, y}` | optional | `→ null` | Mask centre (wipes). |
### AudioGenerator
Used as `audio` in a `motion[]` entry. Each frame the soundtrack FFT reduces to the feature and offsets the element's properties by `amount × feature`.
| Field | Type | | Default | Description |
| ------------------------------ | -------------------------------------------------- | -------- | --------------- | ------------------------------------ |
| `feature` | `amplitude` \| `bass` \| `mid` \| `high` \| `beat` | optional | `→ "amplitude"` | Which FFT feature drives the offset. |
| `scale` / `opacity` / `rotate` | number | optional | `→ 0` | Offset per unit feature. |
| `translate` | `{x, y}` | optional | `→ null` | Translate offset per unit feature. |
### RangeSelector
Used as `selector` in a `motion[]` entry on `text`. Shapes the animation amount by position along the text.
| Field | Type | | Default | Description |
| --------------- | ----------------- | -------- | ----------- | ------------------------------------------------- |
| `based_on` | `glyph` \| `word` | optional | `→ "glyph"` | Selection granularity. |
| `start` / `end` | number 0–1 | optional | `→ 0` / `1` | Range along the text. |
| `falloff` | number | optional | `→ 0` | Ease to zero over this fraction beyond each edge. |
| `ease` | string | optional | `→ null` | Falloff easing curve. |
| `invert` | boolean | optional | `→ false` | Invert the selection. |
### Group
Used in the request-level `groups[]`. Composes member → group → parent (pixel-space, aspect-correct).
| Field | Type | | Default | Description |
| --------------------- | ----------------------------------------------- | ------------ | -------- | ----------------------------------- |
| `id` | string | **required** | — | Unique group id. |
| `parent` | string | optional | `→ null` | Parent group id for nesting. |
| `pivot` / `translate` | `{x, y}` | optional | | Pivot and translation (normalized). |
| `scale` | number > 0 | optional | `→ 1.0` | Group scale. |
| `rotation_degrees` | number | optional | `→ 0` | In-plane (z) rotation. |
| `opacity` | number 0–1 | optional | `→ 1.0` | Group opacity. |
| `members` | string\[] | optional | `→ []` | Member element uuids. |
| `animations` | Motion\[] | optional | `→ []` | Group-level motion. |
| `layout` | `{type:"stack", direction, gap, align, origin}` | optional | `→ null` | Stack layout (row/column). |