---
title: "Video Elements"
canonical_url: https://docs.zvid.io/docs/structure/video-elements/
source: docs/structure/video-elements.md
content_revision: 6338386a1dd87e4a
---

# Video Elements

`VIDEO` elements place remote video clips on the project timeline. They support source trimming, playback speed, volume, filters, crop, chroma key, resize, zoom, animations, and video-to-video transitions.

## Interface

```typescript
interface VideoItem {
  type: "VIDEO";
  src: string;
  id?: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: "contain" | "cover";
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  zoom?: boolean | { depth?: number };
  radius?: BorderRadius;
  enterAnimation?: XFadeEffect | null;
  exitAnimation?: XFadeEffect | null;
  cropParams?: CropParams;
  chromaKey?: ChromaKey;
  filter?: FilterOptions;
  videoBegin?: number;
  videoEnd?: number;
  videoDuration?: number;
  volume?: number;
  speed?: number;
  frameRate?: number;
  transition?: XFadeEffect | null;
  transitionDuration?: number;
  transitionId?: string;
}
```

## Required Fields

| Property | Type      | Notes                               |
| -------- | --------- | ----------------------------------- |
| `type`   | `"VIDEO"` | Case-insensitive in API validation. |
| `src`    | `string`  | Remote `http` or `https` URL.       |

## Properties

Placement, timing, layering, and animation fields are shared by all visual
elements — see [Common Element Properties](https://docs.zvid.io/docs/structure/common-properties/). Videos
support every media option in the
[support matrix](https://docs.zvid.io/docs/structure/common-properties/#media-only-properties), and add source
timing, audio/playback, and transition fields documented below.

## Timeline And Source Timing

| Property        | Default                    | Notes                             |
| --------------- | -------------------------- | --------------------------------- |
| `videoBegin`    | `0`                        | Start offset inside source media. |
| `videoEnd`      | project or source duration | End offset inside source media.   |
| `videoDuration` | project or source duration | Source clip duration hint.        |

Timeline placement (`enterBegin`/`exitEnd`) is the shared timing model — see
[Common Element Properties](https://docs.zvid.io/docs/structure/common-properties/#timing). `videoBegin`/`videoEnd`
trim the **source**; the enter/exit fields place the trimmed clip on the
**timeline**.

All timing values are in seconds. With `speed: 2`, a ten-second source
segment plays in five seconds; set timeline bounds accordingly. The hosted
API needs explicit bounds for automatic-duration requests. See
[Timing](https://docs.zvid.io/docs/concepts/timing/) and [Media assets](https://docs.zvid.io/docs/concepts/media-assets/).

## Audio And Playback

| Property    | Default                   | Range                                 |
| ----------- | ------------------------- | ------------------------------------- |
| `volume`    | `1`                       | `0` to `2`; `1` is the original level |
| `speed`     | `1`                       | `0.1` to `10`                         |
| `frameRate` | source/project frame rate | integer `1` to `60`                   |

Set `volume: 0` on video clips when you want to replace source audio with tracks from `audios`.

## Transitions

Transitions are available only between `VIDEO` elements. Add `id` to the target clip and set `transition`, `transitionDuration`, and `transitionId` on the clip that starts the transition.

```json
[
  {
    "type": "VIDEO",
    "id": "intro",
    "src": "https://cdn.pixabay.com/video/2025/03/12/264272_large.mp4",
    "resize": "cover",
    "enterBegin": 0,
    "exitEnd": 5,
    "transition": "fade",
    "transitionDuration": 1,
    "transitionId": "main"
  },
  {
    "type": "VIDEO",
    "id": "main",
    "src": "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
    "resize": "cover",
    "enterBegin": 5,
    "exitEnd": 10
  }
]
```

The next clip's `id` must match `transitionId`. Keep the handoff timing coordinated: the first clip's `exitEnd` should align with the next clip's `enterBegin` for the documented transition pattern.

## Examples

These are **visual element fragments** for `payload.visuals` or a scene's
`visuals`. Recorded previews use their own complete fixtures, linked below;
they demonstrate the feature without promising identical fragment dimensions
or source trims.

### Simple Video

```json
{
  "type": "VIDEO",
  "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
  "resize": "cover",
  "volume": 0
}
```

### Trimmed Clip

```json
{
  "type": "VIDEO",
  "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
  "videoBegin": 5,
  "videoEnd": 25,
  "volume": 0.8,
  "width": 1920,
  "height": 1080,
  "enterBegin": 0,
  "exitEnd": 20
}
```


```json
{
  "name": "docs-video-trim",
  "width": 960,
  "height": 540,
  "duration": 6,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
      "videoBegin": 5,
      "videoEnd": 11,
      "resize": "cover",
      "width": 960,
      "height": 540,
      "position": "center-center",
      "volume": 0
    }
  ]
}
```

Recorded fixture: videoBegin/videoEnd trim a source clip

[Watch rendered example](https://cdn.zvid.io/library/docs/video-trim.mp4)


### Picture In Picture

```json
{
  "type": "VIDEO",
  "src": "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
  "videoBegin": 10,
  "videoEnd": 30,
  "width": 300,
  "height": 200,
  "position": "bottom-right",
  "volume": 0.3,
  "track": 10
}
```


```json
{
  "name": "docs-video-pip",
  "width": 960,
  "height": 540,
  "duration": 6,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
      "resize": "cover",
      "width": 960,
      "height": 540,
      "position": "center-center",
      "volume": 0
    },
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
      "videoBegin": 10,
      "videoEnd": 16,
      "width": 300,
      "height": 180,
      "position": "bottom-right",
      "volume": 0,
      "track": 10,
      "radius": {
        "tl": 12,
        "tr": 12,
        "bl": 12,
        "br": 12
      }
    }
  ]
}
```

Recorded fixture: picture-in-picture with track layering

[Watch rendered example](https://cdn.zvid.io/library/docs/video-pip.mp4)


## Formats

Input video assets are remote URLs and are checked before rendering. Output video formats are limited to `mp4`, `mov`, `avi`, and `webm`.

## Related Pages

- [Transitions](https://docs.zvid.io/docs/structure/transitions/)
- [Audio Elements](https://docs.zvid.io/docs/structure/audio-elements/)
- [Animation Effects](https://docs.zvid.io/docs/structure/animations/)
- [XFadeEffect](https://docs.zvid.io/docs/structure/properties/xfade-effects/)