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 Header

shown using TypeScript notation, the keys can be set to the following values.

type Natural = number; // An integer floating-point value that is >= 0.
type Source = string; // A path to a media file, must be valid for the given platform.

interface v3 {
  version: "3";       // Must always be set as "3".
  resolution: [number, number];  // width and height. Must both be natural numbers.
  timebase: string;   // The timebase. Must be a rational number.
                      // Typical values are: "24/1", 30/1", "30000/1001"
                      // Values with a decimal ("29.97") should be rejected.

  samplerate: number; // The overall samplerate, must be a natural number.

  background: string; // A web RGB color value for the background. Relevant in cases
                      // like when a video has a different aspect ratio than the..
                      // global resolution. Must be in the format "#000" or "#000000".

  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: Video[][];
   a: Audio[][];
}

Video and Audio Layers

The elements in the v and a keys are a tagged union with name as the discriminant.

interface Video {
  name: "video";
  src: Source;
  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.
}

interface Audio {
  name: "audio";
  src: Source;
  start: Natural;
  dur: Natural;
  offset: Natural;
  stream: Natural;  // Which audio stream from the source to use.
  effects?: string[]; // Optional. See "Effects" below.
}

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",
  "timebase": "30/1",
  "background": "#000",
  "resolution": [1280, 720],
  "samplerate": 48000,
  "layout": "stereo",
  "langs": ["eng", "eng"],
  "v": [
    [
      {
        "name": "video",
        "src": "example.mp4",
        "start": 0,
        "dur": 26,
        "offset": 0,
        "stream": 0
      },
      {
        "name": "video",
        "src": "example.mp4",
        "start": 26,
        "dur": 362,
        "offset": 34,
        "stream": 0
      },
      ...
    ]
  ],
  "a": [
    [
      {
        "name": "audio",
        "src": "example.mp4",
        "start": 0,
        "dur": 26,
        "offset": 0,
        "stream": 0
      },
      {
        "name": "audio",
        "src": "example.mp4",
        "start": 26,
        "dur": 362,
        "offset": 34,
        "stream": 0
      },
      ...
    ]
  ]
}