Source root fields#

Top-level fields on the project object. Everything that isn't on an element lives here.

interface Source {
  clipkit_version?: string;
  output_format?: 'mp4' | 'gif';
  width?: number;
  height?: number;
  duration?: number | 'auto';
  frame_rate?: number;
  background_color?: string;
  fonts?: FontFace[];
  elements: Element[];
}

Fields#

Field	Type	Default	Description
`clipkit_version`	`string`	`"1.0"`	The Clipkit Protocol version this Source conforms to. SHOULD be present on documents produced by tooling. Runtimes attempt to render any 1.x document and warn about 2.x+.
`output_format`	`'mp4' \| 'gif'`	`'mp4'`	What the renderer should produce. Clipkit is video-only: `mp4` (H.264 + AAC) is the default; `gif` is animated (audio dropped).
`width`	`number`	`1920`	Output canvas width in pixels.
`height`	`number`	`1080`	Output canvas height in pixels.
`duration`	`number \| 'auto'`	`'auto'`	Output duration in seconds. `'auto'` uses the last element's `time + duration`.
`frame_rate`	`number`	`30`	Output frame rate (fps). The renderer encodes every frame; higher = smoother + bigger.
`background_color`	`string` (hex)	`'#000000'`	Solid background color applied behind all elements. Use a full-canvas `shape` element if you need a gradient.
`fonts`	`FontFace[]`	—	Font faces the runtime registers before rendering, so the Source doesn't depend on host-installed fonts. See Fonts below.
`elements`	`Element[]`	required	The scene contents. See common element fields for what's on every element.

Fonts#

Each entry registers one face, exactly like a CSS @font-face rule:

interface FontFace {
  family: string;                 // name text elements reference
  weight?: number | string;       // CSS font-weight; variable fonts may use a range ("100 900")
  style?: 'normal' | 'italic';
  src: string;                    // absolute / relative URL or data: URI
  unicode_range?: string;         // CSS unicode-range, e.g. "U+0000-00FF"
}

Multiple entries may share a family — different weights, styles, or unicode_range subsets. Subsetted webfonts (one file per script under identical descriptors) need their unicode_range carried through, or every subset competes for every codepoint and text can fall back to the wrong file's glyphs. The snapshot importer captures all of this automatically.

Examples#

Minimal 16:9, 6 seconds, 30 fps#

{
  "clipkit_version": "1.0",
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "frame_rate": 30,
  "elements": [ /* ... */ ]
}

Vertical 9:16 for Stories / TikTok#

{
  "clipkit_version": "1.0",
  "width": 1080,
  "height": 1920,
  "duration": 8,
  "frame_rate": 30,
  "elements": [ /* ... */ ]
}

Notes#

Aspect ratio is implicit — Clipkit doesn't take an aspect_ratio field. Set width and height directly.
duration: 'auto' is the recommended default while you're iterating; pin a number once the timing is final so adding a hidden element doesn't extend the output.
background_color is rendered before any element. Elements with opacity < 100 show this color through.