Element#

An element is the smallest renderable unit in a movie. Elements live inside a scene's elements array or on the movie's top-level elements array (overlaying every scene). The shape of an element depends on its type field.

Element types#

The template element type is deprecated. Use the template movie-level field to reference a saved template instead.

Common properties#

All element types share the following base properties:

• id — unique identifier.
• type — element discriminator. Required on every element.
• condition — string expression; element is rendered only when truthy.
• variables — element-local variables.
• comment — free-form note.
• duration — element length in seconds. -1 auto-calculates from the asset; -2 matches the container.
• start — start time in seconds relative to the parent container.
• extra-time — additional time after the element ends.
• z-index — stacking order override (-99 to 99).
• cache — reuse the cached render when inputs match.
• fade-in, fade-out — opacity envelope, in seconds.

Visual elements (image, video, text, html, component, audiogram) additionally share:

• position, x, y — placement.
• width, height, resize — sizing.
• rotate, crop, zoom, pan, pan-distance, pan-crop — transformations.
• chroma-key, correction, flip-horizontal, flip-vertical, mask — visual effects.

Audio-producing elements (video, audio, voice, audiogram) additionally share:

• muted — silence the element.
• volume — gain (0–10, 1 = unity).

Positioning and sizing values#

x, y, width and height accept a number of pixels, and also these string forms:

Three rules are worth committing to memory:

Percentages measure to the element's top-left corner, exactly like CSS left and top. On a 1920-wide canvas, "x": "30%" puts the element's LEFT EDGE at 576px — it does not centre it on the 30% mark.

Named values carry no margin. "x": "left" is 0. This is different from the position presets, which inset edge and corner placements by 5% of the canvas. Use position when you want that breathing room, and a named x/y when you want the element flush against the edge. Named values need "position": "custom", which is the default.

text, component, html and audiogram elements are as large as the canvas unless you set width/height. Their box has no natural size, so each unset axis becomes the full canvas — and "x": "center" on a canvas-sized box resolves to 0, because a box that wide is already centred. Give the element a width first, then centre it:

{ "type": "text", "text": "Hello", "width": "50%", "x": "center", "y": "70%" }

A value that cannot be understood — "x": "auto", "width": "wide" — fails the render with a message naming the element and the property.

Two exceptions to the named values. They are not accepted inside keyframes, because an animated value has to be interpolated and a name has no number to interpolate. And they are not accepted on the subtitles element, which is placed by settings.position / settings.x / settings.y instead — its top-level x/y are inherited but never read. Percentages work in keyframes; on subtitles use the settings coordinates, which are plain pixels.

Example#

{
    "resolution": "full-hd",
    "scenes": [
        {
            "elements": [
                { "type": "image", "src": "https://example.com/photo.png" },
                { "type": "text", "text": "Hello", "style": "001" }
            ]
        }
    ]
}

Elements placed at the movie level (instead of inside a scene) render above every scene for the entire movie:

{
    "scenes": [/* … */],
    "elements": [
        { "type": "image", "src": "https://example.com/logo.png", "position": "top-right" }
    ]
}