Automotion docs
Schema reference

Movie settings

Top-level Automotion movie document: output size, fps, quality, draft mode, variables and scenes.

The movie document is the single source of truth for a render: the JSON you send to the API is exactly what gets rendered — no hidden fields, no server-side mutations. All fields below are validated by the schema; unknown keys are rejected.

Properties

PropertyTypeDefaultDescription
schema *"v1"—Movie Schema version tag. Documents keep rendering under the version they declare.
width *integer (16–4096, even)—Output width in pixels (even integer, 16–4096). Use normalizeMovie() to derive it from a preset.
height *integer (16–4096, even)—Output height in pixels (even integer, 16–4096). Use normalizeMovie() to derive it from a preset.
fps24 | 25 | 30 | 6030Frames per second of the output video: 24, 25, 30, or 60.
quality"low" | "medium" | "high""high"Encoding quality of the output video; higher quality means larger files.
format"mp4""mp4"Output container format. MVP supports mp4 only.
draftbooleanfalseRender a fast, low-resolution, watermarked preview instead of final output.
variablesobject—Declared template variables, keyed by name. Reference them as {{name}} inside any string value.
elementsarray of (object | object | object | object | object | object | object)—Movie-level overlay elements rendered across all scenes, e.g. a watermark or background music.
scenes *object[]—Scenes played sequentially, in order.

variables object

Declaration of one template variable.

PropertyTypeDefaultDescription
type *"string" | "number" | "boolean" | "url" | "color" | "enum"—Declared variable type; supplied values are validated against it at render time.
defaultunknown—Fallback value used when the caller does not supply this variable.
descriptionstring (non-empty)—Human-readable explanation shown in docs and template UIs.
valuesarray of (string (non-empty))—Allowed values. Required when type is "enum"; not allowed otherwise.

scenes object

One scene of the movie. Scenes play sequentially in array order.

PropertyTypeDefaultDescription
id *string (non-empty)—Stable identifier, unique across the whole movie. Used by editor selection sync and error paths.
durationnumber (> 0) | "longest" | "voice"—Scene duration: seconds, or "longest" (longest element) or "voice" (voiceover length). Defaults to "longest".
backgroundstring (non-empty) | object—Scene background: a CSS color string, or a media reference object.
transitionobject—Transition from the previous scene into this one.
elements *array of (object | object | object | object | object | object | object)—Elements rendered in this scene.

Sizing by preset

Instead of explicit width/height you can size the movie with a preset (plus an optional resolution, default "1080p"). Provide either the preset pair or explicit dimensions — never both.

presetresolutionOutput size
"9:16""1080p"1080×1920
"9:16""720p"720×1280
"1:1""1080p"1080×1080
"1:1""720p"720×720
"16:9""1080p"1920×1080
"16:9""720p"1280×720

Example

A complete movie: portrait 1080×1920, two scenes, a fade transition:

movie.json
{
  "schema": "v1",
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "quality": "high",
  "draft": false,
  "scenes": [
    {
      "id": "intro",
      "duration": 3,
      "background": "#0f172a",
      "elements": [
        {
          "id": "intro-title",
          "type": "text",
          "text": "Automotion",
          "fontSize": 96,
          "fontWeight": 700,
          "animation": {
            "preset": "fade",
            "duration": 0.6
          }
        }
      ]
    },
    {
      "id": "outro",
      "duration": 3,
      "background": "#1e293b",
      "transition": {
        "type": "fade",
        "duration": 0.5
      },
      "elements": [
        {
          "id": "outro-title",
          "type": "text",
          "text": "Video from JSON",
          "fontSize": 64
        }
      ]
    }
  ]
}

▶ Try it in the playground

See also: Scene settings, the seven element types, and Variables.

Previous

Schema reference

Next

Scene settings

On this page