`video`#

A video clip with optional trim, loop, playback rate, and volume control. Inherits common fields.

interface VideoElement extends BaseElement {
  type: 'video';
  source: string;
  fit?: 'cover' | 'contain' | 'fill' | 'none';
  crop_x?: number;
  crop_y?: number;
  crop_width?: number;
  crop_height?: number;
  volume?: number | Keyframe[];
  playback_rate?: number | Keyframe[];
  trim_start?: number;
  trim_duration?: number;
  loop?: boolean;
}

Required#

Field	Type	Default	Description
`source`	`string` (URL)	required	HTTP(S) URL of the video file. MP4 (H.264 / H.265), WebM (VP8 / VP9), and MOV are supported. Local file paths fail in the render service today; see render-service docs.

Audio#

Field	Type	Default	Description
`volume`	`number \| Keyframe[]`	`100`	Volume from `0` (mute) to `100` (full). Animatable — use keyframes for fade-ins / fade-outs.

To strip audio entirely, set volume: 0.

Playback#

Field	Type	Default	Description
`playback_rate`	`number \| Keyframe[]`	`1`	Speed multiplier. `0.5` = half speed; `2` = double. Animatable.
`loop`	`boolean`	`false`	Whether to loop the clip if the element's `duration` exceeds the trimmed clip length.

Trimming#

Field	Type	Default	Description
`trim_start`	`number` (seconds)	`0`	Where in the source file playback begins.
`trim_duration`	`number` (seconds)	source-derived	How much of the source file to play, starting from `trim_start`. Defaults to the rest of the file.

The element's own duration (from common fields) is the duration on the timeline. The clip's playback fills that window, looping if loop is true and the trimmed clip is shorter, or stopping at the trimmed clip's end if it isn't.

Layout#

The fit semantics from images apply to video too: the runtime defaults to cover. Set the element's width/height explicitly to control framing.

Crop#

crop_x / crop_y / crop_width / crop_height select a normalized sub-rectangle (each 0–1, origin top-left) of the source frame, applied before fit. The element box is unchanged — crop chooses which part of the frame fills it. Omit the fields (or leave the identity 0,0,1,1) for no crop. The editor's Crop widget gives numeric fields plus a drag-to-resize frame over the video. Each component is keyframeable for a Ken Burns pan/zoom. Default crop_width / crop_height are 1; crop_x / crop_y are 0.

Examples#

Trimmed clip with audio fade-out#

{
  "type": "video",
  "source": "https://example.com/intro.mp4",
  "trim_start": 2.5,
  "trim_duration": 6,
  "volume": [
    { "time": 0,   "value": 100 },
    { "time": 5,   "value": 100 },
    { "time": 6,   "value": 0 }
  ]
}

Slow-motion clip#

{
  "type": "video",
  "source": "https://example.com/explosion.mp4",
  "playback_rate": 0.25,
  "duration": 8
}

Looped background plate#

{
  "type": "video",
  "source": "https://example.com/loop.mp4",
  "track": 1,
  "x": 960, "y": 540,
  "width": 1920, "height": 1080,
  "duration": "end",
  "loop": true,
  "volume": 0
}

Notes#

Frame-accurate seeking — the runtime uses WebCodecs for decode, so seeks are frame-accurate.
Codec support in the hosted renderer matches Chromium's: H.264, H.265, VP8, VP9, AV1. Audio codecs: AAC, Opus, MP3.
Multiple audio tracks — if your source has multiple tracks, only the default is mixed. Use ffmpeg to remux if you need to select a non-default track.

video#