# Kavio Website

Kavio is a pre-release, JSON-first programmable video engine for automation,
AI-generated templates, browser preview, and future visual editing.

This website is self-contained. It summarizes the project, documentation,
examples, and package boundaries without relying on local repository markdown
files. The source code and runnable fixtures live at:

https://github.com/kitsra/kavio

## Primary Concepts

- A Kavio composition is portable video data.
- A composition includes canvas settings, props, assets, layers, audio, and exports.
- Timelines are frame-based for deterministic validation, preview, and rendering.
- Props turn compositions into templates using placeholders such as `{{headline}}`.
- Exports describe target formats such as reels, square, and landscape.
- Batch jobs combine one template, one prop row, and one export preset.

## Current Status

Implemented: schema, validator, timeline core, TypeScript builder, browser
preview runtime, render-worker contracts, FFmpeg planning helpers, render
execution, CLI commands, MCP server, provider adapters, portable skill/plugin
bundle, and MVP demo fixtures.

`kavio render` supports opaque `mp4`, `webm`, and `mov` outputs. Schema-valid
`gif`, `png-sequence`, and transparent final outputs are reserved for later
render paths.

## Website Pages

- Home: `index.html`
- Project overview: `project.html`
- Documentation map: `docs.html`
- Examples guide: `examples.html`
- Brand assets: `brand.html`
- Package boundaries: `packages.html`
- Open Graph card: `assets/brand/kavio-og-card.png`
- Square social card: `assets/brand/kavio-og-square.png`
- Getting started: `docs/getting-started.html`
- Concepts: `docs/concepts.html`
- Authoring: `docs/authoring.html`
- CLI reference: `docs/cli.html`
- Browser preview: `docs/preview.html`
- Rendering status: `docs/rendering.html`
- API overview: `docs/api.html`
- MCP server and AI plugins: `docs/mcp.html`
- Troubleshooting: `docs/troubleshooting.html`

## Builder And Template Reference

Static docs include crawler-friendly builder and template indexes:

- `docs/api.html#builder-methods`: `VideoBuilder`, `LayerBuilder`, `TrackBuilder`, `PropReference`, `AssetReference`, `asset`, layer helpers, document helpers, transition series, crop helpers, and namespace aliases.
- `docs/api.html#motion-methods`: `transition`, `camera`, `cinematic`, `textMotion`, `timing`, and `easing` method inventories.
- `docs/api.html#export-methods`: `exportPreset` methods and social export aliases.
- `docs/authoring.html#template-format`: top-level JSON template fields: `version`, `metadata`, `composition`, `props`, `assets`, `layers`, `tracks`, `audio`, and `exports`.
- `docs/authoring.html#template-fields`: prop, asset, common layer, video, image, text, shape, caption, and export fields.
- `docs/authoring.html#motion-fields`: keyframes, timing, transitions, text motion, masks, track clips, and audio track fields.

Important builder exports include `video`, `prop`, `validate`, `keyframes`,
`clip`, `videoLayer`, `image`, `text`, `shape`, `caption`, `track`,
`trackClip`, `asset.video`, `asset.image`, `asset.audio`, `asset.font`,
`transition.fade`, `transition.slide`, `transition.wipe`,
`transition.crossfade`, `transition.zoom`, `transition.push`,
`transition.spin`, `transition.rotate`, `transition.flip`,
`transition.blurDissolve`, `transition.colorDissolve`, `transition.dip`,
`transition.iris`, `transition.stretch`, `transition.squeeze`,
`transition.clockWipe`, `transition.barWipe`, `transition.gridWipe`,
`transition.tileReveal`, `transition.radialBlur`, `transition.zoomBlur`,
`transition.bookFlip`, `transition.pageCurlLite`, `transition.skewSlide`,
`transition.expandMask`, `transition.letterboxReveal`,
`transition.filmFlash`, `transition.cameraWhip`, `camera.kenBurns`,
`camera.pushIn`, `camera.pullBack`, `camera.pan`, `camera.tilt`,
`camera.parallax`, `camera.orbitLite`, `camera.handheld`,
`camera.crashZoom`, `camera.dollyZoomLite`, `cinematic.zoomPush`,
`cinematic.whipPan`, `cinematic.filmFlash`, `cinematic.dreamyBlur`,
`cinematic.broadcastDip`, `cinematic.irisOpen`, `cinematic.flipCard`,
`cinematic.glitchCut`, `cinematic.lightLeak`, `cinematic.kenBurns`,
`cinematic.logoSting`, `cinematic.productReveal`, `cinematic.socialHook`,
`cinematic.titleSequence`, `cinematic.endCard`, `textMotion.rise`,
`textMotion.blurIn`, `textMotion.typeOn`, `textMotion.cascade`,
`textMotion.scramble`, `textMotion.highlightSweep`,
`textMotion.trackingIn`, `timing.tween`, `timing.spring`,
`timing.steps`, `timing.sequence`, `timing.stagger`,
`easing.cubicBezier`, `crop.center`, `crop.subject`,
`exportPreset.vertical`, `exportPreset.reels`,
`exportPreset.instagramReels`, `exportPreset.tiktok`,
`exportPreset.youtubeShorts`, `exportPreset.facebookReels`,
`exportPreset.square`, `exportPreset.portrait`,
`exportPreset.landscape`, `exportPreset.social`, and
`exportPreset.custom`.

## Packages

- `@kitsra/kavio-schema`: JSON Schema, shared types, validation, and migration scaffold.
- `@kitsra/kavio-core`: timeline evaluation, frame math, easing, prop resolution, layout, captions, and limits.
- `@kitsra/kavio-builder`: TypeScript authoring SDK with social export presets that outputs canonical Kavio JSON.
- `@kitsra/kavio-browser-renderer`: browser preview and DOM rendering runtime for text, video, image, shape, and captions.
- `@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, preview, presets, and rendering.
- `@kitsra/kavio-render`: render execution layer for 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.

## Examples Covered

- `basic-json`: small raw composition for validation, inspection, and preview.
- `basic-builder`: TypeScript builder version of the basic JSON fixture.
- `mvp-demo`: batch-oriented fixture with five prop rows and three export presets.
- `visual-fixtures`: browser-renderer regression material.