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, and the proper extension is .v3.

Auto-Editor can generate v3 timelines from media files (instructed with --edit),

auto-editor example.mp4 --export v3 -o input.v3

render media files from the v3 format,

auto-editor input.v3 -o output.mkv

and translate other timeline formats to v3:

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:

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.

"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 for the full list.

The v3 format looks something like this:

{
  "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
      }
    ]
  ]
}