The svgmo file format

Version 1.

An svgmo file is a JSON document describing a vector animation: an artboard, a list of layers, and values that change over time through keyframes. It is what the svgmo editor exports and what the svgmo player plays.

The source of truth is packages/engine/src/types.ts (the data) and packages/engine/src/svgmo.ts (the envelope).

Envelope

{
  "format": "svgmo",
  "v": 1,
  "meta": { "name": "Logo intro", "generator": "svgmo" },
  "comp": { }
}

A reader also accepts a bare composition (the comp object on its own, as in editor project files).

Composition

{
  "version": 1,
  "name": "Logo intro",
  "width": 512,
  "height": 512,
  "fps": 30,
  "duration": 90,
  "background": "#ffffff",
  "layers": []
}

Coordinates: origin at the top-left of the artboard, x to the right, y down, in pixels.

Animatable values

Any value marked animatable below is one of:

{ "value": 100 }

{ "keys": [
  { "t": 0,  "v": 0, "ease": { "x1": 0.42, "y1": 0, "x2": 0.58, "y2": 1 } },
  { "t": 30, "v": 100 }
] }

Rules:

• Before the first key the value is the first key's value; after the last key it is the last key's value.
• Between two keys the value is interpolated: numbers and number arrays component by component, paths point by point.
• ease belongs to the segment that starts at its key. An ease on the last key has no effect.

Easing

Layer

{
  "id": "badge",
  "name": "Badge",
  "transform": { },
  "geometry": { },
  "fill": { },
  "stroke": null,
  "inPoint": 10,
  "outPoint": 80,
  "parent": "group-1",
  "blend": "multiply",
  "motionPath": null
}

Transform

{
  "anchor": [0, 0],
  "position": { "value": [256, 256] },
  "scale":    { "value": [1, 1] },
  "rotation": { "value": 0 },
  "opacity":  { "value": 1 }
}

A point of the shape is placed by, in order: subtract the anchor, scale, rotate, add the position. As an SVG transform: translate(position) rotate(rotation) scale(scale) translate(-anchor).

Parenting

A layer with parent is transformed by its own transform and then by its parent's, and so on up the chain. Opacity, visibility (inPoint, outPoint, hidden) and blend mode are not inherited. A parent that names a missing layer, or a chain that loops, is ignored from that point.

Geometry

Shapes are drawn around the layer's own origin (0, 0).

Rectangle:

{ "kind": "rect", "size": { "value": [160, 90] }, "radius": { "value": 12 } }

Ellipse:

{ "kind": "ellipse", "size": { "value": [120, 120] } }

Path:

{ "kind": "path", "path": { "value": { "closed": true, "points": [ ] } } }

Path

{
  "closed": true,
  "points": [
    { "x": 0,  "y": -50, "inX": -28, "inY": 0, "outX": 28, "outY": 0 },
    { "x": 50, "y": 0,   "inX": 0, "inY": -28, "outX": 0, "outY": 28 }
  ],
  "sub": []
}

The segment from point A to point B is the cubic bezier A, A + out, B + in, B. Handles of 0, 0 give a straight segment and a sharp corner.

Morphing: a path animates between two keys only when both have the same number of points and the same number of sub-paths (each with matching point counts). Otherwise the shape holds the earlier key until the next one.

Fill

{ "color": { "value": [32, 150, 243, 1] }, "rule": "evenodd", "gradient": { } }

Gradient

{ "type": "linear", "angle": 90, "stops": [
  { "offset": 0, "color": [99, 132, 255, 1] },
  { "offset": 1, "color": [255, 99, 132, 1] }
] }

A gradient is placed relative to the shape's bounding box, so it follows the shape as it resizes or morphs. Stops and gradient geometry are not animatable.

Stroke

{
  "color": { "value": [0, 0, 0, 1] },
  "width": { "value": 4 },
  "cap": "round",
  "join": "round",
  "dash": [8, 6],
  "trim": { "start": { "value": 0 }, "end": { "value": 1 } }
}

Motion path

{
  "path": { "closed": false, "points": [ ] },
  "progress": { "keys": [ { "t": 0, "v": 0 }, { "t": 60, "v": 1 } ] },
  "orient": true,
  "orientOffset": 0,
  "repeat": 2,
  "pingpong": true
}

When present, the layer's position comes from the path instead of transform.position.

Blend modes

normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, hue, saturation, color, luminosity.

Validity

A reader rejects a file when:

• width, height, fps or duration is missing or not above 0
• layers is not an array
• a layer has no string id, or two layers share one
• a layer's transform is missing, or anchor is not [x, y]
• geometry.kind is not rect, ellipse or path
• an animatable value has neither value nor a non-empty, time-sorted keys
• blend is not in the list above
• a gradient has fewer than 2 stops or an unknown type
• a motion path has fewer than 2 points, or repeat is outside 1..1000

A complete small file

A blue circle that fades in and slides right:

{
  "format": "svgmo",
  "v": 1,
  "meta": { "name": "Slide", "generator": "by hand" },
  "comp": {
    "version": 1,
    "width": 400,
    "height": 200,
    "fps": 30,
    "duration": 45,
    "layers": [
      {
        "id": "dot",
        "name": "Dot",
        "transform": {
          "anchor": [0, 0],
          "position": { "keys": [
            { "t": 0,  "v": [60, 100], "ease": { "x1": 0, "y1": 0, "x2": 0.58, "y2": 1 } },
            { "t": 30, "v": [340, 100] }
          ] },
          "scale": { "value": [1, 1] },
          "rotation": { "value": 0 },
          "opacity": { "keys": [ { "t": 0, "v": 0 }, { "t": 10, "v": 1 } ] }
        },
        "geometry": { "kind": "ellipse", "size": { "value": [60, 60] } },
        "fill": { "color": { "value": [32, 150, 243, 1] } },
        "stroke": null
      }
    ]
  }
}

Reading and writing from code

import { packSvgmo, readSvgmo } from "@vectormotion/engine";

const text = packSvgmo(composition);              // playback file
const editable = packSvgmo(composition, { editable: true, pretty: true });

const result = readSvgmo(text);
if (result.ok) use(result.comp);
else console.warn(result.errors);

packSvgmo options:

A playback file (the default) drops hidden layers. A hidden layer that is the parent of a visible one is kept, without fill or stroke, so its child still moves with it.

Earlier names

The format was first called VectorMotion. Readers keep accepting:

Nothing else differs, so an old file can simply be renamed. The editor writes the new names.

Versioning

• v increases when a change would make an older reader draw the file wrongly.
• New optional fields that older readers can ignore do not change v.
• Readers ignore fields they do not know.