View raw

Quickstart#

The five-minute path from npx to a rendered MP4.

Prerequisites#

  • Node.js 20+
  • One terminal

That's it. No accounts, no API keys to start.

1. Scaffold a project#

npx @clipkit/cli init my-video
cd my-video
npm install

The scaffold drops the following into your new directory:

  • video.ts — a starter Clipkit Source you can edit
  • package.json — wires up the CLI as a local dependency
  • tsconfig.json — strict TypeScript
  • AGENTS.md — so any AI agent working in this directory auto-loads the authoring guide
  • README.md — project notes

The starter video.ts is a minimal valid Source: a background, a title, a caption. It validates and renders out of the box.

2. Edit your video#

Open video.ts. The Source is just a JSON-shaped TypeScript object — keep it that way to stay schema-clean. Add a text element, change a color, swap the duration. Everything you can do lives in the protocol spec.

import type { Source } from '@clipkit/protocol';

const source: Source = {
  clipkit_version: '1.0',
  output_format: 'mp4',
  width: 1920,
  height: 1080,
  duration: 6,
  frame_rate: 30,
  elements: [
    {
      id: 'title',
      type: 'text',
      track: 1,
      time: 0,
      duration: 6,
      text: 'Hello, Clipkit.',
      x: 960,
      y: 540,
      font_family: 'sans-serif',
      font_size: 120,
      font_weight: 'bold',
      fill_color: '#ffffff',
      animations: [
        { type: 'fade-in', duration: 0.8 },
        { type: 'fade-out', duration: 0.8, time: 'end' },
      ],
    },
  ],
};

export default source;

3. Validate#

npx clipkit validate video.ts
# ✓ video.ts is a valid Clipkit Protocol v1.0 document.

Validation runs the same Zod schema the runtime, the MCP server, and the render service all consume. If it passes here, it will render.

4. Render#

Two paths to MP4 today:

Local (headless Chrome)#

npm install @clipkit/render-service
npx playwright install chromium
import { render } from '@clipkit/render-service';
import { writeFile } from 'node:fs/promises';
import source from './video';

const result = await render({ source });
await writeFile('out.mp4', result.buffer);

See render service docs for backend selection, server mode, and the full API.

Hosted#

POST the Source to https://api.clipkit.dev/render with your API key. The hosted endpoint is the same renderer, on someone else's machine, with a job queue and storage in front. Pricing is per second of output — no editor session fees, no minimums.

What's next#

  • Authoring guide — patterns + recipes (read this if an LLM is writing the JSON for you)
  • Protocol spec — the full normative schema
  • MCP server — wire Clipkit into Claude / Cursor / any MCP host
  • Examples — full Sources you can copy