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?: "tok-str">'mp4' | "tok-str">'gif';
  width?: number;
  height?: number;
  duration?: number | "tok-str">'auto';
  frame_rate?: number;
  background_color?: string;
  fonts?: FontFace[];
  "tok-cmt">// Scene (3D / lighting) — all optional; omit for flat, unlit 2D
  motion_blur?: { samples?: number; shutter?: number };
  camera?: Camera;
  lights?: Light[];
  environment?: Environment;
  bloom?: { threshold?: number; knee?: number; intensity?: number; radius?: number };
  elements: Element[];
}

Fields#

Scene (3D / lighting)#

These root fields turn on Clipkit's 2.5D camera, PBR lighting, and post-process passes. Every one is optional — omit them all and the scene renders flat and unlit. For the math and the full pose/lighting model, see PROTOCOL.md §4.4 (camera) and §4.8 (lights & material).

motion_blur#

Renders each frame as a blend of sub-frame samples taken across the shutter window.

camera#

Adds a perspective projection and a movable pose. With no camera the scene is pure flat 2D and z only re-sorts elements. perspective is the only required field. Pose components (x/y/z, rotations) accept keyframes or expressions.

lights#

An array of lights for PBR material elements. Each entry is one of two types (discriminated on type):

ambient — flat fill from every direction.

directional — a sun-like light with a direction.

environment#

An environment map sampled for material reflections — one of two types:

bloom#

A post-process pass that adds a glow to bright pixels.

Fonts#

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

interface FontFace {
  family: string;                 "tok-cmt">// name text elements reference
  weight?: number | string;       "tok-cmt">// CSS font-weight; variable fonts may use a range ("100 900")
  style?: "tok-str">'normal' | "tok-str">'italic';
  src: string;                    "tok-cmt">// absolute / relative URL or data: URI
  unicode_range?: string;         "tok-cmt">// 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 — the Source has no aspect_ratio field; set width and height directly. (aspect_ratio does exist as an element field, where it derives a missing box dimension from the other one — see common element fields.)
• 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 < 1 show this color through.