Docs
Kavio API overview.
Kavio is split into focused packages so each layer has a clear contract: data, timeline logic, motion authoring, browser preview, render orchestration, media planning, CLI, and agent tools.
Package Contracts
- @kitsra/kavio-schema
- JSON Schema, shared types, validation, and migration scaffold.
- @kitsra/kavio-core
- Timeline evaluation, transition-series overlap windows, timing, prop resolution, layout, captions, masks, and resource limits.
- @kitsra/kavio-builder
- TypeScript authoring helpers for canonical JSON, native transitions, cinematic recipes, camera moves, and text motion.
- @kitsra/kavio-browser-renderer
- Browser preview and DOM rendering runtime for layers, masks, text motion, and transition series.
- @kitsra/kavio-render-worker
- Browser-driver contracts, frame capture helpers, batch expansion, metadata, and cleanup primitives.
- @kitsra/kavio-ffmpeg
- Inspectable FFmpeg plan construction.
- @kitsra/kavio-cli
- Local commands for validation, inspection, migration, and preview.
- @kitsra/kavio-render
- Render execution layer that owns real browser capture, FFmpeg orchestration, MP4 output, metadata, cleanup, and cancellation.
- @kitsra/kavio-mcp
- MCP server, provider tool adapters, portable skill, and plugin manifests for agent-facing Kavio workflows. It calls
@kitsra/kavio-renderinstead of spawning binaries itself.
Import Style
Workspace examples import package helpers directly by package name after the monorepo is built.
import {
asset,
cinematic,
text,
textMotion,
track,
trackClip,
transition,
video
} from "@kitsra/kavio-builder";Builder SDK Method Index
The @kitsra/kavio-builder package emits canonical Kavio JSON while
giving TypeScript templates a fluent authoring surface. These are the
public helpers and methods exposed by the current builder package.
| API | Methods | Use |
|---|---|---|
video(composition, options?) |
new VideoBuilder() |
Create a template builder from width, height, fps, durationFrames, background, and optional metadata. |
VideoBuilder |
prop(), props(), asset(), assets(), add(), addTrack(), tracks(), audio(), addExport(), exports(), toJSON(), validate() |
Register props and assets, add layers and transition tracks, add audio and export presets, then emit or validate the Kavio document. |
LayerBuilder |
animate(), motion(), transitionIn(), transitionOut(), enter(), exit(), toInput(), toJSON(), id |
Attach keyframes, native transitions, and fluent entrance/exit motion to video, image, text, shape, and caption layers. |
TrackBuilder |
clip(), toInput(), toJSON() |
Build top-level transition series from layer ids and overlapping clip timing. |
PropReference |
toString(), toJSON() |
Represent a prop interpolation such as {{headline}} and carry optional prop metadata. |
AssetReference |
toDefinition(), toString(), toJSON() |
Represent a named asset reference and generate its asset definition. |
| Namespace | Helpers | Output |
|---|---|---|
asset |
asset.video(), asset.image(), asset.audio(), asset.font() |
Video, image, audio, and font asset definitions with stable ids. |
| Layer helpers | clip(), videoLayer(), image(), text(), shape(), caption(), plus layers.video, layers.clip, layers.image, layers.text, layers.shape, layers.caption |
Layer builders for the five Kavio layer types. |
| Document helpers | prop(), validate(), keyframes(), track(), trackClip() |
Prop interpolation, document validation, normalized keyframe arrays, and transition-track definitions. |
transitionSeries |
transitionSeries.fromPrevious() |
Converts a native transition into the top-level transition-series shape used between track clips. |
crop |
crop.center(), crop.subject() |
Video crop metadata for centered cover crops and subject-aware crop keyframes. |
| Aliases | transitions, cinematicPresets, textMotions, exportPresets, presetNamespaces, effect |
Compatibility and namespace aliases for tools, editors, and generated authoring UIs. |
Motion Helper Index
Motion helpers remain JSON-first: transitions become transition objects, camera helpers become keyframe maps, cinematic presets become layer fragments, and text motion helpers become text-layer fragments.
| Namespace | Methods | Notes |
|---|---|---|
transition |
fade(), slide(), wipe(), crossfade(), zoom(), push(), spin(), rotate(), flip(), blurDissolve(), colorDissolve(), dip(), iris(), stretch(), squeeze(), clockWipe(), barWipe(), gridWipe(), tileReveal(), radialBlur(), zoomBlur(), bookFlip(), pageCurlLite(), skewSlide(), expandMask(), letterboxReveal(), filmFlash(), cameraWhip() |
Native transition definitions for transitionIn, transitionOut, and transition series. |
camera |
kenBurns(), pushIn(), pullBack(), pan(), tilt(), parallax(), orbitLite(), handheld(), crashZoom(), dollyZoomLite() |
Deterministic keyframe maps for image and video layers. |
cinematic |
zoomPush(), whipPan(), filmFlash(), dreamyBlur(), broadcastDip(), irisOpen(), flipCard(), glitchCut(), lightLeak(), kenBurns(), logoSting(), productReveal(), socialHook(), titleSequence(), endCard() |
Reusable layer fragments for common cinematic moves, stings, hooks, reveals, and end cards. |
textMotion |
rise(), blurIn(), typeOn(), cascade(), scramble(), highlightSweep(), trackingIn() |
Whole-layer entrances and first-class text fragment animation for chars, words, lines, or the whole string. |
timing |
tween(), spring(), steps(), sequence(), stagger() |
Frame-based timing definitions that can be attached to transitions and keyframes. |
easing |
linear, inQuad, outQuad, inOutQuad, inCubic, outCubic, inOutCubic, inCirc, outCirc, inOutCirc, inExpo, outExpo, inOutExpo, anticipate, back, inBack, outBack, inOutBack, inElastic, outElastic, inOutElastic, inBounce, outBounce, inOutBounce, cubicBezier() |
Named easing values and a cubic-bezier helper. |
Export Preset Index
Export helpers return plain export preset objects. They can be passed
to composition.exports() or used as a base for custom
render targets.
| Helper | Default Target | Alias |
|---|---|---|
exportPreset.vertical() | 1080x1920 vertical MP4. | vertical |
exportPreset.reels() | 1080x1920 reels MP4. | reels |
exportPreset.instagramReels() | Instagram Reels 9:16 MP4. | instagramReels |
exportPreset.tiktok() | TikTok 9:16 MP4. | tiktok |
exportPreset.youtubeShorts() | YouTube Shorts 9:16 MP4. | youtubeShorts |
exportPreset.facebookReels() | Facebook Reels 9:16 MP4. | facebookReels |
exportPreset.square() | 1080x1080 square MP4. | square |
exportPreset.portrait() | 1080x1350 portrait MP4. | portrait |
exportPreset.landscape() | 1920x1080 landscape MP4. | landscape |
exportPreset.social() | Array of common social presets. | social |
exportPreset.custom() | Caller-provided name, width, height, and format options. | customExport |
socialMediaPresets | Metadata for Instagram, TikTok, YouTube Shorts, Facebook Reels, square, portrait, and landscape presets. | none |