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
This format is considered partially-stable. Breaking changes can be made to feature level changes, but not patch level changes.
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[][];
}
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. Overlay placement is a
// `pos:x:y[:scale]` effect; see "Compositing layers".
}
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.
}
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": [
[ { "name": "video", "src": "example.mp4", "start": 0, "dur": 60, "offset": 0, "stream": 0 } ],
[ { "name": "video", "src": "pip.mp4", "start": 0, "dur": 60, "offset": 0, "stream": 0,
"effects": ["pos:900:60:0.25"] } ],
[ { "name": "video", "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.
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
},
...
]
]
}