Docs
Author reusable video templates.
Kavio templates can be written directly as JSON or emitted through the TypeScript builder SDK. Both paths produce canonical composition data with deterministic motion.
Template Checklist
- Declare props with type, defaults, required flags, and validation metadata.
- Reference props with double braces, for example
{{headline}}. - Use named assets so layer definitions stay stable and reusable.
- Give layers clear ids that survive debugging, preview, and export overrides.
- Define export presets for the aspect ratios and codecs you intend to support.
- Use native transitions, timing objects, masks, text motion, and transition tracks as data.
- Keep generated outputs out of version control unless they are intentional fixtures.
Builder SDK Shape
The builder creates the same composition shape as raw JSON while giving TypeScript projects typed helpers.
import { asset, clip, exportPreset, prop, text, video } from "@kitsra/kavio-builder";
const headline = prop("headline", {
type: "string",
default: "New collection is live",
maxLength: 80
});
const composition = video({
width: 1080,
height: 1920,
fps: 30,
durationFrames: 240,
background: "#000000"
});
composition
.props(headline)
.assets(asset.video("mainClip", prop("clipUrl", { type: "url", required: true })))
.add(
clip("background-video", { asset: "mainClip", startFrame: 0, durationFrames: 240, fit: "cover" }),
text("headline", { text: headline, startFrame: 20, durationFrames: 100 })
)
.exports(exportPreset.reels());Template Format Reference
A Kavio template is a versioned JSON document. Raw JSON and builder output use the same top-level fields, so templates can move between command line validation, browser preview, MCP tools, and render jobs.
| Field | Required | Shape | Purpose |
|---|---|---|---|
version | yes | "0.1" | Composition schema version. |
metadata | no | { title, author, tags, createdAt } | Human and indexing metadata for a template. |
composition | yes | { width, height, fps, durationFrames, background, colorSpace } | Canvas timing and base visual settings. |
props | no | Map of prop definitions. | Batch/editor inputs such as headline, color, logo URL, or media URL. |
assets | yes | Map of video, image, audio, and font assets. | Reusable external media references. |
layers | yes | Array of video, image, text, shape, and caption layers. | Timeline visuals rendered in z order. |
tracks | no | Array of transition tracks. | Clip-to-clip transition series that preserve ordinary layers. |
audio | no | Array of audio tracks. | Music, voiceover, source audio, and sound effects. |
exports | yes | Array of export presets. | Named output targets such as reels, square, portrait, and landscape. |
{
"version": "0.1",
"metadata": { "title": "Launch Reel", "tags": ["template", "social"] },
"composition": { "width": 1080, "height": 1920, "fps": 30, "durationFrames": 240 },
"props": {
"headline": { "type": "string", "required": true, "maxLength": 80 },
"brandColor": { "type": "color", "default": "#db614d" }
},
"assets": {
"hero": { "type": "image", "src": "{{heroUrl}}" }
},
"layers": [],
"audio": [],
"exports": [{ "name": "reels", "format": "mp4", "width": 1080, "height": 1920 }]
}Props, Assets, Layers, And Exports
These fields are the authoring vocabulary most templates use. Values
may be literals or prop interpolations such as {{headline}}.
| Area | Fields | Notes |
|---|---|---|
| Prop definition | type, required, default, maxLength, min, max, options, description |
Prop types are string, number, boolean, color, url, enum, and asset. |
| Asset definition | type, src, checksum, trimStartFrames, trimEndFrames, loop, family, weight, style |
Asset types are video, image, audio, and font. Font assets require family. |
| Common layer fields | id, type, startFrame, durationFrames, position, anchor, size, opacity, rotation, scale, z, track, keyframes, effects, mask, transitionIn, transitionOut |
Common fields apply to video, image, text, shape, and caption layers. |
| Video layer | asset, fit, crop, muted, volume, playbackRate |
fit accepts cover, contain, fill, or none. Crop can be centered or subject-aware. |
| Image layer | asset, fit |
Use image layers for logos, screenshots, product images, and generated stills. |
| Text layer | text, style, textMotion |
Style supports font family, size, weight, style, color, align, line height, letter spacing, max lines, wrap, background, padding, stroke, and shadow. |
| Shape layer | shape, fill, stroke, radius |
The current built-in shape is rect. |
| Caption layer | source, style, safeArea |
Caption source can be inline cues, VTT, SRT, or an asset reference. Highlight modes are none, word, and line. |
| Export preset | name, format, codec, width, height, fps, bitrate, crf, audioCodec, audioBitrate, loudnessLufs, background, layerOverrides |
Export formats include mp4, webm, mov, gif, and png-sequence. |
Motion, Masks, Tracks, And Audio
Kavio motion is data, so builders, editors, and AI tools can all emit the same fields without depending on a particular runtime component.
| Feature | Fields | Values |
|---|---|---|
| Keyframes | opacity, x, y, scale, rotation |
Each keyframe uses frame, value, optional easing, and optional timing. |
| Timing | type, durationFrames, easing, stiffness, damping, mass, restSpeed, bounce, steps, direction, segments, childCount, eachFrames, childIndex, from |
Timing types are tween, spring, steps, sequence, and stagger. |
| Transition | type, durationFrames, direction, axis, shape, color, amount, intensity, rows, columns, easing, timing |
Transition types include fade, slide, wipe, crossfade, zoom, push, spin, rotate, flip, blur dissolve, color dissolve, dip, iris, stretch, squeeze, clock wipe, bar wipe, grid wipe, tile reveal, radial blur, zoom blur, book flip, page curl, skew slide, expand mask, letterbox reveal, film flash, and camera whip. |
| Text motion | type, split, durationFrames, easing, staggerFrames, origin, seed, preserveLayout, restingBox, direction, amount, intensity, color |
Text motion types are typeOn, cascade, scramble, highlightSweep, and trackingIn. Split modes are none, word, char, and line. |
| Mask | source, opacity, invert |
Mask sources can be shape masks, asset alpha masks, or procedural masks such as linear gradient, radial gradient, and scanlines. |
| Track clip | id, layerId, startFrame, durationFrames, transitionFromPrevious |
Transition tracks describe how ordinary layers overlap and transition between each other. |
| Audio track | id, asset, role, startFrame, durationFrames, offsetFrames, volume, fadeInFrames, fadeOutFrames, loop, duck |
Audio roles are music, voiceover, sfx, and source. Ducking targets another role with amountDb, attackFrames, and releaseFrames. |
Motion
Kavio supports timeline-safe motion through frame-based timing, keyframes, native transitions, transition series, masks, text motion, captions, and layout-aware layer fields. Prefer animation that remains valid across export aspect ratios.
import { cinematic, text, textMotion, track, trackClip, transition } from "@kitsra/kavio-builder";
text("hook", {
text: "Launch in motion",
startFrame: 24,
durationFrames: 72,
...textMotion.scramble({ split: "char", seed: 42 })
}).enter(transition.cameraWhip({ direction: "left", durationFrames: 8 }));
track("main", [
trackClip("outgoing", { layerId: "scene-a", startFrame: 0, durationFrames: 60 }),
trackClip("incoming", {
layerId: "scene-b",
startFrame: 48,
durationFrames: 60,
transitionFromPrevious: transition.push({
direction: "left",
durationFrames: 12,
easing: "outCubic"
})
})
]);
cinematic.glitchCut({ durationFrames: 8 });