---
title: The v3 format
---

## Overview
The v3 format is a nonlinear timeline file format. It supports multiple overlapping video and audio layers. The v3 format is a subset of [JSON](https://www.json.org/), and the proper extension is `.v3`.

Auto-Editor can generate v3 timelines from media files (instructed with `--edit`),
```sh
auto-editor example.mp4 --export v3 -o input.v3
```

render media files from the v3 format,
```sh
auto-editor input.v3 -o output.mkv
```

and translate other timeline formats to v3:
```sh
auto-editor input-fcp7.xml --export v3 -o output.v3
```

## Stability
This format is considered partially-stable. Breaking changes can be made to feature level changes, but not patch level changes.

## The Spec
shown using TypeScript notation, the format can be described:

```ts
type Natural = number; // Number that is >= 0.

interface v3 {
  version: "3";        // Must always be set as "3".
  templateFile?: string;
                       // Copy attachment streams for rendering, if any.
  timebase: string;    // The timebase. Must be a rational number.
                       // Typical values are: "24/1", 30/1", "30000/1001"
  background: string;  // A web RGB color value for the background. Must be in the
                       // format "#000" or "#000000".
  resolution: [Natural , Natural];
                       // width and height. Must be even numbers.
  samplerate: Natural; // The overall samplerate.
  layout: string;      // The audio channel layout, e.g. "mono", "stereo".
  langs: string[];     // Language tag per track (video tracks first, then audio),
                       // e.g. "eng" or "und" when unknown.
   v: Clip[][];        // Video layers. Each layer must contain at least one clip;
                       // an empty layer is malformed and rejected.
   a: Clip[][];        // Audio layers. Same rule: layers must be non-empty.
}

interface Clip {
  src: string;         // Path to a media file
  start: Natural;      // Where in this timeline to start this clip. In terms of timebase.
  dur: Natural;        // The duration of the clip. In terms of timebase.
  offset: Natural;     // Where from the source to start playing at. In terms of timebase.
  stream: Natural;     // Which video stream from the source to use. Usually stream 0.
  effects?: string[];  // Optional. See "Effects" below. Overlay placement is a
                       // `pos:x:y[:scale]` effect; see "Compositing layers".
}
```

## Compositing layers
When more than one video track has a clip active at the same timeline frame, the tracks are composited bottom-to-top: `v[0]` is the base layer and later tracks (`v[1]`, `v[2]`, ...) are painted on top. The base layer fills the canvas (its source is fit to `resolution`). Each higher layer is placed by a `pos:x:y[:scale]` effect in its `effects` array — `x`/`y` are the top-left corner in canvas pixels and `scale` (default `1.0`) multiplies the source's native size. Without a `pos` effect, an overlay is scaled to fit the canvas (preserving aspect ratio) and centered, like a full-frame layer. Other per-clip `effects` are applied to each clip before it is composited.

Still images (PNG, JPG, BMP, TIFF, ...) may be used as a `src`; the single image is held for the clip's whole `dur`, which is convenient for logos and watermarks. Overlay transparency (e.g. a PNG alpha channel) is preserved.

```json
"v": [
  [ { "src": "example.mp4", "start": 0, "dur": 60, "offset": 0, "stream": 0 } ],
  [ { "src": "pip.mp4", "start": 0, "dur": 60, "offset": 0, "stream": 0, "effects": ["pos:900:60:0.25"] } ],
  [ { "src": "logo.png", "start": 0, "dur": 60, "offset": 0, "stream": 0, "effects": ["pos:40:40"] } ]
]
```

For best results, the base track (`v[0]`) should span every frame you intend to render; a frame where only a higher track is active is treated as a single full-frame layer.

## Effects
A clip may carry an optional `effects` key: an array of action strings applied to that clip. Each string is either a bare action like `"invert"` or an action with arguments like `"speed:8.0"`, `"volume:0.5"`, or `"zoom:2.0"`. The single-element array `["cut"]` means the clip is cut (not included). When `effects` is absent, the clip plays unaltered at normal speed. See the [Actions reference](/ref/actions) for the full list.

The v3 format looks something like this:
```json
{
  "version": "3",
  "templateFile": "example.mp4",
  "timebase": "30/1",
  "background": "#000",
  "resolution": [1280, 720],
  "samplerate": 48000,
  "layout": "stereo",
  "langs": ["eng", "eng"],
  "v": [
    [
      {
        "src": "example.mp4",
        "start": 0,
        "dur": 26,
        "offset": 0,
        "stream": 0
      },
      {
        "src": "example.mp4",
        "start": 26,
        "dur": 362,
        "offset": 34,
        "stream": 0
      }
    ]
  ],
  "a": [
    [
      {
        "src": "example.mp4",
        "start": 0,
        "dur": 26,
        "offset": 0,
        "stream": 0
      },
      {
        "src": "example.mp4",
        "start": 26,
        "dur": 362,
        "offset": 34,
        "stream": 0
      }
    ]
  ]
}
```